7.3.11. PF Backend Module

class parflow.tools.pf_backend.ParflowBackendArray(file_or_seq, dims=None, shape=None, z_first=True, z_is='z', init_key={})

Bases: BackendArray

Backend array that allows for lazy indexing on pfb-based data.

__init__(file_or_seq, dims=None, shape=None, z_first=True, z_is='z', init_key={})

Instantiate a new ParflowBackendArray.

Parameters:

  • file_or_seq – File or files that the array will read from.

  • dims – Names of the dimension along each array axis.

  • shape – The expected shape of the array.

  • z_first – Whether the z axis is first. If not, it will be last.

  • z_is – What the z axis represents. Can be ‘z’, ‘time’, ‘variable’

  • init_key – An initial key that can be used to prematurely subset.

property dims

Names of the dimensions of each axis of the array

property pfb_dims

names of dimensions in the underlying pfb file

property pfb_shape

names of dimensions in the underlying pfb file

property shape

Shape of the data once loaded into memory

property squeeze_dims

names of dimensions in the underlying pfb file

class parflow.tools.pf_backend.ParflowBackendEntrypoint

Bases: BackendEntrypoint

Provides an entrypoint for xarray to read Parflow input/output Note: Users should never instantiate, import, or call any of this code directly. This hooks into the xarray library directly via the entrypoints provided at the time of installation. Users should interact with this code by using the xarray library directly.

guess_can_open(filename_or_obj)

Registers the backend to recognize *.pfb and *.pfmetadata files

is_meta_or_pfb(filename_or_obj, strict=True)

Determine if a file is a pfb file or pfmetadata file

load_clm_output_pfb(var_meta, name)

These filetypes have dimensions (time, x, y, variable) where the variable ordering is fixed and each file represents an individual timestep

load_component_pfb(var_meta, name)

These filetypes have dimensions (component, x, y, z) where component represents an anisotropy

load_coords_from_meta(coord_meta) → Mapping[str, DataArray]

Builds coordinate variables from the ‘coordinates’ section of a pfmetadata file.

load_pfb_from_meta(var_meta, name='_') → Mapping[str, Dataset]

Determines which sub-reader call to make based on the information in the metadata section for a single variable of the pfmetadata file.

Parameters:

  • var_meta – The metadata for the variable being read.

  • name – A name to give the xarray dataset.

Returns:

A dictionary of xarray datasets with keys being the variable names

load_pfmetadata(filename_or_obj, pf_meta, read_inputs, read_outputs) → Dataset

Helper method to load data specified via a pfmetadata file.

Parameters:

  • filename_or_obj – The pfmetadata file to read

  • pf_meta – The parsed pfmetadata file - automatically registered via the _is_meta_or_pfb method.

  • read_inputs – Whether or not to read files in the “inputs” section of the pfmetadata file. This can be either a boolean value or a list of variable names to read from the “inputs” section. If true xarray will read all available input variables.

  • read_outputs – Whether or not to read files in the “outputs” section of the pfmetadata file. This can be either a boolean value or a list of variable names to read from the “outputs” section. If true xarray will read all available output variables.

Returns:

The assembled xarray dataset

load_sequence_of_pfb(filenames, dims=None, shape=None, z_first=True, z_is='z', init_key={}) → Variable
load_single_pfb(filename_or_obj, dims=None, shape=None, z_first=True, z_is='z') → Variable

Load a pfb file directly as an xr.Variable

load_time_varying_2d_ts_pfb(var_meta, name)

These filetypes have dimensions (time_stride, x, y, time_slice) where the time dimension will be strided along separate files and each individual file contains time_slice number of timesteps

load_time_varying_pfb(var_meta, name)

These filetypes have dimensions (time, z, y, x) where a each file represents an individual time

open_dataset(filename_or_obj, *, base_dir=None, drop_variables=None, name='parflow_variable', read_inputs=True, read_outputs=True, inferred_dims=None, inferred_shape=None, chunks={}, strict_ext_check=False) → Dataset

Open Parflow input/output as an xarray.Dataset.

Parameters:

  • filename_or_obj – The pfb file or pfmetadata file to read.

  • base_dir – A base directory to read from. This is optional, but allows you to specify a common directory to read multiple files from if it is not recorded in the pfmetadata file.

  • read_inputs – Whether or not to read files in the “inputs” section of the pfmetadata file. This can be either a boolean value or a list of variable names to read from the “inputs” section. If true xarray will read all available input variables.

  • read_outputs – Whether or not to read files in the “outputs” section of the pfmetadata file. This can be either a boolean value or a list of variable names to read from the “outputs” section. If true xarray will read all available output variables.

  • inferred_dims – Expected dimensions of the arrays being read in. This can be used to slightly optimize performance, but is not necessary.

  • inferred_shape – Expected shape of the arrays being read in. This can be used to slightly optimize performance, but is not necessary.

  • chunks – The chunking scheme to apply along dimensions. See: https://xarray.pydata.org/en/stable/generated/xarray.Dataset.chunk.html for usage options. This is primarily set for automatically parallelizing computations via dask.

  • strict_ext_check – Whether or not to strictly check the filename extension for determining if we are opening a pfb file or a pfmetadata file. Strict checks will actually try to open the file, while non-strict simply check the filename extension. This can slightly improve performance when reading many pfb files.

Returns:

An xr.Dataset with a collection of xr.DataArray objects as variables.

open_dataset_parameters: ClassVar[tuple | None] = ['filename_or_obj', 'drop_variables', 'name', 'meta_yaml', 'read_inputs', 'read_outputs', 'inferred_dims', 'inferred_shape']