The Results Class

Results network inference

class idtxl.results.ResultsNetworkInference[source]

Store results of network inference.

Provide a container for results of network inference algorithms, e.g., MultivariateTE or Bivariate TE.

Note that for convenience all dictionaries in this class can additionally be accessed using dot-notation:

>>> res_network.settings.cmi_estimator

or

>>> res_network.settings['cmi_estimator'].
Attributes:
settingsdict

settings used for estimation of information theoretic measures and statistical testing

data_propertiesdict

data properties, contains

  • n_nodes : int - total number of nodes in the network

  • n_realisations : int - number of samples available for analysis given the settings (e.g., a high maximum lag used in network inference, results in fewer data points available for estimation)

  • normalised : bool - indicates if data were z-standardised before estimation

targets_analysedlist

list of analysed targets

get_adjacency_matrix(weights, fdr=True)[source]

Return adjacency matrix.

Return adjacency matrix resulting from network inference. The adjacency matrix can either be generated from FDR-corrected results or uncorrected results. Multiple options for the weight are available.

Args:
weightsstr

can either be

  • ‘max_te_lag’: the weights represent the source -> target

    lag corresponding to the maximum tranfer entropy value (see documentation for method get_target_delays for details)

  • ‘max_p_lag’: the weights represent the source -> target

    lag corresponding to the maximum p-value (see documentation for method get_target_delays for details)

  • ‘vars_count’: the weights represent the number of

    statistically-significant source -> target lags

  • ‘binary’: return unweighted adjacency matrix with binary

    entries

    • 1 = significant information transfer;

    • 0 = no significant information transfer.

fdrbool [optional]

return FDR-corrected results (default=True)

Returns:

AdjacencyMatrix instance

get_source_variables(fdr=True)[source]

Return list of inferred past source variables for all targets.

Return a list of dictionaries, where each dictionary holds the selected past source variables for one analysed target. The list may be used as and input to significant subgraph mining in the postprocessing module.

Args:
fdrbool [optional]

return FDR-corrected results (default=True)

Returns:
list of dicts

selected past source variables for each target

get_target_delays(target, criterion='max_te', fdr=True)[source]

Return list of information-transfer delays for a given target.

Return a list of information-transfer delays for a given target. Information-transfer delays are determined by the lag of the variable in a source past that has the highest information transfer into the target process. There are two ways of identifying the variable with maximum information transfer:

  1. use the variable with the highest absolute TE value (highest information transfer),

  2. use the variable with the smallest p-value (highest statistical significance).

Args:
targetint

target index

criterionstr [optional]

use maximum TE value (‘max_te’) or p-value (‘max_p’) to determine the source-target delay (default=’max_te’)

fdrbool [optional]

return FDR-corrected results (default=True)

Returns:
numpy array

information-transfer delays for each source

print_edge_list(weights, fdr=True)[source]

Print results of network inference to console.

Print edge list resulting from network inference to console. Output may look like this:

>>> 0 -> 1, max_te_lag = 2
>>> 0 -> 2, max_te_lag = 3
>>> 0 -> 3, max_te_lag = 2
>>> 3 -> 4, max_te_lag = 1
>>> 4 -> 3, max_te_lag = 1

The edge list can either be generated from FDR-corrected results or uncorrected results. Multiple options for the weight are available (see documentation of method get_adjacency_matrix for details).

Args:
weightsstr

link weights (see documentation of method get_adjacency_matrix for details)

fdrbool [optional]

return FDR-corrected results (default=True)

Results network comparison

class idtxl.results.ResultsNetworkComparison[source]

Store results of network comparison.

Provide a container for results of network comparison algorithms.

Note that for convenience all dictionaries in this class can additionally be accessed using dot-notation: res_network.settings.cmi_estimator or res_network.settings[‘cmi_estimator’].

Attributes:
settingsdict

settings used for estimation of information theoretic measures and statistical testing

data_propertiesdict

data properties, contains

  • n_nodes : int - total number of nodes in the network

  • n_realisations : int - number of samples available for analysis given the settings (e.g., a high maximum lag used in network inference, results in fewer data points available for estimation)

  • normalised : bool - indicates if data were z-standardised before the estimation

surrogate_distributiondict

for each target, surrogate distributions used for testing of each link into the target

targets_analysedlist

list of analysed targets

abdict

for each target, list of comparison results for all links into the target; True if link in condition A > link in condition B

pvaldict

for each target, list of p-values for all compared links

cmi_diff_absdict

for each target, list of absolute difference in interaction measure for all compared links

data_propertiesdict

information regarding the data used for analysis

settingsdict

settings used for comparison

get_adjacency_matrix(weights='comparison')[source]

Return adjacency matrix.

Return adjacency matrix resulting from network inference. Multiple options for the weights are available.

Args:
weightsstr [optional]

can either be

  • ‘union’: all links in the union network, i.e., all links that were tested for a difference

or return information for links with a significant difference

  • ‘comparison’: True for links with a significant difference in

    inferred effective connectivity (default)

  • ‘pvalue’: absolute differences in inferred effective

    connectivity for significant links

  • ‘diff_abs’: absolute difference

Returns:

AdjacencyMatrix instance

get_single_target(target)[source]

Return results for a single target in the network.

Results for single targets include for each target

  • sources : list of ints - list of sources inferred for the current target (union of sources from both data sets entering the comparison)

  • selected_vars_sources : list of tuples - source variables with significant information about the current value (union of both conditions)

  • selected_vars_target : list of tuples - target variables with significant information about the current value (union of both conditions)

Args:
targetint

target id

Returns:
dict

Results for single target. Note that for convenience dictionary entries can either be accessed via keywords (result[‘selected_vars_sources’]) or via dot-notation (result.selected_vars_sources).

get_target_sources(target)[source]

Return list of sources (parents) for given target.

Args:
targetint

target index

print_edge_list(weights='comparison')[source]

Print results of network comparison to console.

Print results of network comparison to console. Output looks like this:

>>> 0 -> 1, diff_abs = 0.2
>>> 0 -> 2, diff_abs = 0.5
>>> 0 -> 3, diff_abs = 0.7
>>> 3 -> 4, diff_abs = 1.3
>>> 4 -> 3, diff_abs = 0.4

indicating differences in the network inference measure for a link source -> target.

Args:
weightsstr [optional]

weights for the adjacency matrix (see documentation of method get_adjacency_matrix for details)

Results node dynamics

class idtxl.results.ResultsSingleProcessAnalysis[source]

Store results of single process analysis.

Provide a container for the results of algorithms for the analysis of individual processes (nodes) in a multivariate stochastic process, e.g., estimation of active information storage.

Note that for convenience all dictionaries in this class can additionally be accessed using dot-notation:

>>> res_network.settings.cmi_estimator

or

>>> res_network.settings['cmi_estimator'].
Attributes:
settingsdict

settings used for estimation of information theoretic measures and statistical testing

data_propertiesdict

data properties, contains

  • n_nodes : int - total number of nodes in the network

  • n_realisations : int - number of samples available for analysis given the settings (e.g., a high maximum lag used in network inference, results in fewer data points available for estimation)

  • normalised : bool - indicates if data were z-standardised before estimation

processes_analysedlist

list of analysed processes

get_significant_processes(fdr=True)[source]

Return statistically-significant processes.

Indicates for each process whether AIS is statistically significant (equivalent to the adjacency matrix returned for network inference)

Args:
fdrbool [optional]

return FDR-corrected results, see documentation of network inference algorithms and stats.network_fdr (default=True)

Returns:
numpy array

Statistical significance for each process

get_single_process(process, fdr=True)[source]

Return results for a single process in the network.

Return results for individual processes, contains for each process

  • ais : float - AIS-value for current process

  • ais_pval : float - p-value of AIS estimate

  • ais_signbool - significance of AIS estimate wrt. to the

    alpha_mi specified in the settings

  • selected_varlist of tuples - variables with significant

    information about the current value of the process that have been added to the processes past state, a variable is described by the index of the process in the data and its lag in samples

  • current_valuetuple - current value used for analysis,

    described by target and sample index in the data

Setting fdr to True returns FDR-corrected results (Benjamini, 1995).

Args:
processint

process id

fdrbool [optional]

return FDR-corrected results, see documentation of network inference algorithms and stats.network_fdr (default=True)

Returns:
dict

results for single process. Note that for convenience dictionary entries can either be accessed via keywords (result[‘selected_vars’]) or via dot-notation (result.selected_vars).

property processes_analysed

Get index of the current_value.

class idtxl.results.ResultsPID(n_nodes, n_realisations, normalised)[source]

Store results of Partial Information Decomposition (PID) analysis.

Provide a container for results of Partial Information Decomposition (PID) algorithms.

Note that for convenience all dictionaries in this class can additionally be accessed using dot-notation:

>>> res_pid._single_target[2].source_1

or

>>> res_pid._single_target[2].['source_1'].
Attributes:
settingsdict

settings used for estimation of information theoretic measures and statistical testing

data_propertiesdict

data properties, contains

  • n_nodes : int - total number of nodes in the network

  • n_realisations : int - number of samples available for analysis given the settings (e.g., a high maximum lag used in network inference, results in fewer data points available for estimation)

  • normalised : bool - indicates if data were z-standardised before the estimation

targets_analysedlist

list of analysed targets

get_single_target(target)[source]

Return results for a single target in the network.

Results for single targets include for each target

  • source_1 : tuple - source variable 1

  • source_2 : tuple - source variable 2

  • selected_vars_sources : list of tuples - source variables used in PID estimation

  • s1_unq : float - unique information in source 1

  • s2_unq : float - unique information in source 2

  • syn_s1_s2 : float - synergistic information in sources 1 and 2

  • shd_s1_s2 : float - shared information in sources 1 and 2

  • current_value : tuple - current value used for analysis, described by target and sample index in the data

  • [estimator-specific settings]

Args:
targetint

target id

Returns:
dict

Results for single target. Note that for convenience dictionary entries can either be accessed via keywords (result[‘selected_vars_sources’]) or via dot-notation (result.selected_vars_sources).

class idtxl.results.ResultsMultivariatePID(n_nodes, n_realisations, normalised)[source]

Store results of Multivariate Partial Information Decomposition (PID) analysis.

Provide a container for results of Multivariate Partial Information Decomposition (PID) algorithms.

Note that for convenience all dictionaries in this class can additionally be accessed using dot-notation:

>>> res_pid._single_target[2].source_1

or

>>> res_pid._single_target[2].['source_1'].
Attributes:
settingsdict

settings used for estimation of information theoretic measures and statistical testing

data_propertiesdict

data properties, contains

  • n_nodes : int - total number of nodes in the network

  • n_realisations : int - number of samples available for analysis given the settings (e.g., a high maximum lag used in network inference, results in fewer data points available for estimation)

  • normalised : bool - indicates if data were z-standardised before the estimation

targets_analysedlist

list of analysed targets

get_single_target(target)[source]

Return results for a single target in the network.

Results for single targets include for each target

  • source_i : tuple - source variable i

  • selected_vars_sources : list of tuples - source variables used in PID estimation

  • avg : dict - avg pid {alpha -> float} where alpha is a redundancy lattice node

  • ptw : dict of dicts - ptw pid {rlz -> {alpha -> float} } where rlz is a single realisation of the random variables and alpha is a redundancy lattice node

  • current_value : tuple - current value used for analysis, described by target and sample index in the data

  • [estimator-specific settings]

Args:
targetint

target id

Returns:
dict

Results for single target. Note that for convenience dictionary entries can either be accessed via keywords (result[‘selected_vars_sources’]) or via dot-notation (result.selected_vars_sources).

class idtxl.results.ResultsSingleProcessRudelt(processes)[source]

Store results of single process analysis.

Provides a container for the results Rudelt optimization algorithm. To obtain results for individual processes, call the .get_single_process() method (see docstring for details).

Note that for convenience all dictionaries in this class can additionally be accessed using dot-notation:

>>> res_network.settings.estimation_method

or

>>> res_network.settings['estimation_method'].
Attributes:
settingsdict

settings used for estimation of information theoretic measures

data_propertiesdict
data properties, contains

  • n_processes : int - total number of processes analysed

processes_analysedlist

list of analysed processes

get_single_process(process)[source]

Return results for a single process.

Return results for individual processes, contains for each process

Args:
processint

process id

Returns:
dict

results for single process. Note that for convenience dictionary entries can either be accessed via keywords (result[‘selected_vars’]) or via dot-notation (result.selected_vars). Contains keys

  • Processint

    Process that was optimized

  • estimation_methodString

    Estimation method that was used for optimization

  • T_Dfloat

    Estimated optimal value for the temporal depth TD

  • tau_R :

    Information timescale tau_R, a characteristic timescale of history dependence similar to an autocorrelation time.

  • R_totfloat

    Estimated value for the total history dependence Rtot,

  • AIS_totfloat

    Estimated value for the total active information storage

  • opt_number_of_bins_dint

    Number of bins d for the embedding that yields (R̂tot ,T̂D)

  • opt_scaling_kint

    Scaling exponent κ for the embedding that yields (R̂tot , T̂D)

  • opt_first_bin_sizeint

    Size of the first bin τ1 for the embedding that yields (R̂tot , T̂D ),

  • history_dependencearray with floating-point values

    Estimated history dependence for each embedding

  • firing_ratefloat

    Firing rate of the neuron/ spike train

  • recording_lengthfloat

    Length of the recording (in seconds)

  • H_spikingfloat

    Entropy of the spike times

if analyse_auto_MI was set to True additionally:

  • auto_MIdict

    numpy array of MI values for each delay

  • auto_MI_delayslist of int

    list of delays depending on the given auto_MI_bin_sizes and auto_MI_max_delay

property processes_analysed

Get index of the current_value.