Stitching API

Module for stitching netCDF-SCM netCDF files together

‘Stitching’ here means combining results from multiple experiments e.g. combining historical and scenario experiments. This relies on the ‘parent’ conventions within CMIP experiments which define the experiment from which a given set of output started (in CMIP language, the experiment from which a given experiment ‘branched’).

netcdf_scm.stitching.get_branch_time(openscmrun, parent=True, source_path=None, parent_path=None)[source]

Get branch time of an experiment

Parameters
  • openscmrun (scmdata.ScmRun) – Data of which to get the branch time

  • parent (bool) – Should I get the branch time in the parent experiment’s time co-ordinates? If False, return the branch time in the child (i.e. openscmrun’s) time co-ordinates.

  • source_path (str) – Path to the data file from which openscmrun is derived. This is only required if parent is False. It is needed because information about the time calendar and units of the data in openscmrun is only available in the source file.

  • parent_path (str) – Path to the data file containing the parent data of openscmrun. This is only required if the data is from CMIP5 because CMIP5 data does not store information about the parent experiment’s time calendar and units.

Returns

The branch time, rounded to the nearest year, month and day. netCDF-SCM is not designed for very precise calculations, if you need to keep finer information, please raise an issue on our issue tracker to discuss.

Return type

datetime.datetime

Raises
  • ValueErrorparent is not True and the data is CMIP5 data. It is impossible to determine the branch time in the child time co-ordinates from CMIP5 data because of a lack of information.

  • ValueErrorparent_path is None and the data is CMIP5 data. You must supply the parent path if the data is CMIP5 data because the parent file is the only place the parent experiment’s time units and calendar information is available.

netcdf_scm.stitching.get_continuous_timeseries_with_meta(infile, drs, return_picontrol_info=True)[source]

Load a continuous timeseries with metadata

Continuous here means including all parent experiments up to (but not including) piControl

Parameters
  • infile (str) – netCDF-SCM crunched file to load

  • drs (str) – Data reference syntax which applies to this file

  • return_picontrol_info (bool) – If supplied, piControl information will be returned in the second and third outputs if available (rather than None). A caveat is that if the experiment itself is a piControl experiment, None will be returned in the second and third outputs.

Returns

  • scmdata.ScmRun – Loaded timseries, including metadata

  • dt.datetime – Branch time from piControl. If infile points to a piControl or piControl-spinup experiment then this will be None.

  • str – Path from which the piControl data was loaded. If infile points to a piControl or piControl-spinup experiment then this will be None.

netcdf_scm.stitching.get_parent_file_path(infile, parent_replacements, drs)[source]

Get parent file path for a given file

Parameters
  • infile (str) – File path of which to get the parent

  • parent_replacements (dict of str : str) – Replacements to insert in infile to determine the parent filepath

  • drs (str) – Data reference syntax which is applicable to these filepaths

Returns

Path of the parent file

Return type

str

Raises
netcdf_scm.stitching.get_parent_replacements(scmdf)[source]

Get changes in metadata required to identify a dataset’s parent file

Parameters

scmdf (scmdata.ScmRun) – Dataset of which to identify the parent file

Returns

dict of str – Replacements which must be made to the dataset’s metadata in order to identify its parent file

Return type

str

Raises

KeyError – The variant label (e.g. r1i1p1f1) of the parent dataset is missing

netcdf_scm.stitching.step_up_family_tree(in_level)[source]

Step name up the family tree

Parameters

in_level (str) – Level from which to step up

Returns

Level one up from in_level

Return type

str

Examples

>>> step_up_family_tree("(child)")
"(parent)"
>>> step_up_family_tree("(parent)")
"(grandparent)"
>>> step_up_family_tree("(grandparent)")
"(grandparent)"
>>> step_up_family_tree("(greatgreatgrandparent)")
"(greatgreatgreatgrandparent)"