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.FCSDeprecatedError

Raised when a deprecated FCS feature is encountered.

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 the dataframe used to represent DATA is allowed to contain arbitrary data types, but these must be coerced to a given DATA layout when written to an FCS file. This coercion may result in data loss, which is indicated by this error.

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.