andrey.TemporalStructure#

class andrey.TemporalStructure[source]#

A time-series result: one GraphStructure per lag.

varma_lingam, longitudinal_lingam, pcmci, pcmciplus, and lpcmci return one as StructureOutput.structure; from_lag_graphs and from_time_lag_graphs build one from existing graphs. An edge i -> j in lag(k) means X_i(t-k) -> X_j(t). Lag 0 holds the relations within one time step, and a self-loop at a positive lag is a variable’s effect on its own future. lags lists the lag values, lag_weights holds the coefficients, and summary_graph() merges the lags into one graph over the variables.

A longitudinal_lingam result also has a time axis, one lag stack per occasion: times lists the occasions, at(time, lag) selects a graph, and time_weights holds every occasion’s coefficients. On such a result, lag(k), lag_weights, and summary_graph() describe the final occasion only.

classmethod from_lag_graphs(graphs, *, lags=None, lag_weights=None, lag_weights_ma=None, labels=None)[source]#

Build a time-series result from one graph per lag.

Parameters:

graphs (Sequence[GraphStructure]) – One graph per lag, all over the same nodes. An edge i -> j in the graph for lag k means X_i(t-k) -> X_j(t); a variable’s effect on its own future is a self-loop, M[i, i] = 2, built with allow_self_loops=True.
lags (Sequence[int] | None) – The lag value of each graph, without repeats; gaps are allowed, for example, [0, 1, 12]. None numbers the graphs 0, 1, ..., len(graphs) - 1. lag(k) finds a graph by this value, not by position.
lag_weights (ndarray | None) – Coefficients, one block per graph: lag_weights[k, i, j] is the weight of i -> j in graphs[k]. Stored as a read-only float64 copy.
lag_weights_ma (ndarray | None) – Moving-average coefficients of a VARMA model: lag_weights_ma[m, i, j] is the weight of i -> j at moving-average lag m + 1. Stored as a read-only float64 copy.
labels (tuple[str, ...] | None) – Node names, one per node, each taken as text, str(label); None numbers the nodes from 0.

Returns:

The result, without a time axis.

Return type:

TemporalStructure

Raises:

ValueError – If graphs is empty, lags does not have one value per graph or repeats a value, the graphs differ in node count, labels does not have one entry per node or has two that are equal as text, or a weight array has the wrong shape.

classmethod from_time_lag_graphs(time_graphs, *, lags=None, times=None, time_weights=None, labels=None)[source]#

Build a panel result: one lag stack per occasion.

lag, n_lags, lag_weights, and summary_graph() then describe the final occasion; at and time_weights reach every occasion.

Parameters:

time_graphs (Sequence[Sequence[GraphStructure]]) – One row per occasion, each row a graph per lag in the order of lags; every row has the same length. Use an empty graph for a block that cannot be computed.
lags (Sequence[int] | None) – The lag value of each column, without repeats. None numbers the columns 0, 1, ..., n_lags - 1.
times (Sequence[int] | None) – The occasion value of each row, strictly increasing; gaps are allowed. For example, a panel whose first occasion has no estimate starts at 1. None numbers the rows 0, 1, ..., n_times - 1.
time_weights (ndarray | None) – Coefficients: time_weights[t, k, i, j] is the weight of i -> j in time_graphs[t][k], with NaN for a block that cannot be computed. lag_weights is the last row with NaN replaced by 0.
labels (tuple[str, ...] | None) – Node names, one per node, each taken as text, str(label); None numbers the nodes from 0.

Returns:

The result, with a time axis.

Return type:

TemporalStructure

Raises:

ValueError – If the grid is empty or its rows differ in length, lags or times does not match the grid, lags repeats a value, times is not strictly increasing, the graphs differ in node count, labels does not have one entry per node or has two that are equal as text, or time_weights has the wrong shape.

property n_lags: int#: Number of lags in the stack.

property lags: tuple[int, ...]#: The lag value of each graph, in stack order; lag(k) looks up by this value.

lag(k)[source]#

Select the graph at lag value k (not position).

For a time-carrying structure this is the final occasion’s lag graph (at(times[-1], k)); the full grid is reached via at / times.

Parameters:: k (int) – Lag value to look up, matched against lags (not a positional index).
Returns:: The graph stored at lag k.
Return type:: GraphStructure
Raises:: KeyError – If no graph is stored at lag k.

property lag_weights: ndarray | None#

Coefficients (n_lags, n, n), or None when the result has none.

lag_weights[k, i, j] is the weight of i -> j at lag lags[k]. On a panel result it is the final occasion with NaN replaced by 0; time_weights keeps every occasion.

property lag_weights_ma: ndarray | None#

Moving-average coefficients (q, n, n) from varma_lingam, or None.

lag_weights_ma[m, i, j] is the weight of i -> j at moving-average lag m + 1.

property n_times: int#: Number of absolute occasions in the (time, lag) axis; 0 for a lag-only stack.

property times: tuple[int, ...]#: The explicit occasion index of each (time, lag) row; () when lag-only.

at(time, lag)[source]#

Select the graph at occasion value time and lag value lag.

A lag-only stack has no time axis, so every at call raises there – use lag instead.

Parameters:

time (int) – Occasion value to look up, matched against times (not a positional index).
lag (int) – Lag value to look up, matched against lags (not a positional index).

Returns:

The graph stored at occasion time and lag lag.

Return type:

GraphStructure

Raises:

KeyError – If either time or lag is absent (including any at call on a lag-only stack).

property time_weights: ndarray | None#

Coefficients (n_times, n_lags, n, n), or None without a time axis or weights.

time_weights[t, k, i, j] is the weight of i -> j in at(times[t], lags[k]); NaN marks a block that could not be computed.

summary_graph(*, include_lag0=True)[source]#

Merge the lags into one directed graph over the variables.

i -> j in the summary means i -> j in at least one lag graph; lags_of(i, j) lists those lags. i -> j at one lag and j -> i at another form a 2-cycle, and a self-loop at a positive lag stays a self-loop. Only directed edges are kept; an undirected edge or one with a circle is left out. On a panel result it merges the final occasion’s lags. Each call builds a new graph.

Parameters:: include_lag0 (bool) – Include lag 0, the relations within one time step. False summarizes the effects across time steps only.
Returns:: A kind="digraph" graph; lags_of(i, j) gives the lags of each edge.
Return type:: SummaryGraph