Gridded NetCDF surface flux gridded_netcdf/std

Gridded NetCDF surface flux gridded_netcdf/std#

Description#

Reads surface flux from a 1+2D (time x latitude x longitude) gridded NetCDF files

The provided NetCDF files should all have the exact same latitude x longitude grid. The latitude x longitude grid will only be read from the NetCDF file corresponding to the first simulation sub-period.

The time coordinate should be named 'time' in the NetCDF files.

Either file_freq or is_climatology argument is required.

See Gridded NetCDF domain plugin for information about the required coordinates format in the NetCDF file.

YAML arguments#

The following arguments are used to configure the plugin. pyCIF will return an exception at the initialization if mandatory arguments are not specified, or if any argument does not fit accepted values or type:

Optional arguments#

dir : str, optional, default “”

Path to the corresponding component. This value is used if not provided in parameters

file : str, optional, default “”

File format in the given directory. This value is used if not provided in parameters

varname : str, optional, default “”

Variable name to use to read data filesinstead of the parameter name if different to the parameter name

file_freq : str, optional, default “”

The time frequency at which data files are available. Should be a multiple of one of Pandas’ offset aliases which will be passed to the pandas.date_range method, ex: ‘1MS’ for every first day of the month

split_freq : str, optional

Force splitting the processing at a given frequency different to file_freq

is_climatology : bool, optional, default False

Set this argument to True for climatological data (i.e. year-independent data)

var_freq : str, optional

The time frequency of the flux variable within the NetCDF files. Should be one of Pandas’ offset aliases which will be passed to the pandas.DatetimeIndex.to_period method. This argument may not be needed is the time frequency in the NetCDF files is regular, ex: ‘D’ for daily values

force_var_freq : bool, optional, default False

Force using var_freq instead of the time dimension.

remove_duplicates : bool, optional, default True

Remove duplicate files matching the prescribed pattern

time_varname : str, optional

Time coordinate variable name in file. If this argument is not provided, the time coordinate is found by its standard_name or long_name (which should be 'time'). If the time coordinate cannot be found by its attributes, the variable named 'time' will be used if it exists.

period_varname : str, optional

Period variable, used to define time intervals valid for each value in the dataset

time_coordinate : str, optional

Name of the time coordinate if different from the time variable

time_dimname : str, optional, default “time”

Time dimension name in file.

time_midpoint : bool, optional, default False

Whether the time variable defines the beginning of each period of validity of the data, or the midpoint. True for midpoint.

time_endpoint : bool, optional, default False

Whether the time variable defines the beginning of each period of validity of the data, or the endpoint. True for endpoint.

time_unit : str, optional

NetCDF standard time unit, if not specified in the file. Can contain a date format (ex: "%Y-%m-%d) which will be decoded with the current file datetime. Cannot be used along side the time_format argument

time_calendar : “gregorian” or “noleap”, optional

Overwrite the calendar as specified in the files

  • “gregorian”: Standard Gregorian calendar

  • “noleap”: calendar with no leap years

time_format : str, optional

The strftime to parse the time coordinate values, e.g. "%Y%m%d". This argument is passed to the pandas.to_datetime method’s format keyword argument. Cannot be used along side the time_unit argument

add_time_coord : bool, optional, default False

Set this argument to True if there is no time coordinate. in the NetCDF file. Timestamps will be added acording to the var_freq or file_freq argument. Use the var_freq argument only if there is a single timestamp per file. When the var_freq argument is used the time dimension is found with the time_dimname argument. Cannot be used with the is_climatology argument.

sum_along_dim : str, optional

Sum the data along a given dimension (other than lon, lat, lev and time)

group_name : str, optional

Name of the NetCDF group to read in the NetCDF file

sum_variables : str, optional, default False

If several variables are specified in varname, force them to be summed

slice_dimension : optional

Keep only slices over some dimensions. This is useful when the data hqs more dimensions than ones corresponding to (time, level, lat, lon). It is possible to slice over given dimensions with the convention slice(slice_min, slice_max, slice_freq)

Argument structure:
any_key : optional

Name of a dimension.

Argument structure:
slice_min : int, optional

Start for the slice

slice_max : int, optional

End for the slice

slice_freq : int, optional

Frequency for the slice

method : “sum” or “avg”, optional, default “sum”

Method for the slicing

  • “sum”: sum over the slice

  • “avg”: average over the slice

latitude_varname : str, optional, default “latitude”

Latitude coordinate variable name in file. If this argument is not provided, the latitude coordinate is found by its standard_name or long_name attribute (which should be 'latitude').

longitude_varname : str, optional, default “longitude”

Longitude coordinate variable name in file. If this argument is not provided, the longitude coordinate is found by its standard_name or long_name attribute (which should be 'longitude').

latitude_dimname : str, optional, default “latitude”

Latitude dimension name in file.

longitude_dimname : str, optional, default “longitude”

Longitude dimension name in file.

use_corners : bool, optional, default False

True if the longitudes and latitudes are used to defined the corners instead of gridcell centers

extend_lat : bool, optional, default False

Extend corner latitudes by one cell if nlat_corner != nlat + 1

extend_lon : bool, optional, default False

Extend corner longitudes by one cell if nlon_corner != nlon + 1

lat_min : float, optional, default -90.0

Minimum latitude

lat_max : float, optional, default 90.0

Maximum latitude

delta_lat : float, optional

Skip the reading/computation of latitude bounds and use regular gridcells with a size of delta_lat. delta_lat should divide lat_max - lat_min and be coherent with the NetCDF file dimensions.

lon_min : float, optional, default -180.0

Minimum longitude

lon_max : float, optional, default 180.0

Maximum longitude

delta_lon : float, optional

Skip the reading/computation of longitude bounds and use regular gridcells with a size of delta_lon. delta_lon should divide lon_max - lon_min and be coherent with the NetCDF file dimensions.

regular_lon : bool, optional, default True
Overwrites the default behaviour of regular domain

in zonal direction to compute corners. In this case, use the first and last delta to extent East and West

regular_lat : bool, optional, default True

Overwrites the default behaviour of regular domain in meridional direction to compute corners. In this case, use the first and last delta to extent South and North

force_centered_lat : bool, optional, default False

Force grid cells latitude to be centered between thier corners. Grid cells centers and corners will be read normally then the grid cells centers latitudes will be adjusted.

force_centered_lon : bool, optional, default False

Force grid cells longitude to be centered between thier corners. Grid cells centers and corners will be read normally then the grid cells centers longitudes will be adjusted.

sort_lat : bool, optional, default True

Sort latitudes in ascending order

sort_lon : bool, optional, default True

Sort longitudes in ascending order

drop_variables : list, optional, default []

List of variables to drop when reading the NetCDF files. This allows issues of MissingDimensionErrors as documented in, e.g., https://stackoverflow.com/questions/55109481/how-to-import-netcdf4-file-with-xarray-when-index-names-have-multiple-dimensions

dir_vcoord : str, optional, default “”

Directory containing file_vcoord. Use this argument if the vertical coordinates are not in file

file_vcoord : str, optional

NetCDF file containing the vertical coordinates. Use this argument if the vertical coordinates are not in file

vertical_coord : “mids” or “bounds”, optional

Read the domain’s vertical levels if this parameter is used. Should be ‘mids’ if the vertical coordinate represents the levels mid-points or ‘bounds’ if the vertical coordinate represents the levels boundaries. If this parameter is not used a domain single vertical level is created

  • “mids”: levels mid-points

  • “bounds”: levels boundaries

vertical_dim_name : str, optional, default “lev”

Vertical dimension name in file or file_vcoord

vertical_dim_type : “sigma_pressure” or “heights”, optional, default “sigma_pressure”

Vertical dimension type

  • “sigma_pressure”: Levels defined with ap/bp sigma pressure coordinates, with p = psurf * bp + ap

  • “heights”: Levels in meters above ground

sigma_a_var_name : str, optional, default “ap”

‘sigma a’ variable name in file or file_vcoord

sigma_b_var_name : str, optional, default “bp”

‘sigma b’ variable name in file or file_vcoord

pressure_unit : “Pa” or “hPa”, optional

pressure units if different from units attributes in sigma `a` variable, should be ``'Pa' or 'hPa'

reverse_vcoord : bool, optional, default False

reverse the vertical coordinate or not

YAML template#

Please find below a template for a YAML configuration:

 1flux:
 2  plugin:
 3    name: gridded_netcdf
 4    version: std
 5    type: flux
 6
 7  # Optional arguments
 8  dir: XXXXX  # str
 9  file: XXXXX  # str
10  varname: XXXXX  # str
11  file_freq: XXXXX  # str
12  split_freq: XXXXX  # str
13  is_climatology: XXXXX  # bool
14  var_freq: XXXXX  # str
15  force_var_freq: XXXXX  # bool
16  remove_duplicates: XXXXX  # bool
17  time_varname: XXXXX  # str
18  period_varname: XXXXX  # str
19  time_coordinate: XXXXX  # str
20  time_dimname: XXXXX  # str
21  time_midpoint: XXXXX  # bool
22  time_endpoint: XXXXX  # bool
23  time_unit: XXXXX  # str
24  time_calendar: XXXXX  # gregorian|noleap
25  time_format: XXXXX  # str
26  add_time_coord: XXXXX  # bool
27  sum_along_dim: XXXXX  # str
28  group_name: XXXXX  # str
29  sum_variables: XXXXX  # str
30  slice_dimension:
31    any_key:
32      slice_min: XXXXX  # int
33      slice_max: XXXXX  # int
34      slice_freq: XXXXX  # int
35      method: XXXXX  # sum|avg
36  latitude_varname: XXXXX  # str
37  longitude_varname: XXXXX  # str
38  latitude_dimname: XXXXX  # str
39  longitude_dimname: XXXXX  # str
40  use_corners: XXXXX  # bool
41  extend_lat: XXXXX  # bool
42  extend_lon: XXXXX  # bool
43  lat_min: XXXXX  # float
44  lat_max: XXXXX  # float
45  delta_lat: XXXXX  # float
46  lon_min: XXXXX  # float
47  lon_max: XXXXX  # float
48  delta_lon: XXXXX  # float
49  regular_lon: XXXXX  # bool
50  regular_lat: XXXXX  # bool
51  force_centered_lat: XXXXX  # bool
52  force_centered_lon: XXXXX  # bool
53  sort_lat: XXXXX  # bool
54  sort_lon: XXXXX  # bool
55  drop_variables: XXXXX  # list
56  dir_vcoord: XXXXX  # str
57  file_vcoord: XXXXX  # str
58  vertical_coord: XXXXX  # mids|bounds
59  vertical_dim_name: XXXXX  # str
60  vertical_dim_type: XXXXX  # sigma_pressure|heights
61  sigma_a_var_name: XXXXX  # str
62  sigma_b_var_name: XXXXX  # str
63  pressure_unit: XXXXX  # Pa|hPa
64  reverse_vcoord: XXXXX  # bool