arctichoke.analysis =================== .. py:module:: arctichoke.analysis Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/arctichoke/analysis/landfast/index /autoapi/arctichoke/analysis/siconc/index /autoapi/arctichoke/analysis/sum_by_year/index /autoapi/arctichoke/analysis/trend_in_time/index Attributes ---------- .. autoapisummary:: arctichoke.analysis.cdo Functions --------- .. autoapisummary:: arctichoke.analysis.get_current_datetime_str arctichoke.analysis.get_variable_name arctichoke.analysis.trim_latlon arctichoke.analysis.make_file_path arctichoke.analysis.find_packed_ice arctichoke.analysis.find_slow_ice arctichoke.analysis.find_landfast_ice arctichoke.analysis.make_landfast_files arctichoke.analysis.get_current_datetime_str arctichoke.analysis.get_variable_name arctichoke.analysis.trim_latlon arctichoke.analysis.make_file_path arctichoke.analysis.calc_siconc arctichoke.analysis.make_siconc_files arctichoke.analysis.get_current_datetime_str arctichoke.analysis.get_variable_name arctichoke.analysis.sum_by_year arctichoke.analysis.get_current_datetime_str arctichoke.analysis.get_variable_name arctichoke.analysis.get_min_max arctichoke.analysis.trend_in_time arctichoke.analysis.mask_where_all_zero Package Contents ---------------- .. py:data:: cdo .. py:function:: get_current_datetime_str(str_format: str = '%Y-%m-%dT%H:%M:%SZ') Get the current datetime in UTC. Format the current datetime into a string based on the given format string. :param str_format: The format string by which to format the current datetime. Default is `"%Y-%m-%dT%H:%M:%SZ"`. :type str_format: `str`, optional :returns: **datetime_str** -- The formatted current datetime as a string. :rtype: `str` .. rubric:: Examples >>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str .. 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:: trim_latlon(dataset: (str, xarray.Dataset, xarray.DataArray), map_bbox: [float, float, float, float] = sps.NWP_BBOX, precise_trim: bool = False, save_as: str = None, verbose: bool = False) Trim the given dataset. Select only the data within the given bounding box of latitude and longitude coordinates from the given dataset. :param dataset: The dataset to plot. :type dataset: `str`, `xarray.Dataset`, `xarray.DataArray` :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 precise_trim: Whether to precisely trim an irregular grid to the bounding box, making all values outside the bounding box null. Default is `False`. :type precise_trim: `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 :returns: **xr_data_trimmed** -- The dataset trimmed to the latitude and longitude ranges provided. :rtype: `xarray.Dataset` .. rubric:: Examples >>> .. py:function:: make_file_path(path) Create a file path. Create the specified directory structure if the given path doesn't exist. :param path: Relative path to make. :type path: `str` :returns: **path** -- The verified path to the data files. :rtype: `str` .. rubric:: Examples >>> make_file_path('datafiles/some/more/data/a_file.txt') 'datafiles/some/more/data/' .. py:function:: find_packed_ice(dataset: (str, [str], xarray.DataArray, xarray.Dataset), packed_threshold: (int, float) = 85, siconc_var: str = 'siconc', save_as: str = None, verbose: bool = False, **kwargs) Calculate where packed ice is from the dataset. Verify the dataset contains the `siconc` variable, and adds a variable `sipacked` which is 1 where `siconc` is greater than 85 percent (or the given threshold) and 0 elsewhere. :param dataset: The dataset of which to find the locations of packed ice. :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param packed_threshold: The threshold above which to mark packed ice. Default is `85` percent, following Laliberté et al. 2018. :type packed_threshold: `int`, `float`, optional :param siconc_var: The name of the variable to use from the provided dataset. Must be either `siconc` or `siconc2`. Default is `siconc`. :type siconc_var: `str`, 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 `cdo.setrtoc2()`. :returns: **packedice_xr** -- A dataset where packed ice is marked as `1` and all other values are `0`. :rtype: `xarray.Dataset` .. rubric:: Examples >>> from arctichoke.dataset.example_dataset import make_example_dataset >>> dataset = make_example_dataset(n=3, test_var_name='siconc') >>> dataset['siconc'].values array([[0., 1., 2.], [3., 4., 5.], [6., 7., 8.]]) >>> from arctichoke.analysis.landfast import find_packed_ice >>> dataset_sipacked = find_packed_ice(dataset, packed_threshold=4) >>> dataset_sipacked['sipacked'].values array([[0., 0., 0.], [0., 1., 1.], [1., 1., 1.]]) .. py:function:: find_slow_ice(dataset: (str, [str], xarray.DataArray, xarray.Dataset), slow_threshold: (int, float) = 0.01, save_as: str = None, verbose: bool = False, **kwargs) Calculate where slow ice is from the dataset. Verify the dataset contains the `sispeed` variable, and adds a variable `sislow` which is 1 where `sispeed` is less than 1 cm s-1 (or the given threshold) and 0 elsewhere. :param dataset: The dataset of which to find the locations of slow ice. :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param slow_threshold: The threshold above which to mark slow ice. Default is `0.01` m s-1, following Laliberté et al. 2018. :type slow_threshold: `int`, `float`, 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 `cdo.setrtoc2()`. :returns: **slowice_xr** -- A dataset where slow ice is marked as `1` and all other values are `0`. :rtype: `xarray.Dataset` .. rubric:: Examples >>> from arctichoke.dataset.example_dataset import make_example_dataset >>> dataset = make_example_dataset(n=3, test_var_name='sispeed') >>> dataset['sispeed'].values array([[0., 1., 2.], [3., 4., 5.], [6., 7., 8.]]) >>> from arctichoke.analysis.landfast import find_slow_ice >>> dataset_sislow = find_slow_ice(dataset, slow_threshold=4) >>> dataset_sislow['sislow'].values array([[1., 1., 1.], [1., 1., 0.], [0., 0., 0.]]) .. py:function:: find_landfast_ice(siconc_dataset: (str, [str], xarray.DataArray, xarray.Dataset), sispeed_dataset: (str, [str], xarray.DataArray, xarray.Dataset), packed_threshold: (int, float) = 85, slow_threshold: (int, float) = 0.01, siconc_var: str = 'siconc', save_as: str = None, verbose: bool = False, **kwargs) Calculate where landfast ice is from the dataset(s). Verify the dataset(s) contains the `siconc`/`siconc2` and `sispeed` variables, calculates `sipacked` and `sislow` using `find_packed_ice()` and `find_landfast_ice()`, then takes the overlap of these to define `silandfast`. :param siconc_dataset: The dataset of which to find the locations of landfast ice that contains `siconc`/`siconc2`. :type siconc_dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param sispeed_dataset: The dataset of which to find the locations of landfast ice that contains `sispeed`. :type sispeed_dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param packed_threshold: The threshold above which to mark packed ice. Default is `85` percent, following Laliberté et al. 2018. :type packed_threshold: `int`, `float`, optional :param slow_threshold: The threshold above which to mark slow ice. Default is `0.01` m s-1, following Laliberté et al. 2018. :type slow_threshold: `int`, `float`, optional :param siconc_var: The name of the variable to use from the provided sea ice concentration dataset. Must be either `siconc` or `siconc2`. Default is `siconc`. :type siconc_var: `str`, 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 `find_packed_ice()`, `find_slow_ice()` and `cdo.setrtoc2()`. :returns: **landfastice_xr** -- A dataset where landfast ice is marked as `1` and all other values are `0`. :rtype: `xarray.Dataset` .. rubric:: Examples >>> from arctichoke.dataset.example_dataset import make_example_dataset >>> dataset_0 = make_example_dataset(n=3, test_var_name='siconc') >>> dataset_0['siconc'].values array([[0., 1., 2.], [3., 4., 5.], [6., 7., 8.]]) >>> dataset_1 = make_example_dataset(n=3, test_var_name='sispeed') >>> dataset_1['sispeed'].values array([[0., 1., 2.], [3., 4., 5.], [6., 7., 8.]]) >>> from arctichoke.analysis.landfast import find_landfast_ice >>> dataset_landfast = find_landfast_ice(siconc_dataset=dataset_0, sispeed_dataset=dataset_1, packed_threshold=4, slow_threshold=4) >>> dataset_landfast['silandfast'].values array([[0., 0., 0.], [0., 1., 0.], [0., 0., 0.]]) .. py:function:: make_landfast_files(siconc_files: [str], sispeed_files: [str], map_bbox: [float, float, float, float] = None, version_id: str = 'v20260617', siconc_var: str = 'siconc', overwrite: bool = False, **kwargs) Make landfast files based on the lists of files given. For each given pair of files, load the data, trim the datasets (if applicable), calculate the landfast ice, then save the landfast ice dataset as a new file in the same directory structure. :param siconc_files: A list of paths of the sea ice concentration data files. :type siconc_files: List of `str` :param sispeed_files: A list of paths of the sea ice speed data files. :type sispeed_files: List of `str` :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 `None`, meaning the data will not be trimmed. :type map_bbox: Array of `float`, `None`, optional :param version_id: The version ID to use when making the directory structure for the landfast ice files. Default is `'v20260617'`. :type version_id: `str`, optional :param siconc_var: The name of the variable to use from the provided sea ice concentration dataset. Must be either `siconc` or `siconc2`. Default is `siconc`. :type siconc_var: `str`, optional :param overwrite: Whether to overwrite an existing file if it exists. Default is `False`. :type overwrite: `bool`, optional :param \*\*kwargs: Keyword arguments to pass to `trim_latlon()`, and `find_landfast_ice()`. :rtype: None .. rubric:: Examples >>> from arctichoke.path import list_variable_files >>> from arctichoke.analysis.landfast import make_landfast_files >>> from arctichoke.params import CAA_BBOX >>> this_model = 'EC-Earth3P-HR' >>> for this_variant_label in [ >>> 'r1i1p2f1', >>> 'r2i1p2f1', >>> 'r3i1p2f1', >>> ]: >>> for this_experiment in ['hist-1950']:#, 'highres-future']: >>> siconc_list = list_variable_files( >>> source_id = this_model, >>> variable_id = 'siconc', >>> experiment_id = this_experiment, >>> variant_label = this_variant_label, >>> ) >>> sispeed_list = list_variable_files( >>> source_id = this_model, >>> variable_id = 'sispeed', >>> experiment_id = this_experiment, >>> variant_label = this_variant_label, >>> ) >>> make_landfast_files( >>> siconc_files = siconc_list, >>> sispeed_files = sispeed_list, >>> map_bbox = CAA_BBOX, >>> precise_trim = False, >>> ) (make_landfast_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/silandfast/gn/v20260617/trim_CAA_silandfast_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195001-195012.nc`. (make_landfast_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/silandfast/gn/v20260617/trim_CAA_silandfast_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195101-195112.nc`. (make_landfast_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/silandfast/gn/v20260617/trim_CAA_silandfast_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195201-195212.nc`. ... (make_landfast_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/silandfast/gn/v20260617/trim_CAA_silandfast_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_201201-201212.nc`. (make_landfast_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/silandfast/gn/v20260617/trim_CAA_silandfast_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_201301-201312.nc`. (make_landfast_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/silandfast/gn/v20260617/trim_CAA_silandfast_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_201401-201412.nc`. .. py:function:: get_current_datetime_str(str_format: str = '%Y-%m-%dT%H:%M:%SZ') Get the current datetime in UTC. Format the current datetime into a string based on the given format string. :param str_format: The format string by which to format the current datetime. Default is `"%Y-%m-%dT%H:%M:%SZ"`. :type str_format: `str`, optional :returns: **datetime_str** -- The formatted current datetime as a string. :rtype: `str` .. rubric:: Examples >>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str .. 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:: trim_latlon(dataset: (str, xarray.Dataset, xarray.DataArray), map_bbox: [float, float, float, float] = sps.NWP_BBOX, precise_trim: bool = False, save_as: str = None, verbose: bool = False) Trim the given dataset. Select only the data within the given bounding box of latitude and longitude coordinates from the given dataset. :param dataset: The dataset to plot. :type dataset: `str`, `xarray.Dataset`, `xarray.DataArray` :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 precise_trim: Whether to precisely trim an irregular grid to the bounding box, making all values outside the bounding box null. Default is `False`. :type precise_trim: `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 :returns: **xr_data_trimmed** -- The dataset trimmed to the latitude and longitude ranges provided. :rtype: `xarray.Dataset` .. rubric:: Examples >>> .. py:function:: make_file_path(path) Create a file path. Create the specified directory structure if the given path doesn't exist. :param path: Relative path to make. :type path: `str` :returns: **path** -- The verified path to the data files. :rtype: `str` .. rubric:: Examples >>> make_file_path('datafiles/some/more/data/a_file.txt') 'datafiles/some/more/data/' .. py:function:: calc_siconc(sithick_dataset: (str, [str], xarray.DataArray, xarray.Dataset), sivol_dataset: (str, [str], xarray.DataArray, xarray.Dataset), save_as: str = None, verbose: bool = False, **kwargs) Calculate sea ice concentration from sea ice thickness and volume. Verify the dataset(s) contains the `sithick` and `sivol` variables, calculate `siconc` based on those variables, and return a new dataset. :param sithick_dataset: The sea ice thickness dataset. Must have the same source ID, experiment ID, variant label, and dimensions sizes as `sivol_dataset`. :type sithick_dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :param sivol_dataset: The sea ice volume dataset. Must have the same source ID, experiment ID, variant label, and dimensions sizes as `sithick_dataset`. :type sivol_dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset` :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. :returns: **siconc2_xr** -- A dataset of calculated sea ice concentration values. :rtype: `xarray.Dataset` .. rubric:: Examples >>> from arctichoke.dataset.example_dataset import make_example_dataset >>> dataset_0 = make_example_dataset(n=3, test_var_name='sithick') >>> dataset_0['sithick'].values array([[1., 2., 3.], [4., 5., 6.], [7., 8., 9.]]) >>> dataset_1 = make_example_dataset(n=3, test_var_name='sivol') >>> dataset_1['sivol'].values array([[0., 1., 2.], [3., 4., 5.], [6., 7., 8.]]) >>> from arctichoke.analysis import calc_siconc >>> dataset_siconc2 = calc_siconc(sithick_dataset=dataset_0, sivol_dataset=dataset_1) >>> dataset_siconc2['siconc2'].values array([[ 0. , 50. , 66.66666667], [75. , 80. , 83.33333333], [85.71428571, 87.5 , 88.88888889]]) .. py:function:: make_siconc_files(sithick_files: [str], sivol_files: [str], map_bbox: [float, float, float, float] = None, version_id: str = 'v20260617', overwrite: bool = False, **kwargs) Make sea ice concentration files based on the lists of files given. For each given pair of files, load the data, trim the datasets (if applicable), calculate the sea ice concentration, then save the sea ice concentration dataset as a new file in the same directory structure. :param sithick_files: A list of paths of the sea ice thickness data files. :type sithick_files: List of `str` :param sivol_files: A list of paths of the sea ice volume data files. :type sivol_files: List of `str` :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 `None`, meaning the data will not be trimmed. :type map_bbox: Array of `float`, `None`, optional :param version_id: The version ID to use when making the directory structure for the sea ice concentration files. Default is `'v20260617'`. :type version_id: `str`, optional :param overwrite: Whether to overwrite an existing file if it exists. Default is `False`. :type overwrite: `bool`, optional :param \*\*kwargs: Keyword arguments to pass to `trim_latlon()`, and `calc_siconc()`. :rtype: None .. rubric:: Examples >>> from arctichoke.path import list_variable_files >>> from arctichoke.analysis import make_siconc_files >>> from arctichoke.params import CAA_BBOX >>> this_model = 'EC-Earth3P-HR' >>> for this_variant_label in [ >>> 'r1i1p2f1', >>> 'r2i1p2f1', >>> 'r3i1p2f1', >>> ]: >>> for this_experiment in ['hist-1950']:#, 'highres-future']: >>> sithick_list = list_variable_files( >>> source_id = this_model, >>> variable_id = 'sithick', >>> experiment_id = this_experiment, >>> variant_label = this_variant_label, >>> ) >>> sivol_list = list_variable_files( >>> source_id = this_model, >>> variable_id = 'sivol', >>> experiment_id = this_experiment, >>> variant_label = this_variant_label, >>> ) >>> make_siconc_files( >>> sithick_files = sithick_list, >>> sivol_files = sivol_list, >>> map_bbox = CAA_BBOX, >>> precise_trim = False, >>> ) (make_siconc_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc2/gn/v20260617/trim_CAA_siconc2_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195001-195012.nc`. (make_siconc_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc2/gn/v20260617/trim_CAA_siconc2_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195101-195112.nc`. (make_siconc_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r1i1p2f1/SImon/siconc2/gn/v20260617/trim_CAA_siconc2_SImon_EC-Earth3P-HR_hist-1950_r1i1p2f1_gn_195201-195212.nc`. ... (make_siconc_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/siconc2/gn/v20260617/trim_CAA_siconc2_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_201201-201212.nc`. (make_siconc_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/siconc2/gn/v20260617/trim_CAA_siconc2_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_201301-201312.nc`. (make_siconc_files) Writing file `/arctichoke_data/bergybits/data/CMIP6/HighResMIP/EC-Earth-Consortium/EC-Earth3P-HR/hist-1950/r3i1p2f1/SImon/siconc2/gn/v20260617/trim_CAA_siconc2_SImon_EC-Earth3P-HR_hist-1950_r3i1p2f1_gn_201401-201412.nc`. .. py:function:: get_current_datetime_str(str_format: str = '%Y-%m-%dT%H:%M:%SZ') Get the current datetime in UTC. Format the current datetime into a string based on the given format string. :param str_format: The format string by which to format the current datetime. Default is `"%Y-%m-%dT%H:%M:%SZ"`. :type str_format: `str`, optional :returns: **datetime_str** -- The formatted current datetime as a string. :rtype: `str` .. rubric:: Examples >>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str .. 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:: 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:: get_current_datetime_str(str_format: str = '%Y-%m-%dT%H:%M:%SZ') Get the current datetime in UTC. Format the current datetime into a string based on the given format string. :param str_format: The format string by which to format the current datetime. Default is `"%Y-%m-%dT%H:%M:%SZ"`. :type str_format: `str`, optional :returns: **datetime_str** -- The formatted current datetime as a string. :rtype: `str` .. rubric:: Examples >>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str .. 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:: 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:: 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:: mask_where_all_zero(dataset: (str, [str], xarray.Dataset, xarray.DataArray), var: str = None, time_dim: str = 'year', verbose: bool = False) Masks out grid cells which are zero across time. For each grid cell in the dataset, if that grid cell is equal to zero across the entire time dimension, set those values to `nan`. This will allow masking out grid cells which have no trend in time not because the values don't change, but because they are missing data. Note, this is done by summing across time to find which cells have a sum of zero, so this should not be used for any variable which could have negative values. :param dataset: The dataset of which to mask zeros across time. :type dataset: `str`, list of `str`, `xarray.Dataset`, `xarray.DataArray` :param var: The variable in `dataset` for which to mask zeros 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 zeros. Default is `year`. :type time_dim: `str`, optional :param verbose: Whether to verbosely output information as the function executes. Default is `False`. :type verbose: `bool`, optional :returns: **trends_dataset** -- A dataset with the trends in time for the specified variable. :rtype: `xarray.Dataset` or `xarray.DataArray` .. rubric:: Examples >>> import xarray as xr >>> xr_ds = xr.Dataset({ >>> 'test_var': ( >>> ['t', 'i', 'j'], >>> [[[ 0, 0, 0], >>> [ 1, 1, 1], >>> [ 0, 0, 0]], >>> [[ 0, 1, 1], >>> [ 1, 0, 0], >>> [ 0, 0, 0]]] >>> ) >>> }) >>> xr_ds['test_var'].values array([[[0, 0, 0], [1, 1, 1], [0, 0, 0]], [[0, 1, 1], [1, 0, 0], [0, 0, 0]]]) >>> from arctichoke.analysis.trend_in_time import mask_where_all_zero >>> xr_ds_nan = mask_where_all_zero( >>> xr_ds, >>> 'test_var', >>> time_dim = 't' >>> ) >>> xr_ds_nan['test_var'].values array([[[nan, 0., 0.], [ 1., 1., 1.], [nan, nan, nan]], [[nan, 1., 1.], [ 1., 0., 0.], [nan, nan, nan]]])