andrey.StructureOutput

class andrey.StructureOutput

The result of every structure-learning method: the learned graph plus run details.

Each method returns one (multi_group_direct_lingam returns one per group). structure holds the graph, a GraphStructure or TemporalStructure. The other fields depend on the method, and each method’s Returns section lists them: ordering is a causal order, weighted_adjacency holds edge weights, and metadata holds values such as the algorithm name and score. print(out) shows the graph kind, the edges, the order, and the metadata. save writes the result to a file and load reads it back. The result is read-only.

classmethod new(structure, *, ordering=None, weighted_adjacency=None, metadata=None)

Build a result from a structure and optional run details.

Use it to wrap a graph from custom code so that it prints, saves, and loads like a method’s result.

Parameters:

• structure (Structure) – The graph: a GraphStructure or TemporalStructure.

• ordering (tuple[int, ...] | list[int] | None) – Causal order as node indices, causes first; a permutation of range(structure.n_nodes).

• weighted_adjacency (ndarray | None) – Edge weights, W[i, j] for i -> j, stored sparsely. None gives no weights.

• metadata (Mapping[str, str | bool | int | float | None | list | dict] | None) – Run values by name. Keys are strings; values are str, bool, int, float, None, or lists and dicts of them.

Returns:

The result.

Return type:

StructureOutput

Raises:

• TypeError – If metadata has a non-string key or a value of another type, such as a tuple, a set, or a NumPy array or integer.

• ValueError – If weighted_adjacency is not (n_nodes, n_nodes), ordering is not a permutation of range(n_nodes), or a graph in structure fails validate().

property structure: Structure

a GraphStructure, or a TemporalStructure for time series.

Type:

The learned graph

property ordering: tuple[int, ...] | None

Causal order as node indices, causes first; None unless the method finds one.

Set by direct_lingam, ica_lingam, multi_group_direct_lingam, and varma_lingam (the order within one time step).

property metadata: Mapping[str, str | bool | int | float | None | list | dict]

Method-specific values such as algorithm and score, as a read-only mapping.

property weighted_adjacency: ndarray | None

Edge weights as a new dense (n_nodes, n_nodes) array, or None without weights.

W[i, j] is the weight of i -> j, so rows are causes: the transpose of B in x = Bx + e. Set by calm, direct_lingam, ica_lingam, and multi_group_direct_lingam; a time-series result keeps its weights in structure.lag_weights.

to_scipy_sparse(*, weights=True)

Return the edge weights as a scipy.sparse.csr_array, without a dense array.

Parameters:

weights (bool) – Must be True. For the graph’s endpoint marks, call structure.to_scipy_sparse().

Returns:

The weighted_adjacency values: entry [i, j] is the weight of i -> j.

Return type:

csr_array

Raises:

ValueError – If weights is False, or the method gives no edge weights.

save(path, *, fmt='json')

Write the result to path; StructureOutput.load reads it back.

Parameters:

• path (str | PathLike) – Destination file. With fmt="npz" the path must end in .npz.

• fmt (Literal['json', 'npz']) – File format. "json" holds a graph or time-series result; "npz", a NumPy archive, holds a GraphStructure result only.

Raises:

• ValueError – If fmt is neither "json" nor "npz", or fmt="npz" and path does not end in .npz.

• NotImplementedError – If fmt="npz" and the structure is a TemporalStructure.

• TypeError – If the structure is a SummaryGraph; save the TemporalStructure it came from.

Notes

Return type:

None

The JSON file is one object with sorted keys. format_version is 0, or 1 for a panel result that keeps its occasions; load rejects any other version. structure_type is "graph" or "temporal". A graph is stored as its sparse arrays indptr, indices, and marks, beside kind, n_nodes, labels, node_types, ordering, weighted, and metadata; a temporal result stores one such graph per lag under lags. The npz file holds the same arrays, with the other fields as one JSON string, and load reads it without pickle, so loading a file never runs code from it.

classmethod load(path)

Read a result written by save.

After out.save(path), StructureOutput.load(path) == out.

Parameters:

path (str | PathLike) – File to read. A .npz suffix reads the npz format; any other suffix reads JSON.

Returns:

The saved result.

Return type:

StructureOutput

Raises:

• FileNotFoundError – If path does not exist.

• ValueError – If the file has an unsupported format version or an unknown structure type, or holds a result that new would reject.