API Reference

API Reference#

Core Features#

x4c.core.load_dataset(path, adjust_month=False, comp=None, grid=None, vn=None, **kws)#

Load a netCDF file and form a xarray.Dataset

Parameters:

  • path (str) – path to the netCDF file

  • adjust_month (bool) – adjust the month of the xarray.Dataset (the CESM1 output has a month shift)

  • comp (str) – the tag for CESM component, including “atm”, “ocn”, “lnd”, “ice”, and “rof”

  • grid (str) – the grid tag for the CESM output (e.g., ne16, g16)

  • vn (str) – variable name

x4c.core.open_mfdataset(paths, adjust_month=False, comp=None, grid=None, vn=None, **kws)#

Open multiple netCDF files and form a xarray.Dataset in a lazy load mode

Parameters:

  • path (str) – path to the netCDF file

  • adjust_month (bool) – adjust the month of the xarray.Dataset (the default CESM output has a month shift)

  • comp (str) – the tag for general CESM components, including “atm”, “ocn”, “lnd”, “ice”, and “rof”

  • grid (str) – the grid tag for the CESM output (e.g., ne16, g16)

  • vn (str) – variable name

class x4c.core.XDataset(ds=None)#
annualize(months=None, days_weighted=False, time2year=False)#

Annualize/seasonalize a xarray.Dataset

Parameters:

months (list of int) – a list of integers to represent month combinations, e.g., None means calendar year annualization, [7,8,9] means JJA annualization, and [-12,1,2] means DJF annualization

property da#

get its xarray.DataArray version

regrid(dlon=1, dlat=1, weight_file=None, gs='T', method='bilinear', periodic=True)#

Regrid the CESM output to a normal lat/lon grid

Supported atmosphere regridding: ne16np4, ne16pg3, ne30np4, ne30pg3, ne120np4, ne120pg4 TO 1x1d / 2x2d. Supported ocean regridding: any grid similar to g16 TO 1x1d / 2x2d. For any other regridding, weight_file must be provided by the user.

For the atmosphere grid regridding, the default method is area-weighted; while for the ocean grid, the default is bilinear.

Parameters:

  • dlon (float) – longitude spacing

  • dlat (float) – latitude spacing

  • weight_file (str) – the path to an ESMF-generated weighting file for regridding

  • gs (str) – grid style in ‘T’ or ‘U’ for the ocean grid

  • method (str) – regridding method for the ocean grid

  • periodic (bool) – the assumption of the periodicity of the data when perform the regrid method

class x4c.core.XDataArray(da=None)#
annualize(months=None, days_weighted=False)#

Annualize/seasonalize a xarray.DataArray

Parameters:

months (list of int) – a list of integers to represent month combinations, e.g., [7,8,9] means JJA annualization, and [-12,1,2] means DJF annualization

property ds#

get its xarray.Dataset version

geo_mean(ind=None, latlon_range=(-90, 90, 0, 360), **kws)#

The lat-weighted mean given a lat/lon range or a climate index name

Parameters:

  • latlon_range (tuple or list) – the lat/lon range for lat-weighted average in format of (lat_min, lat_max, lon_min, lon_max)

  • ind (str) –

    a climate index name; supported names include:

    • ’nino3.4’

    • ’nino1+2’

    • ’nino3’

    • ’nino4’

    • ’tpi’

    • ’wp’

    • ’dmi’

    • ’iobw’

get_plev(**kws)#

See: https://geocat-comp.readthedocs.io/en/v2024.04.0/user_api/generated/geocat.comp.interpolation.interp_hybrid_to_pressure.html

property gm#

the global area-weighted mean

property gs#

the global area-weighted sum

nearest2d(lat=None, lon=None, lat_coord='lat', lon_coord='lon', lat_dim='lat', lon_dim='lon')#

Select the nearest non-NaN grid point.

Parameters:

  • da – xarray.DataArray or Dataset

  • lat_name – names of coordinate variables in da

  • lon_name – names of coordinate variables in da

  • target_lat – float or 1D arrays of lat/lon values to match

  • target_lon – float or 1D arrays of lat/lon values to match

Returns:

xarray.DataArray or Dataset sliced at nearest grid points

property nhm#

the NH area-weighted mean

property nhs#

the NH area-weighted sum

plot(title=None, figsize=None, ax=None, latlon_range=None, add_clabels=False, clevels=None, clabel_kwargs=None, projection='Robinson', transform='PlateCarree', central_longitude=180, proj_args=None, bad_color='dimgray', add_gridlines=False, gridline_labels=True, gridline_style='--', ssv=None, log=False, vmin=None, vmax=None, coastline_zorder=99, coastline_width=1, site_markersizes=100, df_sites=None, colname_dict=None, gs='T', ux=False, site_marker_dict=None, site_color_dict=None, count_site_num=False, lgd_kws=None, legend=True, return_im=False, **kws)#

The plotting functionality

Parameters:

  • title (str) – figure title

  • figsize (tuple or list) – figure size in format of (w, h)

  • ax (matplotlib.axes) – a matplotlib.axes

  • latlon_range (tuple or list) – lat/lon range in format of (lat_min, lat_max, lon_min, lon_max)

  • projection (str) – a projection name supported by Cartopy

  • transform (str) – a projection name supported by Cartopy

  • central_longitude (float) – the central longitude of the map to plot

  • proj_args (dict) – other keyword arguments for projection

  • add_gridlines (bool) – if True, the map will be added with gridlines

  • gridline_labels (bool) – if True, the lat/lon ticklabels will appear

  • gridline_style (str) – the gridline style, e.g., ‘-’, ‘–’

  • ssv (xarray.DataArray) – a sea surface variable used for plotting the coastlines

  • gs (str) – grid style in ‘T’ or ‘U’ for the ocean grid

  • coastline_zorder (int) – the layer order for the coastlines

  • coastline_width (float) – the width of the coastlines

  • df_sites (pandas.DataFrame) – a pandas.DataFrame that stores the information of a collection of sites

  • colname_dict (dict) – a dictionary of column names for df_sites in the “key:value” format “assumed name:real name”

property shm#

the SH area-weighted mean

property shs#

the SH area-weighted sum

property somin#

the Southern Ocean min

property zm#

the zonal mean

CESM Diagnostics#

class x4c.case.Timeseries(root_dir, grid_dict=None, casename=None, cesm_ver=1)#

Initialize a CESM Timeseries case generated by CESM Postprocessing

Parameters:

  • root_dir (str) – the root directory of the CESM Timeseries output

  • grid_dict (dict) – the grid dictionary for different components

  • timestep (int) – the number of years stored in a single timeseries file

calc(spell: str, comp=None, timespan=None, load_idx=-1, recalculate=False, verbose=True)#

Calculate a diagnostic spell

clear_ds(vn=None)#

Clear the existing .ds property

get_climo(vn, comp=None, timespan=None, slicing=False, regrid=False, dlat=1, dlon=1)#

Generate the climatology file for the given variable

Parameters:

slicing (bool) – could be problematic

Contents