easyclimate.field.monsoon

Submodules

Functions

calc_index_NPWI(→ xarray.DataArray)

Calculate the normalized precipitable water index (NPWI).

find_PW_monsoon_region(→ xarray.DataArray)

The refined monsoon regions.

calc_NPWI_monsoon_onset(→ xarray.DataArray)

Calculate the summer monsoon onset date.

calc_NPWI_monsoon_retreat(→ xarray.DataArray)

Calculate the summer monsoon retreat date.

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.

Package Contents

easyclimate.field.monsoon.calc_index_NPWI(precipitable_water_daily_data: xarray.DataArray, time_dim: str = 'time') → xarray.DataArray

Calculate the normalized precipitable water index (NPWI).

\[\mathrm{NPWI} = \frac{\mathrm{PW} - \mathrm{PW_{min}}}{\mathrm{PW_{max}} - \mathrm{PW_{min}}}\]

Parameters

precipitable_water_daily_data: xarray.DataArray.

Daily precipitable water data.

time_dim: str.

The time coordinate dimension name.

Returns

Normalized precipitable water index (NPWI).

Reference

easyclimate.field.monsoon.find_PW_monsoon_region(precipitable_water_daily_data: xarray.DataArray, time_dim: str = 'time') → xarray.DataArray

The refined monsoon regions.

Note

To refine the definition of monsoon regions on a grid- cell-by-cell basis, we first compute the 10-yr-averaged monthly PW over each cell. Then we obtain the maximum monthly PW during the three summer months [e.g., June–August in the Northern Hemisphere (NH), denoted as PWw], and the maximum monthly PW during the three winter months (e.g., December–February for the NH, denoted as PWc). The refined monsoon regions are simply defined as grid cells that are within the monsoon regions given in the above studies and have a difference between PWw and PWc greater than 12 mm. Initially we have also tried to use the annual maximum and minimum monthly PW values.

Parameters

precipitable_water_daily_data: xarray.DataArray.

Daily precipitable water data.

time_dim: str.

The time coordinate dimension name.

Reference

Example(s) related to the function

Onset and Retreat of Monsoon

Onset and Retreat of Monsoon
easyclimate.field.monsoon.calc_NPWI_monsoon_onset(NPWI: xarray.DataArray, thresh: float = 0.618, consecutive_days: int = 3, n: int = 7, lon_dim: str = 'lon', lat_dim: str = 'lat', time_dim: str = 'time') → xarray.DataArray

Calculate the summer monsoon onset date.

The summer monsoon onset date for grid cell G is defined as the first day (\(d\)) when NWPI is greater than the Golden Ratio (0.618) for three consecutive days in seven of the nine cells centered at cell G in day \(d\) or (\(d \pm 1\)).

Note

If one or more of the nine grids are undefined, for example, at the edge of monsoon regions, the required number of seven is correspondingly reduced. For instance, if only seven grid cells are defined, the required number is five.

Parameters

NPWI: xarray.DataArray.

Normalized precipitable water index (NPWI).

Attention

It must include three dimensions: time, longitude, and latitude.

thresh: float, default: 0.618.

Golden Ratio value for the threshold value.

consecutive_days: int, default: 3.

Consecutive days values.

n: int, default: 7.

\(n\) of the nine cells centered at cell G in day \(d\) or (\(d \pm 1\)).

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default extracting is applied over the lon dimension.

time_dim: str, default: time.

The time coordinate dimension name.

Returns

Summer monsoon onset date.

Reference

Example(s) related to the function

Onset and Retreat of Monsoon

Onset and Retreat of Monsoon
easyclimate.field.monsoon.calc_NPWI_monsoon_retreat(NPWI: xarray.DataArray, monsoon_onset_date: xarray.DataArray, thresh: float = 0.618, consecutive_days: int = 3, n: int = 7, lon_dim: str = 'lon', lat_dim: str = 'lat', time_dim: str = 'time') → xarray.DataArray

Calculate the summer monsoon retreat date.

The summer monsoon retreat date for grid cell G is defined as the first day (\(d\)) when NWPI is less than the Golden Ratio (0.618) for three consecutive days in seven of the nine cells centered at cell G in day \(d\) or (\(d \pm 1\)).

Note

If one or more of the nine grids are undefined, for example, at the edge of monsoon regions, the required number of seven is correspondingly reduced. For instance, if only seven grid cells are defined, the required number is five.

Parameters

NPWI: xarray.DataArray.

Normalized precipitable water index (NPWI).

Attention

It must include three dimensions: time, longitude, and latitude.

monsoon_onset_date: xarray.DataArray.

Summer monsoon onset date. The results is generated by easyclimate.index.calc_NPWI_monsoon_onset.

thresh: float, default: 0.618.

Golden Ratio value for the threshold value.

consecutive_days: int, default: 3.

Consecutive days values.

n: int, default: 7.

\(n\) of the nine cells centered at cell G in day \(d\) or (\(d \pm 1\)).

lat_dim: str, default: lat.

Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

lon_dim: str, default: lon.

Longitude coordinate dimension name. By default extracting is applied over the lon dimension.

time_dim: str, default: time.

The time coordinate dimension name.

Returns

Summer monsoon retreat date.

Reference

Example(s) related to the function

Onset and Retreat of Monsoon

Onset and Retreat of Monsoon
easyclimate.field.monsoon.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.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.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.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.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.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.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.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"])

See also