pycif.plugins.datastreams.fluxes.TNO_nc — API reference

Configuration reference: TNO_nc plugin

pycif.plugins.datastreams.fluxes.TNO_nc.fetch.fetch(ref_dir, ref_file, input_interval, target_dir, tracer=None, **kwargs)

Fetch TNO flux files and build hourly date intervals for each valid day.

For each day in input_interval, uses find_valid_file to locate the nearest available (forecast-style) file bracketing the day, considering the current directory as well as the previous/next month’s directory when the day is near a month boundary. Links the nearest file into target_dir and, if it exists, builds 24 hourly [start, end] intervals for that day.

Parameters:

• ref_dir – directory where the original files are found

• ref_file – (template) name of the original files

• input_interval – list of the periods to simulate, each item is the list of the dates of the period

• target_dir – directory where the links to the orginal files are created

• tracer – the flux tracer plugin (unused directly, kept for interface consistency)

• kwargs – unused, kept for interface consistency

Returns:

list_files: for each date that begins a period, an array containing

the names of the files that are available for the dates within this period

list_dates: for each date that begins a period, an array containing

the names of the dates mathcin the files listed in list_files

pycif.plugins.datastreams.fluxes.TNO_nc.get_domain.get_domain(ref_dir, ref_file, input_interval, target_dir, tracer=None)

Build the TNO domain, dispatching to a gridded or point-source layout.

Delegates to get_area_domain (regular grid) or get_point_domain (unstructured, one cell per emission point) depending on tracer.point_sources.

Args:

ref_dir: directory where the original files are found (unused

directly; the reference file is taken from tracer.input_files)

ref_file: (template) name of the original files (unused directly) input_interval: list of the periods to simulate, each item is the list of the dates of the period (unused directly) target_dir: directory where the links to the orginal files are created

(unused directly)

tracer: the flux tracer plugin, providing point_sources and

input_files

Ouputs:

setup of the domain in section “Initializes domain”

pycif.plugins.datastreams.fluxes.TNO_nc.get_domain.get_area_domain(tracer)

Build a regular gridded, surface-only domain from a reference TNO file.

Reads longitude/latitude/longitude_bounds/latitude_bounds from the first fetched reference file, and builds a Domain with a single dummy vertical level.

Parameters:

tracer – The flux tracer plugin, providing input_files.

Returns:

a regular gridded, single-level Domain.

Return type:

Domain

Raises:

CifError – If no reference file is available.

pycif.plugins.datastreams.fluxes.TNO_nc.get_domain.get_point_domain(tracer)

Build an unstructured, point-source domain from all fetched TNO files.

Reads the vertical height-distribution CSV (TNO_height-distribution_GNFR.csv) to get the level tops, then loops over all files listed in tracer.input_files, collecting the (category- and source-type- filtered) non-zero point-source emission locations from each. Builds an unstructured Domain with one “cell” per point and a value_file attribute mapping each point to its originating file.

Parameters:

tracer – The flux tracer plugin, providing dir_profiles, input_dates, input_files, varname and cat_select.

Returns:

an unstructured domain with one cell per point source.

Return type:

Domain

pycif.plugins.datastreams.fluxes.TNO_nc.read.read(self, name, varnames, dates, files, interpol_flx=False, comp_type=None, tracer=None, **kwargs)

Get TNO fluxes and apply GNFR time (and, for point sources, vertical) profiles.

Loads the month/day/hour (and, for point sources, height) GNFR profile CSVs from tracer.dir_profiles. Then, for each requested date/file (re-reading category indices, source types and emission values only when the file changes), loops over the active emission categories (tracer.cat_select, or all categories found in the file), matches each to its GNFR temporal profile, and applies the corresponding month-of-year, day-of-week and hour-of-day scaling coefficients to the raw category emission (and, for point sources, the height-distribution coefficients to spread across vertical levels). Results are accumulated into a (lev, lat, lon) array per date, either scattered onto point-source domain cells or gridded area cells (area-normalized using the file’s area variable).

Parameters:

• self – The flux tracer plugin instance (unused directly; tracer is used instead).

• name – Unused directly, kept for interface consistency with other flux plugins.

• varnames – Name of the emission variable to read in the file.

• dates – list of [start, end] date intervals to extract; only the start of each interval is used to compute the local month/weekday/hour.

• files – list of files matching dates.

• interpol_flx (bool) – Unused, kept for interface consistency.

• comp_type – Unused, kept for interface consistency.

• tracer – The flux tracer plugin, providing dir_profiles, point_sources, cat_select and domain.

Returns:

the flux data with dimensions

(time, lev, lat, lon).

Return type:

xr.DataArray

pycif.plugins.datastreams.fluxes.TNO_nc.utils.find_valid_file(ref_dir, file_format, dd, ref_dir_next, ref_dir_previous=False)

Find the nearest available files bracketing a given date.

Lists candidate files in ref_dir matching file_format, extending the search to ref_dir_next/ref_dir_previous when dd is close to a month boundary (within 3 hours), sorts them by parsed date, and returns the file/date pair nearest to dd on-or-before and on-or-after it.

Parameters:

• ref_dir (str) – Directory to search for candidate files.

• file_format (str) – strftime-style filename pattern used both to match files and parse their embedded date.

• dd (datetime.datetime) – Reference date to bracket.

• ref_dir_next (str) – Directory for the following month, searched in addition to ref_dir when dd is near a month boundary.

• ref_dir_previous (str or bool) – Directory for the previous month, searched in addition to ref_dir when dd is near a month boundary; False to skip.

Returns:

([file1, file2], [dd1, dd2]), the paths and adjusted dates of the nearest file on-or-before and on-or-after dd (falling back to the first/last available file, with a warning, if none is found strictly before/after dd).

Return type:

tuple[list[str], list[datetime.datetime]]

Raises:

CifError – If no candidate files are found at all.

pycif.plugins.datastreams.fluxes.TNO_nc.write.write(self, name, flx_file, flx, mode='a', **kwargs)

Not implemented; always raises, since writing TNO fluxes is not supported.