Package: event-analysis
Event AnalysisLibrary to find Event Synchronization and Event Coincidence AnalysisThe python library to calculateEvent SynchronizationandEvent Coincidence Analysisfor event series.To learn about ECA, readthis1To learn about ES, readthis2To install the librarypip install event-analysisTo use the Cuda method install PyCuda separately.UsageLook at theExample.ipnbyjupyter 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.DocumentationEventAnalysis( self , event_df , device_Id = None, time_normalization_factor = 3600)Argumentsevent_df : pandas dataframe. This dataframe must have the following propertiesThe index of the dataframe must be a pandas DatetimeIndex.The data inside the dataframe must be of type booleanEach column of this Dataframe will be an event series.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.ReturnEventAnalysis Object : On which you can call the ES, ECA method.NotesBy 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)ArgumentstauMax (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!ReturnQ : 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 doQ[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)ArgumentsDelta_T_obj : must be a python datetime.timedelta object. Quantized using the same value of time_normalization_factor as passed in the constructor.tau (default 0) : a parameter of the ECA algorithm. You can read it in the paperreturn_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. *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.ReturnEC_p_maxEC_p_meanEC_t_maxEC_t_meanpval_precursor[optional] : correspondes to the p-value of the EC_p_max and EC_p_meanpval_trigger[optional] : correspondes to the p-value of the EC_t_max and EC_t_meanAll of them are described in the paper.NotesThe 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 satisfiedNa>> 1 and Nb>> 1Delta_T << T / Nai.e. The number of events on both series must besufficientlygreater than 1 and delta_t must besufficientlyless than Overall time((timeseries[-1] - timeseries[0])) / Number of events on A . What qualifies assufficientlyis for the user to decide.ECA_vec(self, Delta_T_objs, taus = 0, return_p_values = False, pValFillNA = True)ArgumentsDelta_T_objs : must be a python list of python datetime.timedelta objectstaus (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.return_p_values : same as ECApValFillNa : same as ECAReturnsA generator which on the i'th yeild ECA called on Delta_T_objs[i], taus[i].CudaAll 3 method can be called on Nvidia GPU by adding_Cudato their namei.eES_Cuda,ECA_Cuda,ECA_vec_Cuda. All of them take one additional named parameterblock.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).NotesThe 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.ReferencesEvent coincidence analysis for quantifying statistical interrelationships between event time series - Jonathan F. Donges, Carl-Friedrich Schleussner, Jonatan F. Siegmund, and Reik V. DonnerFrederik 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