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

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_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_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_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 a single file (with no time coordinate) per timestamp. Timestamp will be added acording to the file_freq 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

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: str

extend_lat: (optional): False

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

accepted type: str

extend_lon: (optional): False

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

accepted type: str

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

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  is_climatology: XXXXX  # bool
13  var_freq: XXXXX  # str
14  remove_duplicates: XXXXX  # bool
15  time_varname: XXXXX  # str
16  period_varname: XXXXX  # str
17  time_coordinate: XXXXX  # str
18  time_midpoint: XXXXX  # bool
19  time_unit: XXXXX  # str
20  time_format: XXXXX  # str
21  add_time_coord: XXXXX  # bool
22  sum_along_dim: XXXXX  # str
23  closest_year: XXXXX  # bool
24  latitude_varname: XXXXX  # str
25  longitude_varname: XXXXX  # str
26  latitude_dimname: XXXXX  # str
27  longitude_dimname: XXXXX  # str
28  use_corners: XXXXX  # str
29  extend_lat: XXXXX  # str
30  extend_lon: XXXXX  # str
31  lat_min: XXXXX  # float
32  lat_max: XXXXX  # float
33  delta_lat: XXXXX  # float
34  lon_min: XXXXX  # float
35  lon_max: XXXXX  # float
36  delta_lon: XXXXX  # float
37  dir_vcoord: XXXXX  # str
38  file_vcoord: XXXXX  # str
39  vertical_coord: XXXXX  # mids|bounds
40  vertical_dim_name: XXXXX  # str
41  sigma_a_var_name: XXXXX  # str
42  sigma_b_var_name: XXXXX  # str
43  pressure_unit: XXXXX  # Pa|hPa