arctichoke.plot

Submodules

Functions

set_cbar_lims(hv_overlay, cmin, cmax[, verbose])

Limit the colorbar range without changing the colors.

get_min_max(dataset[, var])

Get the minimum / maximum of the dataset.

get_latlon_names(dataset)

Get the latitude and longitude variable names of the dataset.

set_cbar_lims(hv_overlay, cmin, cmax[, verbose])

Limit the colorbar range without changing the colors.

make_title(dataset[, add_source_id, ...])

Create a title for the dataset for use in plots.

make_label(dataset[, var, add_name, add_units])

Create a label for the specified variable in the given dataset for use in plots.

get_limited_extent(map_projection[, map_bbox, n_samples])

Get the extent to which to limit a plot.

save_hvplot(hvplot_to_save, save_as)

Save an hvplot to file.

quadmesh_map(xr_data, var[, save_as, map_projection, ...])

Create an hvplot quadmesh map.

get_variable_name(dataset)

Get the variable name of the dataset.

verify_path(path)

Verify that the filepath exists.

make_title(dataset[, add_source_id, ...])

Create a title for the dataset for use in plots.

make_label(dataset[, var, add_name, add_units])

Create a label for the specified variable in the given dataset for use in plots.

get_limited_extent(map_projection[, map_bbox, n_samples])

Get the extent to which to limit a plot.

save_hvplot(hvplot_to_save, save_as)

Save an hvplot to file.

html_to_png(html_filename[, png_filename])

Save an html hvplot as a png.

get_field_mean(dataset[, save_as])

Get the field mean of the dataset.

list_variable_files(source_id, variable_id[, ...])

Get a list of data files for the specified variable for the specified model.

select_files_by_time(data_filepaths, start, end[, test])

Filter the list to be only the files in the given date range.

plot_seasonal_cycle(datasets[, variable_id, ...])

Plot a seasonal cycle of the dataset.

multi_seasonal_cycle([source_id, variable_ids, ...])

Plot multiple seasonal cycles of different datasets.

plot_time_series(dataset[, variable_id, plt_title, ...])

Plot a time series of the dataset.

sum_by_year(dataset[, attr_long_name, attr_units, ...])

Sum a dataset by year along the time axis.

trend_in_time(dataset[, var, time_dim, ...])

Find the trend for each grid cell along the time axis.

list_variable_files(source_id, variable_id[, ...])

Get a list of data files for the specified variable for the specified model.

quadmesh_map(xr_data, var[, save_as, map_projection, ...])

Create an hvplot quadmesh map.

make_trend_map(this_source_id, this_var, ...[, ...])

Plot the trends of the given data on a map.

Package Contents

arctichoke.plot.set_cbar_lims(hv_overlay: holoviews.core.overlay.Overlay, holoviews.element.raster.QuadMesh, cmin: int, float, cmax: int, float, verbose: bool = False, **kwargs)

Limit the colorbar range without changing the colors.

Set the limits of the colorbar in the given overlay object such that the displayed range of the colorbar is within those limits but the colors to which every value corresponds remains the same as the original. This is done by completely replacing the original colorbar with a new one where the range has been limited.

Parameters:

  • hv_overlay (holoviews.core.overlay.Overlay, holoviews.element.raster.QuadMesh) – The overlay object for which to construct the limited colorbar.

  • cmin (int, float) – The minimum display value for the colormap.

  • cmax (int, float) – The maximum display value for the colormap.

  • verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.

  • **kwargs – Keyword arguments to pass to bokeh.models.LinearColorMapper() and bokeh.models.ColorBar().

Returns:

fig – The figure containing the original plot and the new, limited colorbar.

Return type:

bokeh.plotting._figure.figure

Examples

>>> from arctichoke.plot.cbar_limits import set_cbar_lims
arctichoke.plot.get_min_max(dataset: str, xarray.DataArray, xarray.Dataset, var: str = None)

Get the minimum / maximum of the dataset.

Opens the given dataset, finds the given variable if xr.Dataset, returns the minimum / maximum values of that data.

Parameters:

  • dataset (str, xarray.DataArray, xarray.Dataset) – The dataset for which to determine the minimum / maximum values.

  • var (str, None, optional) – The variable in dataset for which to find the minimum / maximum. Default is None.

Returns:

  • var_min (int, float) – The minimum value of the data.

  • var_max (int, float) – The maximum value of the data.

Examples

>>> from arctichoke.dataset.example_dataset import make_example_dataset
>>> from arctichoke.dataset.get_min_max import get_min_max
>>> dataset = make_example_dataset(n=3)
>>> min, max = get_min_max(dataset, var='test_var')
>>> print('min:',min,'max:',max)
min: 0.0 max: 8.0
arctichoke.plot.get_latlon_names(dataset: str, xarray.DataArray, xarray.Dataset)

Get the latitude and longitude variable names of the dataset.

Opens the given dataset, checks the coordinates, and determines the name of the latitude and longitude variables. This will be either lat/lon or latitude/longitude.

Parameters:

dataset (str, xarray.DataArray, xarray.Dataset) – The dataset for which to determine the latitude and longitude names.

Returns:

  • lat_var (str) – The name of latitude variable in the dataset. This will be either lat or latitude.

  • lon_var (str) – The name of longitude variable in the dataset. This will be either lon or longitude.

Examples

>>> from arctichoke.dataset.grid_type import get_latlon_names
>>> get_latlon_names('/arctichoke_data/bergybits/data/CMIP6/HighResMIP/MOHC/HadGEM3-GC31-MM/hist-1950/r1i1p1f1/SImon/siconc/gn/v20170928/siconc_SImon_HadGEM3-GC31-MM_hist-1950_r1i1p1f1_gn_201401-201412.nc')
('lat', 'lon')
>>> get_latlon_names('/arctichoke_data/bergybits/data/CMIP6/HighResMIP/MOHC/HadGEM3-GC31-MM/hist-1950/r1i1p1f1/SImon/sithick/gn/v20170928/sithick_SImon_HadGEM3-GC31-MM_hist-1950_r1i1p1f1_gn_201401-201412.nc')
('latitude', 'longitude')
arctichoke.plot.set_cbar_lims(hv_overlay: holoviews.core.overlay.Overlay, holoviews.element.raster.QuadMesh, cmin: int, float, cmax: int, float, verbose: bool = False, **kwargs)

Limit the colorbar range without changing the colors.

Set the limits of the colorbar in the given overlay object such that the displayed range of the colorbar is within those limits but the colors to which every value corresponds remains the same as the original. This is done by completely replacing the original colorbar with a new one where the range has been limited.

Parameters:

  • hv_overlay (holoviews.core.overlay.Overlay, holoviews.element.raster.QuadMesh) – The overlay object for which to construct the limited colorbar.

  • cmin (int, float) – The minimum display value for the colormap.

  • cmax (int, float) – The maximum display value for the colormap.

  • verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.

  • **kwargs – Keyword arguments to pass to bokeh.models.LinearColorMapper() and bokeh.models.ColorBar().

Returns:

fig – The figure containing the original plot and the new, limited colorbar.

Return type:

bokeh.plotting._figure.figure

Examples

>>> from arctichoke.plot.cbar_limits import set_cbar_lims
arctichoke.plot.make_title(dataset: str, [str], xarray.Dataset, add_source_id: bool = True, add_experiment_id: bool = True, add_variant_label: bool = True, add_time_stamp: bool = True, **kwargs)

Create a title for the dataset for use in plots.

Assemble a title to be used in plots for this dataset based on the specified attributes.

Parameters:

  • dataset (str, list of str, xarray.Dataset) – The dataset for which to make a title.

  • add_source_id (bool, optional) – Whether to add the source ID to the title. Default is True.

  • add_experiment_id (bool, optional) – Whether to add the eperiment ID to the title. Default is True.

  • add_variant_label (bool, optional) – Whether to add the variant label to the title. Default is True.

  • add_time_stamp (bool, optional) – Whether to add the time stamp to the title. This is only done if the given dataset only has one time value. Default is True.

Returns:

dataset_title – The title for the dataset.

Return type:

str

Examples

>>> from arctichoke.plot.labes_and_titles import make_title
>>> example_file = '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc/gn/v20181212/siconc_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_200001-200012.nc'
>>> make_title(example_file)
'EC-Earth3P-HR hist-1950 r1i1p1f1 '
>>> import xarray as xr
>>> example_xr = xr.open_dataset(example_file).isel(time=6)
>>> make_title(example_xr)
'EC-Earth3P-HR hist-1950 r1i1p1f1 2000-07-16T12:00:00.000000000 '
arctichoke.plot.make_label(dataset: str, [str], xarray.DataArray, xarray.Dataset, var: str = None, add_name: bool = True, add_units: bool = True, **kwargs)

Create a label for the specified variable in the given dataset for use in plots.

Assemble a label to be used in plots on axes or colorbars for the specified variable in the given dataset based on the specified attributes.

Parameters:

  • dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset for which to make a label.

  • var (str, None, optional) – The variable in dataset for which to make a label. This is required if dataset is an xarray.Dataset. Default is None.

  • add_name (bool, optional) – Whether to add the variable name to the label. Default is True.

  • add_units (bool, optional) – Whether to add the units to the label. Default is True.

Returns:

dataset_label – The label for the dataset.

Return type:

str

Examples

>>> from arctichoke.plot.labes_and_titles import make_label
>>> example_file = '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc/gn/v20181212/siconc_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_200001-200012.nc'
>>> make_label(example_file, 'siconc')
'Sea Ice Area Fraction (Ocean Grid) (%) '
arctichoke.plot.get_limited_extent(map_projection: cartopy.crs.CRS, map_bbox: [float, float, float, float] = sps.NWP_BBOX, n_samples: int = 100, **kwargs)

Get the extent to which to limit a plot.

Using the given coordinates to define the corners of a bounding box, sample the edges, and project those points into the given projection.

Parameters:

  • map_projection (cartopy.crs.CRS) – The coordinate reference system from cartopy onto which the bounding box will be projected.

  • map_bbox (Array of float, optional) –

    An array of coordinates defining the bounding box of the map in the following format:

    • [LAT_MAX, LAT_MIN, LON_MAX, LON_MIN]

    Default is arctichoke.params.latlon_params.NWP_BBOX.

  • n_sample (int, optional) – The number of samples to take along the edges of the bounding box. Use a larger number for larger bounding boxes to reduce clipping. Default is 100.

  • **kwargs – Keyword arguments to handle extras that might have been passed by the function above this one.

Return type:

map_extent

Examples

>>>
arctichoke.plot.save_hvplot(hvplot_to_save, save_as: str)

Save an hvplot to file.

Save the given hvplot as either an html or png file in the outputs/ directory.

Parameters:

  • hvplot_to_save (A type of hvplot object) – The hvplot object to save to file.

  • save_as (str) – The file path within the outputs/ directory to which to save the plot. Must end in either .html or .png.

Return type:

None

Examples

>>>
arctichoke.plot.quadmesh_map(xr_data: xarray.Dataset, var: str, save_as: str = None, map_projection: str = 'NorthPolarStereo', map_bbox: [float, float, float, float] = sps.NWP_BBOX, clims: [int, float, int, float] = None, diverging_cbar: bool = False, verbose: bool = False, **kwargs)

Create an hvplot quadmesh map.

Plot a map of the given data using the hvplot.quadmesh() function.

Parameters:

  • xr_data (xarray.Dataset) – The dataset to plot.

  • var (str) – The variable in xr_data to plot.

  • save_as (str, None, optional) – The file name to pass to arctichoke.plot.save_hvplots.save_hvplot(). Default is None, which doesn’t save the plot to a file.

  • map_projection (str, optional) – A string naming the map projection to use in the plot. Must be one of the following: ‘NorthPolarStereo’, ‘Orthograpic’. Default is ‘NorthPolarStereo’.

  • map_bbox (Array of float, optional) –

    An array of coordinates defining the bounding box of the map in the following format:

    • [LAT_MAX, LAT_MIN, LON_MAX, LON_MIN]

    Default is arctichoke.params.latlon_params.NWP_BBOX.

  • clims (List or tuple of int, float, optional) – The limits to use in the colorbar. Note: This overrides the default method of limiting the colorbar range when diverging_cbar=True. Default is None, which uses the minimum / maximum values present in the data.

  • diverging_cbar (bool, optional) – Whether to use a diverging colormap on the colorbar. Default is False.

  • verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.

  • **kwargs – Keyword arguments to pass to hvplot.quadmesh() and arctichoke.plot.limit_extent.get_limited_extent()

Returns:

qm_map_plot – An overlay object which can be used to construct the plot.

Return type:

holoviews.core.overlay.Overlay

Examples

>>> import xarray as xr
>>> this_plot = hvplots.quadmesh_map(xr.open_dataset("data/areacello_Ofx_EC-Earth3P-HR_highres-future_r2i1p2f1_gn.nc", 'areacello')
>>> print(type(this_plot))
<class 'holoviews.core.overlay.Overlay'>
arctichoke.plot.get_variable_name(dataset: str, xarray.DataArray, xarray.Dataset)

Get the variable name of the dataset.

Opens the given dataset, checks the data variable attributes, and returns the variable name.

Parameters:

dataset (str, xarray.DataArray, xarray.Dataset) – The dataset for which to determine the variable name.

Returns:

var_name – The name of the variable

Return type:

str

Examples

>>> from arctichoke.dataset.grid_type import get_variable_name
arctichoke.plot.verify_path(path)

Verify that the filepath exists.

Check if the path to the data files exists and is valid. If not, raise an error.

Parameters:

path (str) – Relative path to the directory containing data files.

Raises:

FileNotFoundError – If the specified path does not exist.

Returns:

path – The verified path to the data files.

Return type:

str

Examples

>>> verify_path('README.md')
'README.md'
arctichoke.plot.make_title(dataset: str, [str], xarray.Dataset, add_source_id: bool = True, add_experiment_id: bool = True, add_variant_label: bool = True, add_time_stamp: bool = True, **kwargs)

Create a title for the dataset for use in plots.

Assemble a title to be used in plots for this dataset based on the specified attributes.

Parameters:

  • dataset (str, list of str, xarray.Dataset) – The dataset for which to make a title.

  • add_source_id (bool, optional) – Whether to add the source ID to the title. Default is True.

  • add_experiment_id (bool, optional) – Whether to add the eperiment ID to the title. Default is True.

  • add_variant_label (bool, optional) – Whether to add the variant label to the title. Default is True.

  • add_time_stamp (bool, optional) – Whether to add the time stamp to the title. This is only done if the given dataset only has one time value. Default is True.

Returns:

dataset_title – The title for the dataset.

Return type:

str

Examples

>>> from arctichoke.plot.labes_and_titles import make_title
>>> example_file = '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc/gn/v20181212/siconc_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_200001-200012.nc'
>>> make_title(example_file)
'EC-Earth3P-HR hist-1950 r1i1p1f1 '
>>> import xarray as xr
>>> example_xr = xr.open_dataset(example_file).isel(time=6)
>>> make_title(example_xr)
'EC-Earth3P-HR hist-1950 r1i1p1f1 2000-07-16T12:00:00.000000000 '
arctichoke.plot.make_label(dataset: str, [str], xarray.DataArray, xarray.Dataset, var: str = None, add_name: bool = True, add_units: bool = True, **kwargs)

Create a label for the specified variable in the given dataset for use in plots.

Assemble a label to be used in plots on axes or colorbars for the specified variable in the given dataset based on the specified attributes.

Parameters:

  • dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset for which to make a label.

  • var (str, None, optional) – The variable in dataset for which to make a label. This is required if dataset is an xarray.Dataset. Default is None.

  • add_name (bool, optional) – Whether to add the variable name to the label. Default is True.

  • add_units (bool, optional) – Whether to add the units to the label. Default is True.

Returns:

dataset_label – The label for the dataset.

Return type:

str

Examples

>>> from arctichoke.plot.labes_and_titles import make_label
>>> example_file = '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc/gn/v20181212/siconc_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_200001-200012.nc'
>>> make_label(example_file, 'siconc')
'Sea Ice Area Fraction (Ocean Grid) (%) '
arctichoke.plot.get_limited_extent(map_projection: cartopy.crs.CRS, map_bbox: [float, float, float, float] = sps.NWP_BBOX, n_samples: int = 100, **kwargs)

Get the extent to which to limit a plot.

Using the given coordinates to define the corners of a bounding box, sample the edges, and project those points into the given projection.

Parameters:

  • map_projection (cartopy.crs.CRS) – The coordinate reference system from cartopy onto which the bounding box will be projected.

  • map_bbox (Array of float, optional) –

    An array of coordinates defining the bounding box of the map in the following format:

    • [LAT_MAX, LAT_MIN, LON_MAX, LON_MIN]

    Default is arctichoke.params.latlon_params.NWP_BBOX.

  • n_sample (int, optional) – The number of samples to take along the edges of the bounding box. Use a larger number for larger bounding boxes to reduce clipping. Default is 100.

  • **kwargs – Keyword arguments to handle extras that might have been passed by the function above this one.

Return type:

map_extent

Examples

>>>
arctichoke.plot.save_hvplot(hvplot_to_save, save_as: str)

Save an hvplot to file.

Save the given hvplot as either an html or png file in the outputs/ directory.

Parameters:

  • hvplot_to_save (A type of hvplot object) – The hvplot object to save to file.

  • save_as (str) – The file path within the outputs/ directory to which to save the plot. Must end in either .html or .png.

Return type:

None

Examples

>>>
arctichoke.plot.html_to_png(html_filename: str, png_filename: str = None)

Save an html hvplot as a png.

Load a previously-saved html format plot from hvplot, launch a headless browser in which to load it, take a screenshot, and save it to a png file.

Parameters:

  • html_filename (str) – The file path within the outputs/ directory to the html file of the hvplot.

  • png_filename (str, None, optional) – The file path within the outputs/ directory to which to save the png image, or None.

Return type:

None

Examples

>>>
arctichoke.plot.get_field_mean(dataset: str, [str], xarray.DataArray, xarray.Dataset, save_as: str = None, **kwargs)

Get the field mean of the dataset.

Use the cdo function fldmean to take the field mean (the mean over the geographic area) of the given dataset.

Parameters:

  • dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset of which to take the field mean.

  • save_as (str, None, optional) – The file name to pass to cdo.fldmean(output=save_as). Default is None, which doesn’t save the dataset to a file.

  • **kwargs – Keyword arguments to pass to cdo.fldmean().

Returns:

fldmean_xr – A dataset of the field mean of the input data.

Return type:

xarray.Dataset

Examples

>>> from arctichoke.dataset.field_mean import get_field_mean
>>> fldmean_xr = get_field_mean('data/NWP_cdo_CLI_areacello_Ofx_EC-Earth3P-HR_highres-future_r2i1p2f1_gn.nc')
>>> fldmean_xr['areacello'].values[0]
(get_field_mean) `save_as`: None
array([1.3731426e+08], dtype=float32)
arctichoke.plot.list_variable_files(source_id: str, variable_id: str, with_modification: str = None, **kwargs)

Get a list of data files for the specified variable for the specified model.

Search for all the files for the given model and variable and return them in a list. This assumes the esgpull convention of subdirectories: data/project/activity_id/institution_id/source_id/experiment_id/variant_label/table_id/variable_id/gn/version/data_file.nc.

Parameters:

  • source_id (str) – The name of the source ID (model) for which to get the variable files.

  • variable_id (str) – The name of the variable ID for which to get the variable files.

  • with_modification (str, None, optional) – The prefix of a modification to the data files to find. Ex: trim_NWP_. If None, returns only the original files. Default is None.

  • **kwargs – Keyword arguments to pass to get_variable_path().

Returns:

data_filepaths – A list, sorted alphabetically, of the filepaths of the variable data files.

Return type:

List of str

Examples

>>> from arctichoke.path.find import list_variable_files
>>> list_variable_files(source_id = 'HadGEM3-GC31-HM', variable_id = 'areacello')
['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/MOHC/HadGEM3-GC31-HM/hist-1950/r1i1p1f1/Ofx/areacello/gn/v20190301/areacello_Ofx_HadGEM3-GC31-HM_hist-1950_r1i1p1f1_gn.nc']
>>> list_variable_files(source_id = 'EC-Earth3P-HR', variable_id = 'siage')
/workspace/src/arctichoke/path/find_data.py:399: UserWarning: (get_variable_path) More than one file path found: ['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siage', '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r2i1p2f1/SImon/siage', '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/siage']
Returning first result in list.
['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siage/gn/v20181212/siage_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195001-195012.nc',
...
'/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siage/gn/v20181212/siage_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_201401-201412.nc']
arctichoke.plot.select_files_by_time(data_filepaths: [str], start: str, int, end: str, int, test: bool = False)

Filter the list to be only the files in the given date range.

From the given list of datafiles, find the ones that are in between the given start and end dates and return those in a list. If the start and end are given as years, the returned list will include both the start and end years, if available.

Parameters:

  • data_filepaths (List of str) – A list, sorted alphabetically, of the filepaths of the variable data files.

  • start (str, int) – The start date of the time range, either a string in the format YYYY-MM-DD or an integer of a year.

  • end (str, int) – The end date of the time range, either a string in the format YYYY-MM-DD or an integer of a year.

  • test (bool, optional) – If True, the function skips verifying the data_filepaths exist for use in testing. Default is False.

Returns:

data_filepaths – A list, sorted alphabetically, of the filepaths in the date range.

Return type:

List of str

Examples

>>> from arctichoke.path.find import select_files_by_time
>>> select_files_by_time(source_id = 'HadGEM3-GC31-HM', variable_id = 'areacello')
['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/MOHC/HadGEM3-GC31-HM/hist-1950/r1i1p1f1/Ofx/areacello/gn/v20190301/areacello_Ofx_HadGEM3-GC31-HM_hist-1950_r1i1p1f1_gn.nc']
arctichoke.plot.plot_seasonal_cycle(datasets: [str, xarray.DataArray, xarray.Dataset], variable_id: str = None, take_mean: bool = False, ax: matplotlib.axes.Axes = None, plt_title: str = None, line_labels: [str] = None, line_styles: [str] = '-', xlims: [str, str] = None, ylims: [float, float] = None, c_map: [matplotlib.colors.ListedColormap] = mplcm.viridis_r, c_map_label: str = 'Year', save_as: str = None, test: bool = False, **kwargs)

Plot a seasonal cycle of the dataset.

Plots a seasonal cycle of the given dataset for the given variable, if applicable.

Parameters:

  • datasets (list of str, xarray.DataArray, xarray.Dataset) – A list of datasets for which to make a plot.

  • variable_id (str) – The name of the variable ID to plot.

  • take_mean (bool, optional) – Whether to take the mean for each month across all the years. Default is False.

  • ax (matplotlib.axes.Axes, optional) – The axes on which to plot the data. If None, a new figure is created. Default is None.

  • plt_title (str, None, optional) – The title to use for the plot. Default is None, which uses a default title for the plot.

  • line_labels (list of str, None, optional) – The labels to use for the lines that are plotted if take_mean = True. Default is None.

  • line_styles (list of str, None, optional) – The line styles to use for the lines that are plotted if take_mean = True. Default is ‘-’.

  • xlims (List of float, optional) –

    The limits to use for the x-axis on the plot in the following format:

    • [x_min, x_max]

    where x_min and x_max are strings in the format YYYY-MM-DD Default is None, which expands the x-axis to include all the data.

  • ylims (List of float, optional) –

    The limits to use for the y-axis on the plot in the following format:

    • [y_min, y_max]

    Default is None, which expands the y-axis to include all the data.

  • c_map (matplotlib.colors.ListedColormap, optional) – The color map to use for the different lines so their order is clearer. Default is matplotlib.cm.viridis_r, the reverse of viridis.

  • c_map_label (str, None, optional) – The label to use on the colorbar. If None, then the colorbar will have no label. Default is Year.

  • save_as (str, None, optional) – The name of the file to which to save the plot. Default is None, which doesn’t save the plot to a file.

  • test (bool, optional) – If True, the function exists before making a plot for use in testing. Default is False.

  • **kwargs – Keyword arguments to pass to xr.DataArray.plot().

Returns:

  • If test == False – fig ax

  • If test == True – dataset : xarray.DataArray

Examples

>>> from arctichoke.dataset.field_mean import get_field_mean
>>> fldmean_xr = get_field_mean('example_siconc_dataset.nc')
>>> from arctichoke.plot.seasonal_cycle import plot_seasonal_cycle
>>> plot_seasonal_cycle(dataset = fldmean_xr, variable_id = 'siconc')
arctichoke.plot.multi_seasonal_cycle(source_id: str = 'EC-Earth3P-HR', variable_ids: [str] = ['siconc', 'sithick'], experiment_ids: [str] = ['hist-1950'], time_bounds_lists: dict = {'hist-1950': [[1950, 1959], [2005, 2014]], 'highres-future': [[2015, 2024], [2041, 2050]]}, variant_labels=['r1i1p2f1', 'r2i1p2f1', 'r3i1p2f1'], super_title: str = None, fig_scale: int, float = 2, save_as: str = None, test: bool = False, **kwargs)

Plot multiple seasonal cycles of different datasets.

Plots a seasonal cycle for each combination of parameters. Different experiments get their own axes, as well as different variables. Multiple time bounds and variant labels are plotted on the same axes.

Parameters:

  • source_id (str) – The name of the source_id to specify the model to plot.

  • variable_ids (list of str) – The variable ID(s) to plot.

  • experiment_ids (list of str, optional) – The experiment(s) to plot. Default is [‘hist-1950’].

  • time_bounds_lists (dict, optional) – A dictionary of the time bounds within which to plot. Each key in the dictionary is the name of an experiment and each value is a list of pairs of years. These time bounds will be passed to select_files_by_time(). Default is shown above.

  • variant_labels (list of str, optional) – The variant label(s) to plot for each subplot. Default is shown above.

  • super_title (str, None, optional) – The title for the overall figure. Default is None.

  • fig_scale (int, float, optional) – The scale factor by which to resize the figure. Default is 2.

  • save_as (str, None, optional) – The name of the file to which to save the plot. Default is None, which doesn’t save the plot to a file.

  • test (bool, optional) – If True, the function exists before making a plot for use in testing. Default is False.

  • **kwargs – Keyword arguments to pass to xr.DataArray.plot().

Return type:

None

Examples

>>> from arctichoke.plot.seasonal_cycle import multi_seasonal_cycle
>>> multi_seasonal_cycle(
        source_id = 'EC-Earth3P-HR',
        variable_ids = ['siconc'],
        super_title = 'Seasonal Cycles',
    )
arctichoke.plot.plot_time_series(dataset: str, xarray.DataArray, xarray.Dataset, variable_id: str = None, plt_title: str = None, xlims: [str, str] = None, ylims: [float, float] = None, save_as: str = None, test: bool = False, **kwargs)

Plot a time series of the dataset.

Plots a time series of the given dataset for the given variable, if applicable.

Parameters:

  • dataset (str, xarray.DataArray, xarray.Dataset) – The dataset for which to make a plot.

  • variable_id (str) – The name of the variable ID to plot.

  • plt_title (str, None, optional) – The title to use for the plot. Default is None, which uses a default title for the plot.

  • xlims (List of float, optional) –

    The limits to use for the x-axis on the plot in the following format:

    • [x_min, x_max]

    where x_min and x_max are strings in the format YYYY-MM-DD Default is None, which expands the x-axis to include all the data.

  • ylims (List of float, optional) –

    The limits to use for the y-axis on the plot in the following format:

    • [y_min, y_max]

    Default is None, which expands the y-axis to include all the data.

  • save_as (str, None, optional) – The name of the file to which to save the plot. Default is None, which doesn’t save the plot to a file.

  • test (bool, optional) – If True, the function exists before making a plot for use in testing. Default is False.

  • **kwargs – Keyword arguments to pass to xr.DataArray.plot().

Returns:

  • If test == False – None

  • If test == True – dataset : xarray.DataArray

Examples

>>> from arctichoke.dataset.field_mean import get_field_mean
>>> fldmean_xr = get_field_mean('example_siconc_dataset.nc')
>>> from arctichoke.plot.time_series import plot_time_series
>>> plot_time_series(dataset = fldmean_xr, variable_id = 'siconc')
arctichoke.plot.sum_by_year(dataset: str, [str], xarray.DataArray, xarray.Dataset, attr_long_name: str = None, attr_units: str = None, save_as: str = None, verbose: bool = False, **kwargs)

Sum a dataset by year along the time axis.

Groups the dataset by year and sums each year. This results in one time step for each year in the given dataset.

Parameters:

  • dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset of which to sum by year.

  • attr_long_name (str, None, optional) – The name of the variable for which to put in the long_name attribute. Default is None, which uses the original long_name plus ‘Yearly Sum of ‘.

  • attr_units (str, None, optional) – The units of the variable for which to put in the units attribute. Default is None, which uses the original units plus ‘_per_year’.

  • save_as (str, None, optional) – The file name to which to save the modified dataset. Default is None, which doesn’t save the dataset to a file.

  • verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.

  • **kwargs – Keyword arguments to pass to xr.sum().

Returns:

dataset – A dataset where the data has been summed by year.

Return type:

xarray.Dataset

Examples

>>> from arctichoke.dataset.example_dataset import make_example_dataset
>>> dataset = make_example_dataset(n=3, time_axis=True)
>>> dataset['test_var'].values
array([[[0., 1., 2.],
        [3., 4., 5.],
        [6., 7., 8.]],
[[0., 1., 2.],

[3., 4., 5.], [6., 7., 8.]]])

>>> from arctichoke.analysis.sum_by_year import sum_by_year
>>> dataset_year_sum = sum_by_year(dataset)
>>> dataset_year_sum['test_var_year_sum'].values
array([[[ 0.,  2.,  4.],
        [ 6.,  8., 10.],
        [12., 14., 16.]]])
arctichoke.plot.trend_in_time(dataset: str, [str], xarray.Dataset, xarray.DataArray, var: str = None, time_dim: str = 'year', mask_where_zero_across_time: bool = False, save_as: str = None, verbose: bool = False, **kwargs)

Find the trend for each grid cell along the time axis.

For each grid cell in the dataset, find the trend in time for the given variable. This results in a new dataset without a time dimension.

Parameters:

  • dataset (str, list of str, xarray.Dataset, xarray.DataArray) – The dataset of which to find the sum across time.

  • var (str, None, optional) – The variable in dataset for which to take the trend across time. This is required if dataset is an xarray.Dataset. Default is None.

  • time_dim (str, optional) – The name of the time dimension over which to find the trend. Default is year.

  • mask_where_zero_across_time (bool, optional) – Whether to mask out grid cells which have zero as a value across the entire time dimension using mask_where_all_zero(). Default is False.

  • save_as (str, None, optional) – The file name to which to save the modified dataset. Default is None, which doesn’t save the dataset to a file.

  • verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.

  • **kwargs – Keyword arguments to pass to xr.sum().

Returns:

trends_dataset – A dataset with the trends in time for the specified variable.

Return type:

xarray.Dataset or xarray.DataArray

Examples

>>> from arctichoke.dataset.example_dataset import make_example_dataset
>>> from arctichoke.path.manipulate_paths import make_file_path
>>> # Create multiple example test files
>>> test_file_dir = 'tests/test_analysis/example_datasets'
>>> make_file_path(test_file_dir)
>>> test_file_names = [
>>>     f"{test_file_dir}/example_dataset_0.nc",
>>>     f"{test_file_dir}/example_dataset_1.nc",
>>>     f"{test_file_dir}/example_dataset_2.nc",
>>> ]
>>> offsets = [0, 1, 3]
>>> for i in range(len(test_file_names)):
>>>     make_example_dataset(
>>>         n=3,
>>>         offset=offsets[i],
>>>         test_var_name='test_var',
>>>         time_axis=(2000+i),
>>>         save_as=test_file_names[i],
>>>     )
>>> import xarray as xr
>>> test_dataset = xr.open_mfdataset(test_file_names)
>>> test_dataset['test_var'].values
array([[[ 0.,  1.,  2.],
        [ 3.,  4.,  5.],
        [ 6.,  7.,  8.]],
[[ 0., 1., 2.],

[ 3., 4., 5.], [ 6., 7., 8.]],

[[ 1., 2., 3.],

[ 4., 5., 6.], [ 7., 8., 9.]],

[[ 1., 2., 3.],

[ 4., 5., 6.], [ 7., 8., 9.]],

[[ 3., 4., 5.],

[ 6., 7., 8.], [ 9., 10., 11.]],

[[ 3., 4., 5.],

[ 6., 7., 8.], [ 9., 10., 11.]]])

>>> from arctichoke.analysis.trend_in_time import trend_in_time
>>> test_trends = trend_in_time(
>>>     test_dataset,
>>>     var='test_var',
>>>     time_dim='time',
>>> )
>>> test_trends['test_var_trends'].values
array([[1.49369, 1.49369, 1.49369],
       [1.49369, 1.49369, 1.49369],
       [1.49369, 1.49369, 1.49369]])
arctichoke.plot.list_variable_files(source_id: str, variable_id: str, with_modification: str = None, **kwargs)

Get a list of data files for the specified variable for the specified model.

Search for all the files for the given model and variable and return them in a list. This assumes the esgpull convention of subdirectories: data/project/activity_id/institution_id/source_id/experiment_id/variant_label/table_id/variable_id/gn/version/data_file.nc.

Parameters:

  • source_id (str) – The name of the source ID (model) for which to get the variable files.

  • variable_id (str) – The name of the variable ID for which to get the variable files.

  • with_modification (str, None, optional) – The prefix of a modification to the data files to find. Ex: trim_NWP_. If None, returns only the original files. Default is None.

  • **kwargs – Keyword arguments to pass to get_variable_path().

Returns:

data_filepaths – A list, sorted alphabetically, of the filepaths of the variable data files.

Return type:

List of str

Examples

>>> from arctichoke.path.find import list_variable_files
>>> list_variable_files(source_id = 'HadGEM3-GC31-HM', variable_id = 'areacello')
['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/MOHC/HadGEM3-GC31-HM/hist-1950/r1i1p1f1/Ofx/areacello/gn/v20190301/areacello_Ofx_HadGEM3-GC31-HM_hist-1950_r1i1p1f1_gn.nc']
>>> list_variable_files(source_id = 'EC-Earth3P-HR', variable_id = 'siage')
/workspace/src/arctichoke/path/find_data.py:399: UserWarning: (get_variable_path) More than one file path found: ['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siage', '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r2i1p2f1/SImon/siage', '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/siage']
Returning first result in list.
['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siage/gn/v20181212/siage_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195001-195012.nc',
...
'/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siage/gn/v20181212/siage_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_201401-201412.nc']
arctichoke.plot.quadmesh_map(xr_data: xarray.Dataset, var: str, save_as: str = None, map_projection: str = 'NorthPolarStereo', map_bbox: [float, float, float, float] = sps.NWP_BBOX, clims: [int, float, int, float] = None, diverging_cbar: bool = False, verbose: bool = False, **kwargs)

Create an hvplot quadmesh map.

Plot a map of the given data using the hvplot.quadmesh() function.

Parameters:

  • xr_data (xarray.Dataset) – The dataset to plot.

  • var (str) – The variable in xr_data to plot.

  • save_as (str, None, optional) – The file name to pass to arctichoke.plot.save_hvplots.save_hvplot(). Default is None, which doesn’t save the plot to a file.

  • map_projection (str, optional) – A string naming the map projection to use in the plot. Must be one of the following: ‘NorthPolarStereo’, ‘Orthograpic’. Default is ‘NorthPolarStereo’.

  • map_bbox (Array of float, optional) –

    An array of coordinates defining the bounding box of the map in the following format:

    • [LAT_MAX, LAT_MIN, LON_MAX, LON_MIN]

    Default is arctichoke.params.latlon_params.NWP_BBOX.

  • clims (List or tuple of int, float, optional) – The limits to use in the colorbar. Note: This overrides the default method of limiting the colorbar range when diverging_cbar=True. Default is None, which uses the minimum / maximum values present in the data.

  • diverging_cbar (bool, optional) – Whether to use a diverging colormap on the colorbar. Default is False.

  • verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.

  • **kwargs – Keyword arguments to pass to hvplot.quadmesh() and arctichoke.plot.limit_extent.get_limited_extent()

Returns:

qm_map_plot – An overlay object which can be used to construct the plot.

Return type:

holoviews.core.overlay.Overlay

Examples

>>> import xarray as xr
>>> this_plot = hvplots.quadmesh_map(xr.open_dataset("data/areacello_Ofx_EC-Earth3P-HR_highres-future_r2i1p2f1_gn.nc", 'areacello')
>>> print(type(this_plot))
<class 'holoviews.core.overlay.Overlay'>
arctichoke.plot.make_trend_map(this_source_id: str, this_var: str, this_variant_label: str, this_modification: str, mask_where_zero_across_time: bool = True, map_projection: str = 'Orthographic', verbose: bool = False)

Plot the trends of the given data on a map.

For each grid cell in the dataset, calculate the yearly sum, then find the trend in time for the given variable and plot it on a map.

Parameters:

  • this_source_id (str) – The source ID of the model to plot. Example: ‘EC-Earth3P-HR’.

  • this_var (str) – The variable ID of the variable to plot. Example: ‘silandfast’.

  • this_variant_label (str) – The variant label of the model to plot. Example: ‘r1i1p2f1’.

  • this_modification (str) – The modification of the data to plot. Example: ‘trim_CAA_’.

  • verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.

Returns:

sum_year_map – The map of the trends in time for the given variable.

Return type:

holoviews.core.overlay.Overlay

Examples

>>> from arctichoke.plot import make_trend_map
>>> make_trend_map(
>>>     this_source_id = 'EC-Earth3P-HR',
>>>     this_var = 'silandfast',
>>>     this_variant_label = 'r1i1p2f1',
>>>     this_modification = 'trim_CAA_',
>>>     verbose = True,
>>> )