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: (optional):

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

accepted type: str

file: (optional):

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

accepted type: str

varname: (optional):

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

accepted type: str

file_freq: (optional):

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

accepted type: str

split_freq: (optional)

Force splitting the processing at a given frequency different to file_freq

accepted type: str

is_climatology: (optional): False

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

accepted type: bool

var_freq: (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

accepted type: str

remove_duplicates: (optional): True

Remove duplicate files matching the prescribed pattern

accepted type: bool

time_varname: (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.

accepted type: str

period_varname: (optional)

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

accepted type: str

time_coordinate: (optional)

Name of the time coordinate if different from the time variable

accepted type: str

time_dimname: (optional): time

Time dimension name in file.

accepted type: str

time_midpoint: (optional): False

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

accepted type: bool

time_endpoint: (optional): False

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

accepted type: bool

time_unit: (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

accepted type: str

time_calendar: (optional)

Overwrite the calendar as specified in the files

accepted values:

  • gregorian: Standard Gregorian calendar

  • noleap: calendar with no leap years

time_format: (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

accepted type: str

add_time_coord: (optional): 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.

accepted type: bool

sum_along_dim: (optional)

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

accepted type: str

closest_year: (optional): False

If the correct year is not available, use the closest one

accepted type: bool

group_name: (optional)

Name of the NetCDF group to read in the NetCDF file

accepted type: str

sum_variables: (optional): False

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

accepted type: str

latitude_varname: (optional): 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').

accepted type: str

longitude_varname: (optional): 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').

accepted type: str

latitude_dimname: (optional): latitude

Latitude dimension name in file.

accepted type: str

longitude_dimname: (optional): longitude

Longitude dimension name in file.

accepted type: str

use_corners: (optional): False

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

accepted type: bool

extend_lat: (optional): False

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

accepted type: bool

extend_lon: (optional): False

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

accepted type: bool

lat_min: (optional): -90.0

Minimum latitude

accepted type: float

lat_max: (optional): 90.0

Maximum latitude

accepted type: float

delta_lat: (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.

accepted type: float

lon_min: (optional): -180.0

Minimum longitude

accepted type: float

lon_max: (optional): 180.0

Maximum longitude

accepted type: float

delta_lon: (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.

accepted type: float

regular_lon: (optional): 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

accepted type: bool

regular_lat: (optional): 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

accepted type: bool

sort_lat: (optional): True

Sort latitudes in ascending order

accepted type: bool

sort_lon: (optional): True

Sort longitudes in ascending order

accepted type: bool

dir_vcoord: (optional):

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

accepted type: str

file_vcoord: (optional)

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

accepted type: str

vertical_coord: (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

accepted values:

  • mids: levels mid-points

  • bounds: levels boundaries

vertical_dim_name: (optional): lev

Vertical dimension name in file or file_vcoord

accepted type: str

sigma_a_var_name: (optional): ap

‘sigma a’ variable name in file or file_vcoord

accepted type: str

sigma_b_var_name: (optional): bp

‘sigma b’ variable name in file or file_vcoord

accepted type: str

pressure_unit: (optional)

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

accepted values: [‘Pa’, ‘hPa’]

Yaml template

Please find below a template for a Yaml configuration:

 1datastream:
 2  plugin:
 3    name: gridded_netcdf
 4    version: std
 5    type: datastream
 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  remove_duplicates: XXXXX  # bool
16  time_varname: XXXXX  # str
17  period_varname: XXXXX  # str
18  time_coordinate: XXXXX  # str
19  time_dimname: XXXXX  # str
20  time_midpoint: XXXXX  # bool
21  time_endpoint: XXXXX  # bool
22  time_unit: XXXXX  # str
23  time_calendar: XXXXX  # gregorian|noleap
24  time_format: XXXXX  # str
25  add_time_coord: XXXXX  # bool
26  sum_along_dim: XXXXX  # str
27  closest_year: XXXXX  # bool
28  group_name: XXXXX  # str
29  sum_variables: XXXXX  # str
30  latitude_varname: XXXXX  # str
31  longitude_varname: XXXXX  # str
32  latitude_dimname: XXXXX  # str
33  longitude_dimname: XXXXX  # str
34  use_corners: XXXXX  # bool
35  extend_lat: XXXXX  # bool
36  extend_lon: XXXXX  # bool
37  lat_min: XXXXX  # float
38  lat_max: XXXXX  # float
39  delta_lat: XXXXX  # float
40  lon_min: XXXXX  # float
41  lon_max: XXXXX  # float
42  delta_lon: XXXXX  # float
43  regular_lon: XXXXX  # bool
44  regular_lat: XXXXX  # bool
45  sort_lat: XXXXX  # bool
46  sort_lon: XXXXX  # bool
47  dir_vcoord: XXXXX  # str
48  file_vcoord: XXXXX  # str
49  vertical_coord: XXXXX  # mids|bounds
50  vertical_dim_name: XXXXX  # str
51  sigma_a_var_name: XXXXX  # str
52  sigma_b_var_name: XXXXX  # str
53  pressure_unit: XXXXX  # Pa|hPa