arctichoke.analysis
Submodules
Attributes
Functions
|
Get the current datetime in UTC. |
|
Get the variable name of the dataset. |
|
Trim the given dataset. |
|
Create a file path. |
|
Calculate where packed ice is from the dataset. |
|
Calculate where slow ice is from the dataset. |
|
Calculate where landfast ice is from the dataset(s). |
|
Make landfast files based on the lists of files given. |
|
Get the current datetime in UTC. |
|
Get the variable name of the dataset. |
|
Trim the given dataset. |
|
Create a file path. |
|
Calculate sea ice concentration from sea ice thickness and volume. |
|
Make sea ice concentration files based on the lists of files given. |
|
Get the current datetime in UTC. |
|
Get the variable name of the dataset. |
|
Sum a dataset by year along the time axis. |
|
Get the current datetime in UTC. |
|
Get the variable name of the dataset. |
|
Get the minimum / maximum of the dataset. |
|
Find the trend for each grid cell along the time axis. |
|
Masks out grid cells which are zero across time. |
Package Contents
- arctichoke.analysis.cdo
- arctichoke.analysis.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.
- Parameters:
str_format (str, optional) – The format string by which to format the current datetime. Default is “%Y-%m-%dT%H:%M:%SZ”.
- Returns:
datetime_str – The formatted current datetime as a string.
- Return type:
str
Examples
>>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str
- arctichoke.analysis.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.analysis.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.
- Parameters:
dataset (str, xarray.Dataset, xarray.DataArray) – The dataset to plot.
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.
precise_trim (bool, optional) – Whether to precisely trim an irregular grid to the bounding box, making all values outside the bounding box null. 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.
- Returns:
xr_data_trimmed – The dataset trimmed to the latitude and longitude ranges provided.
- Return type:
xarray.Dataset
Examples
>>>
- arctichoke.analysis.make_file_path(path)
Create a file path.
Create the specified directory structure if the given path doesn’t exist.
- Parameters:
path (str) – Relative path to make.
- Returns:
path – The verified path to the data files.
- Return type:
str
Examples
>>> make_file_path('datafiles/some/more/data/a_file.txt') 'datafiles/some/more/data/'
- arctichoke.analysis.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.
- Parameters:
dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset of which to find the locations of packed ice.
packed_threshold (int, float, optional) – The threshold above which to mark packed ice. Default is 85 percent, following Laliberté et al. 2018.
siconc_var (str, optional) – The name of the variable to use from the provided dataset. Must be either siconc or siconc2. Default is siconc.
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 cdo.setrtoc2().
- Returns:
packedice_xr – A dataset where packed ice is marked as 1 and all other values are 0.
- Return type:
xarray.Dataset
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.]])
- arctichoke.analysis.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.
- Parameters:
dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset of which to find the locations of slow ice.
slow_threshold (int, float, optional) – The threshold above which to mark slow ice. Default is 0.01 m s-1, following Laliberté et al. 2018.
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 cdo.setrtoc2().
- Returns:
slowice_xr – A dataset where slow ice is marked as 1 and all other values are 0.
- Return type:
xarray.Dataset
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.]])
- arctichoke.analysis.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.
- Parameters:
siconc_dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset of which to find the locations of landfast ice that contains siconc/siconc2.
sispeed_dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The dataset of which to find the locations of landfast ice that contains sispeed.
packed_threshold (int, float, optional) – The threshold above which to mark packed ice. Default is 85 percent, following Laliberté et al. 2018.
slow_threshold (int, float, optional) – The threshold above which to mark slow ice. Default is 0.01 m s-1, following Laliberté et al. 2018.
siconc_var (str, optional) – The name of the variable to use from the provided sea ice concentration dataset. Must be either siconc or siconc2. Default is siconc.
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 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.
- Return type:
xarray.Dataset
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.]])
- arctichoke.analysis.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.
- Parameters:
siconc_files (List of str) – A list of paths of the sea ice concentration data files.
sispeed_files (List of str) – A list of paths of the sea ice speed data files.
map_bbox (Array of float, None, 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 None, meaning the data will not be trimmed.
version_id (str, optional) – The version ID to use when making the directory structure for the landfast ice files. Default is ‘v20260617’.
siconc_var (str, optional) – The name of the variable to use from the provided sea ice concentration dataset. Must be either siconc or siconc2. Default is siconc.
overwrite (bool, optional) – Whether to overwrite an existing file if it exists. Default is False.
**kwargs – Keyword arguments to pass to trim_latlon(), and find_landfast_ice().
- Return type:
None
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`.
- arctichoke.analysis.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.
- Parameters:
str_format (str, optional) – The format string by which to format the current datetime. Default is “%Y-%m-%dT%H:%M:%SZ”.
- Returns:
datetime_str – The formatted current datetime as a string.
- Return type:
str
Examples
>>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str
- arctichoke.analysis.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.analysis.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.
- Parameters:
dataset (str, xarray.Dataset, xarray.DataArray) – The dataset to plot.
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.
precise_trim (bool, optional) – Whether to precisely trim an irregular grid to the bounding box, making all values outside the bounding box null. 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.
- Returns:
xr_data_trimmed – The dataset trimmed to the latitude and longitude ranges provided.
- Return type:
xarray.Dataset
Examples
>>>
- arctichoke.analysis.make_file_path(path)
Create a file path.
Create the specified directory structure if the given path doesn’t exist.
- Parameters:
path (str) – Relative path to make.
- Returns:
path – The verified path to the data files.
- Return type:
str
Examples
>>> make_file_path('datafiles/some/more/data/a_file.txt') 'datafiles/some/more/data/'
- arctichoke.analysis.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.
- Parameters:
sithick_dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The sea ice thickness dataset. Must have the same source ID, experiment ID, variant label, and dimensions sizes as sivol_dataset.
sivol_dataset (str, list of str, xarray.DataArray, xarray.Dataset) – The sea ice volume dataset. Must have the same source ID, experiment ID, variant label, and dimensions sizes as sithick_dataset.
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.
- Returns:
siconc2_xr – A dataset of calculated sea ice concentration values.
- Return type:
xarray.Dataset
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]])
- arctichoke.analysis.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.
- Parameters:
sithick_files (List of str) – A list of paths of the sea ice thickness data files.
sivol_files (List of str) – A list of paths of the sea ice volume data files.
map_bbox (Array of float, None, 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 None, meaning the data will not be trimmed.
version_id (str, optional) – The version ID to use when making the directory structure for the sea ice concentration files. Default is ‘v20260617’.
overwrite (bool, optional) – Whether to overwrite an existing file if it exists. Default is False.
**kwargs – Keyword arguments to pass to trim_latlon(), and calc_siconc().
- Return type:
None
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`.
- arctichoke.analysis.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.
- Parameters:
str_format (str, optional) – The format string by which to format the current datetime. Default is “%Y-%m-%dT%H:%M:%SZ”.
- Returns:
datetime_str – The formatted current datetime as a string.
- Return type:
str
Examples
>>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str
- arctichoke.analysis.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.analysis.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.analysis.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.
- Parameters:
str_format (str, optional) – The format string by which to format the current datetime. Default is “%Y-%m-%dT%H:%M:%SZ”.
- Returns:
datetime_str – The formatted current datetime as a string.
- Return type:
str
Examples
>>> from arctichoke import get_current_datetime_str >>> get_current_datetime_str
- arctichoke.analysis.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.analysis.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.analysis.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.analysis.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.
- Parameters:
dataset (str, list of str, xarray.Dataset, xarray.DataArray) – The dataset of which to mask zeros across time.
var (str, None, optional) – The variable in dataset for which to mask zeros 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 zeros. Default is year.
verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.
- Returns:
trends_dataset – A dataset with the trends in time for the specified variable.
- Return type:
xarray.Dataset or xarray.DataArray
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]]])