easyclimate.field.monsoon.bsiso¶

Boreal Summer Intraseasonal Oscillation (BSISO)

This module provides functions to calculate and visualize the BSISO, a dominant mode of intraseasonal variability in the Asian summer monsoon region during May-October. The BSISO is characterized by northward and eastward propagation of convective anomalies, influencing monsoon rainfall and tropical cyclone activity. The methodology is based on Lee et al. (2013), which defines multivariate indices using outgoing longwave radiation (OLR) and 850-hPa winds to capture BSISO phases.

Functions¶

`draw_bsiso1_phase_space_basemap`([ax, add_phase_text, ...])	Create a phase space basemap for BSISO1 visualization.
`draw_bsiso2_phase_space_basemap`([ax, add_phase_text, ...])	Create a phase space basemap for BSISO2 visualization.
`draw_bsiso_phase_space`(bsiso_data[, y_dim, x_dim, ...])	Visualize BSISO1 phase space trajectory using PC1 and PC2.
`draw_bsiso2_phase_space`(bsiso_data[, pc3_dim, ...])	Visualize BSISO2 phase space trajectory using PC3 and PC4.
`calc_bsiso1_phase`(ds[, amplitude_threshold, pc1_dim, ...])	Calculate BSISO1 phase based on PC1 and PC2 values.
`calc_bsiso2_phase`(ds[, amplitude_threshold, pc3_dim, ...])	Calculate BSISO2 phase based on PC3 and PC4 values.
`get_times_for_phase`(ds, phase_value[, time_dim, phase_dim])	Retrieve time points for a specified BSISO phase.
`calc_bsiso_analysis`(, extract_time_range, ...)	Perform BSISO analysis using OLR and 850-hPa wind data.

Module Contents¶

easyclimate.field.monsoon.bsiso.draw_bsiso1_phase_space_basemap(ax=None, add_phase_text: bool = True, add_location_text: bool = True)¶

Create a phase space basemap for BSISO1 visualization.

This function generates a standardized background diagram for BSISO1 analysis, plotting phase division lines (1-8), amplitude circles, and geographical annotations. The diagram uses normalized principal components (PC1 and PC2) as axes, representing the BSISO1 mode in a Cartesian coordinate system (-4 to 4 range). The BSISO1 mode captures the northward and eastward propagation of convective anomalies over the Asian monsoon region.

Parameters¶

axmatplotlib.axes.Axes, optional: Target axes for plotting. If None, uses the current axes (plt.gca()).
add_phase_textbool, default True: Whether to annotate BSISO phase numbers (1-8) on the diagram.
add_location_textbool, default True: Whether to annotate geographical regions corresponding to BSISO phases, such as: - Bay of Bengal & South China Sea - Indian Ocean & East Asia - Equatorial Indian Ocean - Western North Pacific - India & Maritime Continent

Returns¶

matplotlib.axes.Axes: The configured axes object with the BSISO1 phase space basemap.

Notes¶

The diagram includes 8 radial lines at 45° intervals to divide phases, a unit circle for amplitude threshold (amplitude=1), and labeled axes (PC2, PC1).

Examples¶

>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(figsize=(8, 8))
>>> draw_bsiso1_phase_space_basemap(ax=ax)
>>> plt.show()

easyclimate.field.monsoon.bsiso.draw_bsiso2_phase_space_basemap(ax=None, add_phase_text: bool = True, add_location_text: bool = True)¶

Create a phase space basemap for BSISO2 visualization.

This function generates a standardized background diagram for BSISO2 analysis, plotting phase division lines (1-8), amplitude circles, and geographical annotations. The diagram uses normalized principal components (PC3 and PC4) as axes, representing the BSISO2 mode, which captures higher-frequency intraseasonal variability compared to BSISO1.

Parameters¶

axmatplotlib.axes.Axes, optional: Target axes for plotting. If None, uses the current axes (plt.gca()).
add_phase_textbool, default True: Whether to annotate BSISO phase numbers (1-8) on the diagram.
add_location_textbool, default True: Whether to annotate geographical regions corresponding to BSISO phases, such as: - North East Asia - South East Asia - Philippine Sea - India & South China Sea - Indian Ocean - Western North Pacific - Bay of Bengal

Returns¶

matplotlib.axes.Axes: The configured axes object with the BSISO2 phase space basemap.

Notes¶

The diagram includes 8 radial lines at 45° intervals, a unit circle for amplitude threshold (amplitude=1), and labeled axes (PC4, PC3).
BSISO2 typically represents shorter-period oscillations (10-20 days) compared to BSISO1 (30-60 days).

Examples¶

>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(figsize=(8, 8))
>>> draw_bsiso2_phase_space_basemap(ax=ax)
>>> plt.show()

easyclimate.field.monsoon.bsiso.draw_bsiso_phase_space(bsiso_data: xarray.Dataset, y_dim: str = 'PC1', x_dim: str = 'PC2', time_dim: str = 'time', ax=None, color='blue', start_text='START', add_start_text: bool = True)¶

Visualize BSISO1 phase space trajectory using PC1 and PC2.

Plots the temporal evolution of BSISO1 phases as a parametric curve in PC1-PC2 space, with an optional marker for the starting point. Combines scatter points and connecting lines to show the progression of BSISO phases, typically representing 30-60 day oscillations.

Parameters¶

bsiso_dataxarray.Dataset: Dataset containing normalized principal components (PC1, PC2) and a time coordinate.
y_dimstr, default “PC1”: Variable name for the y-axis component (PC1).
x_dimstr, default “PC2”: Variable name for the x-axis component (PC2).
time_dimstr, default “time”: Name of the time coordinate dimension.
axmatplotlib.axes.Axes, optional: Target axes for plotting. If None, uses the current axes (plt.gca()).
colorstr or tuple, default “blue”: Color for the trajectory and points.
start_textstr, default “START”: Text annotation for the trajectory starting point.
add_start_textbool, default True: Whether to display the start point annotation.

Returns¶

matplotlib.axes.Axes: Configured axes object with the BSISO1 phase space trajectory.

Notes¶

Recommended to use with draw_bsiso1_phase_space_basemap for the background diagram.
Daily data is recommended for smooth trajectory visualization.

Examples¶

>>> import xarray as xr
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(figsize=(8, 8))
>>> draw_bsiso1_phase_space_basemap(ax=ax)
>>> draw_bsiso_phase_space(bsiso_data=ds, ax=ax, color="red")
>>> plt.title("BSISO1 Phase Space Trajectory")
>>> plt.show()

easyclimate.field.monsoon.bsiso.draw_bsiso2_phase_space(bsiso_data: xarray.Dataset, pc3_dim: str = 'PC3', pc4_dim: str = 'PC4', time_dim: str = 'time', ax=None, color='blue', start_text='START', add_start_text: bool = True)¶

Visualize BSISO2 phase space trajectory using PC3 and PC4.

Plots the temporal evolution of BSISO2 phases as a parametric curve in PC3-PC4 space, with an optional marker for the starting point. Combines scatter points and connecting lines to show the progression of BSISO phases, typically representing 10-20 day oscillations.

Parameters¶

bsiso_dataxarray.Dataset: Dataset containing normalized principal components (PC3, PC4) and a time coordinate.
pc3_dimstr, default “PC3”: Variable name for the y-axis component (PC3).
pc4_dimstr, default “PC4”: Variable name for the x-axis component (PC4).
time_dimstr, default “time”: Name of the time coordinate dimension.
axmatplotlib.axes.Axes, optional: Target axes for plotting. If None, uses the current axes (plt.gca()).
colorstr or tuple, default “blue”: Color for the trajectory and points.
start_textstr, default “START”: Text annotation for the trajectory starting point.
add_start_textbool, default True: Whether to display the start point annotation.

Returns¶

matplotlib.axes.Axes: Configured axes object with the BSISO2 phase space trajectory.

Notes¶

Recommended to use with draw_bsiso2_phase_space_basemap for the background diagram.
Daily data is recommended for smooth trajectory visualization.

Examples¶

>>> import xarray as xr
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(figsize=(8, 8))
>>> draw_bsiso2_phase_space_basemap(ax=ax)
>>> draw_bsiso2_phase_space(bsiso_data=ds, ax=ax, color="red")
>>> plt.title("BSISO2 Phase Space Trajectory")
>>> plt.show()

easyclimate.field.monsoon.bsiso.calc_bsiso1_phase(ds: xarray.DataArray, amplitude_threshold: float = 1.5, pc1_dim: str = 'PC1', pc2_dim: str = 'PC2')¶

Calculate BSISO1 phase based on PC1 and PC2 values.

Computes the BSISO1 phase (0-8) based on the principal components PC1 and PC2, following the classification rules defined by Lee et al. (2013). Adds a boolean variable ‘is_event’ to indicate if the amplitude (\(\sqrt{\mathrm{PC1}^2 + \mathrm{PC2}^2}\)) exceeds the threshold, and a 'phase' variable for the BSISO phase.

Parameters¶

dsxarray.Dataset: Dataset containing PC1 and PC2 variables with a time dimension.
amplitude_thresholdfloat, default 1.5: Threshold for event detection based on amplitude.
pc1_dimstr, default “PC1”: Variable name for PC1 in the dataset.
pc2_dimstr, default “PC2”: Variable name for PC2 in the dataset.

Returns¶

xarray.Dataset: Dataset with added ‘phase’ (int, 0-8) and ‘is_event’ (boolean) variables.

Notes¶

Phase classification:

Phase 0: Non-event (amplitude <= threshold)
Phase 1: \(\mathrm{PC1} < 0, \mathrm{PC2} < 0, \mathrm{PC1} > \mathrm{PC2}\)
Phase 2: \(\mathrm{PC1} < 0, \mathrm{PC2} < 0, \mathrm{PC1} < \mathrm{PC2}\)
Phase 3: \(\mathrm{PC1} < 0, \mathrm{PC2} > 0, |\mathrm{PC1}| > \mathrm{PC2}\)
Phase 4: \(\mathrm{PC1} < 0, \mathrm{PC2} > 0, |\mathrm{PC1}| < \mathrm{PC2}\)
Phase 5: \(\mathrm{PC1} > 0, \mathrm{PC2} > 0, \mathrm{PC1} < \mathrm{PC2}\)
Phase 6: \(\mathrm{PC1} > 0, \mathrm{PC2} > 0, \mathrm{PC1} > \mathrm{PC2}\)
Phase 7: \(\mathrm{PC1} > 0, \mathrm{PC2} < 0, \mathrm{PC1} > |\mathrm{PC2}|\)
Phase 8: \(\mathrm{PC1} > 0, \mathrm{PC2} < 0, \mathrm{PC1} < |\mathrm{PC2}|\)

Examples¶

>>> ds = calc_bsiso1_phase(ds, amplitude_threshold=1.5)
>>> print(ds['phase'])

easyclimate.field.monsoon.bsiso.calc_bsiso2_phase(ds: xarray.DataArray, amplitude_threshold: float = 1.5, pc3_dim: str = 'PC3', pc4_dim: str = 'PC4')¶

Calculate BSISO2 phase based on PC3 and PC4 values.

Wrapper function for calc_bsiso1_phase to compute BSISO2 phases (0-8) using principal components PC3 and PC4, which capture higher-frequency (10-20 day) intraseasonal variability.

Parameters¶

dsxarray.Dataset: Dataset containing PC3 and PC4 variables with a time dimension.
amplitude_thresholdfloat, default 1.5: Threshold for event detection based on amplitude.
pc3_dimstr, default “PC3”: Variable name for PC3 in the dataset.
pc4_dimstr, default “PC4”: Variable name for PC4 in the dataset.

Returns¶

xarray.Dataset: Dataset with added ‘phase’ (int, 0-8) and ‘is_event’ (boolean) variables.

Notes¶

Delegates to calc_bsiso1_phase with PC3 and PC4 as inputs.
BSISO2 phases follow the same classification rules as BSISO1 but use different PCs.

Examples¶

>>> ds = calc_bsiso2_phase(ds, amplitude_threshold=1.5)
>>> print(ds['phase'])

easyclimate.field.monsoon.bsiso.get_times_for_phase(ds: xarray.Dataset, phase_value: int, time_dim: str = 'time', phase_dim: str = 'phase')¶

Retrieve time points for a specified BSISO phase.

Extracts time coordinates from the dataset where the ‘phase’ variable matches the specified phase value (0-8), useful for composite analysis of BSISO events.

Parameters¶

dsxarray.Dataset: Dataset containing ‘phase’ variable with a time dimension.
phase_valueint: Target phase value to query (0-8).
time_dimstr, default “time”: Name of the time coordinate dimension.
phase_dimstr, default “phase”: Name of the phase variable.

Returns¶

xarray.DataArray: Array of time coordinates where the phase equals phase_value.

Notes¶

Returns an empty DataArray if no time points match the specified phase.
Assumes the ‘phase’ variable exists in the dataset.

Examples¶

>>> times = get_times_for_phase(ds, phase_value=1)
>>> print(times)

easyclimate.field.monsoon.bsiso.calc_bsiso_analysis(olr_data: xarray.DataArray, u850_data: xarray.DataArray, v850_data: xarray.DataArray, daily_cycle_mean_time_range: slice = slice(None, None), extract_time_range: slice = slice(None, None), harmonics_num: int = 3, threshold: float = 0.05, time_dim: str = 'time', lat_dim: str = 'lat', lon_dim: str = 'lon') → easyclimate.core.datanode.DataNode¶

Perform BSISO analysis using OLR and 850-hPa wind data.

Computes multivariate BSISO indices (BSISO1 and BSISO2) using outgoing longwave radiation (OLR) and 850-hPa zonal (u850) and meridional (v850) winds, following the methodology of Lee et al. (2013). The function processes data to remove seasonal cycles and low-frequency signals, performs multivariate EOF analysis, and derives phase composites for BSISO1 and BSISO2.

Parameters¶

olr_dataxarray.DataArray: Outgoing longwave radiation data with time, latitude, and longitude dimensions.
u850_dataxarray.DataArray: 850-hPa zonal wind data with the same dimensions as olr_data.
v850_dataxarray.DataArray: 850-hPa meridional wind data with the same dimensions as olr_data.
daily_cycle_mean_time_rangeslice, default slice(None, None): Time range for computing the daily annual cycle mean.
extract_time_rangeslice, default slice(None, None): Time range for extracting data for analysis.
harmonics_numint, default 3: Number of harmonics for smoothing the daily annual cycle.
thresholdfloat, default 0.05: P-value threshold for statistical significance in composite analysis.
time_dimstr, default “time”: Name of the time dimension.
lat_dimstr, default “lat”: Name of the latitude dimension.
lon_dimstr, default “lon”: Name of the longitude dimension.

Returns¶

easyclimate.DataNode

Hierarchical data structure containing:

Explained variance ratios
Principal components (PC1-PC4)
Normalized PCs
EOF patterns for OLR and winds
Lead-lag correlation coefficients
Phase information
Composite analysis results for BSISO1 and BSISO2 phases

Notes¶

The analysis focuses on May-October data to capture the boreal summer monsoon season.
BSISO1 represents 30-60 day oscillations, while BSISO2 captures 10-20 day oscillations.
Progress indicators are logged to track major computational steps.

References¶

Lee, JY. (이준이), Wang, B., Wheeler, M.C. et al. Real-time multivariate indices for the boreal summer intraseasonal oscillation over the Asian summer monsoon region. Clim Dyn 40, 493–509 (2013). https://doi.org/10.1007/s00382-012-1544-4
Wheeler, M. C., & Hendon, H. H. (2004). An All-Season Real-Time Multivariate MJO Index: Development of an Index for Monitoring and Prediction. Monthly Weather Review, 132(8), 1917-1932. https://doi.org/10.1175/1520-0493(2004)132<1917:AARMMI>2.0.CO;2

Examples¶

>>> result = calc_bsiso_analysis(olr_data, u850_data, v850_data)
>>> print(result["Phase/PC1_2"])