Exceptions#

These are unique exeption classes raised within pyreflow.

exception pyreflow.PyreflowError#

Base class for all exceptions raised by pyreflow.

exception pyreflow.FileLayoutError#

Raised if FCS file was malformed.

This includes:

  • invalid FCS version

  • unparsable offsets in HEADER

  • unparsable TEXT segment (primary and/or secondary)

  • overlapping segment coordinates

  • mismatches between indicated event number and actual size of DATA

exception pyreflow.ParseKeyError#

Raised if key from TEXT could not be parsed from bytestring.

This includes:

  • Standard keys not starting with a "$"

  • Non-standard keys starting with a "$"

  • blank keys

  • keys already present

  • keys with non-ASCII or non-UTF-8 characters

exception pyreflow.ParseKeywordValueError#

Raised if keyword value could not be parsed from a string.

The source string is that which is literally encoded in TEXT. The final type for the conversion will depend on the keyword and is dictated by its type in the standardized data structure (see CoreTEXT* and CoreDataset*). For instance, $ABRT is an unsigned integer and will raise this exception if string value for this keyword contains invalid digits or if the resulting number is out of range.

This exception will generally only be raised in standard mode, but may also be raised in flat mode when the DATA segment needs to be read (this requires parsing $PnB, $PnR, etc).

exception pyreflow.InvalidKeywordValueError#

Raised if a standardized keyword value is incorrectly specified.

The difference between ParseKeywordValueError and this error is that the former applies to string conversion, and this applies to an invalid value within the keyword value’s native type.

This is mostly used when using class constructors to build the classes from CoreTEXT* and CoreDataset* from scratch without reading an FCS file.

Furthermore, this is only needed for complicated keyword values whose failure mode cannot be described by a build-in Python exception. For instance, $SPILLOVER is a numpy matrix that must follow certain rules. Violations of these rules will trigger this error.

exception pyreflow.ExtraKeywordError#

Raised when extra standard keywords are left unused in standard mode.

exception pyreflow.ConversionError#

Raised upon failure when converting between FCS versions.

This covers two broad classes of failures:

  1. data is required in target version but not specified in source version

  2. data in source version is incompatible with target version

For (1), this generally happens if a keyword in the source version is optional and missing and required in the target version ($PnN for example when going from FCS 3.0 to FCS 3.1).

For (2), this may/may not trigger this exception depending on user configuration. In the non-fatal case, incompatible keys will be dropped with a warning. In the fatal case, this exception will be raised since dropping keywords is a destructive operation.

exception pyreflow.RelationalError#

Raised when a keyword’s value is incorrect given its context.

This can be triggered by the following (and more):

  1. keywords which reference other data which does not exist

  2. attempting to remove a keyword on which data depends

  3. mismatches between $PnB, $PnR, $DATATYPE, and $PnDATATYPE

  4. specifying a temporal value to an optical measurement (and vice versa)

  5. mismatched length between measurements, dataframe, and/or layout

exception pyreflow.EventDataError#

Raised when values in DATA segment are invalid.

exception pyreflow.DataLossError#

Raised when values in DATA segment must be truncated.

This can occur because input data is the wrong type for the target data schema or the data is out of range.

exception pyreflow.ConfigError#

Raised when a configuration value is invalid.

This is used for values whose failure mode cannot be captured using a built-in Python exception or another exception in pyreflow.

exception pyreflow.PyreflowWarning#

Generic warning created by pyreflow.