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

pycif.plugins.datastreams.fluxes.dummy_txt — API reference#

Configuration reference: dummy_txt plugin

pycif.plugins.datastreams.fluxes.dummy_txt.fetch.fetch(ref_dir, ref_file, input_interval, target_dir, tracer=None, **kwargs)[source]#

Fetch (or synthesize) dummy_txt flux files covering the interval.

Extends the requested interval to full tracer.period blocks. For each period, links the existing file into target_dir if present; otherwise generates the flux field on the fly via tracer.make(tracer) and writes it with tracer.write(...) so a file is always available. Each period is then subdivided into tracer.freq sub-intervals for the returned dates/files.

Parameters:

  • ref_dir (str) – directory where the original files are found.

  • ref_file (str) – (template) name of the original files.

  • input_interval (list) – simulation interval, as a list of the two bounding dates.

  • target_dir (str) – directory where links to the original (or generated) files are created.

  • tracer – the tracer Plugin, giving access to period and freq.

  • **kwargs – unused, kept for interface compatibility.

Returns:

list_files and list_dates.

list_files: for each date that begins a period, a list containing

the name of the file used for the dates within this period.

list_dates: for each date that begins a period, a list containing

the date intervals matching the files listed in list_files.

Return type:

(dict, dict)

pycif.plugins.datastreams.fluxes.dummy_txt.read.read(self, name, varnames, dates, files, interpol_flx=False, tracer=None, **kwargs)[source]#

Read comma-delimited dummy_txt flux files into a pyCIF array.

For each requested date/file pair, loads the 2D flux array with numpy.loadtxt(). If the file is missing, the flux field is generated on the fly via self.make(tracer) instead of raising. The loaded/generated array shape is checked against the domain’s (nlat, nlon).

Parameters:

  • self – the fluxes Plugin.

  • name – the name of the component.

  • varnames – unused, kept for interface compatibility.

  • dates (list) – list of the date intervals to extract.

  • files (list) – list of files matching dates.

  • interpol_flx (bool) – unused, kept for interface compatibility.

  • tracer – the tracer Plugin, passed through to self.make when a file needs to be generated.

  • **kwargs – unused, kept for interface compatibility.

Returns:

the flux data with dimensions (time, lev, lat, lon).

Return type:

xr.DataArray

Raises:

CifError – if a loaded or generated flux array’s shape does not match the domain’s (nlat, nlon).

pycif.plugins.datastreams.fluxes.dummy_txt.write.write(self, name, flx_file, flx, mode='w', **kwargs)[source]#

Write a 2D flux array to a comma-delimited text file.

Parameters:

  • self (Fluxes) – the Fluxes plugin.

  • name – unused, kept for interface compatibility.

  • flx_file (str) – the file where to write the flux array.

  • flx (array-like) – 2D flux array to write, shape (nlat, nlon).

  • mode – unused, kept for interface compatibility (always overwrites).

  • **kwargs – unused, kept for interface compatibility.

pycif.plugins.datastreams.fluxes.dummy_txt.make.fromformula.makefromformula(formula, zlon, zlat, formula_type='sum')[source]#

Recursively evaluate a nested-dict formula into a 2D flux array.

The formula is a nested dictionary tree: a node either declares an aggregation operator ("sum" or "product" of a list of sub-formulas), or a unary operator ("cos", "sin", "exp", "log" or "square") applied to zlon or zlat (selected via a "variable" key), optionally divided by a "period" value (default 1) before the operator is applied.

Parameters:

  • formula (dict) – the (sub-)formula to evaluate; either a leaf node with a "variable" key ("zlon" or "zlat") and one operator key set to None, plus an optional "period" key, or an aggregation node with a single key ("sum" or "product") mapping to a list of sub-formulas.

  • zlon (np.ndarray) – 2D array of longitudes (grid centers).

  • zlat (np.ndarray) – 2D array of latitudes (grid centers).

  • formula_type (str) – aggregation operator to use when combining a list of sub-formula results ("sum" or "product"); only relevant for aggregation nodes.

Returns:

the 2D array resulting from evaluating the formula, same shape as zlon/zlat.

Return type:

np.ndarray

Raises:

CifError – if an unrecognized "variable" or operator is encountered.

pycif.plugins.datastreams.fluxes.dummy_txt.make.fromtxt.makefromtext(flx_txt, dom_xsize, dom_ysize, file_font='/usr/share/fonts/dejavu/DejaVuSans-Bold.ttf')[source]#

Render a text string onto a domain-sized grid as a synthetic flux field.

Enumerates possible line-splits of flx_txt (see split_text()) and, for each, the largest font size that fits within dom_xsize/dom_ysize; picks the split/font-size combination that maximizes the rendered text area (with fewest lines and most balanced line lengths as tie-breakers), draws it onto a blank canvas, and returns the result as a grayscale-normalized array usable as a flux field spelling out the text.

Parameters:

  • flx_txt (str) – the text to render; an empty/whitespace-only string produces an all-zero field.

  • dom_xsize (int) – width of the target grid (number of longitude cells).

  • dom_ysize (int) – height of the target grid (number of latitude cells).

  • file_font (str) – path to a TrueType font file used to render the text.

Returns:

a 2D array of shape (dom_ysize, dom_xsize) with values in [0, 1] (1 where the text is drawn, 0 on the background).

Return type:

np.ndarray

pycif.plugins.datastreams.fluxes.dummy_txt.make.fromtxt.split_text(txt)[source]#

Return all possible splits for a given text

Parameters:

txt (str) – the text to split

Returns:

list(str)

Notes: This function is not optimized and can take a long time for string of more than a few words