mzprojection package
Project description
mzprojection
Projection operator method for statistical data analysis (Python3)
Overview
This is the Python3 module of Mori-Zwanzig projection operator method, which is a statistical data analysis tool for an ensemble time-series data set. One splits the analyzed time-series data f(t) (response variables) into correlated and uncorrelated parts with regard to the variable of interests u(t) (explanatory variables).
f(t) = \Omega \cdot u(t) - \int_0^t \Gamma(t) \cdot u(t) + r(t)
In Oct. 2021, the function "mzprojection_multivariate" has been developed for the projection on multiple u_j(t). The previous 1-to-1 projection will be obsolete, because it is covered by multivariate one. Fortran module is no longer supported.
Usage
mzprojection module requires external packages: numpy, scipy.
-
User prepares an ensemble data set as input, namely a number of samples of time-series data,
delta_t # Time step size f[nsample,nperiod,nf] # Response variables u[nsample,nperiod,nu] # Explanatory variables dudt0[nsample,nu] # = du/dt at t=0 of each samples
-
Calculate the Markov coefficient matrix omega and memory function memoryf from the data set,
from mzprojection import mzprojection_multivariate omega, memoryf = mzprojection_multivariate(delta_t, u, dudt0, f)
If one would like to evaluate the memory term s(t) and the uncorrelated term r(t),
omega, memoryf, s, r = mzprojection_multivariate(delta_t, u, dudt0, f, flag_terms=True)
-
That's all! See also the help on the function mzprojection_multivariate.
Jupyter notebook in tests/DEMO_Oct2021_multivariate.ipynb shows an example with some output figures.
Tips
(a) If one would like to create these samples from a long time-series data, the following function could be useful,
from mzprojection import split_long_time_series
u = split_long_time_series(u_raw, ista=100, nperiod=200, nshift=10)
(b) If one would like to calculate various correlations, just take average over samples. Since this would often happens, there is a function (just by numpy.tensordot),
from mzprojection import calc_correlation
u0 = u[:,0,:]
fu = calc_correlation(f,u0)
Then one gets the cross-correlation between f(t) and u(0) as fu[nperiod,nf,nu].
Reference
We politely request that you cite the original paper when you use this module in publications:
Shinya Maeyama and Tomo-Hiko Watanabe, "Extracting and Modeling the Effects of Small-Scale Fluctuations on Large-Scale Fluctuations by Mori-Zwanzig Projection operator method", J. Phys. Soc. Jpn. 89, 024401 (2020).
More details.
Theoretical description
Mori-Zwanzig projection of the analyzed time-series data f(t) onto the variable of interest u(t) provides a generalized Langevin form,
f_i(t) = Omega_{ij}u_j(t) + s_i(t) + r_i(t)
where s_i(t) = - \int_0^t Gamma_{ij}(t)*u_j(t-v) dv is the memory term. Take summation over the repeated index j.
Omega, Gamma(t), r(t) are called as the Markov coefficient matrix, memory function matrix, uncorrelated term (or so-called orthogonal dynamics or noise term), respectively.
They are defined by
Omega = <f*u^*>.<u*u^*>^-1
Gamma(t) = <r(t)*du/dt^*>.<u*u^*>^-1
<r(t)*u^*> = 0
where ( )^* is the complex conjugate, ( )^-1 is the inverse of matrix, ( ).( ) is the matrix product, < > is the ensemble average. f, u, dudt are shorthand of initial values, i.e., f=f(0), u=u(0), dudt=dudt(0).
Therefore, the 1st and 2nd term (Omega.u(t) and s(t)) are correlated with u(t), while the 3rd (r(t)) is not.
Numerical implementation
Let us assume an ensemble of time-series data f(t)^l and u(t)^l are prepared.
t = 0, delta_t, 2*delta_t, 3*delta_t, ..., (nperiod-1)*delta_t
u(t)^l = u(0)^l, u(1)^l, u(2)^l, u(3)^l, ..., u(nperiod-1)^l
f(t)^l = f(0)^l, f(1)^l, f(2)^l, f(3)^l, ..., f(nperiod-1)^l
where l = 0, 1, 2, ..., nsample-1. Note that u={u_0, u_1, ..., u_nu-1} and f={f_0, f_1, ..., f_nf-1} are vectors.
Ensemble average is defined as summation over l, e.g.,
<f_i*u_j^*> = (1/nsample) * sum_{l=0}^{nsample-1} f_i^l*(u_j^l)^*.
Then, Omega is obtained from
Omega = <f*u^*>.<u*u^*>^-1.
Multiplying du^*/dt on the generalized langevin form and taking ensemble average, one obtains the memory equation,
Gamma(t) = F(t) + \int_0^t Gamma(v).G(t-v) dv
where
F(t) = [<f(t)*du/dt^*> - Omega.<u(t)*du/dt^*>].<u*u^*>^-1
G(t) = <u(t)*du/dt^*>.<u*u^*>^-1
Since all ensemble averaged quantities are evaluated, one can construct Gamma(t).
At t=0, Gamma(0) = F(0)
At t=delta_t, time integration is discretized by 2nd-order trapezoid rule,
\int_0^delta_t Gamma(v).G(delta_t-v) dv
= Gamma(0).G(delta_t) * 0.5*delta_t
+ Gamma(delta_t).G(0) * 0.5*delta_t
and then,
Gamma(delta_t) = [F(delta_t) + 0.5*delta_t*Gamma(0).G(delta_t)].[I - 0.5*delta_t*G(0)]^-1
where I is the identity matrix.
In the same way, Gamma(t) is calculated by using Gamma(0) to Gamma(t-delta_t).
The memory term is calculated by the convolution of Gamma(t) and u(t), while integration range is reduced from 0<v<t to t-(nperiod-1)*delta_t<v<t,
s(t) = - \int_{t-(nperiod-1)*delta_t}^t Gamma(t).u(t-v) dv.
The uncorrelated term is calculated as a residual,
r(t) = f(t) - Omega.u(t) - s(t).
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mzprojection-0.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0c3cf66af3c237c1e458e4b8a01d9506974780795898541dce2fb72077c5091b |
|
MD5 | fcca8089f644776a3dfa9d72c144bf31 |
|
BLAKE2b-256 | dc58c8e5704a8f007d74226df1eadc8e9dbd3efb1703c063eb0dbb2bd8fbd6f5 |