input4mips_validation.io#

`input4mips_validation.io` #

Input/output of data to/from disk

`generate_creation_timestamp()` #

Generate creation timestamp, formatted as needed for input4MIPs files

Returns:

Type	Description
`str`	Creation timestamp

Source code in src/input4mips_validation/io.py

def generate_creation_timestamp() -> str:
    """
    Generate creation timestamp, formatted as needed for input4MIPs files

    Returns
    -------
    :
        Creation timestamp
    """
    ts = dt.datetime.now(dt.timezone.utc).replace(
        microsecond=0  # remove microseconds from creation_timestamp
    )

    return ts.strftime(CREATION_DATE_FORMAT)

`generate_tracking_id()` #

Generate tracking ID

Returns:

Type	Description
`str`	Tracking ID

Source code in src/input4mips_validation/io.py

def generate_tracking_id() -> str:
    """
    Generate tracking ID

    Returns
    -------
    :
        Tracking ID
    """
    # TODO: ask Paul what this hdl business is about
    return "hdl:21.14100/" + str(uuid.uuid4())

`prepare_out_path_and_cubes(ds, out_path, cvs, xr_variable_processor=XRVariableHelper(), frequency_metadata_keys=FrequencyMetadataKeys(), bounds_info=BoundsInfo())` #

Prepare a path and iris.cube.Cube's for writing to disk

A note for users of this function. We convert the dataset to a list of iris.cube.Cube with ncdata.iris_xarray.cubes_from_xarray because iris adds CF-conventions upon writing, which is needed for input4MIPs data. This works smoothly in our experience, but the conversion can be tricky to debug. If you are having issues, this may be the reason.

Parameters:

Name	Type	Description	Default
`ds`	`Dataset`	Dataset to write to disk. May contain one or more variables.	required
`out_path`	`Path`	Path in which to write the dataset	required
`cvs`	`Input4MIPsCVs`	CVs to use to validate the dataset before writing	required
`xr_variable_processor`	`XRVariableProcessorLike`	Helper to use for processing the variables in xarray objects.	`XRVariableHelper()`
`frequency_metadata_keys`	`FrequencyMetadataKeys`	Metadata definitions for frequency information	`FrequencyMetadataKeys()`
`bounds_info`	`BoundsInfo`	Metadata definitions for bounds handling	`BoundsInfo()`

Returns:

Type	Description
`CubeList`	iris.cube.Cube's which can be written to disk.

Source code in src/input4mips_validation/io.py

def prepare_out_path_and_cubes(  # noqa: PLR0913
    ds: xr.Dataset,
    out_path: Path,
    cvs: Input4MIPsCVs,
    xr_variable_processor: XRVariableProcessorLike = XRVariableHelper(),
    frequency_metadata_keys: FrequencyMetadataKeys = FrequencyMetadataKeys(),
    bounds_info: BoundsInfo = BoundsInfo(),
) -> iris.cube.CubeList:
    """
    Prepare a path and [iris.cube.Cube][]'s for writing to disk

    A note for users of this function.
    We convert the dataset to a list of [iris.cube.Cube][]
    with [ncdata.iris_xarray.cubes_from_xarray][]
    because [iris][] adds CF-conventions upon writing,
    which is needed for input4MIPs data.
    This works smoothly in our experience,
    but the conversion can be tricky to debug.
    If you are having issues, this may be the reason.

    Parameters
    ----------
    ds
        Dataset to write to disk.
        May contain one or more variables.

    out_path
        Path in which to write the dataset

    cvs
        CVs to use to validate the dataset before writing

    xr_variable_processor
        Helper to use for processing the variables in xarray objects.

    frequency_metadata_keys
        Metadata definitions for frequency information

    bounds_info
        Metadata definitions for bounds handling

    Returns
    -------
    :
        [iris.cube.Cube][]'s which can be written to disk.

    See Also
    --------
    [input4mips_validation.io.write_ds_to_disk][].
    """
    # As part of https://github.com/climate-resource/input4mips_validation/issues/14
    # add final validation here for bullet proofness
    # - tracking ID, creation date, comparison with DRS from cvs etc.
    validation_result = get_ds_to_write_to_disk_validation_result(
        ds=ds,
        out_path=out_path,
        cvs=cvs,
        xr_variable_processor=xr_variable_processor,
        frequency_metadata_keys=frequency_metadata_keys,
        bounds_info=bounds_info,
    )
    validation_result.raise_if_errors()

    # Having validated, make the target directory and write
    out_path.parent.mkdir(parents=True, exist_ok=True)

    # Convert to cubes with ncdata
    cubes = ncdata.iris_xarray.cubes_from_xarray(ds)

    return cubes

`write_ds_to_disk(ds, out_path, cvs, **kwargs)` #

Write a dataset to disk

This function is just a thin wrapper around input4mips_validation.io.prepare_out_path_and_cubes and iris.save. For details, see these functions.

Parameters:

Name	Type	Description	Default
`ds`	`Dataset`	Dataset to write to disk. May contain one or more variables.	required
`out_path`	`Path`	Path in which to write the dataset	required
`cvs`	`Input4MIPsCVs`	CVs to use to validate the dataset before writing	required
`**kwargs`	`Any`	Passed through to iris.save	`{}`

Returns:

Type	Description
`Path`	Path in which the dataset was written

input4mips_validation.io#