Frontend

The module frontend provides predefined configurations of the modular GLDF backend. This includes general purpose hyper-parameter sets hyperparameters.

Preconfigured Execution

run_hccd_temporal_regimes(data: ndarray, regimes_are_large: bool = True, alpha: float = 0.01, alpha_pc1: float = 0.1, allow_latent_confounding: bool = False, tau_max: int = 1) → Result

Run preconfigured HCCD for temporal regimes. Uses PCMCI+ [R20] as default CD-algorithm.

Parameters:

  • data (np.ndarray) – observed data

  • regimes_are_large (bool, optional) – use hyper-parameter sets optimized for large regimes (True is recommended, especially for time-series data), defaults to True

  • alpha (float, optional) – confidence-parameter \(\alpha\) for hypothesis-tests, defaults to 0.01

  • alpha_pc1 (float, optional) – confidence-parameter \(\alpha\) for independence-tests in the PC1-phase, defaults to 0.1

  • allow_latent_confounding (bool, optional) – consider the possibility of latent confounding by using LPCMCI [GR20] (this implementation is currently experimental and regime-discovery may have low recall, see [RR25]), defaults to False

  • tau_max (int, optional) – maximum lag in considered time-window, defaults to 1

Returns:

Structured HCCD result.

Return type:

Result

run_hccd_spatial_regimes(data: ndarray, regimes_are_large: bool = True, alpha: float = 0.01) → Result

Run preconfigured HCCD for spatial (2 dimensional, non-time-series) data. Uses FCI [SGS01] as default CD-algorithm.

Parameters:

  • data (np.ndarray) – observed data

  • regimes_are_large (bool, optional) – use hyper-parameter sets optimized for large regimes (True is recommended, especially for time-series data), defaults to True

  • alpha (float, optional) – confidence-parameter \(\alpha\) for hypothesis-tests, defaults to 0.01

Returns:

Structured HCCD result.

Return type:

Result

Structured Output

Running HCCD through the frontend will produce structured results that bundle the output of the backend with convenience functions for post-processing (in particular approximate indicator resolution) and plotting.

class Result

Structured result presenting output obtained from HCCD.

__init__(hccd_result: IPresentResult, indicator_resolution: IResolveRegimeStructure | None = None)

Construct from backend-result.

Parameters:
var_names: list[str]

Write to this field before plotting to provide variable-names.

union_graph() → graph_t

Get the estimated union-graph.

Returns:

union-graph (tigramite format)

Return type:

graph_t

state_graphs() → list[graph_t]

Get state-specific graphs.

Returns:

list of state-specific graphs (tigramite format)

Return type:

list[graph_t]

model_indicators() → list[ResolvableModelIndicator]

Get structured result representing discovered model-indicators (changing links).

Returns:

list of model indicators

Return type:

list[ResolvableModelIndicator]

plot_labeled_union_graph(**args)

Plot the (color-)labeled union-graph.

Keyword arguments are forwarded to (a modified version of) tigramite.plotting.plot_graph().

See also

Uses colors from color_scheme.

class ResolvableModelIndicator

Structured result presenting results about a particular model-indicator.

__init__(indicator_resolution: IResolveRegimeStructure, model_indicator, assigned_color)

Construct a structured result.

Parameters:

  • indicator_resolution (IResolveRegimeStructure) – Indicator resolution strategy.

  • model_indicator (state-space construction specific) – underlying model-indicator

  • assigned_color (str) – color “label”

The underlying undirected link.

Returns:

the changing link in the model

Return type:

tuple[data_management.var_index,data_management.var_index]

resolve() → ndarray | dict[str, ndarray]

Approximately resolve the indicator relative to index-space.

Returns:

resolved indicator (possibly as dictionary “label”: values)

Return type:

np.ndarray|dict[str, np.ndarray]

plot_resolution() → None

Generate and plot an approximate resolution of the indicator in index-space.

Raises:

NotImplementedError – Currently only supports 1D and 2D data.

By default the union-graph is color-labeled, using colors from:

color_scheme = ['blue', 'orange', 'cyan', 'red', 'green', 'darkgray']

These colors are used (in order, repeating) in labeled union graphs as “labels”.

Customized Configurations

Basic configurations of the backend can be described through the ConfigureHCCD class. The configurations of run_hccd_temporal_regimes() and run_hccd_spatial_regimes() (see above) are available as templates through:

configure_hccd_temporal_regimes(regimes_are_large: bool = True, alpha: float = 0.01, alpha_pc1: float = 0.1, allow_latent_confounding: bool = False, tau_max: int = 1) → ConfigureHCCD

Get standard-configuration of HCCD for temporal regimes. Uses PCMCI+ [R20] as default CD-algorithm.

Parameters:

  • regimes_are_large (bool, optional) – use hyper-parameter sets optimized for large regimes (True is recommended, especially for time-series data), defaults to True

  • alpha (float, optional) – confidence-parameter \(\alpha\) for hypothesis-tests, defaults to 0.01

  • alpha_pc1 (float, optional) – confidence-parameter \(\alpha\) for independence-tests in the PC1-phase, defaults to 0.1

  • allow_latent_confounding (bool, optional) – consider the possibility of latent confounding by using LPCMCI [GR20] (this implementation is currently experimental and regime-discovery may have low recall, see [RR25]), defaults to False

  • tau_max (int, optional) – maximum lag in considered time-window, defaults to 1

Returns:

HCCD configuration used by run_hccd_temporal_regimes().

Return type:

ConfigureHCCD

configure_hccd_spatial_regimes(regimes_are_large: bool = True, alpha: float = 0.01) → ConfigureHCCD

Get standard-configuration of HCCD for spatial (2 dimensional, non-time-series) data. Uses FCI [SGS01] as default CD-algorithm.

Parameters:

  • regimes_are_large (bool, optional) – use hyper-parameter sets optimized for large regimes (True is recommended, especially for time-series data), defaults to True

  • alpha (float, optional) – confidence-parameter \(\alpha\) for hypothesis-tests, defaults to 0.01

Returns:

HCCD configuration used by run_hccd_spatial_regimes().

Return type:

ConfigureHCCD

Besides the members of a ConfigureHCCD instance, also its methods of the form “get_something” are intended to be overwritten (externally by monkey-patching or by defining a derived class). Running the configuration through its ConfigureHCCD.run() method automatically ensures these getters are executed exactely once and cached.

class ConfigureHCCD

Bases: Config

Modular configuration of backend for HCCD.

is_timeseries: bool

is time-series data

alpha: float = 0.01

confidence-parameter \(\alpha\) for hypothesis-tests

min_regime_fraction: float = 0.15

minimum regime-fraction to consider

indicator_resolution_granularity: int = 100

granularity used for post-process approximate indicator resultion

regimes_are_large: bool = True

use hyper-parameter sets optimized for large regimes (True is recommended, especially for time-series data)

tau_max: int = 1

maximum lag to use for time-series algorithms (ignored for IID algorithms)

alpha_pc1: float = 0.1

confidence-parameter \(\alpha\) for independence-tests in PC1-phase of PCMCI-family algorithms.

get_data_manager() → IManageData
get_backend_config() → ConfigureBackend
get_backend() → IProvideIndependenceAtoms
get_mci_backend() → IProvideIndependenceAtoms
alpha_homogeneity_pc1() → float
get_pc1_backend() → IProvideIndependenceAtoms
get_transitionable_backend() → IndependenceAtoms_TimeSeries
get_universal_cd() → abstract_cd_t
get_state_space_construction() → IConstructStateSpace
get_controller() → Controller
get_cit() → ITestCI
get_indicator_resultion() → IResolveRegimeStructure
run(data: ndarray) → Result
__init__(is_timeseries: bool, alpha: float = 0.01, min_regime_fraction: float = 0.15, indicator_resolution_granularity: int = 100, regimes_are_large: bool = True, tau_max: int = 1, alpha_pc1: float = 0.1, _data: ndarray = None) → None

Internally, this uses one or multiple (for PCMCI-family algorithms) backends configured similarly through:

class ConfigureBackend

Bases: Config

Modular configuration of extended independence atom backend.

data_manager: IManageData
alpha: float = 0.01
alpha_homogeneity: float = 0.01
regimes_are_large: bool = True
min_regime_fraction: float = 0.15
enable_weak_test: bool = True
enable_implication_test: bool = True
get_cit() → ITestCI
cit_analytic_quantile_estimate() → IProvideAnalyticQuantilesForCIT
cit_variance_estimate() → IProvideVarianceForCIT
get_homogeneity_test() → ITestHomogeneity
get_weak_test() → ITestWeakRegime
get_mcit() → ITestMarkedCI
get_implication_test() → ITestIndicatorImplications
get_backend() → IProvideIndependenceAtoms
__init__(data_manager: IManageData, alpha: float = 0.01, alpha_homogeneity: float = 0.01, regimes_are_large: bool = True, min_regime_fraction: float = 0.15, enable_weak_test: bool = True, enable_implication_test: bool = True) → None

These configuration-classes are based on Config, which provides convenience features for making produced values unique (execute getters at most once).

class Config

Helper for setting up configuration-objects. Calling finalize() will return a copy which is modified such as to execute each method prefixed with ‘get_’ once, caching the result.

finalize()

Modify methods prefixed by ‘get_’ to be executed at most once (on first invokation) and cached for further calls.

Hyper-Parameter Sets

If substantial prior knowledge concering the regime-structure is available the user may want to provide their own hyper-parameter sets as specified in Interfaces for Hyper-Parameter Sets. For generic cases and a partial correlation test, we provide two preconfigured hyper-parameter sets (one for generic regimes, one for large regimes; numerical experiments suggest that especially for time-series data the one for large regimes currently often leads to better results). These are available in hyperparams. Details can be found in §D.3.4 and §D.4.6 of [RR25].

class Hyperparams_HomogeneityBinomial_ParCorr

Bases: IProvideHyperparamsForBinomial

Helper to configure standard hyper-parameter sets for binomial homogeneity test when using partial correlation.

__init__(alpha_error_control: float = 0.05, min_block_count: int = 5, min_effective_sample_count: int = 5, regimes_are_large: bool = True)

Construct Hyper-parameter set for given parameters.

Parameters:

  • alpha_error_control (float, optional) – Error-control target \(\alpha\), defaults to 0.05

  • min_block_count (int, optional) – Pick block-size to ensure minimum number of blocks, defaults to 5

  • min_effective_sample_count (int, optional) – Pick block-size to ensure minimum effective sample-size per block (for partial correlation), defaults to 5

  • regimes_are_large (bool, optional) – Consider hyper-parameters for large regimes, defaults to True

cache: dict[(<class 'int'>, <class 'int'>), ~GLDF.data_processing.IProvideHyperparamsForBinomial.Hyperparams]

Set to None to disable cache.

hyperparams_for_binomial(N: int, dim_Z: int) → Hyperparams

Implements functionality of interface IProvideHyperparamsForBinomial.

Supply hyper-parameters for the binomial homogeneity-test for the given setup.

Parameters:

  • N (int) – sample-size

  • dim_Z (int) – size of conditioning set

Returns:

The hyper-parameters to use.

Return type:

IProvideHyperparamsForBinomial.Hyperparams

static get_opt_beta(alpha_homogeneity_err_control_requested: float, block_count: int, beta_start_value: float = 0.1) → tuple[float, int]

The binomial test rejects at an integer count. To target a specific error-rate \(\alpha\), this function modifies the quantile \(\beta\)-start-value such that that for the returned \(\beta'\geq\beta\) will realize the error-rate \(\alpha\) for the (also returned) integer cutoff-count.

Parameters:

  • alpha_homogeneity_err_control_requested (float) – Requrested error-control \(\alpha\).

  • block_count (int) – The total number of blocks.

  • beta_start_value (float, optional) – Initial value for \(\beta\), defaults to 0.1

Raises:

RuntimeWarning – The solution for \(\beta'\) is found numerically. In case of convergence problems, an exception is raised.

Returns:

Tuple (\(\beta'\), cutoff-count).

Return type:

tuple[float, int]

get_opt_blocksize(N: int, dim_Z: int) → int

Get heuristic hyper-parameter choice for block-size \(B\).

Parameters:

  • N (int) – Sample-size.

  • dim_Z (int) – Conditioning-set size.

Returns:

Recommended block-size to use.

Return type:

int

compute_for_fixed_sample_count(N: int, dim_Z: int) → Hyperparams

Obtain actual runtime parameters. Typically called only by implementation of the corresponding marked-independence stage.

Parameters:

  • N (int) – Sample-size.

  • dim_Z (int) – Conditioning-set size.

Returns:

Execution-parameters for the corresponding algorithm.

Return type:

dpl.IProvideHyperparamsForBinomial.Hyperparams

class Hyperparams_WeakInterval_ParCorr

Bases: IProvideHyperparamsForAcceptanceInterval

Helper to configure standard hyper-parameter sets for acceptance-interval weak-regime test when using partial correlation.

__init__(alpha=0.05, regimes_are_large=True)

Configure hyper-parameters set based on given parameters.

Parameters:

  • alpha (float, optional) – Error-control target \(\alpha\), defaults to 0.05

  • regimes_are_large (bool, optional) – Consider hyper-parameters for large regimes, defaults to True

hyperparams_for_acceptance_interval(N: int, dim_Z: int) → Hyperparams

Implements functionality of interface IProvideHyperparamsForAcceptanceInterval.

Supply hyper-parameters for acceptance-interval tests for given setup.

Parameters:

  • N (int) – sample-size

  • dim_Z (int) – size of conditioning set

Returns:

The hyper-parameters to use.

Return type:

IProvideHyperparamsForAcceptanceInterval.Hyperparams

get_opt_blocksize(N: int, dim_Z: int) → int

Heuristic choice of hyper-parameter for block-size \(B\).

Parameters:

  • N (int) – Sample-size.

  • dim_Z (int) – Conditioning-set size.

Returns:

Heuristic block-size choice.

Return type:

int

get_opt_cutoff(N: int, dim_Z: int) → float

Heuristic choice of hyper-parameter for cutoff \(c\).

Parameters:

  • N (int) – Sample-size.

  • dim_Z (int) – Conditioning-set size.

Returns:

Heuristic cutoff choice.

Return type:

float

get_for_fixed_sample_count(N: int, dim_Z: int) → Hyperparams

Obtain actual runtime parameters. Typically called only by implementation of the corresponding marked-independence stage.

Parameters:

  • N (int) – Sample-size.

  • dim_Z (int) – Size of the conditioning set.

Returns:

Execution-parameters for the corresponding algorithm.

Return type:

dpl.IProvideHyperparamsForAcceptanceInterval.Hyperparams

Independence Atom Backends

While data_management and data_processing are implemented modular and independent of each other, the Composition Layer accesses only data_processing primitives directly (see Independence Atom Backend). Such a independence-atom backend is provided in independence_atoms (for IID and time-series respectively) by:

class IndependenceAtoms_Backend

Bases: IProvideIndependenceAtoms

Integrate data-provider with mCIT and implication-testing into a independence-atom backend for use in hccd.

__init__(data_manager: IManageData, m_cit: ITestMarkedCI, implication_test: ITestIndicatorImplications = None)

Consstruct from data-manager, mCIT and implication-test.

Parameters:
marked_independence(ci: CI_Identifier) → Result

Implements functionality of interface IProvideIndependenceAtoms.

Provide a marked-independence statement.

See also

Provides functionality described by TestMarkedCI.marked_independence but with actual data made opaque.

Parameters:

ci (CI_Identifier) – conditional independence to test

Returns:

marked CIT result

Return type:

ITestMarkedCI.Result

regime_implication(lhs: list[CI_Identifier], rhs: CI_Identifier) → bool

Implements functionality of interface IProvideIndependenceAtoms.

Provide a regime-implication statement.

See also

Provides functionality described by ITestIndicatorImplications.is_implied_regime but with actual data made opaque.

Parameters:
Returns:

test-result for truth-value of the implication

Return type:

bool

found_globally_independent_for_some_Z(undirected_link: tuple) → bool

Implements functionality of interface IProvideIndependenceAtoms.

Provide information about wheter among the test-results provided so far, there was a CIT on the specified undirected_link for any conditioning set Z which was reported globally independent.

Parameters:

undirected_link (tuple) – the undirected link on which to check for independent CIT-results

Returns:

Truth-value about wheter any globally independent outcome was encountered on this link.

Return type:

bool

class IndependenceAtoms_TimeSeries

Bases: IProvideIndependenceAtoms, IHandleExplicitTransitionToMCI

Dual-phase/transitionable backend to account for different configurations in PC1 and MCI phases of PCMCI-family algorithms.

__init__(independence_atoms_pc1: IProvideIndependenceAtoms, independence_atoms_mci: IProvideIndependenceAtoms)

Construct from two separate backends for PC1 and MCI phases.

Parameters:
marked_independence(ci: CI_Identifier_TimeSeries) → Result

Implements functionality of interface IProvideIndependenceAtoms.

Provide a marked-independence statement.

See also

Provides functionality described by TestMarkedCI.marked_independence but with actual data made opaque.

Parameters:

ci (CI_Identifier) – conditional independence to test

Returns:

marked CIT result

Return type:

ITestMarkedCI.Result

regime_implication(lhs: list[CI_Identifier_TimeSeries], rhs: CI_Identifier_TimeSeries) → bool

Implements functionality of interface IProvideIndependenceAtoms.

Provide a regime-implication statement.

See also

Provides functionality described by ITestIndicatorImplications.is_implied_regime but with actual data made opaque.

Parameters:
Returns:

test-result for truth-value of the implication

Return type:

bool

found_globally_independent_for_some_Z(undirected_link: tuple) → bool

Implements functionality of interface IProvideIndependenceAtoms.

Provide information about wheter among the test-results provided so far, there was a CIT on the specified undirected_link for any conditioning set Z which was reported globally independent.

Parameters:

undirected_link (tuple) – the undirected link on which to check for independent CIT-results

Returns:

Truth-value about wheter any globally independent outcome was encountered on this link.

Return type:

bool

enter_pc1() → None

Implements functionality of interface IHandleExplicitTransitionToMCI.

Callback for notification that the underlying cd-algorithm has (re)entered (what is considered by the controller) to be part of the PC1-phase.

enter_mci() → None

Implements functionality of interface IHandleExplicitTransitionToMCI.

Callback for notification that the underlying cd-algorithm has (re)entered (what is considered by the controller) to be part of the MCI-phase.