Note
This page was generated from a Jupyter notebook.
Download the notebook
Event Synchronization (ES) networks¶
Event Synchronization (ES) is a statistical method used to quantify the synchrony between event time series by measuring the relative timing of events in two time series. ES has become particularly useful in climate science for analyzing extreme events across different geographical locations.
This notebook demonstrates how to use the dominosee
package to perform Event Synchronization for the temporal positions of events and construct event-based climate networks from time series data.
Input Data¶
We’ll start by creating a synthetic dataset to demonstrate the ES workflow. For real-world applications, you would typically load climate data from NetCDF files or other sources. In this example, we’ll generate a simple dataset with the Standardized Precipitation Index (SPI) values, which are commonly used to identify drought conditions.
We’ll create a synthetic dataset with the following properties:
Spatial dimensions: 20x20 grid points (latitude x longitude)
Temporal dimension: 365 days (daily data for one year)
Variable: SPI1
[2]:
import numpy as np
import xarray as xr
xr.set_options(display_expand_data=False)
[2]:
<xarray.core.options.set_options at 0x17575d6d0>
[3]:
# Using smaller dimensions for demonstration
nx_demo, ny_demo, nt_demo = 20, 20, 365
# Create coordinates
lats = np.linspace(-90, 90, nx_demo)
lons = np.linspace(-180, 180, ny_demo)
times = xr.date_range("1950-01-01", periods=nt_demo, freq="D")
# Create standard normal data for SPI values (mean=0, std=1)
spi_data = np.random.normal(0, 1, size=(nx_demo, ny_demo, nt_demo)) # Standard normal distribution
# Create xarray Dataset
spi = xr.Dataset(
data_vars={
"SPI1": (["lat", "lon", "time"], spi_data)
},
coords={
"lat": lats,
"lon": lons,
"time": times
}
)
spi
[3]:
<xarray.Dataset> Size: 1MB Dimensions: (lat: 20, lon: 20, time: 365) Coordinates: * lat (lat) float64 160B -90.0 -80.53 -71.05 -61.58 ... 71.05 80.53 90.0 * lon (lon) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 * time (time) datetime64[ns] 3kB 1950-01-01 1950-01-02 ... 1950-12-31 Data variables: SPI1 (lat, lon, time) float64 1MB -0.6445 -0.3062 ... 0.3327 -0.5354
Extract the timing of extreme events¶
Event Synchronization analysis requires the extraction of discrete event positions from continuous time series data. In this step, we convert our continuous SPI time series into binary event time series by applying a threshold.
We’ll use the get_event
function from the dominosee.eventorize
module, which identifies events based on a specified threshold and direction (above or below). For drought events, we’re interested in SPI values below a threshold of -1.0. It is recommended to only consider the burst timing for each series of consecutive event occurrences to avoid the effects of temporal clustering on ES calculations, so we set select="start"
and select_period=1
.
[5]:
from dominosee.eventorize import get_event
da_burst = get_event(spi.SPI1, threshold=-1.0, extreme="below", event_name="drought", select="start", select_period=1)
da_burst
[5]:
<xarray.DataArray 'drought' (lat: 20, lon: 20, time: 365)> Size: 146kB False False True False False False False ... True False True False False False Coordinates: * lat (lat) float64 160B -90.0 -80.53 -71.05 -61.58 ... 71.05 80.53 90.0 * lon (lon) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 * time (time) datetime64[ns] 3kB 1950-01-01 1950-01-02 ... 1950-12-31 Attributes: threshold: -1.0 extreme: below long_name: drought events description: Events with -1.0 below threshold event_name: drought select: start select_period: 1
After identifying extreme events with the get_event
function, we need to extract the timing positions of these events using get_event_positions
. This is because ES analysis requires the exact timing of events to calculate the time delay between event pairs between two locations.
[6]:
from dominosee.es import get_event_positions
da_burst_ep = get_event_positions(da_burst)
da_burst_ep
[6]:
<xarray.Dataset> Size: 106kB Dimensions: (lat: 20, lon: 20, event: 64) Coordinates: * lat (lat) float64 160B -90.0 -80.53 -71.05 ... 71.05 80.53 90.0 * lon (lon) float64 160B -180.0 -161.1 -142.1 ... 161.1 180.0 * event (event) int64 512B 0 1 2 3 4 5 6 7 ... 57 58 59 60 61 62 63 Data variables: event_positions (lat, lon, event) int32 102kB 2 12 27 34 37 ... -1 -1 -1 -1 event_count (lat, lon) int64 3kB 41 42 48 44 51 55 ... 43 47 45 46 56
The result is a integer Dataset of event positions, where:
event_position
indicates the position of the event in the time dimensionevent_count
indicates the number of events
This integer representation allows us to easily identify the positions of events in the time dimension, and the number of events. The event Dataset includes attributes that document the threshold and criteria used to define the events.
Calculate Event Synchronization between location pairs¶
Event Synchronization quantifies the similarity in the timing of events between two time series. Unlike ECA, which counts coincidences within fixed time windows, ES dynamically adapts the tolerance window based on the local event lags.
[10]:
from dominosee.es import get_event_sync_from_positions
da_es = get_event_sync_from_positions(positionsA=da_burst_ep.event_positions,
positionsB=da_burst_ep.event_positions,
tm=10)
da_es
OMP: Info #276: omp_set_nested routine deprecated, please use omp_set_max_active_levels instead.
[10]:
<xarray.DataArray 'event_positions' (latA: 20, latB: 20, lonA: 20, lonB: 20)> Size: 160kB 39 11 9 16 14 18 14 10 14 14 16 11 15 ... 17 16 16 16 14 18 9 15 13 14 18 12 54 Coordinates: * latA (latA) float64 160B -90.0 -80.53 -71.05 -61.58 ... 71.05 80.53 90.0 * lonA (lonA) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 * latB (latB) float64 160B -90.0 -80.53 -71.05 -61.58 ... 71.05 80.53 90.0 * lonB (lonB) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 Attributes: long_name: Event Synchronization units: count description: Number of synchronized events between locations A and B tau_max: 10 output_dtype: <class 'numpy.uint8'>
The get_event_sync_from_positions
function calculates the event synchronization between all pairs of grid points. The resulting DataArray has four dimensions:
latA
,lonA
: Coordinates of the location AlatB
,lonB
: Coordinates of the location B
The function parameters control the ES calculation:
tm
: The maximum time window (in time steps) within which events must occur to be considered synchronized
Calculate the statistical confidence of ES¶
EXPERIMENTAL: The Event Synchronization null model in dominosee is currently experimental. The functionality may change in future releases.
Event Synchronization (ES) is a statistical method used to quantify the synchrony between event time series…
After calculating the raw event coincidence counts, the next critical step is to determine which connections are statistically significant. This involves:
Get critical values: Computing ES values for many realizations of the surrogate data. Unlike ECA, which can utilize analytical formulas for significance testing, ES typically relies on computational methods like bootstrapping to generate surrogate data. The significance level (e.g., p < 0.05 or p < 0.01) determines how conservative our network construction will be - stricter thresholds produce sparser but more reliable networks.
Construct a null model for location pairs: Map the critical values to the number of total events in the locations pairs.
[28]:
from dominosee.es import create_null_model_from_indices
da_cvalues = create_null_model_from_indices(spi.time, tm=da_es.attrs["tau_max"],
max_events=da_burst_ep.event_count.max().values, significances=0.001)
da_cvalues
[28]:
<xarray.DataArray (noeA: 65, noeB: 65, significance: 1)> Size: 34kB 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ... 15 14 16 17 16 15 15 18 17 18 17 17 17 18 17 Coordinates: * noeA (noeA) int64 520B 0 1 2 3 4 5 6 7 ... 57 58 59 60 61 62 63 64 * noeB (noeB) int64 520B 0 1 2 3 4 5 6 7 ... 57 58 59 60 61 62 63 64 * significance (significance) float64 8B 0.001 Attributes: description: Event synchronization null model for pairs of number of events tau_max: 10 max_events: 64 min_es: None
[29]:
from dominosee.es import convert_null_model_for_locations
da_null = convert_null_model_for_locations(da_cvalues, da_burst_ep.event_count, da_burst_ep.event_count, sig=0.001)
da_null
[29]:
<xarray.DataArray (latA: 20, lonA: 20, latB: 20, lonB: 20)> Size: 1MB 12 10 11 10 12 12 12 11 12 12 11 9 12 ... 13 14 11 14 13 11 14 14 12 14 13 13 15 Coordinates: noeA (latA, lonA) int64 3kB 41 42 48 44 51 55 ... 51 43 47 45 46 56 noeB (latB, lonB) int64 3kB 41 42 48 44 51 55 ... 51 43 47 45 46 56 significance float64 8B 0.001 * latA (latA) float64 160B -90.0 -80.53 -71.05 ... 71.05 80.53 90.0 * lonA (lonA) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 * latB (latB) float64 160B -90.0 -80.53 -71.05 ... 71.05 80.53 90.0 * lonB (lonB) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 Attributes: description: Event synchronization null model for pairs of locations tau_max: 10 max_events: 64 min_es: None
Construct network represented by adjacency matrix¶
The next step involves constructing the climate network based on statistically significant connections. We’ll create an adjacency matrix, which is a fundamental representation of the network structure:
Adjacency Matrix: A square matrix where both rows and columns correspond to grid points (locations).
Matrix Elements: Each element (i,j) contains a binary value:
1 if a statistically significant connection exists between locations i and j
0 if no significant connection is present
Interpretation: This matrix provides a concise representation of the network topology, enabling further analysis of the climate system’s spatial relationships.
[30]:
from dominosee.network import get_link_from_critical_values
da_link = get_link_from_critical_values(da_es, da_null, rule="greater")
da_link
[30]:
<xarray.DataArray (latA: 20, latB: 20, lonA: 20, lonB: 20)> Size: 160kB True True False True True True True ... False True True False True False True Coordinates: * latA (latA) float64 160B -90.0 -80.53 -71.05 ... 71.05 80.53 90.0 * lonA (lonA) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 * latB (latB) float64 160B -90.0 -80.53 -71.05 ... 71.05 80.53 90.0 * lonB (lonB) float64 160B -180.0 -161.1 -142.1 ... 142.1 161.1 180.0 noeA (latA, lonA) int64 3kB 41 42 48 44 51 55 ... 51 43 47 45 46 56 noeB (latB, lonB) int64 3kB 41 42 48 44 51 55 ... 51 43 47 45 46 56 significance float64 8B 0.001
[31]:
print(f"The network density is {da_link.sum().values/da_link.size*100:.2f}%.")
The network density is 82.36%.