epygram.base — Basic, non-specific classes

Contains some base classes of epygram.

---

class epygram.base.Resource(*args, **kwargs)

Bases: epygram.util.RecursiveObject, footprints.FootprintBase

Generic abstract class implementing a Resource.

Note

This class is managed by footprint.

• info: Not documented
• priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

• openmode (builtins.str) - rxx - Opening mode.
  • Values: set([‘append’, ‘write’, ‘w’, ‘read’, ‘r’, ‘a’])
  • Remap: dict(append = ‘a’, read = ‘r’, write = ‘w’,)

Constructor. See its footprint for arguments.

find_fields_in_resource_by_generic_fid(handgrip)

Find in resource the fields whose generic fid (if the resource is able to give one) matches the handgrip.

listfields(**kwargs)

Returns a list containing the identifiers (in the resource format) of all the fields of the resource.

(Generic wrapper with buffering if openmode == ‘r’.)

openmode

Undocumented footprint attribute

readfields(requestedfields, getdata=True)

Returns a FieldSet containing requested fields read in the resource.

Parameters:

• requestedfields – a field identifier of the resource format, or a list of.
• getdata – optional, if False, only metadata are read, the fields do not contain data. Default is True.

writefields(fieldset)

Write the fields of the ‘fieldset’ in the resource; fieldset must be a FieldSet instance.

---

class epygram.base.Field(*args, **kwargs)

Bases: epygram.util.RecursiveObject, footprints.FootprintBase

Generic abstract class implementing a Field, composed of an identifier and a data.

The field identifier fid identifies a field with a set of keys. Each key (named after the format name) identifies the field for a given format. A specific key ‘generic’ is a GRIB2-like description. E.g. *{‘FA’:’SURFTEMPERATURE’,

‘generic’:{‘typeOfFirstFixedSurface’:1, ‘discipline’:2, ‘parameterCategory’:3, ‘parameterNumber’:18}}*.

Note

This class is managed by footprint.

• info: Not documented
• priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

• comment (builtins.str) - rwd - Not documented, sorry.
  • Optional. Default is None.
• fid (footprints.stdtypes.FPDict) - rwx - Not documented, sorry.
• misc_metadata (footprints.stdtypes.FPDict) - rwd - Not documented, sorry.
  • Optional. Default is FPDict::<<as_dict:: dict()>>.
• units (builtins.str) - rwd - Not documented, sorry.
  • Optional. Default is ‘’.

Constructor. See its footprint for arguments.

absmean(**kwargs)

Returns the mean of absolute value of data.

clone(fid=None)

Returns a cloned field, optionally with a new fid given as a dict.

comment

Undocumented footprint attribute

compare_to(other)

Compare a field to another one, with several criteria:

• bias: average of errors distribution
• std: standard deviation of errors distribution
• errmax: maximum absolute error
• common_mask: indicate whether fields have the same mask or not; beware that above statistics apply only to commonly unmasked data

:return ({bias, std, errmax}, common_mask)

correlation(other, commonmask=False, mask_outside=1e+19)

Compute a correlation coefficient R to another field.

Parameters:

• commonmask – if True, compute distance on the subset of point that are not masked for any of the two fields.
• mask_outside – if None, mask is empty; else, mask data outside +/- this value

data

Accessor to the field data.

deldata()

Empties the data.

fid

Undocumented footprint attribute

getdata()

Returns the field data. Generic, default method for inheriting classes that do not overwrite it.

max(**kwargs)

Returns the maximum value of data.

mean(**kwargs)

Returns the mean value of data.

min(**kwargs)

Returns the minimum value of data.

misc_metadata

Undocumented footprint attribute

nonzero(**kwargs)

Returns the number of non-zero values (whose absolute value > config.epsilon).

normalized_comparison(ref)

Compare field to a reference, with prior normalization (by reference magnitude) of both fields. Hence the figures of comparison can be interpretated as percentages.

operation(operation, operand=None)

Makes the requested operation on the field.

Parameters:

• operation – any of ‘+’, ‘-‘, ‘*’, ‘/’, or ‘normalize’, ‘ceil’, ‘exp’, ‘log’… and you can try with every other numpy function.
• operand – operand for the 4 basic operations, may be a scalar or another field with according geometry.

operation_with_other(operation, other)

Makes an in-place operation with another field.

Parameters:

• operation – among (‘+’, ‘-‘, ‘*’, ‘/’)
• other – another field, with according dimensions

quadmean(**kwargs)

Returns the quadratic mean of data.

scalar_operation(operation, scalar)

Makes an in-place scalar operation on field.

Parameters:

• operation – among (‘+’, ‘-‘, ‘*’, ‘/’)
• scalar – a float or int.

setdata(data)

Sets or overwrites the field data as a numpy array.

setfid(fid)

Sets or overwrites the field fid given as a dict.

sha256_checksum(**kwargs)

Return a SHA256 checksum of the field data.

stats(**kwargs)

Computes some basic statistics on the field, as a dict containing: {‘min’, ‘max’, ‘mean’, ‘std’, ‘quadmean’, ‘nonzero’}.

See each of these methods for details.

Optional arguments can be passed, depending on the inheriting class, passed to getdata().

std(**kwargs)

Returns the standard deviation of data.

units

Undocumented footprint attribute

---

class epygram.base.FieldSet(fields=())

Bases: epygram.util.RecursiveObject, list

Handles a set of Fields, in the manner of Python’s builtin list, with some extra features, especially ensuring its components all are Fields.

Constructor optional argument fields has to be either a Field or an iterable of.

Constructor. Checks that optional ‘fields’ argument is actually iterable and contains Field instances, or is a single Field.

append(field)

Checks that field is a Field instance before appending it.

extend(fieldset)

Checks that fieldset is a FieldSet instance before extending with it.

filter(by, criteria)

Not Implemented Yet.

Returns a new FieldSet filtered according to criteria specified in argument.

Args:

• by: the kind of filter; on what to filter ?
• criteria: how to filter on that ?

Examples of filters:

• by=’id’, criteria={typefmt:identifier} will return only fields whose id[typefmt] match value…

index(fid)

Returns the index of the first field of the FieldSet whose fid matches fid, fid being a dict.

insert(position, field)

Checks that field is a Field instance before inserting it at the position.

listfields(fidkey=None)

Returns a list of the identifiers of the FieldSet. If fidkey is supplied, the list contains only fid[*fidkey*], and not whole fid.

remove(fid)

Removes from the FieldSet the first field whose fid matches fid, fid being a dict.

sort(attribute, key=None, reverse=False)

Sorts the fields of the FieldSet by the increasing criterion.

If attribute is a string, sorting will be done according to field.attribute[key] or field.attribute (if key is None).

If attribute is a list [a1, a2…], sorting will be done according to field.a1.a2[key] or field.a1.a2 (if key==None).

If reverse is True, sorts by decreasing order.

---

class epygram.base.FieldValidity(date_time=None, basis=None, term=None, cumulativeduration=None, statistical_process_on_duration=None, statistical_time_increment=None)

Bases: epygram.util.RecursiveObject

This class handles a unique temporal validity for a meteorological field: its date and time of validity (date_time), as well as the validity of its origin (basis, i.e. for a forecast field for instance, the beginning of the forecast) and its term.

An additional optional cumulativeduration parameter can define the duration for which cumulative fields (e.g. precipitation) are valid.

If such, optional statistical_process_on_duration can be supplied as a string or an int (cf. GRIB2 table typeOfStatisticalProcessing) to describe the kind of statistical process that runs over the cumulativeduration.

Constructor arguments: cf. set() method.

Constructor.

Parameters:

• date_time – has to be of type datetime.datetime;
• basis – has to be of type datetime.datetime;
• term – has to be of type datetime.timedelta;
• cumulativeduration – has to be of type datetime.timedelta;
• statistical_process_on_duration – kind of statistical process that runs over the cumulative duration.
• statistical_time_increment – time step over used for statistical process.

cumulativeduration(fmt=None)

This method returns the cumulative duration, i.e. the duration for which cumulative fields (e.g. precipitation) are valid.

By default, it is returned as a datetime.timedelta; otherwise, fmt argument can specify the desired return format.

Coded versions of fmt: ‘IntHours’, ‘IntSeconds’, and that’s all for now…

get(fmt=None)

Returns the date and time of validity.

By default, as a datetime.datetime; otherwise, fmt argument can specify the desired return format.

Coded versions of fmt: ‘IntStr’ (e.g. ‘20140731104812’ = 2014 july 31th at 10h, 48m, 12s). And that’s all for now…

getbasis(fmt=None)

Returns the date and time of origin (basis).

By default, as a datetime.datetime; otherwise, fmt argument can specify the desired return format.

Coded versions of fmt: ‘IntStr’ (e.g. ‘20140731104812’ = 2014 july 31th at 10h, 48m, 12s). And that’s all for now…

is_valid()

Check the validity is valid, i.e. not null.

set(date_time=None, basis=None, term=None, cumulativeduration=None, statistical_process_on_duration=None, statistical_time_increment=None)

Sets validity and basis according to arguments. A consistency check is done if the three arguments are provided (which is useless anyway).

Args:

Parameters:

• date_time – has to be of type datetime.datetime
• basis – has to be of type datetime.datetime
• term – has to be of type datetime.timedelta
• cumulativeduration – has to be of type datetime.timedelta
• statistical_process_on_duration – kind of statistical process that runs over the cumulative duration. Cf. GRIB2 typeOfStatisticalProcessing
• statistical_time_increment – time step over used for statistical process.

statistical_process_on_duration(asGRIB2code=False)

If the field describes a cumulative process over a cumulativeduration, returns the kind of statistical process that runs over the duration.

If asGRIB2code, returned as a GRIB2 code (cf. GRIB2 table 4.10).

statistical_time_increment(fmt=None)

This method returns the statistical_time_increment, i.e. the time step used for statistical process over cumulative duration.

By default, it is returned as a datetime.timedelta; otherwise, fmt argument can specify the desired return format.

Coded versions of fmt: ‘IntHours’, ‘IntSeconds’, and that’s all for now…

term(fmt=None)

This method returns the term as the difference between date and time of validity and basis.

By default, it is returned as a datetime.timedelta; otherwise, fmt argument can specify the desired return format.

Coded versions of fmt: ‘IntHours’, ‘IntSeconds’, and that’s all for now…

---

class epygram.base.FieldValidityList(validity_instance=None, length=1, **kwargs)

Bases: epygram.util.RecursiveObject, list

This class handles a list of temporal validity.

Constructor.

• validity_instance, if given is an instance of FieldValidity
• length, to build a series of validities from either the

validity_instance or from an uninitialized one. - other kwargs: same as FieldValidity constructor.

cumulativeduration(one=True, **kwargs)

This method returns the cumulative duration of all the validities.

get(one=True, **kwargs)

Returns the date and time of all the validities.

getbasis(one=True, **kwargs)

Returns the date and time of origin (basis) of all the validities.

is_valid()

Check the validity is valid, i.e. not null.

recursive_diff(other)

Recursively list what differs from other.

set(**kwargs)

Sets validity objects

statistical_process_on_duration(one=True, **kwargs)

This method returns the statistical process on duration of all the validities.

statistical_time_increment(one=True, **kwargs)

This method returns the statistical_time_increment of all the validities.

term(one=True, **kwargs)

This method returns the terms of all the validities

what(out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, cumulativeduration=True)

Writes in file a summary of the validity.

Parameters:

• out – the output open file-like object.
• cumulativeduration – if False, not written.