Skip to main content

ECG

UDTF: cugraph_ecg

Official cuGraph reference: C API

Stabilize community assignments by combining an ensemble of randomized Louvain partitions into a final consensus clustering.

Quickstart​

The call below supplies edges from registered relation target_edges with canonical src and dst columns and may include weight.

SELECT *
FROM cugraph_ecg(
edges => (SELECT src, dst FROM target_edges)
);

Inputs​

Every relation is a named parenthesized SELECT subquery. The required edges role uses canonical src and dst columns. Every role, its canonical columns, and their accepted Arrow types are listed under Relation arguments. Metadata validation resolves registered tables named in its JSON request.

The vertex-ID types this UDTF accepts, the numeric types a per-call codebook maps to native ids, and its string-key limits are listed in Vertex ID support; the concrete call-specific schema comes from gpu_validate_call.

Arguments and options​

Relation arguments​

ArgumentRequiredColumnsDescription
edgesyes
  • src, dst: Int32, Int64, Utf8, LargeUtf8, Utf8View
  • weight (optional): Float32, Float64
  • edge_id (optional): Int32, Int64
edge relation with canonical src and dst columns, plus optional weight and edge_id columns; this algorithm ignores weight

Every edge_id column must have the integer type of src and dst; string-keyed graphs accept no edge IDs.

Named value arguments​

OptionTypeDefaultConstraintsDescription
ensemble_sizeinteger10min 1; max 4294967295number of ECG ensemble iterations
max_levelinteger100min 1; max 4294967295maximum hierarchy level, at least 1
min_weightnumber0.001min 0minimum ECG edge weight
resolutionnumber1max 1; > 0community resolution in (0, 1]
seedinteger0min 0; max 18446744073709552000random initialization seed
thresholdnumber1e-7max 1; > 0convergence threshold in (0, 1]

Graph construction options​

This UDTF requires directed=false (undirected/symmetric graph). All other graph construction options follow the shared defaults documented in Graph Construction Options.

Output​

ColumnTypeNullableDescription
vertexInt64|Utf8noVertex assigned to an ECG community.
communityInt64noCommunity identifier assigned by ECG.

These are generic descriptor schemas. Run gpu_validate_call to get the concrete, table-specific output schema.

Examples​

This example runs on the citation network demo dataset.

Which grouping best matches our catalog's research-field labels?​

This comparison uses the share of members carrying their community's most common primary_fos label as a diagnostic against the catalog. It includes communities with at least 100 members in the purity calculation. Community sizes and that cutoff affect the result. The field labels provide a diagnostic reference for the score, while citation structure defines the communities. The query runs Louvain, Leiden, and ECG on the same 2010s AI citation subgraph.

CREATE OR REPLACE VIEW ai_nodes AS
SELECT paper_id FROM papers
WHERE year >= 2010 AND primary_fos IN (
'Deep learning', 'Artificial neural network', 'Convolutional neural network',
'Recurrent neural network', 'Natural language processing',
'Reinforcement learning', 'Image segmentation', 'Feature extraction',
'Object detection', 'Speech recognition');

CREATE OR REPLACE VIEW ai_edges AS
SELECT e.src, e.dst
FROM citation_edges e
JOIN ai_nodes a ON a.paper_id = e.src
JOIN ai_nodes b ON b.paper_id = e.dst;

WITH labeled AS (
SELECT 'louvain' AS algorithm, c.community, p.primary_fos
FROM cugraph_louvain(edges => (SELECT src, dst FROM ai_edges)) c
JOIN papers p ON p.paper_id = c.vertex
UNION ALL
SELECT 'leiden', c.community, p.primary_fos
FROM cugraph_leiden(edges => (SELECT src, dst FROM ai_edges)) c
JOIN papers p ON p.paper_id = c.vertex
UNION ALL
SELECT 'ecg', c.community, p.primary_fos
FROM cugraph_ecg(edges => (SELECT src, dst FROM ai_edges)) c
JOIN papers p ON p.paper_id = c.vertex),
counts AS (
SELECT algorithm, community, primary_fos, COUNT(*) AS n
FROM labeled GROUP BY 1, 2, 3),
sized AS (
SELECT algorithm, community, SUM(n) AS members, MAX(n) AS top_label
FROM counts GROUP BY 1, 2)
SELECT algorithm,
COUNT(*) AS communities,
COUNT(*) FILTER (WHERE members >= 100) AS ge100,
ROUND(SUM(top_label) FILTER (WHERE members >= 100) * 100.0
/ SUM(members) FILTER (WHERE members >= 100), 1) AS purity_pct
FROM sized
GROUP BY algorithm
ORDER BY purity_pct DESC;
algorithmcommunitiesge100purity_pct
ecg1,9324147.7
louvain1,2332747.1
leiden8512645.9

The default seed is 0, but it does not guarantee identical labels across GPU runs.

Limits​

  • seed sets the random initial community labels of each Louvain pass; the same seed does not guarantee identical communities across runs