easyclimate ¶

easyclimate.calc_dy_laplacian(data_input: xarray.DataArray | xarray.Dataset, lat_dim: str = 'lat', min_dy2: float = 1.0, edge_order: int = 2, R: float = 6371200.0) → xarray.DataArray | xarray.Dataset¶

Calculation of the second-order partial derivative term (Laplace term) along latitude.

\[\frac{\partial^2 F}{\partial y^2} = \frac{1}{R^2} \cdot \frac{\partial^2 F}{\partial \varphi^2}\]

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The spatio-temporal data to be calculated.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.
min_dy2: float, default: 1.0.: The minimum acceptable value of \((\mathrm{d}y)^2\), below which parts will set nan to avoid large computational errors. The unit is m. You can set it to a negative value in order to remove this benefit.
edge_order: {1, 2}, optional: Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1.
R: float, default: 6370000.: Radius of the Earth.

Returns¶

The second-order partial derivative term (Laplace term) along latitude (xarray.DataArray or xarray.Dataset).

See also

easyclimate.calc_dxdy_mixed_derivatives(data_input: xarray.DataArray | xarray.Dataset, lon_dim: str = 'lon', lat_dim: str = 'lat', min_dxdy: float = 10000000000.0, edge_order: int = 2, R: float = 6371200.0) → xarray.DataArray | xarray.Dataset¶

Calculation of second-order mixed partial derivative terms along longitude and latitude.

\[\frac{\partial^2 F}{\partial x \partial y} = \frac{1}{R^2 \cos\varphi} \cdot \frac{\partial^2 F}{\partial \lambda \partial \varphi}\]

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The spatio-temporal data to be calculated.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.
min_dxdy: float, default: 1e10.: The minimum acceptable value of \(\mathrm{d}x\mathrm{d}y\), below which parts will set nan to avoid large computational errors. The unit is m. You can set it to a negative value in order to remove this benefit.
edge_order: {1, 2}, optional: Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1.
R: float, default: 6370000.: Radius of the Earth.

Returns¶

The second-order mixed partial derivative terms along longitude and latitude (xarray.DataArray or xarray.Dataset).

See also

easyclimate.calc_p_gradient(data_input: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar']) → xarray.DataArray¶

Calculate the gradient along the barometric pressure direction in the p-coordinate system.

\[\frac{\partial F}{\partial p}\]

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The spatio-temporal data to be calculated.
vertical_dim: str.: Vertical coordinate dimension name.
vertical_dim_units: str.: The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.

Returns¶

The gradient along the barometric pressure direction in the p-coordinate system (xarray.DataArray or xarray.Dataset).

See also

easyclimate.calc_time_gradient(data_input: xarray.DataArray, time_units: str, time_dim: str = 'time') → xarray.DataArray¶

Calculate the gradient along the time direction.

\[\frac{\partial F}{\partial t}\]

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The spatio-temporal data to be calculated.
time_units: str.: The unit corresponding to the time dimension value. Optional values are seconds, months, years and so on.
time_dim: str, default: time.: The time coordinate dimension name.

Returns¶

The gradient along the time direction (xarray.DataArray or xarray.Dataset).

Caution

The units for partial derivative of time are \(\mathrm{s^{-1}}\).

See also

calc_apparent_heat_source

easyclimate.calc_dxdy_laplacian(data_input: xarray.DataArray, lon_dim: str = 'lon', lat_dim: str = 'lat', R: float = 6371200.0, spherical_coord: bool = True) → xarray.DataArray¶

Calculate the horizontal Laplace term.

rectangular coordinates

\[\nabla^2 F = \frac{\partial^2 F}{\partial x^2} + \frac{\partial^2 F}{\partial y^2}\]

Spherical coordinates

\[\nabla^2 F = \frac{\partial^2 F}{\partial x^2} + \frac{\partial^2 F}{\partial y^2} - \frac{1}{R} \frac{\partial F}{\partial y} \tan \varphi\]

Parameters¶

data_input: xarray.DataArray.: The spatio-temporal data to be calculated.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.
R: float, default: 6370000.: Radius of the Earth.
spherical_coord: bool, default: True.: Whether or not to compute the horizontal Laplace term in spherical coordinates.

Returns¶

The horizontal Laplace term. (xarray.DataArray).

easyclimate.calc_shear_stretch_deform(u_data: xarray.DataArray, v_data: xarray.DataArray, lon_dim: str = 'lon', lat_dim: str = 'lat', edge_order: {1, 2} = 2, R: float = 6371200.0)¶

https://www.ncl.ucar.edu/Document/Functions/Contributed/shear_stretch_deform_cfd.shtml
Spensberger, C., & Spengler, T. (2014). A New Look at Deformation as a Diagnostic for Large-Scale Flow. Journal of the Atmospheric Sciences, 71(11), 4221-4234. https://doi.org/10.1175/JAS-D-14-0108.1

easyclimate.calc_eady_growth_rate(u_daily_data: xarray.DataArray, z_daily_data: xarray.DataArray, temper_daily_data: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar'], lat_dim: str = 'lat') → xarray.Dataset¶

Calculate the maximum Eady growth rate.

\[\sigma = 0.3098 \frac{f}{N} \frac{\mathrm{d} U}{\mathrm{d} z}\]

Caution

Eady growth rate (EGR) is a non-linear quantity. Hence, calc_eady_growth_rate should NOT be directly applied to monthly means variables. If a monthly climatology of EGR is desired, the EGR values at the high frequency temporal time steps should be calculated; then, use calculate monthly mean.

Parameters¶

u_daily_data: xarray.DataArray.: The zonal wind daily data.
z_daily_data: xarray.DataArray.: Daily atmospheric geopotential height.

Attention

The unit of z_daily_data should be meters, NOT \(\mathrm{m^2 \cdot s^2}\) which is the unit used in the representation of potential energy.

temper_data: xarray.DataArray.: Daily air temperature.
vertical_dim: str.: Vertical coordinate dimension name.
vertical_dim_units: str.: The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The maximum Eady growth rate (xarray.Dataset).

eady_growth_rate: The maximum Eady growth rate.
dudz: \(\frac{\mathrm{d} U}{\mathrm{d} z}\)
brunt_vaisala_frequency: Brunt-väisälä frequency.

See also

Eady, E. T. (1949). Long Waves and Cyclone Waves. Tellus, 1(3), 33–52. https://doi.org/10.3402/tellusa.v1i3.8507, https://www.tandfonline.com/doi/abs/10.3402/tellusa.v1i3.8507
Lindzen, R. S. , & Farrell, B. (1980). A Simple Approximate Result for the Maximum Growth Rate of Baroclinic Instabilities. Journal of Atmospheric Sciences, 37(7), 1648-1654. https://journals.ametsoc.org/view/journals/atsc/37/7/1520-0469_1980_037_1648_asarft_2_0_co_2.xml
Simmonds, I., and E.-P. Lim (2009), Biases in the calculation of Southern Hemisphere mean baroclinic eddy growth rate, Geophys. Res. Lett., 36, L01707, https://doi.org/10.1029/2008GL036320.
Sloyan, B. M., and T. J. O’Kane (2015), Drivers of decadal variability in the Tasman Sea, J. Geophys. Res. Oceans, 120, 3193–3210, https://doi.org/10.1002/2014JC010550.
eady_growth_rate -NCL
瞬变涡旋诊断量

easyclimate.calc_apparent_heat_source(u_data: xarray.DataArray, v_data: xarray.DataArray, omega_data: xarray.DataArray, temper_data: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar'], time_units: str, lon_dim='lon', lat_dim='lat', time_dim='time', c_p=1005.7) → xarray.DataArray¶

Calculate the apparent heat source.

\[Q_1 = C_p \frac{T}{\theta} \left( \frac{\partial \theta}{\partial t} + u \frac{\partial \theta}{\partial x} + v \frac{\partial \theta}{\partial y} + \omega \frac{\partial \theta}{\partial p} \right)\]

Parameters¶

u_data: xarray.DataArray.: The zonal wind data.
v_data: xarray.DataArray.: The meridional wind data.
omega_data: xarray.DataArray.: The vertical velocity data (\(\frac{\mathrm{d} p}{\mathrm{d} t}\)).
temper_data: xarray.DataArray.: Air temperature.
vertical_dim: str.: Vertical coordinate dimension name.
vertical_dim_units: str.: The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.
time_units: str.: The unit corresponding to the time dimension value. Optional values are seconds, months, years and so on.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.
time_dim: str.: The time coordinate dimension name.
c_p: float, default: 1005.7.: The specific heat at constant pressure of dry air.

Note

specific heat capacity - Glossary of Meteorology

Returns¶

The apparent heat source (xarray.DataArray).

See also

easyclimate.calc_total_diabatic_heating(u_data: xarray.DataArray, v_data: xarray.DataArray, omega_data: xarray.DataArray, temper_data: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar'], time_units: str, lat_dim='lat', lon_dim='lon', time_dim='time', c_p=1005.7) → xarray.DataArray¶

Calculate the total diabatic heating.

Calculated in exactly the same way as for the apparent heat source.

Parameters¶

u_data: xarray.DataArray.: The zonal wind data.
v_data: xarray.DataArray.: The meridional wind data.
omega_data: xarray.DataArray.: The vertical velocity data (\(\frac{\mathrm{d} p}{\mathrm{d} t}\)).
temper_data: xarray.DataArray.: Air temperature.
vertical_dim: str.: Vertical coordinate dimension name.
vertical_dim_units: str.: The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.
time_units: str.: The unit corresponding to the time dimension value. Optional values are seconds, months, years and so on.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.
time_dim: str, default: time.: The time coordinate dimension name.
c_p: float, default: 1005.7 (\(\mathrm{J \cdot kg^{-1} \cdot K^{-1}}\)).: The specific heat at constant pressure of dry air.

Note

specific heat capacity - Glossary of Meteorology

Returns¶

The total diabatic heating (xarray.DataArray).

See also

easyclimate.calc_apparent_moisture_sink(u_data: xarray.DataArray, v_data: xarray.DataArray, omega_data: xarray.DataArray, specific_humidity_data: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar'], time_units: str, specific_humidity_data_units: str, lon_dim='lon', lat_dim='lat', time_dim='time', latent_heat_of_condensation=2501000.0) → xarray.DataArray¶

Calculate the apparent moisture sink.

\[Q_2 = -L \left( \frac{\partial q}{\partial t} + u \frac{\partial q}{\partial x} + v \frac{\partial q}{\partial y} + \omega \frac{\partial q}{\partial p} \right)\]

Parameters¶

u_data: xarray.DataArray.

The zonal wind data.

v_data: xarray.DataArray.

The meridional wind data.

omega_data: xarray.DataArray.

The vertical velocity data (\(\frac{\mathrm{d} p}{\mathrm{d} t}\)).

specific_humidity_data: xarray.DataArray.

The absolute humidity data.

vertical_dim: str.

Vertical coordinate dimension name.

vertical_dim_units: str.

The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.

time_units: str.

The unit corresponding to the time dimension value. Optional values are seconds, months, years and so on.

specific_humidity_data_units: str.

The unit corresponding to specific_humidity value. Optional values are kg/kg, g/kg and so on.

lon_dim: str, default: lon.

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

lat_dim: str, default: lat.

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

time_dim: str, default: time.

The time coordinate dimension name.

latent_heat_of_condensation: float, default: 2.5008e6 (\(\mathrm{J \cdot kg^{-1}}\)).

Latent heat of condensation of water at 0°C.

Note

Returns¶

The apparent moisture sink (xarray.DataArray).

See also

easyclimate.calc_Plumb_wave_activity_horizontal_flux(z_prime_data: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar'], lon_dim='lon', lat_dim='lat', omega=7.292e-05, g=9.8, R=6370000) → xarray.Dataset¶

Calculate Plumb wave activity horizontal flux.

Parameters¶

z_prime_data: xarray.DataArray.: The anormaly of atmospheric geopotential height.
vertical_dim: str.: Vertical coordinate dimension name.
vertical_dim_units: str.: The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.
omega: float, default: 7.292e-5.: The angular speed of the earth.
g: float, default: 9.8.: The acceleration of gravity.
R: float, default: 6370000.: Radius of the Earth.

Returns¶

The Plumb wave activity horizontal flux (xarray.DataArray).

See also

Plumb, R. A., 1985: On the Three-Dimensional Propagation of Stationary Waves. J. Atmos. Sci., 42, 217–229

easyclimate.calc_TN_wave_activity_horizontal_flux(z_prime_data: xarray.DataArray | None, u_climatology_data: xarray.DataArray, v_climatology_data: xarray.DataArray, vertical_dim: str, vertical_dim_units: Literal['hPa', 'Pa', 'mbar'], psi_prime_data: xarray.DataArray | None = None, lon_dim: str = 'lon', lat_dim: str = 'lat', time_dim: str = 'time', omega: float = 7.292e-05, g: float = 9.8, R: float = 6371200.0) → xarray.Dataset¶

Calculate TN wave activity horizontal flux.

\[\begin{split}\mathbf{W_h} = \frac{p\cos\varphi}{2\lvert \mathbf{U_c} \rvert}\begin{pmatrix} \frac{U_c}{R^2 \cos^2 \varphi} \left[ \left( \frac{\partial \psi'}{\partial \lambda} \right)^2 - \psi'\frac{\partial^2 \psi'}{\partial \lambda^2} \right] + \frac{V_c}{R^2 \cos \varphi} \left[ \frac{\partial \psi'}{\partial \lambda} \frac{\partial \psi'}{\partial \varphi} - \psi' \frac{\partial^2 \psi'}{\partial \lambda \partial \varphi} \right] \\ \frac{U_c}{R^2 \cos \varphi} \left[ \frac{\partial \psi'}{\partial \lambda} \frac{\partial \psi'}{\partial \varphi} - \psi' \frac{\partial^2 \psi'}{\partial \lambda \partial \varphi} \right] + \frac{V_c}{R^2} \left[ \left( \frac{\partial \psi'}{\partial \varphi} \right)^2 - \psi'\frac{\partial^2 \psi'}{\partial \varphi^2} \right] \\ \end{pmatrix}\end{split}\]

Parameters¶

z_prime_data: xarray.DataArray.: The anormaly of atmospheric geopotential height.

Attention

The unit of z_prime_data should be meters, NOT \(\mathrm{m^2 \cdot s^2}\) which is the unit used in the representation of potential energy.

u_climatology_data: xarray.DataArray.: The climatology of zonal wind data.
v_climatology_data: xarray.DataArray.: The climatology of meridional wind data.
vertical_dim: str.: Vertical coordinate dimension name.
vertical_dim_units: str.: The unit corresponding to the vertical p-coordinate value. Optional values are hPa, Pa, mbar.
psi_prime_data: xarray.DataArray.: Perturbation stream function. Geostrophic stream function perturbation calculated from geopotential height anomaly.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.
omega: float, default: 7.292e-5.: The angular speed of the earth.
g: float, default: 9.8.: The acceleration of gravity.
R: float, default: 6370000.: Radius of the Earth.

Returns¶

The TN wave activity horizontal flux (xarray.Dataset).

Reference¶

Takaya, K., & Nakamura, H. (2001). A Formulation of a Phase-Independent Wave-Activity Flux for Stationary and Migratory Quasigeostrophic Eddies on a Zonally Varying Basic Flow. Journal of the Atmospheric Sciences, 58(6), 608-627. https://journals.ametsoc.org/view/journals/atsc/58/6/1520-0469_2001_058_0608_afoapi_2.0.co_2.xml

See also

easyclimate.calc_EP_horizontal_flux(u_prime_data: xarray.DataArray, v_prime_data: xarray.DataArray, time_dim: str = 'time', lat_dim: str = 'lat') → xarray.Dataset¶

Calculate horizontal Eliassen–Palm Flux.

Parameters¶

u_prime_data: xarray.DataArray.: The anormaly of zonal wind data.
v_prime_data: xarray.DataArray.: The anormaly of meridional wind data.
time_dim: str, default: time.: The time coordinate dimension name.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The Eliassen–Palm Flux (xarray.DataArray).

See also

easyclimate.calc_monthly_rossby_wave_source(u_data: xarray.DataArray, v_data: xarray.DataArray, u_climatology_data: xarray.DataArray, v_climatology_data: xarray.DataArray, lat_dim: str = 'lat', omega: float = 7.292e-05, R: float = 6371200.0) → xarray.DataArray¶

Calculate the Rossby wave source following Sardeshmukh and Hoskins (1988).

The Rossby wave source (RWS) represents the forcing term for stationary Rossby waves and is widely used to diagnose atmospheric teleconnections. It is decomposed into five terms representing different physical mechanisms:

\[S' = -\nabla \cdot (\mathbf{v}_\chi \zeta)' = \text{term1a} + \text{term1b} + \text{term2a} + \text{term2b} + \text{term3} + \text{term4} + \text{term5}\]

where:

term1a: \(-\bar{\zeta} \nabla \cdot \mathbf{v}'_\chi\) (stretching of climatological vorticity by divergent wind anomalies)
Term1b: \(-f \nabla \cdot \mathbf{v'_\chi}\) (Stretching of planetary vorticity by anomalous divergence)
term2a: \(-\mathbf{v}'_\chi \cdot \nabla\bar{\zeta}\) (advection of climatological vorticity by divergent wind anomalies)
term2b: \(-\beta v'_\chi\) (planetary vorticity advection, where \(\beta = \partial f/\partial y\))
term3: \(-\zeta' \nabla \cdot \bar{\mathbf{v}}_\chi\) (stretching of vorticity anomalies by climatological divergent wind)
term4: \(-\bar{\mathbf{v}}_\chi \cdot \nabla\zeta'\) (advection of vorticity anomalies by climatological divergent wind)
term5: \(-\nabla \cdot (\mathbf{v}'_\chi \zeta')\) (nonlinear term: divergence of transient vorticity flux)

where \(\mathbf{v}_\chi = (u_\chi, v_\chi)\) is the divergent (irrotational) wind component, \(\zeta\) is relative vorticity, overbar denotes climatology, and prime denotes anomaly.

Note

Anomalies are computed as deviations from the monthly climatology.
The planetary term (term6) represents the beta effect, which is important for Rossby wave propagation, especially in the tropics and subtropics.
Terms 1, 2, and 6 typically dominate the Rossby wave source.
Positive RWS indicates a cyclonic wave source; negative indicates anticyclonic.

Parameters¶

u_dataxarray.DataArray (\(\mathrm{m/s}\)): Zonal wind component. Must contain a ‘time’ dimension with monthly or higher frequency data. Expected dimensions: (time, lat, lon) or (time, level, lat, lon).
v_dataxarray.DataArray (\(\mathrm{m/s}\)): Meridional wind component. Must have the same dimensions as u_data.
u_climatology_dataxarray.DataArray (\(\mathrm{m/s}\)): Monthly climatology of zonal wind. Expected dimensions: (time, lat, lon) or (time, level, lat, lon), where time/month ranges from 1 to 12.
v_climatology_dataxarray.DataArray (\(\mathrm{m/s}\)): Monthly climatology of meridional wind. Must have the same dimensions as u_climatology_data.

Returns¶

resultxarray.Dataset

Dataset containing the Rossby wave source and its five decomposed terms:

RWS: Total Rossby wave source (sum of all terms)
term1a: Vorticity stretching by anomalous divergence
term1b: Stretching of planetary vorticity by anomalous divergence
term2a: Vorticity advection by anomalous divergent wind
term2b: Planetary vorticity advection (beta effect)
term3: Anomalous vorticity stretching by climatological divergence
term4: Anomalous vorticity advection by climatological divergent wind
term5: Nonlinear transient eddy term

All variables have units of \(\mathrm{s^{-2}}\) and retain the spatial/temporal dimensions of the input data.

See also

Sardeshmukh, P. D., & Hoskins, B. J. (1988). The generation of global rotational flow by steady idealized tropical divergence. Journal of the Atmospheric Sciences, 45(7), 1228-1251. https://journals.ametsoc.org/view/journals/atsc/45/7/1520-0469_1988_045_1228_tgogrf_2_0_co_2.xml, https://doi.org/10.1175/1520-0469(1988)045<1228:TGOGRF>2.0.CO;2

Examples¶

>>> # Calculate monthly climatology
>>> u_clim = u.groupby('time.month').mean('time')
>>> v_clim = v.groupby('time.month').mean('time')
>>>
>>> # Compute Rossby wave source
>>> rws_result = calc_rossby_wave_source(u, v, u_clim, v_clim)
>>>
>>> # Visualize the dominant terms
>>> rws_result['RWS'].sel(time='2015-12').plot()
>>> (rws_result['term1'] + rws_result['term2']).sel(time='2015-12').plot()

easyclimate.get_specific_years_data(data_input: xarray.DataArray | xarray.Dataset, year_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer years.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
year_array: list[int]: Year(s) to be extracted.
dimstr: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_months_data(data_input: xarray.DataArray | xarray.Dataset, month_array: numpy.array, dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer months.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
month_array: list[int]: Month(s) to be extracted.
dimstr: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_days_data(data_input: xarray.DataArray | xarray.Dataset, day_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer days.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
day_array: list[int]: Days(s) to be extracted.
dimstr: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_hours_data(data_input: xarray.DataArray | xarray.Dataset, hour_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer hours.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
hour_array: list[int]: Hour(s) to be extracted.
dimstr: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_minutes_data(data_input: xarray.DataArray | xarray.Dataset, minute_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer minutes.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
minute_array: list[int]: Minute(s) to be extracted.
dimstr: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_seconds_data(data_input: xarray.DataArray | xarray.Dataset, second_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer seconds.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
second_array: list[int]: Second(s) to be extracted.
dimstr: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_microseconds_data(data_input: xarray.DataArray | xarray.Dataset, microsecond_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer microseconds.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
microsecond_array: list[int]: Microsecond(s) to be extracted.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_nanoseconds_data(data_input: xarray.DataArray | xarray.Dataset, nanosecond_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer nanoseconds.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
nanosecond_array: list[int]: Nanosecond(s) to be extracted.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_specific_dayofweek_data(data_input: xarray.DataArray | xarray.Dataset, dayofweek_array: np.array(int) | List[int], dim: str = 'time') → xarray.DataArray | xarray.Dataset¶

Slicing and extracting the part of the data containing the specified year based on an array of given integer dayofweek.

Parameters¶

data_inputxarray.DataArray

xarray.DataArray to be extracted.

dayofweek_array: list[int]

The days of the week to be extracted.

The integer numbers correspond to the days of the week as follows.

Day of the week	Integer numbers
Monday	0
Tuesday	1
Wednesday	2
Thursday	3
Friday	4
Saturday	5
Sunday	6

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

Returns¶

easyclimate.get_yearmean_for_specific_months_data(data_input: xarray.DataArray | xarray.Dataset, month_array: np.array(int) | List[int], dim: str = 'time', **kwargs) → xarray.DataArray | xarray.Dataset¶

Get the annual average of certain months.

Parameters¶

data_inputxarray.DataArray: xarray.DataArray to be extracted.
month_array: list[int]: Month(s) to be extracted.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

scipy.stats.linregress.

easyclimate.get_year_exceed_index_upper_bound(data_input: xarray.DataArray, thresh: float, time_dim: str = 'time') → numpy.array¶

Extract the years under the specified threshold (upper bound) in the annual average index (one-dimensional data with only a time dimension).

Parameters¶

data_inputxarray.DataArray: The one-dimensional data with only a time dimension.
thresh: float.: The threshold value.
time_dim: str.: The time coordinate dimension name.

Returns¶

numpy.array.

easyclimate.get_year_exceed_index_lower_bound(data_input: xarray.DataArray, thresh: float, time_dim: str = 'time') → numpy.array¶

Extract the years under the specified threshold (lower bound) in the annual average index (one-dimensional data with only a time dimension).

Parameters¶

data_inputxarray.DataArray: The one-dimensional data with only a time dimension.
thresh: float.: The threshold value.
time_dim: str.: The time coordinate dimension name.

Returns¶

numpy.array.

easyclimate.get_time_exceed_index_upper_bound(data_input: xarray.DataArray, thresh: float, time_dim: str = 'time') → numpy.array¶

Extract the time under the specified threshold (upper bound) in the annual average index (one-dimensional data with only a time dimension).

Parameters¶

data_inputxarray.DataArray: The one-dimensional data with only a time dimension.
thresh: float.: The threshold value.
time_dim: str.: The time coordinate dimension name.

Returns¶

Time array.

easyclimate.get_time_exceed_index_lower_bound(data_input: xarray.DataArray, thresh: float, time_dim: str = 'time') → numpy.array¶

Extract the time under the specified threshold (lower bound) in the annual average index (one-dimensional data with only a time dimension).

Parameters¶

data_inputxarray.DataArray: The one-dimensional data with only a time dimension.
thresh: float.: The threshold value.
time_dim: str.: The time coordinate dimension name.

Returns¶

Time array.

easyclimate.open_muliti_dataset(files: str, dim: str, **kwargs) → xarray.Dataset¶

Open multiple netCDF files without the need for xarray’s necessary dimension checks

Parameters¶

ver1: Version number 1
ver2: Version number 2

Returns¶

int.

Note

If ver1<ver2, return -1; If ver1=ver2, return 0; If ver1>ver2, return 1.

Examples¶

>>> import easyclimate as ecl
>>> result = assert_compared_version("10.12.2.6.5", "10.12.2.6")
>>> print(result)
1

Note

easyclimate.calc_linregress_spatial(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', x: numpy.array = None, alternative: str = 'two-sided', returns_type: {'dataset_returns', 'dataset_vars'} = 'dataset_returns') → xarray.Dataset | xarray.DataTree¶

Calculate a linear least-squares regression (trend) for spatial data of time.

Parameters¶

data_input: xarray.DataArray or xarray.Dataset: xarray.DataArray or xarray.Dataset to be regression.
dim: str, default time.: Dimension(s) over which to apply linregress. By default linregress is applied over the time dimension.
x: numpy.array: Independent variable. If None, use np.arange(len(data_input[‘time’].shape[0])) instead.
returns_type: str, default ‘dataset_returns’.: Return data type.

Returns¶

resultLinregressResult Dataset

The return Dataset have following data_var:

slope: float: Slope of the regression line.
intercept: float: Intercept of the regression line.
rvalue: float: The Pearson correlation coefficient. The square of rvalue is equal to the coefficient of determination.
pvalue: float: The p-value for a hypothesis test whose null hypothesis is that the slope is zero, using Wald Test with t-distribution of the test statistic. See alternative above for alternative hypotheses.
stderr: float: Standard error of the estimated slope (gradient), under the assumption of residual normality.
intercept_stderr: float: Standard error of the estimated intercept, under the assumption of residual normality.

See also

easyclimate.calc_detrend_spatial(data_input: xarray.DataArray | xarray.Dataset, time_dim: str = 'time') → xarray.DataArray | xarray.DataTree¶

Remove linear trend along axis from data.

Parameters¶

data_input: xarray.DataArray: The spatio-temporal data of xarray.DataArray to be detrended.
time_dim: str: Dimension(s) over which to detrend. By default dimension is applied over the time dimension.

Returns¶

xarray.DataArray.

See also

scipy.signal.detrend.

easyclimate.calc_corr_spatial(data_input: xarray.DataArray, x: xarray.DataArray | numpy.ndarray, time_dim: str = 'time', method: Literal['scipy', 'xarray'] = 'xarray') → xarray.Dataset¶

Calculate Pearson correlation coefficients and corresponding p-values between spatial data and a time series using scipy.stats.pearsonr.

Parameters¶

data_inputxarray.DataArray

Input spatial data with dimensions (time, ...).

Note

NaN values are automatically skipped in calculations.

xxarray.DataArray or numpy.ndarray

Time series data with dimension (time,). Must have the same length as data_input’s time dimension.

Note

NaN values are automatically skipped in calculations.

time_dim: str

Dimension(s) over which to detrend. By default dimension is applied over the time dimension.

method{‘scipy’, ‘xarray’}, optional

Method used to compute correlations:

‘scipy’: Uses scipy.stats.pearsonr for direct calculation
‘xarray’: Uses xarray’s built-in correlation with t-test conversion (faster)

Default is ‘xarray’.

Returns¶

reg_coeff, corr & pvalue (xarray.Dataset)

reg_coeff: xarray.DataArray

Regression coefficient, in units of data_input per standard deviation of the index.

corrxarray.DataArray

Pearson correlation coefficients with dimensions. Values range from -1 to 1 where:

1: perfect positive correlation
-1: perfect negative correlation
0: no correlation

pvaluexarray.DataArray

Two-tailed p-values with dimensions. Small p-values (<0.05) indicate statistically significant correlations.

Examples¶

>>> data_input = xr.DataArray(np.random.rand(10, 3, 4),
...                           dims=['time', 'lat', 'lon'],
...                           coords={'time': pd.date_range('2000-01-01', periods=10)})
>>> x = xr.DataArray(np.random.rand(10), dims=['time'])
>>> corr_dataset = ecl.calc_corr_spatial(data_input, x)

See also

scipy.stats.pearsonr: The underlying correlation function used for calculations.

easyclimate.calc_leadlag_corr_spatial(data_input: xarray.DataArray, x: xarray.DataArray | numpy.ndarray, leadlag_array: numpy.array | List[int], time_dim: str = 'time', method: Literal['scipy', 'xarray'] = 'xarray')¶

Calculate Pearson correlation coefficients and corresponding p-values between spatial data and a time series with specified lead or lag shifts, using scipy.stats.pearsonr or xarray methods.

Parameters¶

data_inputxarray.DataArray

Input spatial data with dimensions (time, ...) representing spatial fields over time.

Note

NaN values are automatically skipped in calculations.

xxarray.DataArray or numpy.ndarray

Time series data with dimension (time,). Must have the same length as data_input’s time dimension.

Note

NaN values are automatically skipped in calculations.

leadlag_arraynumpy.ndarray or List[int]

Array or list of integers specifying the lead or lag shifts (in time steps) to apply to the time series x relative to data_input.

Positive values indicate a lag: the time series x is shifted forward in time (e.g., a value of +2 means x is delayed by 2 time steps relative to data_input).
Negative values indicate a lead: the time series x is shifted backward in time (e.g., a value of -2 means x leads data_input by 2 time steps).
A value of 0 means no shift (synchronous correlation).

Example: If leadlag_array = [-2, 0, 2], correlations are computed for \(x\) leading by 2 time steps, no shift, and lagging by 2 time steps, respectively.

time_dimstr

Name of the time dimension in data_input and x. Default is “time”.

method{‘scipy’, ‘xarray’}, optional

Method used to compute correlations:

‘scipy’: Uses scipy.stats.pearsonr for direct calculation, which may be more precise but slower.
‘xarray’: Uses xarray’s built-in correlation function with t-test conversion, which is typically faster.

Default is ‘xarray’.

Returns¶

resultxarray.Dataset

Dataset containing two variables:

corrxarray.DataArray
Pearson correlation coefficients with dimensions (leadlag, ...). Values range from -1 to 1, where: - 1 indicates a perfect positive correlation. - -1 indicates a perfect negative correlation. - 0 indicates no correlation.
pvaluexarray.DataArray
Two-tailed p-values with dimensions (leadlag, ...). Small p-values (<0.05) indicate statistically significant correlations.

Notes¶

The function iterates over each lead/lag value in leadlag_array, computes the correlation between the shifted x and data_input, and concatenates results along a new leadlag dimension.
Shifting x may introduce NaN values at the edges of the time series, which are handled automatically during correlation calculations.
Ensure data_input and x have compatible time dimensions to avoid errors.

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>> data = xr.DataArray(np.random.rand(100, 10, 10), dims=["time", "lat", "lon"])
>>> ts = xr.DataArray(np.random.rand(100), dims=["time"])
>>> leadlag = [-2, 0, 2]
>>> result = calc_leadlag_corr_spatial(data, ts, leadlag, time_dim="time", method="xarray")
>>> print(result)
Processing leadlag: 2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
<xarray.Dataset> Size: 7kB
Dimensions:    (leadlag: 3, lat: 10, lon: 10)
Coordinates:
* leadlag    (leadlag) int64 24B -2 0 2
Dimensions without coordinates: lat, lon
Data variables:
    reg_coeff  (leadlag, lat, lon) float64 2kB 0.006322 0.002647 ... -0.02781
    corr       (leadlag, lat, lon) float64 2kB 0.02141 0.00894 ... -0.09169
    pvalue     (leadlag, lat, lon) float64 2kB 0.8326 0.9297 ... 0.3053 0.3643

easyclimate.calc_multiple_linear_regression_spatial(y_data: xarray.DataArray, x_datas: List[xarray.DataArray], dim='time') → xarray.Dataset¶

Apply multiple linear regression to dataset across spatial dimensions.

\[y = a_1 x_1 + a_2 x_2 + \cdots\]

Parameters¶

y_dataxarray.DataArray: Dependent variable with dimensions, each with dimensions (time,).
x_dataslist of xarray.DataArray: List of independent variables, each with dimensions (time,).
dimstr, optional: Time dimension name (default: 'time')

Returns¶

xarray.Dataset

xarray.Dataset containing regression results with:

slopes: slope coefficients for each predictor (coef, lat, lon)
intercept: intercept values (lat, lon)
r_squared: coefficient of determination (lat, lon)
slopes_p: p-values for slope coefficients (coef, lat, lon)
intercept_p: p-values for intercept (lat, lon)

Raises¶

ValueError: If the time coordinates of input variables don’t match.

Notes¶

NaN and Inf values are omitted independently at each spatial point. If the remaining samples are insufficient for the requested predictors, the corresponding regression results are returned as NaN.

easyclimate.calc_ttestSpatialPattern_spatial(data_input1: xarray.DataArray, data_input2: xarray.DataArray, dim: str = 'time', equal_var: bool = True, alternative: Literal['two-sided', 'less', 'greater'] = 'two-sided', method: Literal['scipy', 'xarray'] = 'xarray') → xarray.Dataset¶

Calculate the T-test for the means of two independent sptial samples along with other axis (i.e. ‘time’) of scores.

Parameters¶

data_input1: xarray.DataArray: The first spatio-temporal data of xarray DataArray to be calculated.
data_input2: xarray.DataArray: The second spatio-temporal data of xarray DataArray to be calculated.

Note

The order of data_input1 and data_input2 has no effect on the calculation result.
The non-time dimensions of the two data sets must be exactly the same, and the dimensionality values must be arranged in the same order (ascending or descending).

dim: str

Dimension(s) over which to apply the test. By default the test is applied over the time dimension.

equal_var: bool

If True (default), perform a standard independent 2 sample test that assumes equal population variances (see https://en.wikipedia.org/wiki/T-test#Independent_two-sample_t-test). If False, perform Welch’s t-test, which does not assume equal population variance (see https://en.wikipedia.org/wiki/Welch%27s_t-test).

alternative{‘two-sided’, ‘less’, ‘greater’}, optional

Defines the alternative hypothesis. The following options are available (default is ‘two-sided’):

‘two-sided’: the means of the distributions underlying the samples are unequal.
‘less’: the mean of the distribution underlying the first sample is less than the mean of the distribution underlying the second sample.
‘greater’: the mean of the distribution underlying the first sample is greater than the mean of the distribution underlying the second sample.

method{‘scipy’, ‘xarray’}, optional

Method used to compute correlations:

‘scipy’: Uses scipy.stats.ttest_ind for direct calculation
‘xarray’: Uses xarray’s built-in method to calculate (faster)

Default is ‘xarray’.

Returns¶

statistic, pvalue: xarray.Dataset.

See also

scipy.stats.ttest_ind.

easyclimate.calc_windmask_ttestSpatialPattern_spatial(data_input1: xarray.Dataset, data_input2: xarray.Dataset, dim: str = 'time', u_dim: str = 'u', v_dim: str = 'v', mask_method: Literal['or', 'and'] = 'or', thresh: float = 0.05, equal_var: bool = True, alternative: Literal['two-sided', 'less', 'greater'] = 'two-sided', method: Literal['scipy', 'xarray'] = 'xarray')¶

Generate a significance mask for T-tests on the means of two independent spatial zonal (u) and meridional (v) wind samples, aggregated over the specified dimension (default ‘time’).

Parameters¶

data_input1xarray.Dataset: The first spatio-temporal data of xarray Dataset to be calculated. It is necessary to include the zonal wind component (u_dim) and the meridional wind component (v_dim).
data_input2xarray.Dataset: The second spatio-temporal data of xarray Dataset to be calculated. It is necessary to include the zonal wind component (u_dim) and the meridional wind component (v_dim).

Note

The order of data_input1 and data_input2 has no effect on the calculation result.
The non-time dimensions of the two data sets must be exactly the same, and the dimensionality values must be arranged in the same order (ascending or descending).

dimstr, default: time

Dimension(s) over which to apply the test. By default the test is applied over the time dimension.

u_dimstr, default: u

Variable name for the u velocity (zonal wind, in x direction).

v_dimstr, default: v

Variable name for the v velocity (meridional wind, in y direction).

mask_methodLiteral[“or”, “and”], default: “or”

Method to combine the significance masks for u and v components:

“or”: A grid point is considered significant if either the u or v component is significant (p <= thresh).
“and”: A grid point is considered significant if both the u and v components are significant (p <= thresh).

threshfloat, default: 0.05

The significance level (alpha) for the p-value threshold used to create the mask.

equal_varbool, default: True

alternative{‘two-sided’, ‘less’, ‘greater’}, optional=

Defines the alternative hypothesis. The following options are available (default is ‘two-sided’):

‘two-sided’: the means of the distributions underlying the samples are unequal.
‘less’: the mean of the distribution underlying the first sample is less than the mean of the distribution underlying the second sample.
‘greater’: the mean of the distribution underlying the first sample is greater than the mean of the distribution underlying the second sample.

method{‘scipy’, ‘xarray’}, optional

Method used to compute t-tests:

‘scipy’: Uses scipy.stats.ttest_ind for direct calculation
‘xarray’: Uses xarray’s built-in method to calculate (faster)

Default is ‘xarray’.

Returns¶

masked_pvaluexarray.DataArray: A boolean mask indicating significant regions (True where p <= thresh, combined via mask_method for u and v).

See also

scipy.stats.ttest_ind.

easyclimate.calc_levenetestSpatialPattern_spatial(data_input1: xarray.DataArray, data_input2: xarray.DataArray, dim: str = 'time', center: {'mean', 'median', 'trimmed'} = 'median', proportiontocut: float = 0.05) → xarray.Dataset¶

Perform Levene test for equal variances of two independent sptial samples along with other axis (i.e. ‘time’) of scores.

The Levene test tests the null hypothesis that all input samples are from populations with equal variances. Levene’s test is an alternative to Bartlett’s test in the case where there are significant deviations from normality.

Parameters¶

data_input1: xarray.DataArray.: The first spatio-temporal data of xarray DataArray to be calculated.
data_input2: xarray.DataArray.: The second spatio-temporal data of xarray DataArray to be calculated.

Note

The order of data_input1 and data_input2 has no effect on the calculation result.
The non-time dimensions of the two data sets must be exactly the same, and the dimensionality values must be arranged in the same order (ascending or descending).

dim: str.

Dimension(s) over which to apply the test. By default the test is applied over the time dimension.

center: {‘mean’, ‘median’, ‘trimmed’}, default ‘median’.

Which function of the data to use in the test.

Note

Three variations of Levene’s test are possible. The possibilities and their recommended usages are:

median: Recommended for skewed (non-normal) distributions.
mean: Recommended for symmetric, moderate-tailed distributions.
trimmed: Recommended for heavy-tailed distributions.

The test version using the mean was proposed in the original article of Levene (Levene, H., 1960) while the median and trimmed mean have been studied by Brown and Forsythe (Brown, M. B. and Forsythe, A. B., 1974), sometimes also referred to as Brown-Forsythe test.

proportiontocut: float, default 0.05.

When center is ‘trimmed’, this gives the proportion of data points to cut from each end (See scipy.stats.trim_mean).

Returns¶

statistic, pvalue: xarray.Dataset.

Reference¶

Levene, H. (1960). In Contributions to Probability and Statistics: Essays in Honor of Harold Hotelling, I. Olkin et al. eds., Stanford University Press, pp. 278-292.
Morton B. Brown & Alan B. Forsythe (1974) Robust Tests for the Equality of Variances, Journal of the American Statistical Association, 69:346, 364-367, DOI: https://doi.org/10.1080/01621459.1974.10482955

See also

scipy.stats.levene.

easyclimate.calc_skewness_spatial(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time') → xarray.Dataset | xarray.DataTree¶

Calculate the skewness of the spatial field on the time axis and its significance test.

The \(k\) th statistical moment about the mean is given by

\[m_k = \sum_{i=1}^{N} \frac{(x_i-\bar{x})^k}{N}\]

where \(x_i\) is the \(i\) th observation, \(\bar{x}\) the mean and \(N\) the number of observations.

One definition of the coefficient of skewness is

\[a_3 = \frac{m_3}{(m_2)^{3/2}}\]

Skewness is a measure of the asymmetry of a distribution and is zero for a normal distribution. If the longer wing of a distribution occurs for values of \(x\) higher than the mean, that distribution is said to have positive skewness. If thelonger wing occurs for values of \(x\) lower than the mean, the distribution is said to have negative skewness.

Parameters¶

data_input: xarray.DataArray: The spatio-temporal data of xarray DataArray to be calculated.
dim: str: Dimension(s) over which to apply skewness. By default skewness is applied over the time dimension.

Returns¶

skewness, pvalue: xarray.Dataset.

Reference¶

White, G. H. (1980). Skewness, Kurtosis and Extreme Values of Northern Hemisphere Geopotential Heights, Monthly Weather Review, 108(9), 1446-1455. Website: https://journals.ametsoc.org/view/journals/mwre/108/9/1520-0493_1980_108_1446_skaevo_2_0_co_2.xml

easyclimate.calc_kurtosis_spatial(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time') → xarray.DataArray | xarray.DataTree¶

Calculate the kurtosis of the spatial field on the time axis and its significance test.

The \(k\) th statistical moment about the mean is given by

\[m_k = \sum_{i=1}^{N} \frac{(x_i-\bar{x})^k}{N}\]

where \(x_i\) is the \(i\) th observation, \(\bar{x}\) the mean and \(N\) the number of observations.

The coefficient of kurtosis is defined by

\[a_4 = \frac{m_4}{(m_2)^{2}}\]

The kurtosis of a normal distribution is 3. If a distribution has a large central region which is flatter than a normal distribution with the same mean and variance, it has a kurtosis of less than 3. If the distribution has a central maximum more peaked and with longer wings than the equivalent normal distribution, its kurtosis is higher than 3 (Brooks and Carruthers, 1954). Extreme departures from the mean will cause very high values of kurtosis. Consequently, high kurtosis has been used as an indicator of bad data (Craddock and Flood, 1969). For the same reason, high values of kurtosis can be a result of one or two extreme events in a period of several years.

Parameters¶

data_input: xarray.DataArray: The spatio-temporal data of xarray DataArray to be calculated.
dim: str: Dimension(s) over which to apply kurtosis. By default kurtosis is applied over the time dimension.

Returns¶

kurtosis: xarray.DataArray.

Reference¶

Køie, M., Brooks, C.E., & Carruthers, N. (1954). Handbook of Statistical Methods in Meteorology. Oikos, 4, 202.

Craddock, J.M. and Flood, C.R. (1969), Eigenvectors for representing the 500 mb geopotential surface over the Northern Hemisphere. Q.J.R. Meteorol. Soc., 95: 576-593. doi: https://doi.org/10.1002/qj.49709540510

See also

scipy.stats.kurtosis.

easyclimate.calc_theilslopes_spatial(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', x=None, alpha: float = 0.95, method: {'joint', 'separate'} = 'separate', returns_type: {'dataset_returns', 'dataset_vars'} = 'dataset_returns') → xarray.Dataset | xarray.DataTree¶

Computes the Theil-Sen estimator.

Theilslopes implements a method for robust linear regression. It computes the slope as the median of all slopes between paired values.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset

xarray.DataArray or xarray.Dataset to be regression.

dim: str, default time.

Dimension(s) over which to apply linregress. By default linregress is applied over the time dimension.

x: numpy.array

Independent variable. If None, use np.arange(len(data_input[‘time’].shape[0])) instead.

alpha: float, default 0.95.

Confidence degree between 0 and 1. Default is 95% confidence. Note that alpha is symmetric around 0.5, i.e. both 0.1 and 0.9 are interpreted as “find the 90% confidence interval”.

method: {‘joint’, ‘separate’}, default ‘separate’.

Method to be used for computing estimate for intercept. Following methods are supported,

joint: Uses np.median(y - slope * x) as intercept.
separate: Uses np.median(y) - slope * np.median(x) as intercept.

returns_type: str, default ‘dataset_returns’.

Return data type.

Returns¶

resultTheilslopesResult Dataset

The return Dataset have following data_var:

slope: float: Theil slope.
intercept: float: Intercept of the Theil line.
low_slope: float: Lower bound of the confidence interval on slope.
high_slope: float: Upper bound of the confidence interval on slope.

See also

scipy.stats.theilslopes.

easyclimate.calc_lead_lag_correlation_coefficients(pcs: dict, pairs: List[tuple], max_lag: int) → xarray.Dataset¶

Compute lead-lag correlation coefficients for specified pairs of indexes.

This function calculates the cross-correlation between pairs of time series (e.g., MJO/BSISO principal components PC1 vs. PC2) to determine their lead-lag relationships. The correlation coefficients are computed for a range of lags, and the maximum correlation and corresponding lag are stored as attributes in the output dataset.

Parameters¶

pcspy:class:dict <dict>: Dictionary mapping PC names (e.g., ‘PC1’, ‘PC2’) to xarray.DataArray objects, where each DataArray represents a principal component time series with a 'time' dimension.
pairspy:class:list <list> of tuples: List of tuples, where each tuple contains (pair_name, pc_name1, pc_name2). For example, [(‘PC1_vs_PC2’, ‘PC1’, ‘PC2’), (‘PC3_vs_PC4’, ‘PC3’, ‘PC4’)].
max_lagpy:class:int <int>: Maximum lag (in time steps) to consider for the cross-correlation. The function computes correlations for lags from -max_lag to +max_lag.

Returns¶

corr_daxarray.Dataset: Dataset containing correlation coefficients for each pair, with a ‘lag’ dimension. Each variable (e.g., ‘PC1_vs_PC2’) has attributes 'max_correlation' (float) and 'lag_at_max_correlation' (int) indicating the maximum correlation and the lag at which it occurs.

Notes¶

Positive lags indicate that the first PC leads the second; negative lags indicate the opposite.
The input PCs should have no missing values. Use fillna or interpolate_na if needed.
The correlation coefficients are normalized to range between \(-1\) and \(1\).

easyclimate.calc_timeseries_correlations(da: dict[str, xarray.DataArray] | list[xarray.DataArray], dim: str = 'time') → xarray.DataArray¶

Calculate the correlation matrix between multiple DataArray time series.

This function calculates pairwise correlations between time series in the input DataArrays using the specified correlation method along the given dimension. The output is a symmetric correlation matrix stored as an xarray DataArray with dimensions (var1, var2).

Parameters¶

dadict[str, xarray.DataArray<xarray.DataArray>] or list[xarray.DataArray<xarray.DataArray>].: A dictionary with names as keys and DataArrays as values, or a list of DataArrays. Each DataArray must contain the specified dimension.
dimstr, default: time.: The dimension along which to compute correlations. All DataArrays must have this dimension.

Returns¶

xarray.DataArray.: A DataArray containing the correlation matrix with dimensions (var1, var2). Coordinates are set to the names of the input time series.

Examples¶

>>> time = pd.date_range('2020-01-01', '2020-12-31', freq='D')
>>> da1 = xr.DataArray(np.random.randn(len(time)), dims='time', coords={'time': time}, name='series1')
>>> da2 = xr.DataArray(da1 * 0.5 + np.random.randn(len(time)) * 0.5, dims='time', coords={'time': time}, name='series2')
>>> data = {'series1': da1, 'series2': da2}
>>> corr_matrix = calc_timeseries_correlations(data, method='pearson')
>>> print(corr_matrix)

easyclimate.calc_non_centered_corr(data_input1, data_input2, dim=None)¶

Compute the non-centered (uncentered) correlation coefficient between two xarray DataArrays. This is equivalent to the cosine similarity, calculated as the sum of the product of the two arrays divided by the product of their L2 norms (Euclidean norms), without subtracting the means.

The formula is:

\[r = \frac{\sum (x \cdot y)}{\sqrt{\sum x^2} \cdot \sqrt{\sum y^2}}\]

Parameters¶

data_input1xarray.DataArray: The first input data array to be correlated.
data_input2xarray.DataArray: The second input data array to be correlated.

Note

Both inputs must be xarray DataArray objects.
The arrays must have compatible shapes: if dim is specified, it must be a shared dimension; if dim is None, all dimensions are flattened into a single vector for computation.
The result is set to 0 where the denominator (product of norms) is zero to avoid division by zero.

dimstr or None, optional: Dimension(s) over which to compute the correlation. If None (default), the arrays are flattened across all dimensions into a single vector before computation. If a string, the correlation is computed along the specified dimension, preserving other dimensions.

Returns¶

corrxarray.DataArray: The non-centered correlation coefficient, with the same dimensions as the input arrays (or broadcasted appropriately).

See also

scipy.spatial.distance.cosine (for the related cosine distance metric).

Examples¶

Compute correlation along a dimension:

>>> import xarray as xr
>>> import numpy as np
>>> import easyclimate as ecl
>>> da1 = xr.DataArray(np.array([[1, 2], [3, 4]]), dims=['x', 'y'])
>>> da2 = xr.DataArray(np.array([[2, 3], [4, 5]]), dims=['x', 'y'])
>>> corr = ecl.calc_non_centered_corr(da1, da2, dim='y')
>>> print(corr)
<xarray.DataArray (x: 2)> Size: 16B
array([0.99227788, 0.99951208])

Flatten and compute scalar correlation:

>>> corr_flat = calc_non_centered_corr(da1, da2)
>>> print(corr_flat)
Dimensions without coordinates: x
<xarray.DataArray ()> Size: 8B
array(0.99380799)

easyclimate.calc_pattern_corr(data_input1: xarray.DataArray, data_input2: xarray.DataArray, time_dim: str = 'time')¶

Compute the pattern correlation (non-centered) between two xarray DataArrays over their common spatial dimensions. This is useful for comparing spatial patterns, such as in climate data.

It uses the non-centered correlation formula:

\[r = \frac{\sum (x \cdot y)}{\sqrt{\sum x^2} \cdot \sqrt{\sum y^2}}\]

where the summation is over the stacked spatial (pattern) dimensions.

The spatial pattern dimensions are automatically detected as the intersection of the input dimensions, excluding ‘time’ (if present). Both inputs are stacked along these pattern dimensions into a temporary ‘pattern’ dimension, and the non-centered correlation is computed along it.

If both inputs lack ‘time’, the result is a scalar.
If one input has ‘time’ and the other does not, the result preserves the ‘time’ dimension from the timed input.
Broadcasting occurs automatically for compatible shapes.

Parameters¶

data_input1xarray.DataArray: The first input data array (e.g., spatial pattern or time series of patterns).
data_input2xarray.DataArray: The second input data array (must have compatible spatial dimensions).
time_dim: str, default: time.: The time coordinate dimension name.

Returns¶

corrxarray.DataArray or scalar: The pattern correlation coefficient(s). Dimensions match the non-spatial dimensions of the inputs (e.g., ‘time’ if present in one input).

Note

Assumes inputs have compatible shapes and the only differing dimension is ‘time’.
Equivalent to cosine similarity over the spatial pattern.
For zero-norm cases, correlation is set to 0.

See also

pattern_cor -NCL
calc_non_centered_corr()

Examples¶

Scalar correlation between two spatial patterns:

>>> import xarray as xr
>>> import numpy as np
>>> import easyclimate as ecl
>>> # Create a random number generator with a fixed seed.
>>> rng = np.random.default_rng(42)
>>> pat1 = xr.DataArray(rng.random((2, 3)), dims=['lat', 'lon'])
>>> pat2 = xr.DataArray(rng.random((2, 3)), dims=['lat', 'lon'])
>>> pcc = ecl.calc_pattern_corr(pat1, pat2)
>>> print(pcc)
<xarray.DataArray 'pcc' ()> Size: 8B
array(0.85730639)
Attributes:
    long_name:  Pattern Correlation Coefficient (non-centered)
    units:      dimensionless

Time series correlation (one with time):

>>> # Create a random number generator with a fixed seed.
>>> rng = np.random.default_rng(42)
>>> time = xr.DataArray(np.arange(4), dims=['time'])
>>> timed_pat = xr.DataArray(rng.random((4, 2, 3)), dims=['time', 'lat', 'lon'])
>>> pcc_time = ecl.calc_pattern_corr(timed_pat, pat2)
>>> print(pcc_time)
<xarray.DataArray 'pcc' (time: 4)> Size: 32B
array([0.85730639, 1.        , 0.78188174, 0.88162673])
Dimensions without coordinates: time
Attributes:
    long_name:  Pattern Correlation Coefficient (non-centered)
    units:      dimensionless

easyclimate.remove_sst_trend(ssta: xarray.DataArray, spatial_dims: list[str] = ['lat', 'lon']) → xarray.DataArray¶

Remove the global mean SST anomaly trend from the SST anomaly field for EOF/PC analysis and so on.

This function computes the deviation of the SST anomaly at each grid point \((x, y)\) from the global-mean SST anomaly for the same time step \(t\), following the approach described in Zhang et al. (1997). The resulting field is:

\[\mathrm{SSTA}^*_{x,y,t} = \mathrm{SSTA}_{x,y,t} - [\mathrm{SSTA}]_t\]

where \([\mathrm{SSTA}]_t\) is the spatial mean over the specified dimensions for time \(t\). This removes the dominant global warming mode trend, avoiding unrealistic orthogonality constraints in subsequent PC analysis.

Parameters¶

sstaxarray.DataArray: The SST anomaly field with dimensions including ‘time’ and the spatial dimensions (e.g., ‘lat’, ‘lon’).
spatial_dimslist of str, optional: The spatial dimensions over which to compute the global mean. Default: [‘lat’, ‘lon’].

Returns¶

xarray.DataArray: The deviation SST anomaly field with the same shape and coordinates as the input.

Reference¶

Zhang, Y., Wallace, J. M., & Battisti, D. S. (1997). ENSO-like Interdecadal Variability: 1900-93. Journal of Climate, 10(5), 1004-1020. https://journals.ametsoc.org/view/journals/clim/10/5/1520-0442_1997_010_1004_eliv_2.0.co_2.xml

Examples¶

>>> import xarray as xr
>>> # Load or create an xarray Dataset with SST anomalies
>>> ds = xr.open_dataset('path_to_sst_data.nc')
>>> # Assume 'ssta' is the variable name for SST anomalies
>>> ssta_dev = remove_sst_tendency(ds['ssta'])
>>> print(ssta_dev)
<xarray.DataArray 'ssta' (time: 120, lat: 180, lon: 360)>
Coordinates:
  * time     (time) datetime64[ns] 1940-01-01 ... 2024-12-01
  * lat      (lat) float32 -89.5 -88.5 -87.5 ... 87.5 88.5 89.5
  * lon      (lon) float32 0.5 1.5 2.5 ... 357.5 358.5 359.5

easyclimate.calc_detrend_spatial_fast(data_input: xarray.DataArray, time_dim: str = 'time', min_valid_fraction: float = 0.5, method: Literal['scipy_reduce', 'scipy', 'numpy', 'rust', 'rust_chunked', 'rust_flexible', 'auto'] = 'auto', **kwargs) → xarray.DataArray¶

Remove linear trend along time dimension from spatio-temporal data.

Supports multiple computation methods with optional automatic selection.

Parameters¶

data_inputxr.DataArray: The spatio-temporal data to be detrended.
time_dimstr, default “time”: Name of the time dimension.
min_valid_fractionfloat, default 0.5: Minimum fraction of valid (finite) values required for detrending. Grid points with fewer valid values will be set to NaN.
methodstr, default ‘auto’: Computation method to use: - ‘scipy_reduce’: Simplified version using scipy.signal.detrend - ‘scipy’: Optimized version using scipy.signal.detrend - ‘numpy’: Manual numpy vectorized implementation - ‘rust’: High-performance Rust backend - ‘rust_chunked’: Rust backend with chunked processing (for large datasets) - ‘rust_flexible’: Rust backend with flexible dimension handling - ‘auto’: Automatically selects the best available method
**kwargsdict: Additional arguments passed to specific methods: - chunk_size: int (for ‘rust_chunked’ method) - use_chunked: bool (for ‘rust_chunked’ method)

Returns¶

xr.DataArray: Detrended data with same shape and coordinates as input.

Raises¶

TypeError: If data_input is not an xarray.DataArray.
ValueError: If input parameters are invalid.
ImportError: If Rust method is selected but Rust backend is not available.

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>>
>>> # Create sample data
>>> data = xr.DataArray(
...     np.random.randn(100, 50, 100),
...     dims=['time', 'lat', 'lon']
... )
>>>
>>> # Using scipy method
>>> result1 = calc_detrend_spatial_fast(data, method='scipy')
>>>
>>> # Using numpy method
>>> result2 = calc_detrend_spatial_fast(data, method='numpy')
>>>
>>> # Using Rust method (if available)
>>> try:
>>>     result3 = calc_detrend_spatial_fast(data, method='rust')
>>> except ImportError:
>>>     print("Rust backend not available")
>>>
>>> # Automatic method selection
>>> result4 = calc_detrend_spatial_fast(data, method='auto')

Notes¶

‘scipy_reduce’: Simplest method but less robust with NaN values
‘scipy’: Optimized scipy version with better special value handling
‘numpy’: Manual vectorized implementation, typically 2-3x faster than scipy
‘rust’: High-performance Rust implementation, typically 10-50x faster than numpy
‘rust_chunked’: Rust chunked version for large memory datasets
‘rust_flexible’: Rust version with flexible dimension ordering
‘auto’: Uses ‘rust’ if available, otherwise ‘numpy’

easyclimate.calc_monthly_mean(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate monthly mean.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same month it is:

\[o(t, x) = \mathrm{mean} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is daily.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>> import pandas as pd
>>> import easyclimate as ecl
>>> # Create sample data with daily frequency
>>> time_index = pd.date_range('2020-01-01', '2020-03-31', freq='D')
>>> rng = np.random.default_rng(42)
>>> data = rng.random((len(time_index), 3, 3))
>>> da = xr.DataArray(data, dims=['time', 'x', 'y'], coords={'time': time_index})
>>> # Calculate monthly mean
>>> monthly_mean = ecl.calc_monthly_mean(da)
>>> print(monthly_mean)
<xarray.DataArray (time: 3, x: 3, y: 3)> Size: 216B
array([[[0.50635175, 0.45767908, 0.50271707],
        [0.52091523, 0.44830133, 0.44293946],
        [0.47944591, 0.53314083, 0.48073062]],
    [[0.53431127, 0.48259521, 0.47464862],
        [0.41070456, 0.51619935, 0.4872374 ],
        [0.6009132 , 0.43963445, 0.6028882 ]],
    [[0.48363606, 0.60589154, 0.42622008],
        [0.47519641, 0.46989711, 0.45327877],
        [0.44193025, 0.45050389, 0.641573  ]]])
Coordinates:
* time     (time) datetime64[ns] 24B 2020-01-01 2020-02-01 2020-03-01
Dimensions without coordinates: x, y

easyclimate.calc_monthly_sum(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate monthly sum.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same month it is:

\[o(t, x) = \mathrm{sum} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is daily.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>> import pandas as pd
>>> import easyclimate as ecl
>>> # Create sample data with daily frequency
>>> time_index = pd.date_range('2020-01-01', '2020-03-31', freq='D')
>>> rng = np.random.default_rng(42)
>>> data = rng.random((len(time_index), 3, 3))
>>> da = xr.DataArray(data, dims=['time', 'x', 'y'], coords={'time': time_index})
>>> # Calculate monthly sum
>>> monthly_sum = ecl.calc_monthly_sum(da)
>>> print(monthly_sum)
<xarray.DataArray (time: 3, x: 3, y: 3)> Size: 216B
array([[[15.69690421, 14.18805154, 15.58422905],
        [16.14837203, 13.89734131, 13.7311233 ],
        [14.86282316, 16.52736588, 14.90264935]],
    [[15.49502686, 13.99526102, 13.76481005],
        [11.91043229, 14.96978113, 14.1298847 ],
        [17.42648281, 12.7493991 , 17.48375789]],
    [[14.99271788, 18.78263759, 13.21282259],
        [14.73108859, 14.56681052, 14.05164186],
        [13.69983774, 13.96562059, 19.88876291]]])
Coordinates:
* time     (time) datetime64[ns] 24B 2020-01-01 2020-02-01 2020-03-01
Dimensions without coordinates: x, y

easyclimate.calc_monthly_std(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate monthly standard deviation.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same month it is:

\[o(t, x) = \mathrm{std} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is daily.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>> import pandas as pd
>>> import easyclimate as ecl
>>> # Create sample data with daily frequency
>>> time_index = pd.date_range('2020-01-01', '2020-03-31', freq='D')
>>> rng = np.random.default_rng(42)
>>> data = rng.random((len(time_index), 3, 3))
>>> da = xr.DataArray(data, dims=['time', 'x', 'y'], coords={'time': time_index})
>>> # Calculate monthly std
>>> monthly_std = ecl.calc_monthly_std(da)
>>> print(monthly_std)
<xarray.DataArray (time: 3, x: 3, y: 3)> Size: 216B
array([[[0.30528844, 0.29905447, 0.26472868],
        [0.23456056, 0.30879525, 0.29333846],
        [0.26139562, 0.306974  , 0.27987361]],
    [[0.30196879, 0.24783961, 0.26078164],
        [0.2708643 , 0.3012602 , 0.29801453],
        [0.24816804, 0.33863555, 0.25623523]],
    [[0.29399346, 0.31595077, 0.30336434],
        [0.31117807, 0.3130123 , 0.28909393],
        [0.27104435, 0.26864038, 0.22912052]]])
Coordinates:
* time     (time) datetime64[ns] 24B 2020-01-01 2020-02-01 2020-03-01
Dimensions without coordinates: x, y

easyclimate.calc_monthly_var(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate monthly variance.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same month it is:

\[o(t, x) = \mathrm{var} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is daily.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>> import pandas as pd
>>> import easyclimate as ecl
>>> # Create sample data with daily frequency
>>> time_index = pd.date_range('2020-01-01', '2020-03-31', freq='D')
>>> rng = np.random.default_rng(42)
>>> data = rng.random((len(time_index), 3, 3))
>>> da = xr.DataArray(data, dims=['time', 'x', 'y'], coords={'time': time_index})
>>> # Calculate monthly var
>>> monthly_var = ecl.calc_monthly_var(da)
>>> print(monthly_var)
<xarray.DataArray (time: 3, x: 3, y: 3)> Size: 216B
array([[[0.09320103, 0.08943358, 0.07008127],
        [0.05501865, 0.09535451, 0.08604745],
        [0.06832767, 0.09423304, 0.07832924]],
    [[0.09118515, 0.06142447, 0.06800706],
        [0.07336747, 0.09075771, 0.08881266],
        [0.06158738, 0.11467404, 0.0656565 ]],
    [[0.08643216, 0.09982489, 0.09202992],
        [0.09683179, 0.0979767 , 0.0835753 ],
        [0.07346504, 0.07216766, 0.05249621]]])
Coordinates:
* time     (time) datetime64[ns] 24B 2020-01-01 2020-02-01 2020-03-01
Dimensions without coordinates: x, y

easyclimate.calc_monthly_max(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate monthly maximum.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same month it is:

\[o(t, x) = \mathrm{max} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is daily.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>> import pandas as pd
>>> import easyclimate as ecl
>>> # Create sample data with daily frequency
>>> time_index = pd.date_range('2020-01-01', '2020-03-31', freq='D')
>>> rng = np.random.default_rng(42)
>>> data = rng.random((len(time_index), 3, 3))
>>> da = xr.DataArray(data, dims=['time', 'x', 'y'], coords={'time': time_index})
>>> # Calculate monthly max
>>> monthly_max = ecl.calc_monthly_max(da)
>>> print(monthly_max)
<xarray.DataArray (time: 3, x: 3, y: 3)> Size: 216B
<xarray.DataArray (time: 3, x: 3, y: 3)> Size: 216B
array([[[0.96189766, 0.95855921, 0.93604357],
        [0.97182643, 0.97069802, 0.97562235],
        [0.99237556, 0.96623191, 0.91601185]],
    [[0.95119466, 0.88414571, 0.85053368],
        [0.94602445, 0.99910473, 0.99546447],
        [0.98002718, 0.98663154, 0.99703466]],
    [[0.989133  , 0.99874337, 0.99308458],
        [0.99032166, 0.98180595, 0.92746046],
        [0.99758004, 0.91879368, 0.99470175]]])
Coordinates:
* time     (time) datetime64[ns] 24B 2020-01-01 2020-02-01 2020-03-01
Dimensions without coordinates: x, y

easyclimate.calc_monthly_min(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate monthly minimum.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same month it is:

\[o(t, x) = \mathrm{min} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is daily.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

Examples¶

>>> import xarray as xr
>>> import numpy as np
>>> import pandas as pd
>>> import easyclimate as ecl
>>> # Create sample data with daily frequency
>>> time_index = pd.date_range('2020-01-01', '2020-03-31', freq='D')
>>> rng = np.random.default_rng(42)
>>> data = rng.random((len(time_index), 3, 3))
>>> da = xr.DataArray(data, dims=['time', 'x', 'y'], coords={'time': time_index})
>>> # Calculate monthly min
>>> monthly_min = ecl.calc_monthly_min(da)
>>> print(monthly_min)
<xarray.DataArray (time: 3, x: 3, y: 3)> Size: 216B
array([[[0.02280387, 0.02485949, 0.05338193],
        [0.02271207, 0.01783678, 0.02161208],
        [0.00736227, 0.04161417, 0.02114802]],
    [[0.0289995 , 0.04347506, 0.0401513 ],
        [0.01072764, 0.09172101, 0.01468284],
        [0.07205915, 0.01230269, 0.00542983]],
    [[0.0040076 , 0.0165798 , 0.00166071],
        [0.04896371, 0.01903415, 0.00123306],
        [0.04737402, 0.00450012, 0.22825288]]])
Coordinates:
* time     (time) datetime64[ns] 24B 2020-01-01 2020-02-01 2020-03-01
Dimensions without coordinates: x, y

easyclimate.calc_yearly_mean(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate yearly mean.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same year it is:

\[o(t, x) = \mathrm{mean} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Tip

This function uses xarray.DataArray.groupby to implement the calculation. To substantially improve the performance of GroupBy operations, particularly with dask install the flox package. flox extends Xarray’s in-built GroupBy capabilities by allowing grouping by multiple variables, and lazy grouping by dask arrays. If installed, Xarray will automatically use flox by default.

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is monthly.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

xarray.DataArray with time dimension type of numpy.datetime64.

easyclimate.calc_yearly_sum(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate yearly sum.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same year it is:

\[o(t, x) = \mathrm{sum} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Tip

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is monthly.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating sum on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

xarray.DataArray with time dimension type of numpy.datetime64.

easyclimate.calc_yearly_std(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate yearly standard deviation.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same year it is:

\[o(t, x) = \mathrm{std} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Tip

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is monthly.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating std on this object’s data. These could include dask-specific kwargs like split_every.

Note

The parameter ddof is Delta Degrees of Freedom: the divisor used in the calculation is N - ddof, where N represents the number of elements. If the data needs to be Normalize by (n-1), then ddof=1.

Returns¶

xarray.DataArray with time dimension type of numpy.datetime64.

easyclimate.calc_yearly_var(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate yearly standard deviation.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same year it is:

\[o(t, x) = \mathrm{var} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Tip

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is monthly.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating var on this object’s data. These could include dask-specific kwargs like split_every.

Note

The parameter ddof is Delta Degrees of Freedom: the divisor used in the calculation is N - ddof, where N represents the number of elements. If the data needs to be Normalize by (n-1), then ddof=1.

Returns¶

xarray.DataArray with time dimension type of numpy.datetime64.

easyclimate.calc_yearly_max(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate yearly standard deviation.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same year it is:

\[o(t, x) = \mathrm{max} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Tip

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is monthly.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating max on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

xarray.DataArray with time dimension type of numpy.datetime64.

easyclimate.calc_yearly_min(data_input: xarray.DataArray, dim: str = 'time', **kwargs)¶

Calculate yearly standard deviation.

For every adjacent sequence \(t_1, ..., t_n\) of timesteps of the same year it is:

\[o(t, x) = \mathrm{min} \left \lbrace i(t', x), t_1 < t' \leqslant t_n \right\rbrace\]

Tip

Parameters¶

data_input: xarray.DataArray.: xarray.DataArray to be calculated.

Note

The recommended frequence of the data_input is monthly.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating min on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

xarray.DataArray with time dimension type of numpy.datetime64.

easyclimate.calc_all_climatological_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the climatological mean over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

easyclimate.calc_seasonal_climatological_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the seasonal climatological mean over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.
dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

easyclimate.calc_seasonal_cycle_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the seasonal cycle means over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be monthly data.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

easyclimate.calc_seasonal_cycle_std(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the seasonal cycle standard deviation over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be monthly data.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating standard deviation on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

easyclimate.calc_seasonal_cycle_var(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the seasonal cycle standard deviation over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be monthly data.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating variance on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

easyclimate.calc_seasonal_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', extract_season: Literal['seasonly', 'DJF', 'MAM', 'JJA', 'SON', 'JJAS', 'OND'] = 'seasonly', **kwargs) → xarray.DataArray¶

Calculation of the seasonal means per year over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be monthly data.

dim: str

Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.

extract_season: list. default: “seasonly”.

Extraction seasons.

“seasonly”: Calculate by meteorological seasons (DJF, MAM, JJA, SON)
custom seasons: Calculate climatology by custom seasons, e.g., ‘DJF’, ‘MAM’, ‘JJA’, ‘SON’, 'JJAS', 'OND'.

Returns¶

easyclimate.remove_seasonal_cycle_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', time_range: slice = slice(None, None)) → xarray.DataArray¶

Remove of the seasonal cycle means over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset.: The data of xarray.DataArray to be calculated.

Caution

data_input must be monthly data.

dim: str.: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
time_range: slice, default: slice(None, None).: The time range of seasonal cycle means to be calculated. The default value is the entire time range.

Returns¶

Regression and Correlation Analyses

Example(s) related to the function¶

easyclimate.calc_monthly_climatological_std_without_seasonal_cycle_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculate the standard deviation of monthly data anomalies over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be monthly data.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating standard deviation on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

easyclimate.calc_monthly_climatological_var_without_seasonal_cycle_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculate the variance of monthly data anomalies over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray or xarray.Dataset to be calculated.

Caution

data_input must be monthly data.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed on to the appropriate array function for calculating variance on this object’s data. These could include dask-specific kwargs like split_every.

Returns¶

easyclimate.smooth_daily_annual_cycle(daily_annual_cycle_data: xarray.DataArray, harmonics_num: int = 3, time_dim: str = 'dayofyear') → xarray.DataArray¶

Calculates a smooth mean daily annual cycle for an array nominally dimensioned.

Parameters¶

daily_annual_cycle_dataxarray.DataArray: The input data array with time as the first dimension. The time dimension should be named as specified by time_dim.
harmonics_numint, optional: The number of harmonics to retain in the FFT. Default is 3.
time_dimstr, optional: The name of the time dimension in the DataArray. Default is “dayofyear”.

Returns¶

xarray.DataArray

The smoothed daily cycle data.

See also

https://www.ncl.ucar.edu/Document/Functions/Contributed/smthClmDayTLL.shtml

easyclimate.calc_daily_annual_cycle_mean(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the daily means per year over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be daily or hourly data. At least one year of time range must be included in the data_input.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed to the mean function.

Returns¶

Caution

For complete coverage, the data should span at least one full year.
If the data is sub-daily (e.g., hourly), the mean is taken over all sub-daily time points for each day of the year.

easyclimate.calc_daily_annual_cycle_std(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the daily standard deviation per year over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be daily or hourly data. At least one year of time range must be included in the data_input.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed to the standard deviation function.

Returns¶

Caution

For complete coverage, the data should span at least one full year.
If the data is sub-daily (e.g., hourly), the std is taken over all sub-daily time points for each day of the year.

easyclimate.calc_daily_annual_cycle_var(data_input: xarray.DataArray | xarray.Dataset, dim: str = 'time', **kwargs) → xarray.DataArray¶

Calculation of the daily variance per year over the entire time range.

Parameters¶

data_inputxarray.DataArray or xarray.Dataset: The data of xarray.DataArray to be calculated.

Caution

data_input must be daily or hourly data. At least one year of time range must be included in the data_input.

dim: str: Dimension(s) over which to apply extracting. By default extracting is applied over the time dimension.
**kwargs:: Additional keyword arguments passed to the variance function.

Returns¶

Caution

For complete coverage, the data should span at least one full year.
If the data is sub-daily (e.g., hourly), the var is taken over all sub-daily time points for each day of the year.

easyclimate.remove_smooth_daily_annual_cycle_mean(data_input: xarray.DataArray, daily_cycle_mean_time_range: slice = slice(None, None), extract_time_range: slice = slice(None, None), harmonics_num: int = 3, dim: str = 'time')¶

Removes the smooth daily annual cycle mean from the input data.

This function first calculates the daily cycle mean over a specified time range, smooths that mean using a specified number of harmonics, and then subtracts this smoothed cycle from the input data over another specified time range.

Parameters¶

data_inputxarray.DataArray: The input data from which to remove the smooth daily annual cycle mean.
daily_cycle_mean_time_rangeslice, optional: The time range used to compute the daily annual cycle mean. Default is all time.
extract_time_rangeslice, optional: The time range from which to extract the data and remove the daily annual cycle. Default is all time.
harmonics_numint, optional: The number of harmonics to use in smoothing the daily annual cycle mean. Default is 3.
dimstr, optional: The name of the time dimension. Default is “time”.

Returns¶

xarray.DataArray: The input data with the smooth daily cycle mean removed.

easyclimate.calc_horizontal_wind_components_std(uv_dataset: xarray.Dataset, u_dim='u', v_dim='v', time_dim='time', ddof=0) → xarray.Dataset¶

Calculate the standard deviation of vector wind speed and direction.

The standard deviation of vector wind speed

\[\sigma_s = [U^2 \sigma_u^2 + V^2 \sigma_v^2 + 2 U V \sigma_{uv}]^{1/2} S^{-1},\]

The standard deviation of vector wind direction

\[\sigma_d = [V^2 \sigma_u^2 + U^2 \sigma_v^2 + 2 U V \sigma_{uv}]^{1/2} S^{-2},\]

Where time mean of \(u\) is \(U = n^{-1} \sum u_i\), time mean of \(v\) is \(V = n^{-1} \sum v_i\), time variance of \(u\) is \(\sigma_u^2 = n^{-1} \sum u_{i}^{2} - U^2\), time variance of \(v\) is \(\sigma_v^2 = n^{-1} \sum v_{i}^{2} - V^2\), time covariance of \(u\), \(v\) is \(\sigma_{uv} = n^{-1} \sum u_i v_i - UV\), vector mean wind speed is \(S = (U^2 + V^2)^{1/2}\).

Parameters¶

uv_datasetxarray.Dataset: xarray.Dataset data containing zonal and meridional wind components.
u_dim: str, default: u: Variable name for the u velocity (in x direction).
v_dim: str, default: v: Variable name for the v velocity (in y direction).
time_dimstr, default: time: Dimension(s) over which to apply. By default is applied over the time dimension.
ddofint, default: 1: If ddof=1, covariance is normalized by N-1, giving an unbiased estimate, else normalization is by N.

Returns¶

xarray.Dataset

sigma_s: the standard deviation of vector wind speed.
sigma_d: the standard deviation of vector wind direction.

Reference¶

1. 1. Ackermann. (1983). Means and Standard Deviations of Horizontal Wind Components. https://doi.org/10.1175/1520-0450(1983)022%3C0959:MASDOH%3E2.0.CO;2

easyclimate.calc_windspeed_dataset(uv_dataset: xarray.Dataset, u_dim: str = 'u', v_dim: str = 'v') → xarray.Dataset¶

Calculate the horizontal wind speed from zonal and meridional wind components in a xarray.Dataset.

The wind speed is computed as the magnitude of the horizontal wind vector:

\[S = \sqrt{u^2 + v^2},\]

where \(u\) is the zonal wind component and \(v\) is the meridional wind component.

Parameters¶

uv_datasetxarray.Dataset: xarray.Dataset containing zonal and meridional wind components.
u_dimstr, default: u: Variable name for the zonal wind component (in x direction).
v_dimstr, default: v: Variable name for the meridional wind component (in y direction).

Returns¶

xarray.Dataset: A copy of the input dataset with an additional variable speed containing the wind speed.

Examples¶

>>> ds = xr.Dataset({"u": (("time",), [1, 2, 3]), "v": (("time",), [4, 5, 6])})
>>> ds_with_speed = calc_windspeed_dataset(ds, u_dim="u", v_dim="v")
>>> print(ds_with_speed["speed"])
<xarray.DataArray 'speed' (time: 3)> Size: 24B
array([4.12310563, 5.38516481, 6.70820393])
Dimensions without coordinates: time

easyclimate.calc_windspeed_dataarray(u_data: xarray.DataArray, v_data: xarray.DataArray) → xarray.DataArray¶

Calculate the horizontal wind speed from zonal and meridional wind components in xarray.DataArray.

The wind speed is computed as the magnitude of the horizontal wind vector:

\[S = \sqrt{u^2 + v^2},\]

where \(u\) is the zonal wind component and \(v\) is the meridional wind component.

Parameters¶

u_dataxarray.DataArray: xarray.DataArray containing the zonal wind component (in x direction).
v_dataxarray.DataArray: xarray.DataArray containing the meridional wind component (in y direction).

Returns¶

xarray.DataArray: A xarray.DataArray containing the wind speed.

Examples¶

>>> u = xr.DataArray([1, 2, 3], dims="time")
>>> v = xr.DataArray([4, 5, 6], dims="time")
>>> speed = calc_windspeed_dataarray(u, v)
>>> print(speed)
<xarray.DataArray (time: 3)> Size: 24B
array([4.12310563, 5.38516481, 6.70820393])
Dimensions without coordinates: time

easyclimate.populate_monmean2everymon(data_monthly: xarray.DataArray, data_climatology_monthly_data: xarray.DataArray = None, time_dim: str = 'time') → xarray.DataArray¶

Populate the data of each month using the monthly mean state of the data_monthly or given dataset.

Parameters¶

data_monthly: xarray.DataArray.: xarray.DataArray to be calculated.
data_climatology_monthly_data: xarray.DataArray, default None.: The monthly climatology dataset. If it is None, the climatology is derived from data_monthly.
time_dim: str, default: time.: The time coordinate dimension name.

Returns¶

easyclimate.populate_daymean2everyday(data_daily: xarray.DataArray, data_climatology_daily_data: xarray.DataArray = None, time_dim: str = 'time') → xarray.DataArray¶

Populate the data of each day using the daily mean state of the data_daily or given dataset.

Parameters¶

data_daily: xarray.DataArray.
xarray.DataArray to be calculated.
data_climatology_daily_data: xarray.DataArray, default None.
The daily climatology dataset. If it is None, the climatology is derived from data_monthly.
time_dim: str, default: time.
The time coordinate dimension name.

Returns¶

easyclimate.calc_daily_climatological_anomaly(data_daily: xarray.DataArray | xarray.Dataset, data_climatology_daily_data: xarray.DataArray | xarray.Dataset, timd_dim='time') → xarray.DataArray | xarray.Dataset¶

Calulate daily anomaly using the given dataset of climatological mean state .

data_daily: xarray.DataArray or xarray.Dataset.
xarray.DataArray to be calculated.
data_climatology_daily_data: xarray.DataArray or xarray.Dataset.
The daily climatology dataset.
time_dim: str, default: time.
The time coordinate dimension name.

Returns¶