arctichoke.plot =============== .. py:module:: arctichoke.plot Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/arctichoke/plot/cbar_limits/index /autoapi/arctichoke/plot/diverging_cmap/index /autoapi/arctichoke/plot/hvplots/index /autoapi/arctichoke/plot/labels_and_titles/index /autoapi/arctichoke/plot/limit_extent/index /autoapi/arctichoke/plot/save_hvplots/index /autoapi/arctichoke/plot/seasonal_cycle/index /autoapi/arctichoke/plot/time_series/index /autoapi/arctichoke/plot/trend_in_time_map/index Functions --------- .. autoapisummary:: arctichoke.plot.set_cbar_lims arctichoke.plot.get_min_max arctichoke.plot.get_latlon_names arctichoke.plot.set_cbar_lims arctichoke.plot.make_title arctichoke.plot.make_label arctichoke.plot.get_limited_extent arctichoke.plot.save_hvplot arctichoke.plot.quadmesh_map arctichoke.plot.get_variable_name arctichoke.plot.verify_path arctichoke.plot.make_title arctichoke.plot.make_label arctichoke.plot.get_limited_extent arctichoke.plot.save_hvplot arctichoke.plot.html_to_png arctichoke.plot.get_field_mean arctichoke.plot.list_variable_files arctichoke.plot.select_files_by_time arctichoke.plot.plot_seasonal_cycle arctichoke.plot.multi_seasonal_cycle arctichoke.plot.plot_time_series arctichoke.plot.sum_by_year arctichoke.plot.trend_in_time arctichoke.plot.list_variable_files arctichoke.plot.quadmesh_map arctichoke.plot.make_trend_map Package Contents ---------------- .. py:function:: 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. :param hv_overlay: The overlay object for which to construct the limited colorbar. :type hv_overlay: `holoviews.core.overlay.Overlay`, `holoviews.element.raster.QuadMesh` :param cmin: The minimum display value for the colormap. :type cmin: `int`, `float` :param cmax: The maximum display value for the colormap. :type cmax: `int`, `float` :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :param \*\*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. :rtype: `bokeh.plotting._figure.figure` .. rubric:: Examples >>> from arctichoke.plot.cbar_limits import set_cbar_lims .. py:function:: 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. :param dataset: The dataset for which to determine the minimum / maximum values. :type dataset: `str`, `xarray.DataArray`, `xarray.Dataset` :param var: The variable in `dataset` for which to find the minimum / maximum. Default is `None`. :type var: `str`, `None`, optional :returns: * **var_min** (`int`, `float`) -- The minimum value of the data. * **var_max** (`int`, `float`) -- The maximum value of the data. .. rubric:: 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 .. py:function:: 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`. :param dataset: The dataset for which to determine the latitude and longitude names. :type dataset: `str`, `xarray.DataArray`, `xarray.Dataset` :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`. .. rubric:: 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') .. py:function:: 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. :param hv_overlay: The overlay object for which to construct the limited colorbar. :type hv_overlay: `holoviews.core.overlay.Overlay`, `holoviews.element.raster.QuadMesh` :param cmin: The minimum display value for the colormap. :type cmin: `int`, `float` :param cmax: The maximum display value for the colormap. :type cmax: `int`, `float` :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :param \*\*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. :rtype: `bokeh.plotting._figure.figure` .. rubric:: Examples >>> from arctichoke.plot.cbar_limits import set_cbar_lims .. py:function:: 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. :param dataset: The dataset for which to make a title. :type dataset: `str`, list of `str`, `xarray.Dataset` :param add_source_id: Whether to add the source ID to the title. Default is `True`. :type add_source_id: `bool`, optional :param add_experiment_id: Whether to add the eperiment ID to the title. Default is `True`. :type add_experiment_id: `bool`, optional :param add_variant_label: Whether to add the variant label to the title. Default is `True`. :type add_variant_label: `bool`, optional :param add_time_stamp: 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`. :type add_time_stamp: `bool`, optional :returns: **dataset_title** -- The title for the dataset. :rtype: `str` .. rubric:: 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 ' .. py:function:: 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. :param dataset: The dataset for which to make a label. :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param var: The variable in `dataset` for which to make a label. This is required if `dataset` is an `xarray.Dataset`. Default is `None`. :type var: `str`, `None`, optional :param add_name: Whether to add the variable name to the label. Default is `True`. :type add_name: `bool`, optional :param add_units: Whether to add the units to the label. Default is `True`. :type add_units: `bool`, optional :returns: **dataset_label** -- The label for the dataset. :rtype: `str` .. rubric:: 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) (%) ' .. py:function:: 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. :param map_projection: The coordinate reference system from `cartopy` onto which the bounding box will be projected. :type map_projection: `cartopy.crs.CRS` :param map_bbox: 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`. :type map_bbox: Array of `float`, optional :param n_sample: 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`. :type n_sample: `int`, optional :param \*\*kwargs: Keyword arguments to handle extras that might have been passed by the function above this one. :rtype: map_extent .. rubric:: Examples >>> .. py:function:: 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. :param hvplot_to_save: The `hvplot` object to save to file. :type hvplot_to_save: A type of `hvplot` object :param save_as: The file path within the `outputs/` directory to which to save the plot. Must end in either `.html` or `.png`. :type save_as: `str` :rtype: None .. rubric:: Examples >>> .. py:function:: 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. :param xr_data: The dataset to plot. :type xr_data: `xarray.Dataset` :param var: The variable in `xr_data` to plot. :type var: `str` :param save_as: The file name to pass to `arctichoke.plot.save_hvplots.save_hvplot()`. Default is `None`, which doesn't save the plot to a file. :type save_as: `str`, `None`, optional :param map_projection: A string naming the map projection to use in the plot. Must be one of the following: 'NorthPolarStereo', 'Orthograpic'. Default is 'NorthPolarStereo'. :type map_projection: `str`, optional :param map_bbox: 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`. :type map_bbox: Array of `float`, optional :param clims: 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. :type clims: List or tuple of `int`, `float`, optional :param diverging_cbar: Whether to use a diverging colormap on the colorbar. Default is `False`. :type diverging_cbar: `bool`, optional :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :param \*\*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. :rtype: `holoviews.core.overlay.Overlay` .. rubric:: 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)) .. py:function:: 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. :param dataset: The dataset for which to determine the variable name. :type dataset: `str`, `xarray.DataArray`, `xarray.Dataset` :returns: **var_name** -- The name of the variable :rtype: `str` .. rubric:: Examples >>> from arctichoke.dataset.grid_type import get_variable_name .. py:function:: 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. :param path: Relative path to the directory containing data files. :type path: `str` :raises FileNotFoundError: If the specified path does not exist. :returns: **path** -- The verified path to the data files. :rtype: `str` .. rubric:: Examples >>> verify_path('README.md') 'README.md' .. py:function:: 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. :param dataset: The dataset for which to make a title. :type dataset: `str`, list of `str`, `xarray.Dataset` :param add_source_id: Whether to add the source ID to the title. Default is `True`. :type add_source_id: `bool`, optional :param add_experiment_id: Whether to add the eperiment ID to the title. Default is `True`. :type add_experiment_id: `bool`, optional :param add_variant_label: Whether to add the variant label to the title. Default is `True`. :type add_variant_label: `bool`, optional :param add_time_stamp: 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`. :type add_time_stamp: `bool`, optional :returns: **dataset_title** -- The title for the dataset. :rtype: `str` .. rubric:: 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 ' .. py:function:: 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. :param dataset: The dataset for which to make a label. :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param var: The variable in `dataset` for which to make a label. This is required if `dataset` is an `xarray.Dataset`. Default is `None`. :type var: `str`, `None`, optional :param add_name: Whether to add the variable name to the label. Default is `True`. :type add_name: `bool`, optional :param add_units: Whether to add the units to the label. Default is `True`. :type add_units: `bool`, optional :returns: **dataset_label** -- The label for the dataset. :rtype: `str` .. rubric:: 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) (%) ' .. py:function:: 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. :param map_projection: The coordinate reference system from `cartopy` onto which the bounding box will be projected. :type map_projection: `cartopy.crs.CRS` :param map_bbox: 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`. :type map_bbox: Array of `float`, optional :param n_sample: 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`. :type n_sample: `int`, optional :param \*\*kwargs: Keyword arguments to handle extras that might have been passed by the function above this one. :rtype: map_extent .. rubric:: Examples >>> .. py:function:: 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. :param hvplot_to_save: The `hvplot` object to save to file. :type hvplot_to_save: A type of `hvplot` object :param save_as: The file path within the `outputs/` directory to which to save the plot. Must end in either `.html` or `.png`. :type save_as: `str` :rtype: None .. rubric:: Examples >>> .. py:function:: 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. :param html_filename: The file path within the `outputs/` directory to the `html` file of the `hvplot`. :type html_filename: `str` :param png_filename: The file path within the `outputs/` directory to which to save the `png` image, or `None`. :type png_filename: `str`, `None`, optional :rtype: None .. rubric:: Examples >>> .. py:function:: 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. :param dataset: The dataset of which to take the field mean. :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param save_as: The file name to pass to `cdo.fldmean(output=save_as)`. Default is `None`, which doesn't save the dataset to a file. :type save_as: `str`, `None`, optional :param \*\*kwargs: Keyword arguments to pass to `cdo.fldmean()`. :returns: **fldmean_xr** -- A dataset of the field mean of the input data. :rtype: `xarray.Dataset` .. rubric:: 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) .. py:function:: 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`. :param source_id: The name of the source ID (model) for which to get the variable files. :type source_id: `str` :param variable_id: The name of the variable ID for which to get the variable files. :type variable_id: `str` :param with_modification: The prefix of a modification to the data files to find. Ex: `trim_NWP_`. If `None`, returns only the original files. Default is `None`. :type with_modification: `str`, `None`, optional :param \*\*kwargs: Keyword arguments to pass to `get_variable_path()`. :returns: **data_filepaths** -- A list, sorted alphabetically, of the filepaths of the variable data files. :rtype: List of `str` .. rubric:: 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'] .. py:function:: 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. :param data_filepaths: A list, sorted alphabetically, of the filepaths of the variable data files. :type data_filepaths: List of `str` :param start: The start date of the time range, either a string in the format `YYYY-MM-DD` or an integer of a year. :type start: `str`, `int` :param end: The end date of the time range, either a string in the format `YYYY-MM-DD` or an integer of a year. :type end: `str`, `int` :param test: If `True`, the function skips verifying the `data_filepaths` exist for use in testing. Default is `False`. :type test: `bool`, optional :returns: **data_filepaths** -- A list, sorted alphabetically, of the filepaths in the date range. :rtype: List of `str` .. rubric:: 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'] .. py:function:: 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. :param datasets: A list of datasets for which to make a plot. :type datasets: list of `str`, `xarray.DataArray`, `xarray.Dataset` :param variable_id: The name of the variable ID to plot. :type variable_id: `str` :param take_mean: Whether to take the mean for each month across all the years. Default is `False`. :type take_mean: `bool`, optional :param ax: The axes on which to plot the data. If `None`, a new figure is created. Default is `None`. :type ax: `matplotlib.axes.Axes`, optional :param plt_title: The title to use for the plot. Default is `None`, which uses a default title for the plot. :type plt_title: `str`, `None`, optional :param line_labels: The labels to use for the lines that are plotted if `take_mean = True`. Default is `None`. :type line_labels: list of `str`, `None`, optional :param line_styles: The line styles to use for the lines that are plotted if `take_mean = True`. Default is `'-'`. :type line_styles: list of `str`, `None`, optional :param xlims: 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. :type xlims: List of `float`, optional :param ylims: 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. :type ylims: List of `float`, optional :param c_map: The color map to use for the different lines so their order is clearer. Default is `matplotlib.cm.viridis_r`, the reverse of `viridis`. :type c_map: `matplotlib.colors.ListedColormap`, optional :param c_map_label: The label to use on the colorbar. If `None`, then the colorbar will have no label. Default is `Year`. :type c_map_label: `str`, `None`, optional :param save_as: The name of the file to which to save the plot. Default is `None`, which doesn't save the plot to a file. :type save_as: `str`, `None`, optional :param test: If `True`, the function exists before making a plot for use in testing. Default is `False`. :type test: `bool`, optional :param \*\*kwargs: Keyword arguments to pass to `xr.DataArray.plot()`. :returns: * If `test` == `False` -- fig ax * If `test` == `True` -- dataset : `xarray.DataArray` .. rubric:: 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') .. py:function:: 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. :param source_id: The name of the `source_id` to specify the model to plot. :type source_id: `str` :param variable_ids: The variable ID(s) to plot. :type variable_ids: list of `str` :param experiment_ids: The experiment(s) to plot. Default is `['hist-1950']`. :type experiment_ids: list of `str`, optional :param time_bounds_lists: 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. :type time_bounds_lists: `dict`, optional :param variant_labels: The variant label(s) to plot for each subplot. Default is shown above. :type variant_labels: list of `str`, optional :param super_title: The title for the overall figure. Default is `None`. :type super_title: `str`, `None`, optional :param fig_scale: The scale factor by which to resize the figure. Default is `2`. :type fig_scale: `int`, `float`, optional :param save_as: The name of the file to which to save the plot. Default is `None`, which doesn't save the plot to a file. :type save_as: `str`, `None`, optional :param test: If `True`, the function exists before making a plot for use in testing. Default is `False`. :type test: `bool`, optional :param \*\*kwargs: Keyword arguments to pass to `xr.DataArray.plot()`. :rtype: `None` .. rubric:: 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', ) .. py:function:: 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. :param dataset: The dataset for which to make a plot. :type dataset: `str`, `xarray.DataArray`, `xarray.Dataset` :param variable_id: The name of the variable ID to plot. :type variable_id: `str` :param plt_title: The title to use for the plot. Default is `None`, which uses a default title for the plot. :type plt_title: `str`, `None`, optional :param xlims: 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. :type xlims: List of `float`, optional :param ylims: 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. :type ylims: List of `float`, optional :param save_as: The name of the file to which to save the plot. Default is `None`, which doesn't save the plot to a file. :type save_as: `str`, `None`, optional :param test: If `True`, the function exists before making a plot for use in testing. Default is `False`. :type test: `bool`, optional :param \*\*kwargs: Keyword arguments to pass to `xr.DataArray.plot()`. :returns: * If `test` == `False` -- `None` * If `test` == `True` -- dataset : `xarray.DataArray` .. rubric:: 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') .. py:function:: 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. :param dataset: The dataset of which to sum by year. :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param attr_long_name: 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 '`. :type attr_long_name: `str`, `None`, optional :param attr_units: The units of the variable for which to put in the `units` attribute. Default is `None`, which uses the original `units` plus `'_per_year'`. :type attr_units: `str`, `None`, optional :param save_as: The file name to which to save the modified dataset. Default is `None`, which doesn't save the dataset to a file. :type save_as: `str`, `None`, optional :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :param \*\*kwargs: Keyword arguments to pass to `xr.sum()`. :returns: **dataset** -- A dataset where the data has been summed by year. :rtype: `xarray.Dataset` .. rubric:: 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.]]]) .. py:function:: 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. :param dataset: The dataset of which to find the sum across time. :type dataset: `str`, list of `str`, `xarray.Dataset`, `xarray.DataArray` :param var: The variable in `dataset` for which to take the trend across time. This is required if `dataset` is an `xarray.Dataset`. Default is `None`. :type var: `str`, `None`, optional :param time_dim: The name of the time dimension over which to find the trend. Default is `year`. :type time_dim: `str`, optional :param mask_where_zero_across_time: 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`. :type mask_where_zero_across_time: `bool`, optional :param save_as: The file name to which to save the modified dataset. Default is `None`, which doesn't save the dataset to a file. :type save_as: `str`, `None`, optional :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :param \*\*kwargs: Keyword arguments to pass to `xr.sum()`. :returns: **trends_dataset** -- A dataset with the trends in time for the specified variable. :rtype: `xarray.Dataset` or `xarray.DataArray` .. rubric:: 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]]) .. py:function:: 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`. :param source_id: The name of the source ID (model) for which to get the variable files. :type source_id: `str` :param variable_id: The name of the variable ID for which to get the variable files. :type variable_id: `str` :param with_modification: The prefix of a modification to the data files to find. Ex: `trim_NWP_`. If `None`, returns only the original files. Default is `None`. :type with_modification: `str`, `None`, optional :param \*\*kwargs: Keyword arguments to pass to `get_variable_path()`. :returns: **data_filepaths** -- A list, sorted alphabetically, of the filepaths of the variable data files. :rtype: List of `str` .. rubric:: 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'] .. py:function:: 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. :param xr_data: The dataset to plot. :type xr_data: `xarray.Dataset` :param var: The variable in `xr_data` to plot. :type var: `str` :param save_as: The file name to pass to `arctichoke.plot.save_hvplots.save_hvplot()`. Default is `None`, which doesn't save the plot to a file. :type save_as: `str`, `None`, optional :param map_projection: A string naming the map projection to use in the plot. Must be one of the following: 'NorthPolarStereo', 'Orthograpic'. Default is 'NorthPolarStereo'. :type map_projection: `str`, optional :param map_bbox: 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`. :type map_bbox: Array of `float`, optional :param clims: 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. :type clims: List or tuple of `int`, `float`, optional :param diverging_cbar: Whether to use a diverging colormap on the colorbar. Default is `False`. :type diverging_cbar: `bool`, optional :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :param \*\*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. :rtype: `holoviews.core.overlay.Overlay` .. rubric:: 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)) .. py:function:: 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. :param this_source_id: The source ID of the model to plot. Example: `'EC-Earth3P-HR'`. :type this_source_id: `str` :param this_var: The variable ID of the variable to plot. Example: `'silandfast'`. :type this_var: `str` :param this_variant_label: The variant label of the model to plot. Example: `'r1i1p2f1'`. :type this_variant_label: `str` :param this_modification: The modification of the data to plot. Example: `'trim_CAA_'`. :type this_modification: `str` :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :returns: **sum_year_map** -- The map of the trends in time for the given variable. :rtype: `holoviews.core.overlay.Overlay` .. rubric:: 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, >>> )