event-analysis 1.1.2

This package allows you to run Event Coincidence Analysis and Event Synchronization on your event series on the CPU and Nvidia-GPU

Event Analysis

Library to find Event Synchronization and Event Coincidence Analysis

---

The python library to calculate Event Synchronization and Event Coincidence Analysis for event series.

To learn about ECA, read this ¹

To learn about ES, read this ²

To install the library

pip install event-analysis

To use the Cuda method install PyCuda separately.

Usage

Look at the Example.ipnby jupyter notebook to see the detailed usage.

from EventAnalysis import EventAnalysis

EA = EventAnalysis(event_dataframe)

Q = EA.ES()

p_max, p_mean, t_max, t_mean = EA.ECA(time_delta)

p_max, p_mean, t_max, t_mean, pval_p, pval_t = EA.ECA(time_delta, return_p_values = True)

Please read the notes for the EventAnalysis class before you use this library.

Documentation

---

EventAnalysis( self , event_df , device_Id = None, time_normalization_factor = 3600)

Arguments

1. event_df : pandas dataframe. This dataframe must have the following properties

   1. The index of the dataframe must be a pandas DatetimeIndex.

   2. The data inside the dataframe must be of type boolean

Each column of this Dataframe will be an event series.

2. device_Id : if you have an multiple Nvidia GPU's then you can use this to specify the ID of the GPU you want the computation to run on. Reverts to 0 if not provided.

Return

1. EventAnalysis Object : On which you can call the ES, ECA method.

Notes

By default the library quantiese the time to hours, ignoring minutes and seconds. However this behavious can be overridden by passing the time_normalization_factor argument to the constructor. You can set it to 1 and quantise to seconds (however this limits you to just 69 years of data). Setting it to 60 will quantize it to minutes allowing for 4000 years of data, finally setting it to 3600 (the default value) will allow for 250 centuries of data!

ES(self, tauMax = np.Inf)

Arguments

1. tauMax (default = np.Inf): currently the code doesn't use this. Functionality to use this will be added in future release. Please open an issue if you require this and it will be added ASAP!

Return

1. Q : a dataframe of N x N where N is the number of event series (number of columns in the dataframe given to the contructor ). You can do Q[event_series_1_name][event_series_2_name] to get those 2 event series Event Synchronization.

---

ECA(self, Delta_T_obj, tau = 0, return_p_values = False, pValFillNA = True)

Arguments

1. Delta_T_obj : must be a python datetime.timedelta object. Quantized using the same value of time_normalization_factor as passed in the constructor.

2. tau (default 0) : a parameter of the ECA algorithm. You can read it in the paper

3. return_p_values(default false) : if set to true will calculate the p-values for each combination of event series as described in paper and return them as well. *

4. pValFillNA (default true) : because of the method used to calculate p-value internally some values may be nan. If this is true it will replace them with 1.

Return

1. EC_p_max

2. EC_p_mean

3. EC_t_max

4. EC_t_mean

5. pval_precursor[optional] : correspondes to the p-value of the EC_p_max and EC_p_mean

6. pval_trigger[optional] : correspondes to the p-value of the EC_t_max and EC_t_mean

All of them are described in the paper.

Notes

The paper gives a formula for calculating P-Value of the result of ECA on 2 event series A and B as long as 2 conditions are satisfied

1. N_a >> 1 and N_b >> 1

2. Delta_T << T / N_a

i.e. The number of events on both series must be sufficiently greater than 1 and delta_t must be sufficiently less than Overall time((timeseries[-1] - timeseries[0])) / Number of events on A . What qualifies as sufficiently is for the user to decide.

---

ECA_vec(self, Delta_T_objs, taus = 0, return_p_values = False, pValFillNA = True)

Arguments

1. Delta_T_objs : must be a python list of python datetime.timedelta objects

2. taus (default 0) : must be an int, a list of ints or an numpy array of ints of the same length as Delta_T_objs. If an int is provided all ECA's are called using that one value.

3. return_p_values : same as ECA

4. pValFillNa : same as ECA

Returns

1. A generator which on the i'th yeild ECA called on Delta_T_objs[i], taus[i].

---

Cuda

All 3 method can be called on Nvidia GPU by adding _Cuda to their name

i.e ES_Cuda, ECA_Cuda, ECA_vec_Cuda. All of them take one additional named parameter block.

ES_Cuda(..., block = None)

When block is set to none it defaults to the value of (16, 8, 1). During experimentation it was observed this is the optimal value. However any tuple of the form (x, y, 1) where x * y is a multiple of the GPU's Warp size is valid (Nvidia has yet to make a GPU which doesn't have 32 as it warp size).

ECA_Cuda(..., block = None), ECA_vec_Cuda(..., block = None)

When block is set to none it defaults to the value of (32, 1, 1). During experimentation it was observed this is the optimal value. However any tuple of the form (x, 1, 1) where x is a multiple of the GPU's Warp size is valid (Nvidia has yet to make a GPU which doesn't have 32 as it warp size).

Notes

The p_values returned by the GPU maybe sligthly different from the once by CPU. Although the methods are identical across both, it is caused by GPU floating points operation returning results sligtly different than CPU. However they wont be much different. Setting Epsilong to 10e-2 should make them allclose.

---

References

1. Event coincidence analysis for quantifying statistical interrelationships between event time series - Jonathan F. Donges, Carl-Friedrich Schleussner, Jonatan F. Siegmund, and Reik V. Donner

2. Frederik Wolf, Jurek Bauer, Niklas Boers, and Reik V. Donner , "Event synchrony measures for functional climate network analysis: A case study on South American rainfall dynamics", Chaos 30, 033102 (2020) https://doi.org/10.1063/1.5134012