API Reference
All functions are importable directly from the ouxinfo namespace.
Core Estimators
Shannon Entropy
ouxinfo.shannon_entropy()
builtin
Compute Shannon entropy using the Kozachenko-Leonenko estimator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, dim)
|
Input data. Must be float64. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
float
|
Shannon entropy in nats. |
Notes
Uses the Kozachenko-Leonenko k-NN estimator with Chebyshev metric. See: Kozachenko & Leonenko (1987), Kraskov et al. (2004).
KL Divergence
ouxinfo.KL_div()
builtin
Compute Kullback-Leibler divergence using the Pérez-Cruz estimator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, dim)
|
Samples from distribution X. Must be float64. |
required |
Y
|
ndarray of shape (M, dim)
|
Samples from distribution Y. Must be float64. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
float
|
KL divergence D_KL(X || Y) in nats. |
Notes
Uses the k-NN estimator of Pérez-Cruz (2008).
Mutual Information
ouxinfo.mutual_info()
builtin
Compute mutual information using the Kraskov-Stögbauer-Grassberger (KSG) estimator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, dim_x)
|
First dataset. Must be float64. |
required |
Y
|
ndarray of shape (N, dim_y)
|
Second dataset. Must be float64. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
Thei
|
int
|
Length of Theiler window to exclude temporal neighbors. Default 0. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
float
|
Mutual information I(X; Y) in nats. |
Notes
Uses KSG estimator type 1. See: Kraskov et al. (2004).
Conditional Mutual Information
ouxinfo.conditional_mutual_info()
builtin
Compute conditional mutual information using the KSG estimator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, dim_x)
|
First dataset. Must be float64. |
required |
Y
|
ndarray of shape (N, dim_y)
|
Second dataset. Must be float64. |
required |
Z
|
ndarray of shape (N, dim_z)
|
Conditioning dataset. Must be float64. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
float
|
Conditional mutual information I(X; Y | Z) in nats. |
Notes
Uses KSG estimator type 1. See: Kraskov et al. (2004).
Transfer Entropy
Transfer Entropy
ouxinfo.transfer_entropy()
builtin
Compute transfer entropy from X to Y using the KSG estimator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, dim)
|
Source time series. Must be float64. |
required |
Y
|
ndarray of shape (N, dim)
|
Target time series. Must be float64. |
required |
tau
|
int
|
Time delay (in samples). Default 1. |
required |
m
|
int
|
Embedding dimension for Y. Default 1. |
required |
lag
|
int
|
Time lag for embedding. Default 1. |
required |
dt
|
float
|
Physical time step. Default 1.0. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
trial
|
int
|
Number of surrogate trials for significance testing. Default 0. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
float
|
Transfer entropy TE(X -> Y) in nats per dt. |
Notes
Computed as conditional mutual information: TE = I(Y_{t+tau}; X_t^(m) | Y_t^(m)). See: Schreiber (2000), Kraskov et al. (2004).
Backward Transfer Entropy
ouxinfo.backward_transfer_entropy(x, y, tau=1, m=1, lag=1, dt=1.0, k=5, trial=0)
Compute backward transfer entropy from x to y.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
ndarray of shape (N, dim)
|
Source time series. Must be float64. |
required |
y
|
ndarray of shape (N, dim)
|
Target time series. Must be float64. |
required |
tau
|
int
|
Time delay (in samples). Default 1. |
1
|
m
|
int
|
Embedding dimension for y. Default 1. |
1
|
lag
|
int
|
Time lag for embedding. Default 1. |
1
|
dt
|
float
|
Physical time step. Default 1.0. |
1.0
|
k
|
int
|
Number of nearest neighbors. Default 5. |
5
|
trial
|
int
|
Number of surrogate trials for significance testing. Default 0. |
0
|
Returns:
| Type | Description |
|---|---|
float
|
Backward transfer entropy computed on time-reversed series. |
Transfer Entropy Causal Map
ouxinfo.transfer_entropy_causal_map()
builtin
Compute a transfer entropy causal map for multivariate time series.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, Nt) or (N, Nt, dim)
|
Multivariate time series with N variables and Nt time steps. Must be float64. |
required |
tau
|
ndarray of shape (N,), dtype int32
|
Time delay for each variable. |
required |
m
|
int
|
Embedding dimension. Default 1. |
required |
lag
|
int
|
Time lag for embedding. Default 1. |
required |
dt
|
float
|
Physical time step. Default 1.0. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
trial
|
int
|
Number of surrogate trials. Default 0. |
required |
n_threads
|
int
|
Number of OpenMP threads. Default 1. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
ndarray of shape (N, N)
|
Causal map where entry [i, j] is TE(X_j -> X_i). |
Information Flow
Information Flow
ouxinfo.information_flow()
builtin
Compute information flow from X to Y using the KSG estimator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, dim)
|
Source time series. Must be float64. |
required |
Y
|
ndarray of shape (N, dim)
|
Target time series. Must be float64. |
required |
tau
|
int
|
Time delay (in samples). Default 1. |
required |
dt
|
float
|
Physical time step. Default 1.0. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
float
|
Information flow dI_X (rate of mutual information change due to X) in nats per dt. |
Notes
Based on the decomposition
dI/dt = dI_X + dI_Y + Leak
See: Horowitz & Esposito (2014).
Information Flow Causal Map
ouxinfo.information_flow_causal_map()
builtin
Compute an information flow causal map for multivariate time series.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, Nt) or (N, Nt, dim)
|
Multivariate time series with N variables and Nt time steps. Must be float64. |
required |
tau
|
ndarray of shape (N,), dtype int32
|
Time delay for each variable. |
required |
dt
|
float
|
Physical time step. Default 1.0. |
required |
k
|
int
|
Number of nearest neighbors. Default 5. |
required |
n_threads
|
int
|
Number of OpenMP threads. Default 1. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
tuple of three ndarray, each of shape (N, N)
|
(IF_map, Leak_map, dI_map) where IF_map[i, j] is the information flow from X_j to X_i, Leak_map[i, j] is the associated leak, and dI_map[i, j] is the mutual information rate. |
Spatial Information Flux
1D Spatial Flux
ouxinfo.flux1d.information_flow_1d(data, dt=1.0, tau=1, k=5, n_jobs=1)
Compute directed information flux across interfaces of a 1D spatial grid. For each neighboring cell interface i+½, evaluates both directional information flows and derives interface flux quantities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
(ndarray, shape(nx, nt) or (nz, nx, nt))
|
Spatiotemporal data. data[i, :] or data[:, i, :] is the time series at spatial cell i. Must be float64 (or convertible). |
required |
dt
|
float
|
Physical time step between samples. Default 1.0. |
1.0
|
tau
|
int
|
Time delay. Default 1. |
1
|
k
|
int
|
Number of nearest neighbours for the KSG estimator. Default 5. |
5
|
n_jobs
|
int
|
Number of parallel jobs (joblib). Default 1. |
1
|
Returns:
| Type | Description |
|---|---|
dict
|
All values are ndarray of shape (nx-1,), indexed by interface i: 'J_fwd' : J_{i → i+1} 'J_bwd' : J_{i+1 → i} 'J_net' : J_fwd - J_bwd (positive = left-to-right dominant) 'J_sym' : 0.5*(J_fwd + J_bwd) (bidirectional coupling strength) 'Leak' : leak associated with the forward direction |
2D Spatial Flux
ouxinfo.flux1d.information_flow_2d(data, dt=1.0, tau=1, k=5, n_jobs=1, x1=None, x2=None)
Compute directed information flux across interfaces of a 2D spatial grid. For each neighboring cell interface i+½ and j+½, evaluates both directional information flows and derives interface flux quantities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
(ndarray, shape(ny, nx, nt) or (nz, ny, nx, nt))
|
Spatiotemporal data. data[j,i,:] or data[:,j,i,:] is the time series at spatial cell (i,j). Must be float64 (or convertible). |
required |
dt
|
float
|
Physical time step between samples. Default 1.0. |
1.0
|
tau
|
int
|
Time delay. Default 1. |
1
|
k
|
int
|
Number of nearest neighbours for the KSG estimator. Default 5. |
5
|
n_jobs
|
int
|
Number of parallel jobs (joblib). Default 1. |
1
|
Returns:
| Type | Description |
|---|---|
dict
|
Values are ndarray of shape (ny,nx-1), indexed by interface i: 'Jx_fwd' : J_{i → i+1} [ny,nx-1] 'Jx_bwd' : J_{i+1 → i} [ny,nx-1] 'Jx_net' : J_fwd - J_bwd (positive = left-to-right dominant) 'Jx_sym' : 0.5(J_fwd + J_bwd) (bidirectional coupling strength) 'Leakx' : leak associated with the forward direction Values are ndarray of shape (ny-1,nx), indexed by interface j: 'Jy_fwd' : J_{j → j+1} [ny-1,nx] 'Jy_bwd' : J_{j+1 → j} [ny-1,nx] 'Jy_net' : J_fwd - J_bwd (positive = down-to-top dominant) 'Jy_sym' : 0.5(J_fwd + J_bwd) (bidirectional coupling strength) 'Leaky' : leak associated with the forward direction |
TEIFL (All-in-One Analysis)
TEIFL
ouxinfo.teifl.TEIFL(X, tau=1, dt=1.0, lag=1, max_m=10, tol=0.01, k=5, n_threads=1, result_dir='.', multi=False)
Compute transfer entropy, information flow, and leak for a multivariate time series.
Computes single-step transfer entropy (sTE), optionally multi-step TE (mTE) and
backward TE (bTE), plus information flow (IF), Leak, and dI. Saves results as a
compressed .npz file in result_dir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray of shape (N, Nt) or (N, Nt, dim)
|
Multivariate time series. N variables, Nt time steps, optional dim dimensions. |
required |
tau
|
int
|
Time delay (in samples). Default 1. |
1
|
dt
|
float
|
Physical time step. Default 1.0. |
1.0
|
lag
|
int
|
Time lag for embedding. Default 1. |
1
|
max_m
|
int
|
Maximum embedding dimension for mTE. Default 10. |
10
|
tol
|
float
|
Convergence tolerance for mTE calculation. Default 0.01. |
0.01
|
k
|
int
|
Number of nearest neighbors. Default 5. |
5
|
n_threads
|
int
|
Number of OpenMP threads for causal map computation. Default 1. |
1
|
result_dir
|
str
|
Directory to save the result file. Default '.'. |
'.'
|
multi
|
bool
|
If True, also compute mTE and bTE. Default False. |
False
|
Returns:
| Type | Description |
|---|---|
None
|
Saves |
plot_TEIFL
ouxinfo.teifl.plot_TEIFL(file_path, labels)
Plot causal maps from TEIFL output and save as PNG files.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str
|
Path to the |
required |
labels
|
list of str
|
Variable labels used for axis annotation. |
required |
Returns:
| Type | Description |
|---|---|
None
|
Saves PNG figures in the same directory as |