Core* Classes

Each of these classes is a version-specific, in-memory, non-redundant data structure to represent and manipulate an FCS file.

These can be regarded as database-like entities that encode a hierarchical ‘schema’, maintain an internally-consistent state, and update this state atomically.

Each class corresponds to an FCS version. When applicable, keywords are stored in a “native” datatype (int, float, tuple, etc) corresponding to its version specification, rather than a raw string as written in the TEXT of an FCS file. CoreDataset* classes additionally store DATA (as a polars DataFrame), ANALYSIS, and OTHER segments (as bytes).

Each Core* class is further composed of other version-specific classes as follows:

Version	CoreTEXT*	CoreDataset*	Optical*	Temporal*
FCS2.0	CoreTEXT2_0	CoreDataset2_0	Optical2_0	Temporal2_0
FCS3.0	CoreTEXT3_0	CoreDataset3_0	Optical3_0	Temporal3_0
FCS3.1	CoreTEXT3_1	CoreDataset3_1	Optical3_1	Temporal3_1
FCS3.2	CoreTEXT3_2	CoreDataset3_2	Optical3_2	Temporal3_2

Some keywords are redundant and therefore not stored in any Core* classes:

• $TOT since this implied by the length of the dataframe

• $PAR since this is implied by the length of the measurement vector

• any offsets ($(BEGIN|END)(DATA|ANALYSIS|STEXT) and $NEXTDATA), since these can be computed by serializing the class’s contents

• any pseudostandard keywords since this would allow the FCS standard to be violated when writing to a new file

CoreTEXT*

Represents HEADER and TEXT.

These can be created by:

• calling pyreflow.api.fcs_read_std_text()

• calling from_kws (described below)

• calling __new__

In general, the following manipulations are possible:

• modifying the values of all keywords (within the constraints of the FCS standards)

• adding/removing measurements

• converting measurements to/from temporal and optical types

• upgrading/downgrading the FCS version

• converting to CoreDataset* by supplying a DataFrame and/or byte segments for ANALYSIS and OTHER.

• writing to disk; the file will be an “empty” FCS file with a single dataset and no events (ie only HEADER and TEXT).

class pyreflow.CoreTEXT2_0(measurements, layout, mode='L', cyt='', comp=None, btim=None, etim=None, date=None, abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=([], {}, None), nonstandard_keywords={})

Represents TEXT for an FCS 2.0 file.

Parameters:

measurements (tuple[str | None, Optical2_0 | Temporal2_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.

• mode (Literal[“L”, “U”, “C”]) – (read-write) Value of $MODE. Defaults to "L".

• cyt (str) – (read-write) Value of $CYT. Defaults to "".

• comp (ndarray | None) – (read-write) The compensation matrix. Must be a square array with number of rows/columns equal to the number of measurements. Non-zero entries will produce a $DFCmTOn keyword. Defaults to None.

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[list[GatedMeasurement], dict[int, UnivariateRegion2_0 | BivariateRegion2_0], str | None]) – (read-write) Value for $Gm/$RnI/$RnW/$GATING/$GATE* keywords. The first member of the tuple corresponds to the $Gm* keywords, where m is given by position in the list. The second member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to an index in the list in the first element. The third member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the second member. Defaults to ([], {}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

Raises:

• OverflowError – if abrt or lost is less than 0 or greater than 2**32-1

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_peak_bins

The value of $PKn for all measurements (read-write).

Return type:

list[int | None]

all_peak_sizes

The value of $PKNn for all measurements (read-write).

Return type:

list[int | None]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scales

The value for $PnE for all measurements (read-write).

Will be () for linear scaling (0,0 in FCS encoding), a 2-tuple for log scaling, or None if missing.

The temporal measurement must always be (). Setting it to another value will raise RelationalError.

Return type:

list[tuple[()] | tuple[float, float] | None]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_shortnames_maybe

The possibly-empty values of $PnN for all measurements (read-write).

$PnN is optional for this FCS version so values may be None.

Return type:

list[str | None]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

classmethod from_kws(std, nonstd, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, allow_optional_dropping=False, transfer_dropped_optional=False, integer_widths_from_byteord=False, integer_byteord_override=None, disallow_range_truncation=False, warnings_are_errors=False, hide_warnings=False)

Make new instance from keywords.

Parameters:

• std (dict[str, str]) – Standard keywords. Must not contain any $Pn* keywords not indexed by $PAR or $TOT.

• nonstd (dict[str, str]) – Non-Standard keywords.

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• integer_widths_from_byteord (bool) – If True set all $PnB to the number of bytes from $BYTEORD. Only has an effect for FCS 2.0/3.0 where $DATATYPE is I. Defaults to False.

• integer_byteord_override (list[int] | None) – Override $BYTEORD for integer layouts. Defaults to None.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

Return type:

tuple[CoreTEXT2_0, ExtraStdKeywords]

Raises:

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• InvalidKeywordValueError – if integer_byteord_override is not a list of integers including all from 1 to N where N is the length of the list (up to 8)

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords that are referenced by other keywords do not exist

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical2_0) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal2_0) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical2_0 | Temporal2_0

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical2_0 | Temporal2_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical2_0 | Temporal2_0]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical2_0) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal2_0) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str | None, Optical2_0 | Temporal2_0, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical2_0 | Temporal2_0, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical2_0) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical2_0) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal2_0) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal2_0) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (list[Optical2_0 | Temporal2_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout.

Parameters:

• measurements (tuple[str | None, Optical2_0 | Temporal2_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (tuple[str | None, Optical2_0 | Temporal2_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal2_0] | None

to_dataset(data, analysis=b'', others=[])

Convert to a dataset object.

This will fully represent an FCS file, as opposed to just representing HEADER and TEXT.

Parameters:

• data (polars.DataFrame) – A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• analysis (bytes) – Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – A list of byte strings encoding the OTHER segments. Defaults to [].

Return type:

CoreDataset2_0

Raises:

EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

to_version_3_0(allow_loss=False)

Convert to FCS 3.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.0.

Return type:

CoreTEXT3_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.0

to_version_3_1(allow_loss=False)

Convert to FCS 3.1.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.1.

Return type:

CoreTEXT3_1

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.1 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.1

to_version_3_2(allow_loss=False)

Convert to FCS 3.2.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.2.

Return type:

CoreTEXT3_2

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.2 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.2

unset_measurements()

Remove measurements and clear the layout.

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal()

Convert the temporal measurement to an optical measurement.

Returns:

True if temporal measurement was present and converted, False if there was not a temporal measurement.

Return type:

bool

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT, DATA, or ANALYSIS offsets are greater than 99,999,999

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False)

Write multiple datasets to path.

The resulting file will have HEADER and TEXT from each object

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreTEXT2_0]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT, DATA, or ANALYSIS offsets are greater than 99,999,999

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreTEXT3_0(measurements, layout, mode='L', cyt='', comp=None, btim=None, etim=None, date=None, cytsn='', unicode=None, csvbits=0, cstot=0, csvflags=[], abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=([], {}, None), nonstandard_keywords={})

Represents TEXT for an FCS 3.0 file.

Parameters:

measurements (tuple[str | None, Optical3_0 | Temporal3_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.

• mode (Literal[“L”, “U”, “C”]) – (read-write) Value of $MODE. Defaults to "L".

• cyt (str) – (read-write) Value of $CYT. Defaults to "".

• comp (ndarray | None) – (read-write) The value of $COMP. Must be a square array with number of rows/columns equal to the number of measurements. Defaults to None.

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• cytsn (str) – (read-write) Value of $CYTSN. Defaults to "".

• unicode (tuple[int, list[str]] | None) – (read-write) Value of $UNICODE. Defaults to None.

• csvbits (int) – (read-write) Value of $CSVBITS. Defaults to 0.

• cstot (int) – (read-write) Value of $CSTOT. Defaults to 0.

• csvflags (list[int | None]) – (read-write) Subset flags. Each element in the list corresponds to $CSVnFLAG and the length of the list corresponds to $CSMODE. Defaults to [].

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[list[GatedMeasurement], dict[int, UnivariateRegion3_0 | BivariateRegion3_0], str | None]) – (read-write) Value for $Gm/$RnI/$RnW/$GATING/$GATE* keywords. The first member of the tuple corresponds to the $Gm* keywords, where m is given by position in the list. The second member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to an index in the list in the first element or a physical measurement. The third member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the second member. Defaults to ([], {}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

Raises:

• OverflowError – if abrt, cstot, csvbits, or lost is less than 0 or greater than 2**32-1

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• OverflowError – if any in csvflags is less than 0 or greater than 2**32-1

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_peak_bins

The value of $PKn for all measurements (read-write).

Return type:

list[int | None]

all_peak_sizes

The value of $PKNn for all measurements (read-write).

Return type:

list[int | None]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scale_transforms

The value for $PnE and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

If scaling is linear, return a float which corresponds to the value of $PnG when $PnE is 0,0. If scaling is logarithmic, return a pair of floats, corresponding to unset $PnG and the non-0,0 value of $PnE.

The FCS standards disallow any other combinations.

The temporal measurement will always be 1.0, corresponding to an identity transform. Setting it to another value will raise RelationalError.

Return type:

list[float | tuple[float, float]]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_shortnames_maybe

The possibly-empty values of $PnN for all measurements (read-write).

$PnN is optional for this FCS version so values may be None.

Return type:

list[str | None]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

classmethod from_kws(std, nonstd, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, ignore_time_gain=False, allow_optional_dropping=False, transfer_dropped_optional=False, integer_widths_from_byteord=False, integer_byteord_override=None, disallow_range_truncation=False, warnings_are_errors=False, hide_warnings=False)

Make new instance from keywords.

Parameters:

• std (dict[str, str]) – Standard keywords. Must not contain any $Pn* keywords not indexed by $PAR or $TOT, $BEGINDATA, $ENDDATA, $BEGINANALYSIS, $ENDANALYSIS, or $TIMESTEP (if time measurement not included).

• nonstd (dict[str, str]) – Non-Standard keywords.

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S:%!". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• ignore_time_gain (bool) – If True ignore the $PnG (gain) keyword. This keyword should not be set according to the standard} however, this library will allow gain to be 1.0 since this equates to identity. If gain is not 1.0, this is nonsense and it can be ignored with this flag. Defaults to False.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• integer_widths_from_byteord (bool) – If True set all $PnB to the number of bytes from $BYTEORD. Only has an effect for FCS 2.0/3.0 where $DATATYPE is I. Defaults to False.

• integer_byteord_override (list[int] | None) – Override $BYTEORD for integer layouts. Defaults to None.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

Return type:

tuple[CoreTEXT3_0, ExtraStdKeywords]

Raises:

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• InvalidKeywordValueError – if integer_byteord_override is not a list of integers including all from 1 to N where N is the length of the list (up to 8)

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords that are referenced by other keywords do not exist

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_0) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_0) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical3_0 | Temporal3_0

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical3_0 | Temporal3_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical3_0 | Temporal3_0]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_0) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_0) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str | None, Optical3_0 | Temporal3_0, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical3_0 | Temporal3_0, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical3_0) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical3_0) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal3_0) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal3_0) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (list[Optical3_0 | Temporal3_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout.

Parameters:

• measurements (tuple[str | None, Optical3_0 | Temporal3_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (tuple[str | None, Optical3_0 | Temporal3_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, timestep, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

• InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

• ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, timestep, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_timestep(timestep)

Set the $TIMESTEP if time measurement is present.

Parameters:

timestep (float) – The timestep to set. Must be greater than zero.

Returns:

Previous $TIMESTEP if present.

Return type:

float | None

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal3_0] | None

timestep

The value of $TIMESTEP (read-only).

Return type:

float | None

to_dataset(data, analysis=b'', others=[])

Convert to a dataset object.

This will fully represent an FCS file, as opposed to just representing HEADER and TEXT.

Parameters:

• data (polars.DataFrame) – A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• analysis (bytes) – Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – A list of byte strings encoding the OTHER segments. Defaults to [].

Return type:

CoreDataset3_0

Raises:

EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

to_version_2_0(allow_loss=False)

Convert to FCS 2.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 2.0.

Return type:

CoreTEXT2_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 2.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 2.0

to_version_3_1(allow_loss=False)

Convert to FCS 3.1.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.1.

Return type:

CoreTEXT3_1

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.1 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.1

to_version_3_2(allow_loss=False)

Convert to FCS 3.2.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.2.

Return type:

CoreTEXT3_2

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.2 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.2

unset_measurements()

Remove measurements and clear the layout.

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal()

Convert the temporal measurement to an optical measurement.

Returns:

Value of $TIMESTEP if time measurement was present.

Return type:

float | None

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False)

Write multiple datasets to path.

The resulting file will have HEADER and TEXT from each object

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreTEXT3_0]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreTEXT3_1(measurements, layout, mode='L', cyt='', btim=None, etim=None, date=None, cytsn='', spillover=None, last_modifier='', last_modified=None, originality=None, plateid='', platename='', wellid='', vol=None, csvbits=0, cstot=0, csvflags=[], abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=([], {}, None), nonstandard_keywords={})

Represents TEXT for an FCS 3.1 file.

Parameters:

measurements (tuple[str, Optical3_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.

• mode (Literal[“L”, “U”, “C”]) – (read-write) Value of $MODE. Defaults to "L".

• cyt (str) – (read-write) Value of $CYT. Defaults to "".

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• cytsn (str) – (read-write) Value of $CYTSN. Defaults to "".

• spillover (tuple[list[str], ndarray] | None) – (read-write) Value for $SPILLOVER. First element of tuple the list of measurement names and the second is the matrix. Each measurement name must correspond to a $PnN, must be unique, and the length of this list must match the number of rows and columns of the matrix. The matrix must be at least 2x2. Defaults to None.

• last_modifier (str) – (read-write) Value of $LAST_MODIFIER. Defaults to "".

• last_modified (datetime | None) – (read-write) Value of $LAST_MODIFIED. Defaults to None.

• originality (Literal[“Original”, “NonDataModified”, “Appended”, “DataModified”] | None) – (read-write) Value of $ORIGINALITY. Defaults to None.

• plateid (str) – (read-write) Value of $PLATEID. Defaults to "".

• platename (str) – (read-write) Value of $PLATENAME. Defaults to "".

• wellid (str) – (read-write) Value of $WELLID. Defaults to "".

• vol (float | None) – (read-write) Value of $VOL. Defaults to None.

• csvbits (int) – (read-write) Value of $CSVBITS. Defaults to 0.

• cstot (int) – (read-write) Value of $CSTOT. Defaults to 0.

• csvflags (list[int | None]) – (read-write) Subset flags. Each element in the list corresponds to $CSVnFLAG and the length of the list corresponds to $CSMODE. Defaults to [].

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[list[GatedMeasurement], dict[int, UnivariateRegion3_0 | BivariateRegion3_0], str | None]) – (read-write) Value for $Gm/$RnI/$RnW/$GATING/$GATE* keywords. The first member of the tuple corresponds to the $Gm* keywords, where m is given by position in the list. The second member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to an index in the list in the first element or a physical measurement. The third member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the second member. Defaults to ([], {}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

Raises:

• OverflowError – if abrt, cstot, csvbits, or lost is less than 0 or greater than 2**32-1

• InvalidKeywordValueError – if vol is negative, NaN, inf, or -inf

• InvalidKeywordValueError – if matrix in spillover does not have the same number of rows and columns as the measurement vector

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• InvalidKeywordValueError – if field 2 in spillover is not a square matrix that is 2x2 or larger

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• OverflowError – if any in csvflags is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if any in field 1 in spillover is "" or contains commas

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

all_calibrations

Value of $PnCALIBRATION for all measurements (read-write).

() will be returned for time since $PnCALIBRATION is not defined for temporal measurements.

Return type:

list[tuple[float, str] | tuple[()] | None]

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_displays

Value of $PnD for all measurements (read-write).

Return type:

list[tuple[bool, float, float] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_peak_bins

The value of $PKn for all measurements (read-write).

Return type:

list[int | None]

all_peak_sizes

The value of $PKNn for all measurements (read-write).

Return type:

list[int | None]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scale_transforms

The value for $PnE and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

If scaling is linear, return a float which corresponds to the value of $PnG when $PnE is 0,0. If scaling is logarithmic, return a pair of floats, corresponding to unset $PnG and the non-0,0 value of $PnE.

The FCS standards disallow any other combinations.

The temporal measurement will always be 1.0, corresponding to an identity transform. Setting it to another value will raise RelationalError.

Return type:

list[float | tuple[float, float]]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[list[float] | tuple[()]]

classmethod from_kws(std, nonstd, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, ignore_time_gain=False, parse_indexed_spillover=False, allow_optional_dropping=False, transfer_dropped_optional=False, disallow_range_truncation=False, warnings_are_errors=False, hide_warnings=False)

Make new instance from keywords.

Parameters:

• std (dict[str, str]) – Standard keywords. Must not contain any $Pn* keywords not indexed by $PAR or $TOT, $BEGINDATA, $ENDDATA, $BEGINANALYSIS, $ENDANALYSIS, or $TIMESTEP (if time measurement not included).

• nonstd (dict[str, str]) – Non-Standard keywords.

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S.%@". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• ignore_time_gain (bool) – If True ignore the $PnG (gain) keyword. This keyword should not be set according to the standard} however, this library will allow gain to be 1.0 since this equates to identity. If gain is not 1.0, this is nonsense and it can be ignored with this flag. Defaults to False.

• parse_indexed_spillover (bool) – Parse $SPILLOVER with numeric indices rather than strings (ie names or $PnN) Defaults to False.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

Return type:

tuple[CoreTEXT3_1, ExtraStdKeywords]

Raises:

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords that are referenced by other keywords do not exist

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_1) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_1) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical3_1 | Temporal3_1

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical3_1 | Temporal3_1

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical3_1 | Temporal3_1]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_1) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_1) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str, Optical3_1 | Temporal3_1, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical3_1 | Temporal3_1, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical3_1) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical3_1) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal3_1) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal3_1) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (list[Optical3_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout) – The new layout.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout.

Parameters:

• measurements (tuple[str, Optical3_1 | Temporal3_1]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (tuple[str, Optical3_1 | Temporal3_1]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, timestep, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

• InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

• ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, timestep, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_timestep(timestep)

Set the $TIMESTEP if time measurement is present.

Parameters:

timestep (float) – The timestep to set. Must be greater than zero.

Returns:

Previous $TIMESTEP if present.

Return type:

float | None

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal3_1] | None

timestep

The value of $TIMESTEP (read-only).

Return type:

float | None

to_dataset(data, analysis=b'', others=[])

Convert to a dataset object.

This will fully represent an FCS file, as opposed to just representing HEADER and TEXT.

Parameters:

• data (polars.DataFrame) – A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• analysis (bytes) – Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – A list of byte strings encoding the OTHER segments. Defaults to [].

Return type:

CoreDataset3_1

Raises:

EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

to_version_2_0(allow_loss=False)

Convert to FCS 2.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 2.0.

Return type:

CoreTEXT2_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 2.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 2.0

to_version_3_0(allow_loss=False)

Convert to FCS 3.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.0.

Return type:

CoreTEXT3_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.0

to_version_3_2(allow_loss=False)

Convert to FCS 3.2.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.2.

Return type:

CoreTEXT3_2

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.2 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.2

unset_measurements()

Remove measurements and clear the layout.

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal()

Convert the temporal measurement to an optical measurement.

Returns:

Value of $TIMESTEP if time measurement was present.

Return type:

float | None

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False)

Write multiple datasets to path.

The resulting file will have HEADER and TEXT from each object

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreTEXT3_1]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreTEXT3_2(measurements, layout, cyt, mode=None, btim=None, etim=None, date=None, begindatetime=None, enddatetime=None, cytsn='', spillover=None, last_modifier='', last_modified=None, originality=None, plateid='', platename='', wellid='', vol=None, carrierid='', carriertype='', locationid='', unstainedinfo='', unstainedcenters={}, flowrate='', abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=({}, None), nonstandard_keywords={})

Represents TEXT for an FCS 3.2 file.

Parameters:

measurements (tuple[str, Optical3_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout | MixedLayout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, $DATATYPE, and $PnDATATYPE.

• cyt (str) – (read-write) Value of $CYT.

• mode (Literal[“L”] | None) – (read-write) Value of $MODE. Defaults to None.

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• begindatetime (datetime | None) – (read-write) Value for $BEGINDATETIME. Defaults to None.

• enddatetime (datetime | None) – (read-write) Value for $ENDDATETIME. Defaults to None.

• cytsn (str) – (read-write) Value of $CYTSN. Defaults to "".

• spillover (tuple[list[str], ndarray] | None) – (read-write) Value for $SPILLOVER. First element of tuple the list of measurement names and the second is the matrix. Each measurement name must correspond to a $PnN, must be unique, and the length of this list must match the number of rows and columns of the matrix. The matrix must be at least 2x2. Defaults to None.

• last_modifier (str) – (read-write) Value of $LAST_MODIFIER. Defaults to "".

• last_modified (datetime | None) – (read-write) Value of $LAST_MODIFIED. Defaults to None.

• originality (Literal[“Original”, “NonDataModified”, “Appended”, “DataModified”] | None) – (read-write) Value of $ORIGINALITY. Defaults to None.

• plateid (str) – (read-write) Value of $PLATEID. Defaults to "".

• platename (str) – (read-write) Value of $PLATENAME. Defaults to "".

• wellid (str) – (read-write) Value of $WELLID. Defaults to "".

• vol (float | None) – (read-write) Value of $VOL. Defaults to None.

• carrierid (str) – (read-write) Value of $CARRIERID. Defaults to "".

• carriertype (str) – (read-write) Value of $CARRIERTYPE. Defaults to "".

• locationid (str) – (read-write) Value of $LOCATIONID. Defaults to "".

• unstainedinfo (str) – (read-write) Value of $UNSTAINEDINFO. Defaults to "".

• unstainedcenters (dict[str, float]) – (read-write) Value for $UNSTAINEDCENTERS. Each key must match a *$PnN. Defaults to {}.

• flowrate (str) – (read-write) Value of $FLOWRATE. Defaults to "".

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[dict[int, UnivariateRegion3_2 | BivariateRegion3_2], str | None]) – (read-write) Value for $RnI/$RnW/$GATING keywords. The first member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to a physical measurement. The second member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the first member. Defaults to ({}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

Raises:

• OverflowError – if abrt or lost is less than 0 or greater than 2**32-1

• InvalidKeywordValueError – if cyt is empty

• InvalidKeywordValueError – if vol is negative, NaN, inf, or -inf

• InvalidKeywordValueError – if matrix in spillover does not have the same number of rows and columns as the measurement vector

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• InvalidKeywordValueError – if field 2 in spillover is not a square matrix that is 2x2 or larger

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• ParseKeywordValueError – if any in field 1 in spillover is "" or contains commas

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

• ParseKeywordValueError – if dict key in unstainedcenters is "" or contains commas

all_analytes

Value of $PnANALYTE for all measurements (read-write).

() will be returned for time since $PnANALYTE is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_calibrations

Value of $PnCALIBRATION for all measurements (read-write).

() will be returned for time since $PnCALIBRATION is not defined for temporal measurements.

Return type:

list[tuple[float, float, str] | tuple[()] | None]

all_detector_names

Value of $PnDET for all measurements (read-write).

() will be returned for time since $PnDET is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_displays

Value of $PnD for all measurements (read-write).

Return type:

list[tuple[bool, float, float] | None]

all_features

Value of $PnFEATURE for all measurements (read-write).

() will be returned for time since $PnFEATURE is not defined for temporal measurements.

Return type:

list[Literal[“Area”, “Width”, “Height”] | tuple[()] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_measurement_types

Value of $PnTYPE for all measurements (read-write).

A bool will be returned for the time measurement where True indicates it is set to "Time".

Return type:

list[str | bool]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scale_transforms

The value for $PnE and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

If scaling is linear, return a float which corresponds to the value of $PnG when $PnE is 0,0. If scaling is logarithmic, return a pair of floats, corresponding to unset $PnG and the non-0,0 value of $PnE.

The FCS standards disallow any other combinations.

The temporal measurement will always be 1.0, corresponding to an identity transform. Setting it to another value will raise RelationalError.

Return type:

list[float | tuple[float, float]]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_tags

Value of $PnTAG for all measurements (read-write).

() will be returned for time since $PnTAG is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[list[float] | tuple[()]]

classmethod from_kws(std, nonstd, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, ignore_time_gain=False, parse_indexed_spillover=False, disallow_localtime=False, allow_optional_dropping=False, transfer_dropped_optional=False, disallow_range_truncation=False, warnings_are_errors=False, hide_warnings=False)

Make new instance from keywords.

Parameters:

• std (dict[str, str]) – Standard keywords. Must not contain any $Pn* keywords not indexed by $PAR or $TOT, $BEGINDATA, $ENDDATA, $BEGINANALYSIS, $ENDANALYSIS, or $TIMESTEP (if time measurement not included).

• nonstd (dict[str, str]) – Non-Standard keywords.

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S.%@". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• ignore_time_gain (bool) – If True ignore the $PnG (gain) keyword. This keyword should not be set according to the standard} however, this library will allow gain to be 1.0 since this equates to identity. If gain is not 1.0, this is nonsense and it can be ignored with this flag. Defaults to False.

• parse_indexed_spillover (bool) – Parse $SPILLOVER with numeric indices rather than strings (ie names or $PnN) Defaults to False.

• disallow_localtime (bool) – If true, require that $BEGINDATETIME and $ENDDATETIME have a timezone if provided. This is not required by the standard, but not having a timezone is ambiguous since the absolute value of the timestamp is dependent on localtime and therefore is location-dependent. Only affects FCS 3.2. Defaults to False.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

Return type:

tuple[CoreTEXT3_2, ExtraStdKeywords]

Raises:

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords that are referenced by other keywords do not exist

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_2) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_2) – The measurement to insert.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical3_2 | Temporal3_2

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical3_2 | Temporal3_2

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical3_2 | Temporal3_2]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_2) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_2) – The measurement to push.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str, Optical3_2 | Temporal3_2, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical3_2 | Temporal3_2, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical3_2) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical3_2) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas, allow_loss=False)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal3_2) – Temporal measurement to replace measurement at index.

• allow_loss (bool) – If False, raise ConversionError if conversion from temporal measurement to optical measurement is necessary and data keywords must be dropped. Defaults to False.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas, allow_loss=False)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal3_2) – Temporal measurement to replace measurement at name.

• allow_loss (bool) – If False, raise ConversionError if conversion from temporal measurement to optical measurement is necessary and data keywords must be dropped. Defaults to False.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (list[Optical3_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout | MixedLayout) – The new layout.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout.

Parameters:

• measurements (tuple[str, Optical3_2 | Temporal3_2]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout .

Parameters:

• measurements (tuple[str, Optical3_2 | Temporal3_2]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout | MixedLayout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, timestep, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

• InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

• ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, timestep, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_timestep(timestep)

Set the $TIMESTEP if time measurement is present.

Parameters:

timestep (float) – The timestep to set. Must be greater than zero.

Returns:

Previous $TIMESTEP if present.

Return type:

float | None

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal3_2] | None

timestep

The value of $TIMESTEP (read-only).

Return type:

float | None

to_dataset(data, analysis=b'', others=[])

Convert to a dataset object.

This will fully represent an FCS file, as opposed to just representing HEADER and TEXT.

Parameters:

• data (polars.DataFrame) – A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• analysis (bytes) – Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – A list of byte strings encoding the OTHER segments. Defaults to [].

Return type:

CoreDataset3_2

Raises:

EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

to_version_2_0(allow_loss=False)

Convert to FCS 2.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 2.0.

Return type:

CoreTEXT2_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 2.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 2.0

to_version_3_0(allow_loss=False)

Convert to FCS 3.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.0.

Return type:

CoreTEXT3_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.0

to_version_3_1(allow_loss=False)

Convert to FCS 3.1.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.1.

Return type:

CoreTEXT3_1

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.1 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.1

unset_measurements()

Remove measurements and clear the layout.

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal(allow_loss=False)

Convert the temporal measurement to an optical measurement.

Parameters:

allow_loss (bool) – If True and current time measurement has data which cannot be converted to optical, force the conversion anyways. Otherwise raise ConversionError. Defaults to False.

Returns:

Value of $TIMESTEP if time measurement was present.

Return type:

float | None

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False)

Write multiple datasets to path.

The resulting file will have HEADER and TEXT from each object

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreTEXT3_2]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

CoreDataset*

Represents one dataset from an FCS file (HEADER + TEXT + DATA + ANALYSIS + OTHER).

These can be created by:

• calling pyreflow.api.fcs_read_std_dataset()

• calling pyreflow.api.fcs_read_std_dataset_with_keywords()

• calling from_kws (described below)

• calling __new__

In addition to all the minipulations offered by CoreTEXT*, these additionally allow:

• modifying the DataFrame corresponding to DATA

• modifying the byte segments corresponding to ANALYSIS and/or *OTHER

• removing all data by converting to CoreTEXT*

When written, these will result in an FCS file a single dataset reflecting its contents.

class pyreflow.CoreDataset2_0(measurements, layout, data, mode='L', cyt='', comp=None, btim=None, etim=None, date=None, abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=([], {}, None), nonstandard_keywords={}, analysis=b'', others=[])

Represents one dataset in an FCS 2.0 file.

Parameters:

measurements (tuple[str | None, Optical2_0 | Temporal2_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.

• data (polars.DataFrame) – (read-write) A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• mode (Literal[“L”, “U”, “C”]) – (read-write) Value of $MODE. Defaults to "L".

• cyt (str) – (read-write) Value of $CYT. Defaults to "".

• comp (ndarray | None) – (read-write) The compensation matrix. Must be a square array with number of rows/columns equal to the number of measurements. Non-zero entries will produce a $DFCmTOn keyword. Defaults to None.

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[list[GatedMeasurement], dict[int, UnivariateRegion2_0 | BivariateRegion2_0], str | None]) – (read-write) Value for $Gm/$RnI/$RnW/$GATING/$GATE* keywords. The first member of the tuple corresponds to the $Gm* keywords, where m is given by position in the list. The second member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to an index in the list in the first element. The third member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the second member. Defaults to ([], {}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

• analysis (bytes) – (read-write) Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – (read-write) A list of byte strings encoding the OTHER segments. Defaults to [].

Raises:

• OverflowError – if abrt or lost is less than 0 or greater than 2**32-1

• EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_peak_bins

The value of $PKn for all measurements (read-write).

Return type:

list[int | None]

all_peak_sizes

The value of $PKNn for all measurements (read-write).

Return type:

list[int | None]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scales

The value for $PnE for all measurements (read-write).

Will be () for linear scaling (0,0 in FCS encoding), a 2-tuple for log scaling, or None if missing.

The temporal measurement must always be (). Setting it to another value will raise RelationalError.

Return type:

list[tuple[()] | tuple[float, float] | None]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_shortnames_maybe

The possibly-empty values of $PnN for all measurements (read-write).

$PnN is optional for this FCS version so values may be None.

Return type:

list[str | None]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

classmethod from_kws(path, std, nonstd, data_seg, analysis_seg=(0, 0), other_segs=[], trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, allow_optional_dropping=False, transfer_dropped_optional=False, integer_widths_from_byteord=False, integer_byteord_override=None, disallow_range_truncation=False, allow_uneven_event_width=False, allow_tot_mismatch=False, warnings_are_errors=False, hide_warnings=False, dataset_offset=0)

Make new instance from keywords.

Parameters:

• path (Path) – Path to be read.

• std (dict[str, str]) – Standard keywords.

• nonstd (dict[str, str]) – Non-Standard keywords.

• data_seg (tuple[int, int]) – The DATA segment from HEADER.

• analysis_seg (tuple[int, int]) – The DATA segment from HEADER. Defaults to (0, 0).

• other_segs (list[tuple[int, int]]) – The OTHER segments from HEADER. Defaults to [].

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• integer_widths_from_byteord (bool) – If True set all $PnB to the number of bytes from $BYTEORD. Only has an effect for FCS 2.0/3.0 where $DATATYPE is I. Defaults to False.

• integer_byteord_override (list[int] | None) – Override $BYTEORD for integer layouts. Defaults to None.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• allow_uneven_event_width (bool) – If True allow event width to not perfectly divide length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• allow_tot_mismatch (bool) – If True allow $TOT to not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

• dataset_offset (int) – Starting position in the file of the dataset to be read Defaults to 0.

Return type:

tuple[CoreDataset2_0, StdDatasetWithKwsOutput]

Raises:

• ValueError – if analysis_seg or data_seg has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• InvalidKeywordValueError – if integer_byteord_override is not a list of integers including all from 1 to N where N is the length of the list (up to 8)

• ValueError – if any in other_segs has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• FCSDeprecatedError – If any keywords or their values are deprecated and disallow_deprecated is True

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords are incompatible with indicated layout of DATA or if keywords that are referenced by other keywords do not exist

• EventDataError – If values in DATA cannot be read

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, col, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical2_0) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, col, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal2_0) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical2_0 | Temporal2_0

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical2_0 | Temporal2_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical2_0 | Temporal2_0]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, col, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical2_0) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, col, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal2_0) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str | None, Optical2_0 | Temporal2_0, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical2_0 | Temporal2_0, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical2_0) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical2_0) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal2_0) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal2_0) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | Temporal2_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_data(measurements, data)

Set measurements and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (list[Optical2_0 | Temporal2_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• data (polars.DataFrame) – The new data.

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (list[Optical2_0 | Temporal2_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

set_measurements_layout_and_data(measurements, layout, data)

Set measurements, layout, and data at once.

Length of measurements and layout must match number of columns in data.

Parameters:

• measurements (list[Optical2_0 | Temporal2_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

• data (polars.DataFrame) – The new data.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout and dataframe.

Parameters:

• measurements (tuple[str | None, Optical2_0 | Temporal2_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_data(measurements, data, allow_shared_names=False, skip_index_check=False)

Set measurements, names, and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (tuple[str | None, Optical2_0 | Temporal2_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• data (polars.DataFrame) – The new data.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (tuple[str | None, Optical2_0 | Temporal2_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal2_0] | None

to_version_3_0(allow_loss=False)

Convert to FCS 3.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.0.

Return type:

CoreDataset3_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.0

to_version_3_1(allow_loss=False)

Convert to FCS 3.1.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.1.

Return type:

CoreDataset3_1

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.1 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.1

to_version_3_2(allow_loss=False)

Convert to FCS 3.2.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.2.

Return type:

CoreDataset3_2

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.2 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.2

truncate_data(skip_conv_check=False)

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

skip_conv_check (bool) – If True, silently truncate data; otherwise return warnings when truncation is performed. Defaults to False.

Return type:

tuple[()]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout and skip_conversion_check is False

unset_data()

Remove all measurements and their data.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal()

Convert the temporal measurement to an optical measurement.

Returns:

True if temporal measurement was present and converted, False if there was not a temporal measurement.

Return type:

bool

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_dataset(path, delim=30, big_other=False, skip_conversion_check=False, appendable=False, append=False)

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA which would point to next dataset if written

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT, DATA, or ANALYSIS offsets are greater than 99,999,999

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_datasets(path, datasets, delim=30, big_other=False, skip_conversion_check=False)

Write multiple datasets to path.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreDataset2_0]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset if written

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT, DATA, or ANALYSIS offsets are greater than 99,999,999

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT, DATA, or ANALYSIS offsets are greater than 99,999,999

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreDataset3_0(measurements, layout, data, mode='L', cyt='', comp=None, btim=None, etim=None, date=None, cytsn='', unicode=None, csvbits=0, cstot=0, csvflags=[], abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=([], {}, None), nonstandard_keywords={}, analysis=b'', others=[])

Represents one dataset in an FCS 3.0 file.

Parameters:

measurements (tuple[str | None, Optical3_0 | Temporal3_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.

• data (polars.DataFrame) – (read-write) A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• mode (Literal[“L”, “U”, “C”]) – (read-write) Value of $MODE. Defaults to "L".

• cyt (str) – (read-write) Value of $CYT. Defaults to "".

• comp (ndarray | None) – (read-write) The value of $COMP. Must be a square array with number of rows/columns equal to the number of measurements. Defaults to None.

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• cytsn (str) – (read-write) Value of $CYTSN. Defaults to "".

• unicode (tuple[int, list[str]] | None) – (read-write) Value of $UNICODE. Defaults to None.

• csvbits (int) – (read-write) Value of $CSVBITS. Defaults to 0.

• cstot (int) – (read-write) Value of $CSTOT. Defaults to 0.

• csvflags (list[int | None]) – (read-write) Subset flags. Each element in the list corresponds to $CSVnFLAG and the length of the list corresponds to $CSMODE. Defaults to [].

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[list[GatedMeasurement], dict[int, UnivariateRegion3_0 | BivariateRegion3_0], str | None]) – (read-write) Value for $Gm/$RnI/$RnW/$GATING/$GATE* keywords. The first member of the tuple corresponds to the $Gm* keywords, where m is given by position in the list. The second member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to an index in the list in the first element or a physical measurement. The third member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the second member. Defaults to ([], {}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

• analysis (bytes) – (read-write) Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – (read-write) A list of byte strings encoding the OTHER segments. Defaults to [].

Raises:

• OverflowError – if abrt, cstot, csvbits, or lost is less than 0 or greater than 2**32-1

• EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• OverflowError – if any in csvflags is less than 0 or greater than 2**32-1

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_peak_bins

The value of $PKn for all measurements (read-write).

Return type:

list[int | None]

all_peak_sizes

The value of $PKNn for all measurements (read-write).

Return type:

list[int | None]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scale_transforms

The value for $PnE and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

If scaling is linear, return a float which corresponds to the value of $PnG when $PnE is 0,0. If scaling is logarithmic, return a pair of floats, corresponding to unset $PnG and the non-0,0 value of $PnE.

The FCS standards disallow any other combinations.

The temporal measurement will always be 1.0, corresponding to an identity transform. Setting it to another value will raise RelationalError.

Return type:

list[float | tuple[float, float]]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_shortnames_maybe

The possibly-empty values of $PnN for all measurements (read-write).

$PnN is optional for this FCS version so values may be None.

Return type:

list[str | None]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

classmethod from_kws(path, std, nonstd, data_seg, analysis_seg=(0, 0), other_segs=[], trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, ignore_time_gain=False, allow_optional_dropping=False, transfer_dropped_optional=False, integer_widths_from_byteord=False, integer_byteord_override=None, disallow_range_truncation=False, text_data_correction=(0, 0), text_analysis_correction=(0, 0), ignore_text_data_offsets=False, ignore_text_analysis_offsets=False, allow_header_text_offset_mismatch=False, allow_missing_required_offsets=False, truncate_text_offsets=False, allow_uneven_event_width=False, allow_tot_mismatch=False, warnings_are_errors=False, hide_warnings=False, dataset_offset=0)

Make new instance from keywords.

Parameters:

• path (Path) – Path to be read.

• std (dict[str, str]) – Standard keywords.

• nonstd (dict[str, str]) – Non-Standard keywords.

• data_seg (tuple[int, int]) – The DATA segment from HEADER.

• analysis_seg (tuple[int, int]) – The DATA segment from HEADER. Defaults to (0, 0).

• other_segs (list[tuple[int, int]]) – The OTHER segments from HEADER. Defaults to [].

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S:%!". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• ignore_time_gain (bool) – If True ignore the $PnG (gain) keyword. This keyword should not be set according to the standard} however, this library will allow gain to be 1.0 since this equates to identity. If gain is not 1.0, this is nonsense and it can be ignored with this flag. Defaults to False.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• integer_widths_from_byteord (bool) – If True set all $PnB to the number of bytes from $BYTEORD. Only has an effect for FCS 2.0/3.0 where $DATATYPE is I. Defaults to False.

• integer_byteord_override (list[int] | None) – Override $BYTEORD for integer layouts. Defaults to None.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• text_data_correction (tuple[int, int]) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).

• text_analysis_correction (tuple[int, int]) – Corrections for ANALYSIS offsets in TEXT. Defaults to (0, 0).

• ignore_text_data_offsets (bool) – If True ignore DATA offsets in TEXT Defaults to False.

• ignore_text_analysis_offsets (bool) – If True ignore ANALYSIS offsets in TEXT Defaults to False.

• allow_header_text_offset_mismatch (bool) – If True allow TEXT and HEADER offsets to mismatch. Defaults to False.

• allow_missing_required_offsets (bool) – If True allow required DATA and ANALYSIS offsets in TEXT to be missing. If missing, fall back to offsets from HEADER. Defaults to False.

• truncate_text_offsets (bool) – If True truncate offsets that exceed end of file. Defaults to False.

• allow_uneven_event_width (bool) – If True allow event width to not perfectly divide length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• allow_tot_mismatch (bool) – If True allow $TOT to not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

• dataset_offset (int) – Starting position in the file of the dataset to be read Defaults to 0.

Return type:

tuple[CoreDataset3_0, StdDatasetWithKwsOutput]

Raises:

• ValueError – if analysis_seg or data_seg has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• InvalidKeywordValueError – if integer_byteord_override is not a list of integers including all from 1 to N where N is the length of the list (up to 8)

• OverflowError – if field 1 or 2 in text_analysis_correction or text_data_correction is less than -2**31 or greater than 2**31-1

• ValueError – if any in other_segs has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• FCSDeprecatedError – If any keywords or their values are deprecated and disallow_deprecated is True

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords are incompatible with indicated layout of DATA or if keywords that are referenced by other keywords do not exist

• EventDataError – If values in DATA cannot be read

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, col, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_0) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, col, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_0) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical3_0 | Temporal3_0

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical3_0 | Temporal3_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical3_0 | Temporal3_0]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, col, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_0) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, col, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_0) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str | None, Optical3_0 | Temporal3_0, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical3_0 | Temporal3_0, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical3_0) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical3_0) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal3_0) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal3_0) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | Temporal3_0

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_data(measurements, data)

Set measurements and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (list[Optical3_0 | Temporal3_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• data (polars.DataFrame) – The new data.

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (list[Optical3_0 | Temporal3_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

set_measurements_layout_and_data(measurements, layout, data)

Set measurements, layout, and data at once.

Length of measurements and layout must match number of columns in data.

Parameters:

• measurements (list[Optical3_0 | Temporal3_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

• data (polars.DataFrame) – The new data.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout and dataframe.

Parameters:

• measurements (tuple[str | None, Optical3_0 | Temporal3_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_data(measurements, data, allow_shared_names=False, skip_index_check=False)

Set measurements, names, and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (tuple[str | None, Optical3_0 | Temporal3_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• data (polars.DataFrame) – The new data.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (tuple[str | None, Optical3_0 | Temporal3_0]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | OrderedUint08Layout | OrderedUint16Layout | OrderedUint24Layout | OrderedUint32Layout | OrderedUint40Layout | OrderedUint48Layout | OrderedUint56Layout | OrderedUint64Layout | OrderedF32Layout | OrderedF64Layout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, timestep, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

• InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

• ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, timestep, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_timestep(timestep)

Set the $TIMESTEP if time measurement is present.

Parameters:

timestep (float) – The timestep to set. Must be greater than zero.

Returns:

Previous $TIMESTEP if present.

Return type:

float | None

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal3_0] | None

timestep

The value of $TIMESTEP (read-only).

Return type:

float | None

to_version_2_0(allow_loss=False)

Convert to FCS 2.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 2.0.

Return type:

CoreDataset2_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 2.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 2.0

to_version_3_1(allow_loss=False)

Convert to FCS 3.1.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.1.

Return type:

CoreDataset3_1

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.1 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.1

to_version_3_2(allow_loss=False)

Convert to FCS 3.2.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.2.

Return type:

CoreDataset3_2

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.2 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.2

truncate_data(skip_conv_check=False)

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

skip_conv_check (bool) – If True, silently truncate data; otherwise return warnings when truncation is performed. Defaults to False.

Return type:

tuple[()]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout and skip_conversion_check is False

unset_data()

Remove all measurements and their data.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal()

Convert the temporal measurement to an optical measurement.

Returns:

Value of $TIMESTEP if time measurement was present.

Return type:

float | None

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_dataset(path, delim=30, big_other=False, skip_conversion_check=False, appendable=False, append=False)

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA which would point to next dataset if written

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_datasets(path, datasets, delim=30, big_other=False, skip_conversion_check=False)

Write multiple datasets to path.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreDataset3_0]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset if written

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreDataset3_1(measurements, layout, data, mode='L', cyt='', btim=None, etim=None, date=None, cytsn='', spillover=None, last_modifier='', last_modified=None, originality=None, plateid='', platename='', wellid='', vol=None, csvbits=0, cstot=0, csvflags=[], abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=([], {}, None), nonstandard_keywords={}, analysis=b'', others=[])

Represents one dataset in an FCS 3.1 file.

Parameters:

measurements (tuple[str, Optical3_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.

• data (polars.DataFrame) – (read-write) A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• mode (Literal[“L”, “U”, “C”]) – (read-write) Value of $MODE. Defaults to "L".

• cyt (str) – (read-write) Value of $CYT. Defaults to "".

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• cytsn (str) – (read-write) Value of $CYTSN. Defaults to "".

• spillover (tuple[list[str], ndarray] | None) – (read-write) Value for $SPILLOVER. First element of tuple the list of measurement names and the second is the matrix. Each measurement name must correspond to a $PnN, must be unique, and the length of this list must match the number of rows and columns of the matrix. The matrix must be at least 2x2. Defaults to None.

• last_modifier (str) – (read-write) Value of $LAST_MODIFIER. Defaults to "".

• last_modified (datetime | None) – (read-write) Value of $LAST_MODIFIED. Defaults to None.

• originality (Literal[“Original”, “NonDataModified”, “Appended”, “DataModified”] | None) – (read-write) Value of $ORIGINALITY. Defaults to None.

• plateid (str) – (read-write) Value of $PLATEID. Defaults to "".

• platename (str) – (read-write) Value of $PLATENAME. Defaults to "".

• wellid (str) – (read-write) Value of $WELLID. Defaults to "".

• vol (float | None) – (read-write) Value of $VOL. Defaults to None.

• csvbits (int) – (read-write) Value of $CSVBITS. Defaults to 0.

• cstot (int) – (read-write) Value of $CSTOT. Defaults to 0.

• csvflags (list[int | None]) – (read-write) Subset flags. Each element in the list corresponds to $CSVnFLAG and the length of the list corresponds to $CSMODE. Defaults to [].

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[list[GatedMeasurement], dict[int, UnivariateRegion3_0 | BivariateRegion3_0], str | None]) – (read-write) Value for $Gm/$RnI/$RnW/$GATING/$GATE* keywords. The first member of the tuple corresponds to the $Gm* keywords, where m is given by position in the list. The second member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to an index in the list in the first element or a physical measurement. The third member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the second member. Defaults to ([], {}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

• analysis (bytes) – (read-write) Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – (read-write) A list of byte strings encoding the OTHER segments. Defaults to [].

Raises:

• OverflowError – if abrt, cstot, csvbits, or lost is less than 0 or greater than 2**32-1

• EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

• InvalidKeywordValueError – if vol is negative, NaN, inf, or -inf

• InvalidKeywordValueError – if matrix in spillover does not have the same number of rows and columns as the measurement vector

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• InvalidKeywordValueError – if field 2 in spillover is not a square matrix that is 2x2 or larger

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• OverflowError – if any in csvflags is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if any in field 1 in spillover is "" or contains commas

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

all_calibrations

Value of $PnCALIBRATION for all measurements (read-write).

() will be returned for time since $PnCALIBRATION is not defined for temporal measurements.

Return type:

list[tuple[float, str] | tuple[()] | None]

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_displays

Value of $PnD for all measurements (read-write).

Return type:

list[tuple[bool, float, float] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_peak_bins

The value of $PKn for all measurements (read-write).

Return type:

list[int | None]

all_peak_sizes

The value of $PKNn for all measurements (read-write).

Return type:

list[int | None]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scale_transforms

The value for $PnE and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

If scaling is linear, return a float which corresponds to the value of $PnG when $PnE is 0,0. If scaling is logarithmic, return a pair of floats, corresponding to unset $PnG and the non-0,0 value of $PnE.

The FCS standards disallow any other combinations.

The temporal measurement will always be 1.0, corresponding to an identity transform. Setting it to another value will raise RelationalError.

Return type:

list[float | tuple[float, float]]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[list[float] | tuple[()]]

classmethod from_kws(path, std, nonstd, data_seg, analysis_seg=(0, 0), other_segs=[], trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, ignore_time_gain=False, parse_indexed_spillover=False, allow_optional_dropping=False, transfer_dropped_optional=False, disallow_range_truncation=False, text_data_correction=(0, 0), text_analysis_correction=(0, 0), ignore_text_data_offsets=False, ignore_text_analysis_offsets=False, allow_header_text_offset_mismatch=False, allow_missing_required_offsets=False, truncate_text_offsets=False, allow_uneven_event_width=False, allow_tot_mismatch=False, warnings_are_errors=False, hide_warnings=False, dataset_offset=0)

Make new instance from keywords.

Parameters:

• path (Path) – Path to be read.

• std (dict[str, str]) – Standard keywords.

• nonstd (dict[str, str]) – Non-Standard keywords.

• data_seg (tuple[int, int]) – The DATA segment from HEADER.

• analysis_seg (tuple[int, int]) – The DATA segment from HEADER. Defaults to (0, 0).

• other_segs (list[tuple[int, int]]) – The OTHER segments from HEADER. Defaults to [].

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S.%@". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• ignore_time_gain (bool) – If True ignore the $PnG (gain) keyword. This keyword should not be set according to the standard} however, this library will allow gain to be 1.0 since this equates to identity. If gain is not 1.0, this is nonsense and it can be ignored with this flag. Defaults to False.

• parse_indexed_spillover (bool) – Parse $SPILLOVER with numeric indices rather than strings (ie names or $PnN) Defaults to False.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• text_data_correction (tuple[int, int]) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).

• text_analysis_correction (tuple[int, int]) – Corrections for ANALYSIS offsets in TEXT. Defaults to (0, 0).

• ignore_text_data_offsets (bool) – If True ignore DATA offsets in TEXT Defaults to False.

• ignore_text_analysis_offsets (bool) – If True ignore ANALYSIS offsets in TEXT Defaults to False.

• allow_header_text_offset_mismatch (bool) – If True allow TEXT and HEADER offsets to mismatch. Defaults to False.

• allow_missing_required_offsets (bool) – If True allow required DATA and ANALYSIS offsets in TEXT to be missing. If missing, fall back to offsets from HEADER. Defaults to False.

• truncate_text_offsets (bool) – If True truncate offsets that exceed end of file. Defaults to False.

• allow_uneven_event_width (bool) – If True allow event width to not perfectly divide length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• allow_tot_mismatch (bool) – If True allow $TOT to not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

• dataset_offset (int) – Starting position in the file of the dataset to be read Defaults to 0.

Return type:

tuple[CoreDataset3_1, StdDatasetWithKwsOutput]

Raises:

• ValueError – if analysis_seg or data_seg has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• OverflowError – if field 1 or 2 in text_analysis_correction or text_data_correction is less than -2**31 or greater than 2**31-1

• ValueError – if any in other_segs has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• FCSDeprecatedError – If any keywords or their values are deprecated and disallow_deprecated is True

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords are incompatible with indicated layout of DATA or if keywords that are referenced by other keywords do not exist

• EventDataError – If values in DATA cannot be read

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, col, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_1) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, col, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_1) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical3_1 | Temporal3_1

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical3_1 | Temporal3_1

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical3_1 | Temporal3_1]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, col, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_1) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, col, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_1) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str, Optical3_1 | Temporal3_1, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical3_1 | Temporal3_1, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical3_1) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical3_1) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal3_1) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal3_1) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | Temporal3_1

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_data(measurements, data)

Set measurements and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (list[Optical3_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• data (polars.DataFrame) – The new data.

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (list[Optical3_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout) – The new layout.

set_measurements_layout_and_data(measurements, layout, data)

Set measurements, layout, and data at once.

Length of measurements and layout must match number of columns in data.

Parameters:

• measurements (list[Optical3_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout) – The new layout.

• data (polars.DataFrame) – The new data.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout and dataframe.

Parameters:

• measurements (tuple[str, Optical3_1 | Temporal3_1]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_data(measurements, data, allow_shared_names=False, skip_index_check=False)

Set measurements, names, and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (tuple[str, Optical3_1 | Temporal3_1]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• data (polars.DataFrame) – The new data.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (tuple[str, Optical3_1 | Temporal3_1]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, timestep, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

• InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

• ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, timestep, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_timestep(timestep)

Set the $TIMESTEP if time measurement is present.

Parameters:

timestep (float) – The timestep to set. Must be greater than zero.

Returns:

Previous $TIMESTEP if present.

Return type:

float | None

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal3_1] | None

timestep

The value of $TIMESTEP (read-only).

Return type:

float | None

to_version_2_0(allow_loss=False)

Convert to FCS 2.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 2.0.

Return type:

CoreDataset2_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 2.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 2.0

to_version_3_0(allow_loss=False)

Convert to FCS 3.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.0.

Return type:

CoreDataset3_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.0

to_version_3_2(allow_loss=False)

Convert to FCS 3.2.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.2.

Return type:

CoreDataset3_2

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.2 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.2

truncate_data(skip_conv_check=False)

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

skip_conv_check (bool) – If True, silently truncate data; otherwise return warnings when truncation is performed. Defaults to False.

Return type:

tuple[()]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout and skip_conversion_check is False

unset_data()

Remove all measurements and their data.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal()

Convert the temporal measurement to an optical measurement.

Returns:

Value of $TIMESTEP if time measurement was present.

Return type:

float | None

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_dataset(path, delim=30, big_other=False, skip_conversion_check=False, appendable=False, append=False)

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA which would point to next dataset if written

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_datasets(path, datasets, delim=30, big_other=False, skip_conversion_check=False)

Write multiple datasets to path.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreDataset3_1]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset if written

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreDataset3_2(measurements, layout, data, cyt, mode=None, btim=None, etim=None, date=None, begindatetime=None, enddatetime=None, cytsn='', spillover=None, last_modifier='', last_modified=None, originality=None, plateid='', platename='', wellid='', vol=None, carrierid='', carriertype='', locationid='', unstainedinfo='', unstainedcenters={}, flowrate='', abrt=None, com='', cells='', exp='', fil='', inst='', lost=None, op='', proj='', smno='', src='', sys='', tr=None, applied_gates=({}, None), nonstandard_keywords={}, analysis=b'', others=[])

Represents one dataset in an FCS 3.2 file.

Parameters:

measurements (tuple[str, Optical3_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout | MixedLayout) – (read-write) Layout to describe data encoding. Represents $PnB, $PnR, $BYTEORD, $DATATYPE, and $PnDATATYPE.

• data (polars.DataFrame) – (read-write) A dataframe encoding the contents of DATA. Number of columns must match number of measurements. May be empty. Types do not necessarily need to correspond to those in the data layout but mismatches may result in truncation.

• cyt (str) – (read-write) Value of $CYT.

• mode (Literal[“L”] | None) – (read-write) Value of $MODE. Defaults to None.

• btim (time | None) – (read-write) Value of $BTIM. Defaults to None.

• etim (time | None) – (read-write) Value of $ETIM. Defaults to None.

• date (date | None) – (read-write) Value of $DATE. Defaults to None.

• begindatetime (datetime | None) – (read-write) Value for $BEGINDATETIME. Defaults to None.

• enddatetime (datetime | None) – (read-write) Value for $ENDDATETIME. Defaults to None.

• cytsn (str) – (read-write) Value of $CYTSN. Defaults to "".

• spillover (tuple[list[str], ndarray] | None) – (read-write) Value for $SPILLOVER. First element of tuple the list of measurement names and the second is the matrix. Each measurement name must correspond to a $PnN, must be unique, and the length of this list must match the number of rows and columns of the matrix. The matrix must be at least 2x2. Defaults to None.

• last_modifier (str) – (read-write) Value of $LAST_MODIFIER. Defaults to "".

• last_modified (datetime | None) – (read-write) Value of $LAST_MODIFIED. Defaults to None.

• originality (Literal[“Original”, “NonDataModified”, “Appended”, “DataModified”] | None) – (read-write) Value of $ORIGINALITY. Defaults to None.

• plateid (str) – (read-write) Value of $PLATEID. Defaults to "".

• platename (str) – (read-write) Value of $PLATENAME. Defaults to "".

• wellid (str) – (read-write) Value of $WELLID. Defaults to "".

• vol (float | None) – (read-write) Value of $VOL. Defaults to None.

• carrierid (str) – (read-write) Value of $CARRIERID. Defaults to "".

• carriertype (str) – (read-write) Value of $CARRIERTYPE. Defaults to "".

• locationid (str) – (read-write) Value of $LOCATIONID. Defaults to "".

• unstainedinfo (str) – (read-write) Value of $UNSTAINEDINFO. Defaults to "".

• unstainedcenters (dict[str, float]) – (read-write) Value for $UNSTAINEDCENTERS. Each key must match a *$PnN. Defaults to {}.

• flowrate (str) – (read-write) Value of $FLOWRATE. Defaults to "".

• abrt (int | None) – (read-write) Value of $ABRT. Defaults to None.

• com (str) – (read-write) Value of $COM. Defaults to "".

• cells (str) – (read-write) Value of $CELLS. Defaults to "".

• exp (str) – (read-write) Value of $EXP. Defaults to "".

• fil (str) – (read-write) Value of $FIL. Defaults to "".

• inst (str) – (read-write) Value of $INST. Defaults to "".

• lost (int | None) – (read-write) Value of $LOST. Defaults to None.

• op (str) – (read-write) Value of $OP. Defaults to "".

• proj (str) – (read-write) Value of $PROJ. Defaults to "".

• smno (str) – (read-write) Value of $SMNO. Defaults to "".

• src (str) – (read-write) Value of $SRC. Defaults to "".

• sys (str) – (read-write) Value of $SYS. Defaults to "".

• tr (tuple[int, str] | None) – (read-write) Value for $TR. First member of tuple is threshold and second is the measurement name which must match a $PnN. Defaults to None.

• applied_gates (tuple[dict[int, UnivariateRegion3_2 | BivariateRegion3_2], str | None]) – (read-write) Value for $RnI/$RnW/$GATING keywords. The first member corresponds to the $RnI and $RnW keywords and is a mapping of regions and windows to be used in gating scheme. Keys in dictionary are the region indices (the n in $RnI and $RnW). The values in the dictionary are either univariate or bivariate gates and must correspond to a physical measurement. The second member corresponds to the $GATING keyword. All ‘Rn’ in this string must reference a key in the dict of the first member. Defaults to ({}, None).

• nonstandard_keywords (dict[str, str]) – (read-write) Pairs of non-standard keyword values. Keys must not start with $. Defaults to {}.

• analysis (bytes) – (read-write) Contents of the ANALYSIS segment. Defaults to b"".

• others (list[bytes]) – (read-write) A list of byte strings encoding the OTHER segments. Defaults to [].

Raises:

• OverflowError – if abrt or lost is less than 0 or greater than 2**32-1

• EventDataError – If data contains columns which are not unsigned 8/16/32/64-bit integers or 32/64-bit floats

• InvalidKeywordValueError – if cyt is empty

• InvalidKeywordValueError – if vol is negative, NaN, inf, or -inf

• InvalidKeywordValueError – if matrix in spillover does not have the same number of rows and columns as the measurement vector

• OverflowError – if field 1 in tr is less than 0 or greater than 2**32-1

• ParseKeywordValueError – if field 1 in measurements is "" or contains commas

• InvalidKeywordValueError – if field 2 in spillover is not a square matrix that is 2x2 or larger

• ParseKeywordValueError – if field 2 in tr is "" or contains commas

• ParseKeywordValueError – if any in field 1 in spillover is "" or contains commas

• ParseKeyError – if dict key in nonstandard_keywords is empty or starts with "$"

• ParseKeywordValueError – if dict key in unstainedcenters is "" or contains commas

all_analytes

Value of $PnANALYTE for all measurements (read-write).

() will be returned for time since $PnANALYTE is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_calibrations

Value of $PnCALIBRATION for all measurements (read-write).

() will be returned for time since $PnCALIBRATION is not defined for temporal measurements.

Return type:

list[tuple[float, float, str] | tuple[()] | None]

all_detector_names

Value of $PnDET for all measurements (read-write).

() will be returned for time since $PnDET is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_types

Value of $PnT for all measurements (read-write).

() will be returned for time since $PnT is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_detector_voltages

Value of $PnV for all measurements (read-write).

() will be returned for time since $PnV is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_displays

Value of $PnD for all measurements (read-write).

Return type:

list[tuple[bool, float, float] | None]

all_features

Value of $PnFEATURE for all measurements (read-write).

() will be returned for time since $PnFEATURE is not defined for temporal measurements.

Return type:

list[Literal[“Area”, “Width”, “Height”] | tuple[()] | None]

all_filters

Value of $PnF for all measurements (read-write).

() will be returned for time since $PnF is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_longnames

Value of $PnS for all measurements (read-write).

Return type:

list[str]

all_meas_nonstandard_keywords

The non-standard keywords for each measurement (read-write).

Return type:

list[dict[str, str]]

all_measurement_types

Value of $PnTYPE for all measurements (read-write).

A bool will be returned for the time measurement where True indicates it is set to "Time".

Return type:

list[str | bool]

all_percents_emitted

Value of $PnP for all measurements (read-write).

() will be returned for time since $PnP is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_powers

Value of $PnO for all measurements (read-write).

() will be returned for time since $PnO is not defined for temporal measurements.

Return type:

list[float | tuple[()] | None]

all_scale_transforms

The value for $PnE and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

If scaling is linear, return a float which corresponds to the value of $PnG when $PnE is 0,0. If scaling is logarithmic, return a pair of floats, corresponding to unset $PnG and the non-0,0 value of $PnE.

The FCS standards disallow any other combinations.

The temporal measurement will always be 1.0, corresponding to an identity transform. Setting it to another value will raise RelationalError.

Return type:

list[float | tuple[float, float]]

all_shortnames

Value of $PnN for all measurements (read-write).

Strings are unique and cannot contain commas.

Return type:

list[str]

all_tags

Value of $PnTAG for all measurements (read-write).

() will be returned for time since $PnTAG is not defined for temporal measurements.

Return type:

list[str | tuple[()]]

all_wavelengths

Value of $PnL for all measurements (read-write).

() will be returned for time since $PnL is not defined for temporal measurements.

Return type:

list[list[float] | tuple[()]]

classmethod from_kws(path, std, nonstd, data_seg, analysis_seg=(0, 0), other_segs=[], trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time=False, force_time_linear=False, ignore_time_optical_keys=[], date_pattern=None, time_pattern=None, allow_pseudostandard=False, allow_unused_standard=False, disallow_deprecated=False, fix_log_scale_offsets=False, nonstandard_measurement_pattern=None, ignore_time_gain=False, parse_indexed_spillover=False, disallow_localtime=False, allow_optional_dropping=False, transfer_dropped_optional=False, disallow_range_truncation=False, text_data_correction=(0, 0), text_analysis_correction=(0, 0), ignore_text_data_offsets=False, ignore_text_analysis_offsets=False, allow_header_text_offset_mismatch=False, allow_missing_required_offsets=False, truncate_text_offsets=False, allow_uneven_event_width=False, allow_tot_mismatch=False, warnings_are_errors=False, hide_warnings=False, dataset_offset=0)

Make new instance from keywords.

Parameters:

• path (Path) – Path to be read.

• std (dict[str, str]) – Standard keywords.

• nonstd (dict[str, str]) – Non-Standard keywords.

• data_seg (tuple[int, int]) – The DATA segment from HEADER.

• analysis_seg (tuple[int, int]) – The DATA segment from HEADER. Defaults to (0, 0).

• other_segs (list[tuple[int, int]]) – The OTHER segments from HEADER. Defaults to [].

• trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as , and ; within keyword value strings. Defaults to False.

• time_meas_pattern (str | None) – A pattern to match the $PnN of the time measurement. If None, do not try to find a time measurement. Defaults to "^(TIME|Time)$".

• allow_missing_time (bool) – If True allow time measurement to be missing. Defaults to False.

• force_time_linear (bool) – If True force time measurement to be linear independent of $PnE. Defaults to False.

• ignore_time_optical_keys (list[Literal[“F”, “L”, “O”, “T”, “P”, “V”, “CALIBRATION”, “DET”, “TAG”, “FEATURE”, “ANALYTE”]]) – Ignore optical keys in temporal measurement. These keys are nonsensical for time measurements but are not explicitly forbidden in the the standard. Provided keys are the string after the “Pn” in the “PnX” keywords. Defaults to [].

• date_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $DATE. If not supplied, $DATE will be parsed according to the standard pattern which is %d-%b-%Y. Defaults to None.

• time_pattern (str | None) – If supplied, will be used as an alternative pattern when parsing $BTIM and $ETIM. The values "%!" or "%@" may be used to match 1/60 seconds or centiseconds respectively. If not supplied, $BTIM and $ETIM will be parsed according to the standard pattern which is "%H:%M:%S.%@". Defaults to None.

• allow_pseudostandard (bool) – If True allow non-standard keywords with a leading $. The presence of such keywords often means the version in HEADER is incorrect. Defaults to False.

• allow_unused_standard (bool) – If True allow unused standard keywords to be present. Defaults to False.

• disallow_deprecated (bool) – If True throw error if a deprecated key is encountered. Defaults to False.

• fix_log_scale_offsets (bool) – If True fix log-scale PnE and keywords which have zero offset (ie X,0.0 where X is non-zero). Defaults to False.

• nonstandard_measurement_pattern (str | None) – Pattern to use when matching nonstandard measurement keys. Must be a regular expression pattern with %n which will represent the measurement index and should not start with $. Otherwise should be a normal regular expression as defined in regexp-syntax. Defaults to None.

• ignore_time_gain (bool) – If True ignore the $PnG (gain) keyword. This keyword should not be set according to the standard} however, this library will allow gain to be 1.0 since this equates to identity. If gain is not 1.0, this is nonsense and it can be ignored with this flag. Defaults to False.

• parse_indexed_spillover (bool) – Parse $SPILLOVER with numeric indices rather than strings (ie names or $PnN) Defaults to False.

• disallow_localtime (bool) – If true, require that $BEGINDATETIME and $ENDDATETIME have a timezone if provided. This is not required by the standard, but not having a timezone is ambiguous since the absolute value of the timestamp is dependent on localtime and therefore is location-dependent. Only affects FCS 3.2. Defaults to False.

• allow_optional_dropping (bool) – If True drop optional keys that cause an error and emit warning instead. Defaults to False.

• transfer_dropped_optional (bool) – If True transfer optional keys to non-standard dict if dropped. Defaults to False.

• disallow_range_truncation (bool) – If True throw error if $PnR values need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. Defaults to False.

• text_data_correction (tuple[int, int]) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).

• text_analysis_correction (tuple[int, int]) – Corrections for ANALYSIS offsets in TEXT. Defaults to (0, 0).

• ignore_text_data_offsets (bool) – If True ignore DATA offsets in TEXT Defaults to False.

• ignore_text_analysis_offsets (bool) – If True ignore ANALYSIS offsets in TEXT Defaults to False.

• allow_header_text_offset_mismatch (bool) – If True allow TEXT and HEADER offsets to mismatch. Defaults to False.

• allow_missing_required_offsets (bool) – If True allow required DATA offsets in TEXT to be missing. If missing, fall back to offsets from HEADER. Defaults to False.

• truncate_text_offsets (bool) – If True truncate offsets that exceed end of file. Defaults to False.

• allow_uneven_event_width (bool) – If True allow event width to not perfectly divide length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• allow_tot_mismatch (bool) – If True allow $TOT to not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII layouts. Defaults to False.

• warnings_are_errors (bool) – If True all warnings will be regarded as errors. Defaults to False.

• hide_warnings (bool) – If True hide all warnings. Defaults to False.

• dataset_offset (int) – Starting position in the file of the dataset to be read Defaults to 0.

Return type:

tuple[CoreDataset3_2, StdDatasetWithKwsOutput]

Raises:

• ValueError – if analysis_seg or data_seg has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ConfigError – if nonstandard_measurement_pattern does not have "%n"

• ConfigError – if time_pattern does not have specifiers for hours, minutes, seconds, and optionally sub-seconds (where "%!" and "%@" correspond to 1/60 seconds and centiseconds respectively) as outlined in chrono

• ConfigError – if date_pattern does not have year, month, and day specifiers as outlined in chrono

• ConfigError – if time_meas_pattern is not a valid regular expression as described in regexp-syntax

• OverflowError – if field 1 or 2 in text_analysis_correction or text_data_correction is less than -2**31 or greater than 2**31-1

• ValueError – if any in other_segs has offsets which exceed the end of the file, are inverted (begin after end), or are either negative or greater than 2**64-1

• ParseKeyError – if dict key in nonstd is empty or starts with "$"

• ParseKeyError – if dict key in std is empty, does not start with "$", or is only a "$"

• FCSDeprecatedError – If any keywords or their values are deprecated and disallow_deprecated is True

• ParseKeywordValueError – If any keyword values could not be read from their string encoding

• RelationalError – If keywords are incompatible with indicated layout of DATA or if keywords that are referenced by other keywords do not exist

• EventDataError – If values in DATA cannot be read

• ExtraKeywordError – If any standard keys are unused and allow_pseudostandard or allow_unused_standard are False

insert_optical(index, name, meas, col, range, disallow_trunc=False)

Insert optical measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_2) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, col, range, disallow_trunc=False)

Insert temporal measurement at position in measurement vector.

Parameters:

• index (int) – Position at which to insert new measurement.

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_2) – The measurement to insert.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)

Return measurement at index.

Parameters:

index (int) – Index to retrieve.

Return type:

Optical3_2 | Temporal3_2

Raises:

IndexError – If index not found

measurement_named(name)

Return measurement with name.

Parameters:

name (str) – Name to retrieve. Corresponds to $PnN.

Return type:

Optical3_2 | Temporal3_2

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

measurements

All measurements (read-write).

Return type:

list[Optical3_2 | Temporal3_2]

par

The value for $PAR (read-only).

Return type:

int

push_optical(name, meas, col, range, disallow_trunc=False)

Push optical measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Optical3_2) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, col, range, disallow_trunc=False)

Push temporal measurement to end of measurement vector.

Parameters:

• name (str) – Name of new measurement. Corresponds to $PnN.

• meas (Temporal3_2) – The measurement to push.

• col (polars.Series) – Data for measurement. Must be same length as existing columns.

• range (Decimal) – Range of measurement. Corresponds to $PnR.

• disallow_trunc (bool) – If False, raise RelationalError if range must be truncated to fit into measurement type. Defaults to False.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)

Remove a measurement with a given index.

Parameters:

index (int) – Index to remove.

Returns:

Name and measurement object.

Return type:

tuple[str, Optical3_2 | Temporal3_2, Decimal]

Raises:

IndexError – If index not found

remove_measurement_by_name(name)

Remove a measurement with a given name.

Parameters:

name (str) – Name to remove. Corresponds to $PnN.

Returns:

Index and measurement object.

Return type:

tuple[int, Optical3_2 | Temporal3_2, Decimal]

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name not found

rename_temporal(name)

Rename temporal measurement if present.

Parameters:

name (str) – New name to assign. Corresponds to $PnN.

Returns:

Previous name if present.

Return type:

str | None

Raises:

ParseKeywordValueError – if name is "" or contains commas

replace_optical_at(index, meas)

Replace measurement at index with given optical measurement.

Parameters:

• index (int) – Index to replace.

• meas (Optical3_2) – Optical measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)

Replace named measurement with given optical measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Optical3_2) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist.

replace_temporal_at(index, meas, allow_loss=False)

Replace measurement at index with given temporal measurement.

Parameters:

• index (int) – Index to replace.

• meas (Temporal3_2) – Temporal measurement to replace measurement at index.

• allow_loss (bool) – If False, raise ConversionError if conversion from temporal measurement to optical measurement is necessary and data keywords must be dropped. Defaults to False.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

• IndexError – If index does not exist

• RelationalError – If a temporal measurement already exists at a different position

replace_temporal_named(name, meas, allow_loss=False)

Replace named measurement with given temporal measurement.

Parameters:

• name (str) – Name to replace. Corresponds to $PnN.

• meas (Temporal3_2) – Temporal measurement to replace measurement at name.

• allow_loss (bool) – If False, raise ConversionError if conversion from temporal measurement to optical measurement is necessary and data keywords must be dropped. Defaults to False.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | Temporal3_2

Raises:

• ParseKeywordValueError – if name is "" or contains commas

• KeyError – If name does not exist

• RelationalError – If a temporal measurement already exists at a different position

set_measurements_and_data(measurements, data)

Set measurements and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (list[Optical3_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• data (polars.DataFrame) – The new data.

set_measurements_and_layout(measurements, layout)

Set all measurements and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (list[Optical3_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout | MixedLayout) – The new layout.

set_measurements_layout_and_data(measurements, layout, data)

Set measurements, layout, and data at once.

Length of measurements and layout must match number of columns in data.

Parameters:

• measurements (list[Optical3_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout | MixedLayout) – The new layout.

• data (polars.DataFrame) – The new data.

set_named_measurements(measurements, allow_shared_names=False, skip_index_check=False)

Set all measurements at once.

Length of measurements must match number of columns in existing layout and dataframe.

Parameters:

• measurements (tuple[str, Optical3_2 | Temporal3_2]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_data(measurements, data, allow_shared_names=False, skip_index_check=False)

Set measurements, names, and data at once.

Length of measurements must match number of columns in data.

Parameters:

• measurements (tuple[str, Optical3_2 | Temporal3_2]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• data (polars.DataFrame) – The new data.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_named_measurements_and_layout(measurements, layout, allow_shared_names=False, skip_index_check=False)

Set all measurements, names, and layout at once.

Length of measurements must match number of columns in layout and both must match number of columns in existing dataframe.

Parameters:

• measurements (tuple[str, Optical3_2 | Temporal3_2]) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.

• layout (FixedAsciiLayout | DelimAsciiLayout | EndianUintLayout | EndianF32Layout | EndianF64Layout | MixedLayout) – The new layout.

• allow_shared_names (bool) – If False, raise RelationalError if any non-measurement keywords reference any $PnN keywords. If True raise RelationalError if any non-measurement keywords reference a $PnN which is not present in measurements. In other words, False forbids named references to exist, and True allows named references to be updated. References cannot be broken in either case. Defaults to False.

• skip_index_check (bool) – If False, raise RelationalError if any non-measurement keyword have an index reference to the current measurements. If True allow such references to exist as long as they do not break (which really means that the length of measurements is such that existing indices are satisfied). Defaults to False.

Raises:

ParseKeywordValueError – if field 1 in measurements is "" or contains commas

set_temporal(name, timestep, allow_loss=False)

Set the temporal measurement to a given name.

Parameters:

• name (str) – Name to set to temporal. Corresponds to $PnN.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to name.

Return type:

bool

Raises:

• InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

• ParseKeywordValueError – if name is "" or contains commas

set_temporal_at(index, timestep, allow_loss=False)

Set the temporal measurement to a given index.

Parameters:

• index (int) – Index to set.

• timestep (float) – The value of $TIMESTEP to use.

• allow_loss (bool) – If True remove any optical-specific metadata (detectors, lasers, etc) without raising an ConversionError if an optical measurement must be converted. Defaults to False.

Returns:

True if temporal measurement was set, which will happen for all cases except when the time measurement is already set to index.

Return type:

bool

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_timestep(timestep)

Set the $TIMESTEP if time measurement is present.

Parameters:

timestep (float) – The timestep to set. Must be greater than zero.

Returns:

Previous $TIMESTEP if present.

Return type:

float | None

Raises:

InvalidKeywordValueError – if timestep is negative, 0.0, NaN, inf, or -inf

set_trigger_threshold(threshold)

Set the threshold for $TR.

Parameters:

threshold (int) – The threshold to set.

Returns:

True if trigger is set and was updated.

Return type:

bool

standard_keywords(req_or_opt, root_or_meas)

Return standard keywords as string pairs.

Each key will be prefixed with $.

This will not include $TOT, $NEXTDATA, or any of the offset keywords since these only matter if the dataset is written.

Parameters:

• req_or_opt (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

• root_or_meas (Literal[“both”, “req_only”, “opt_only”]) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

dict[str, str]

temporal

The temporal measurement if it exists (read-only).

Returns:

Index, name, and measurement or None.

Return type:

tuple[int, str, Temporal3_2] | None

timestep

The value of $TIMESTEP (read-only).

Return type:

float | None

to_version_2_0(allow_loss=False)

Convert to FCS 2.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 2.0.

Return type:

CoreDataset2_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 2.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 2.0

to_version_3_0(allow_loss=False)

Convert to FCS 3.0.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.0.

Return type:

CoreDataset3_0

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.0 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.0

to_version_3_1(allow_loss=False)

Convert to FCS 3.1.

Parameters:

allow_loss (bool) – If False, do not proceed with conversion if it would result in data loss. This is most likely to happen when converting from a later to an earlier version, as many keywords from the later version may not exist in the earlier version. There is no place to keep these values so they must be discarded. Set to True to perform the conversion with such discarding; otherwise, remove the keywords manually before converting. Defaults to False.

Returns:

A new class conforming to FCS 3.1.

Return type:

CoreDataset3_1

Raises:

• ConversionError – If keywords which are unsupported in FCS 3.1 exist in current data and allow_loss is False

• ConversionError – If optional keywords are that are missing in current version are required in FCS 3.1

truncate_data(skip_conv_check=False)

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

skip_conv_check (bool) – If True, silently truncate data; otherwise return warnings when truncation is performed. Defaults to False.

Return type:

tuple[()]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout and skip_conversion_check is False

unset_data()

Remove all measurements and their data.

Return type:

tuple[()]

Raises:

RelationalError – If keywords are set which refer to measurements and would be invalidated if measurements were removed

unset_temporal(allow_loss=False)

Convert the temporal measurement to an optical measurement.

Parameters:

allow_loss (bool) – If True and current time measurement has data which cannot be converted to optical, force the conversion anyways. Otherwise raise ConversionError. Defaults to False.

Returns:

Value of $TIMESTEP if time measurement was present.

Return type:

float | None

version

Show the FCS version (read-only).

Return type:

Literal[“FCS2.0”, “FCS3.0”, “FCS3.1”, “FCS3.2”]

write_dataset(path, delim=30, big_other=False, skip_conversion_check=False, appendable=False, append=False)

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA which would point to next dataset if written

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

classmethod write_datasets(path, datasets, delim=30, big_other=False, skip_conversion_check=False)

Write multiple datasets to path.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as they present from this class.

Parameters:

• path (Path) – Path to be written.

• datasets (list[CoreDataset3_2]) – datasets to write

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• skip_conversion_check (bool) – Skip check to ensure that types of the dataframe match the columns ($PnB, $DATATYPE, etc). If this is False, perform this check before writing, and raise DataLossError on failure. If True, raise warnings as file is being written. Skipping this is faster since the data needs to be traversed twice to perform the conversion check, but may result in loss of precision and/or truncation. Defaults to False.

Returns:

the value of $NEXTDATA as written in the last dataset if written

Return type:

int | None

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, appendable=False, append=False)

Write data to path.

Resulting FCS file will include HEADER and TEXT.

Parameters:

• path (Path) – Path to be written.

• delim (int) – Delimiter to use when writing TEXT. Defaults to 30.

• big_other (bool) – If True use 20 chars for OTHER segment offsets, and 8 otherwise. Defaults to False.

• appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This obviously assumes the next dataset is actually written, which will require another call to this method with append set to True. Defaults to False.

• append (bool) – If True, append this dataset to the end of the file if it exists and already has at least one dataset in it. This assumes that the previous dataset was written with appendable set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

int

Raises:

• ConfigError – if delim is not between 1 and 126

• OverflowError – If TEXT offsets are greater than 99,999,999 bytes

• OverflowError – If any OTHER offsets are greater than 99,999,999 and big_other is False