API

A tutorial-like presentation is available at Examples using API.

The core public API is:

• graynet.extract for single-feature edge runs

• graynet.extract_multiedge for multi-feature runs with summary edges

• graynet.roiwise_stats_indiv for ROI-wise summary statistics

• graynet.load_run and related helpers for reading canonical run outputs

graynet 2.0 writes canonical run-level outputs in Parquet plus JSON metadata. GraphML and CSV are now optional exports derived from those canonical tables.

API Reference

graynet.api.extract(subject_id_list, input_dir, base_feature=('freesurfer_thickness',), weight_method_list=('manhattan',), num_bins=25, edge_range=None, atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False, num_procs=2)

Compute single-feature edge weights for one or more subjects.

Parameters mirror the classic graynet API, but outputs now follow the 2.0 run-level layout. When out_dir is provided, graynet writes a canonical run directory containing run_metadata.json and edges_raw.parquet. When return_results is True, a mapping of (weight_method, subject_id) -> edge_vector is returned in addition to writing the run outputs.

graynet.api.extract_multiedge(subject_id_list, input_dir, base_feature_list=('freesurfer_thickness', 'freesurfer_curv'), weight_method_list=('manhattan',), summary_stats=('prod', 'median'), num_bins=25, edge_range_dict={'freesurfer_area': (0.0, 1.5), 'freesurfer_curv': (-0.3, 0.3), 'freesurfer_sulc': (-1.5, 1.5), 'freesurfer_thickness': (0.0, 5.0)}, atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False, overwrite_results=False, num_procs=2)

Compute multi-feature edge tables and summary edges for one or more subjects.

Raw multi-edge rows are written to edges_raw.parquet with one row per (subject, base_feature, weight_method, u, v) combination. Requested summary statistics across features are written to edges_summary.parquet.

When return_results is True, the returned mapping uses keys of the form (weight_method, base_feature, subject_id).

graynet.api.roiwise_stats_indiv(subject_id_list, input_dir, base_feature=('freesurfer_thickness',), chosen_roi_stats='median', atlas='fsaverage', smoothing_param=10, node_size=None, out_dir=None, return_results=False, num_procs=2)

Compute ROI-wise summary statistics for one or more subjects.

Canonical outputs are written to roi_stats.parquet in a run directory. When return_results is True, the returned mapping is keyed by (stat_name, subject_id) when multiple statistics are requested, or by subject_id when only one statistic is requested.

class graynet.results.EdgeData(table: Table, metadata: dict[str, Any])

Bases: object

Canonical edge table plus run metadata.

EdgeData is the primary read-side helper for graynet 2.0 results. It wraps a Parquet-backed table and provides convenient filtering, subject-wise iteration, graph reconstruction, and conversion to dense subject-by-edge matrices for downstream analysis.

filter(subject_id: str | Sequence[str] | None = None, base_feature: str | None = None, weight_method: str | None = None, summary_stat: str | None = None) → EdgeData

Return a filtered view of the edge table.

iter_subjects() → Iterator[tuple[str, EdgeData]]

Yield (subject_id, edge_rows_for_subject) using stable_subject_ids() order.

metadata: dict[str, Any]

stable_subject_ids() → list[str]

Subject IDs present in this table, in a defined (stabilized) order.

Order is not arbitrary Parquet row order: IDs from run metadata subject_ids come first when they appear in the table (preserving that list’s order), then any IDs found only in the table, in first-seen column order.

Note

This ordering is intentional for iteration and analysis, but it is not yet guaranteed as a stable public contract across graynet releases or if on-disk layout / metadata conventions change.

table: Table

to_ndarray(subject_ids: Sequence[str], base_feature: str | None = None, weight_method: str | None = None, summary_stat: str | None = None, fill_value: float = nan) → ndarray

Convert edge rows into a dense X matrix.

Rows follow the exact order of subject_ids. Columns follow the run’s node_labels metadata order, using the upper-triangular edge ordering implied by (u, v) pairs.

to_pandas()

Materialize the current table view as a pandas DataFrame.

to_rows() → list[dict[str, Any]]

Materialize the current table view as a list of row dictionaries.

class graynet.results.RoiStatsData(table: Table, metadata: dict[str, Any])

Bases: object

Canonical ROI-statistics table plus run metadata.

filter(subject_id: str | None = None, base_feature: str | None = None, stat_name: str | None = None) → RoiStatsData

metadata: dict[str, Any]

table: Table

to_pandas()

Materialize the current table view as a pandas DataFrame.

class graynet.results.RunData(run_dir: Path, metadata: dict[str, Any], raw_edges: EdgeData | None = None, summary_edges: EdgeData | None = None, roi_stats: RoiStatsData | None = None)

Bases: object

Loaded graynet run directory.

RunData contains run metadata plus any available canonical result tables: raw edges, summary edges, and ROI statistics.

metadata: dict[str, Any]

raw_edges: EdgeData | None = None

roi_stats: RoiStatsData | None = None

run_dir: Path

summary_edges: EdgeData | None = None

graynet.results.export_to_nx(edge_data: EdgeData, metadata: dict[str, Any] | None = None) → Graph

Reconstruct a networkx.Graph from an edge table view.

Centroid metadata is added to nodes when available in run metadata.

graynet.results.get_edge_values(edge_data: EdgeData, subject_id: str | Sequence[str] | None = None, base_feature: str | None = None, weight_method: str | None = None, summary_stat: str | None = None) → EdgeData

Convenience wrapper around EdgeData.filter().

graynet.results.load_run(run_dir) → RunData

Load a graynet 2.0 run directory from disk.

Parameters

run_dirstr or pathlib.Path

Path to a run directory containing run_metadata.json and one or more canonical Parquet tables.