Core* Classes #

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 (MeasIndex) – Index to set.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal2_0] | None

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

Convert to a dataset object.

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

Parameters:

data (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 schema but mismatches may result in truncation.
analysis (AnalysisBytes) – Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – A list of (byte) strings encoding the OTHER segments. Defaults to [].

Return type:

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 (TriFlag) – Choose what happens if conversion 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. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

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:

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

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0. Keywords which reference any $PnN must not be set.

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:: FCSVersion

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

tuple[CoreTEXT3_0, StdTEXTDiagnostics, RepairDiagnostics]

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT, DATA, or ANALYSIS end offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. 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 end offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreTEXT3_0(measurements, data_schema, 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 (Measurements3_0) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – (read-write) Schema to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.
mode (Mode) – (read-write) Value of $MODE. Defaults to "L".
cyt (str) – (read-write) Value of $CYT. Defaults to "".
comp (Compensation | 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 (Unicode | 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 (CsvFlags) – (read-write) Subset flags (combined values of $CSVnFLAG and $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 (Trigger | None) – (read-write) Value of $TR. The measurement name which must match a $PnN. Defaults to None.
applied_gates (AppliedGates3_0) – (read-write) Value for $Gm*/$Rn*/$GATING/$GATE keywords. Defaults to ([], {}, None).
nonstandard_keywords (NonStdKeywords) – (read-write) Pairs of non-standard keyword values. Keys must not start with "$". Defaults to {}.

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_peak_bins#

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

Return type:: list[int | None]

all_peak_sizes#

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 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[OpticalScale3_0]

all_shortnames#

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

Strings are unique and cannot contain commas.

Return type:: list[Shortname]

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[Shortname | 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, dedup_measurement_names=False, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time='false', force_linear_scale='none', ignore_optical_only_keys=[], process_optical_only_keys='demote_warn', date_pattern=None, time_pattern=None, datetime_pattern=None, last_modified_pattern=None, allow_other_feature=False, process_pseudostandard='error', process_hyper_par='error', process_other_version='error', process_extra_timestep='error', fix_log_scale_offsets=False, add_missing_timestep=None, ignore_standard_keys=[], promote_to_standard=[], demote_from_standard=[], rename_standard_keys={}, replace_standard_key_values={}, append_standard_keywords={}, substitute_standard_key_values={}, allow_repair_non_unique='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='error', allow_missing_required_offsets='false', process_optional_failure='error', int_width_override='never', byteord_override='none', disallow_range_truncation='false', warnings_are_errors=False, hide_warnings=False)#

Make new instance from keywords.

Parameters:

std (StdKeywords) – 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 (NonStdKeywords) – Non-Standard keywords.
dedup_measurement_names (bool) – If True, force all $PnN to be unique by appending "~X" to each duplicate and incrementing X starting at 0. Defaults to False.
trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as "," and ";" within keyword value strings. Defaults to False.
time_meas_pattern (Selector[str | None]) – A pattern to match the $PnN of the time measurement. If "NoTime", do not try to find a time measurement. Defaults to "^(TIME|Time)$".
allow_missing_time (TriFlag) – Choose what to do when time measurement is be missing. If "false", raise RelationalError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
force_linear_scale (ForceLinearScale) – Force $PnE to be linear for certain measurements. Affected measurements will never fail. Defaults to "none".
ignore_optical_only_keys (list[OpticalOnlyKey]) – Ignore optical keys in temporal measurement. These keys are $PnG which is explicitly forbidden by the standard but allowed in this library to be set to 1.0 (noop), or others which are nonsensical for time measurements but are not explicitly forbidden in the the standard (such as $PnL). Provided keys are the string after the "Pn" in the "PnX" keywords. Defaults to [].
process_optical_only_keys (ProcessOpticalOnlyKeys) – Choose how to handle optical keys found in temporal measurements. Does nothing unless keys are specified in ignore_optical_only_keys. Defaults to "demote_warn".
date_pattern (Selector[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 (Selector[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.
datetime_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $BEGINDATETIME and $ENDDATETIME. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed as ISO timestamps with optional timezone. Defaults to None.
last_modified_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $LAST_MODIFIED. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed according to the default pattern which is "%d-%b-%Y %H:%M:%S" possibly with centiseconds after. Defaults to None.
allow_other_feature (bool) – If True, allow $PnFEATURE to be a value other than "Area", "Width", or "Height". Defaults to False.
process_pseudostandard (ProcessKeywordFailure) – Process non-standard keywords with a leading "$". The presence of such keywords often means the version in HEADER is incorrect. Defaults to "error".
process_hyper_par (ProcessKeywordFailure) – Process measurement keywords whose index is greater than $PAR. Defaults to "error".
process_other_version (ProcessKeywordFailure) – Process standard keywords from different FCS versions. Defaults to "error".
process_extra_timestep (ProcessKeywordFailure) – Process $TIMESTEP to be present which may indicate a time measurement is present but not identified. Defaults to "error".
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.
add_missing_timestep (Timestep | None) – Set $TIMESTEP if it is not present and required. This will do nothing on FCS2.0 files since this version does not specify $TIMESTEP. Defaults to None.
ignore_standard_keys (AppendableSelector[KeyPatterns]) – Remove standard keys from TEXT. The leading "$" is implied so do not include it. Defaults to [].
promote_to_standard (AppendableSelector[KeyPatterns]) – Promote nonstandard keys to standard keys in TEXT. Defaults to [].
demote_from_standard (AppendableSelector[KeyPatterns]) – Demote nonstandard keys from standard keys in TEXT. Defaults to [].
rename_standard_keys (AppendableSelector[KeyStringPairs]) – Rename standard keys in TEXT. Keys matching the first part of the pair will be replaced by the second. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
replace_standard_key_values (AppendableSelector[KeyStringValues]) – Replace values for standard keys in TEXT. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
append_standard_keywords (AppendableSelector[KeyStringValues]) – Append standard key/value pairs to TEXT. All keys and values will be included as they appear here. The leading "$" is implied so do not include it. Defaults to {}.
substitute_standard_key_values (AppendableSelector[SubPatterns]) – Apply sed-like substitution operation on matching standard keys. The leading "$" is implied when matching keys. Defaults to {}.
allow_repair_non_unique (TriFlag) – Choose how to handle key collisions when repairing keywords. Non-unique keywords will not be kept in the final FCS file since each list of standard and non-standard keywords must be unique. If "false", raise ConfigError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
text_data_correction (OffsetCorrection) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).
text_analysis_correction (OffsetCorrection) – 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 (AllowHeaderTextOffsetMismatch) – Choose what to do if HEADER and TEXT offsets are different. Exception will be FileLayoutError if emitted. Defaults to "error".
allow_missing_required_offsets (TriFlag) – Choose what happens when required DATA and ANALYSIS offsets in TEXT are be missing. If missing, fall back to offsets from HEADER. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
process_optional_failure (ProcessKeywordFailure) – Process optional keys which cause an error. Defaults to "error".
int_width_override (IntWidthOverride) – Override $PnB. Only affects integer layouts in FCS 2.0/3.0. Defaults to "never".
byteord_override (ByteordOverride) – Override $BYTEORD. Only affects integer layouts in FCS 2.0/3.0. Defaults to "none".
disallow_range_truncation (TriFlag) – Choose how to handle $PnR values that need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. If "false", throw warning. If "true", raise RelationalError. If "silent", do nothing. 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:

Raises:

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 not dropped by some other option

insert_optical(index, name, meas, range, scale=1.0)#

Insert optical measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_0) – The measurement to insert.
range (Range) – Range of measurement. Corresponds to $PnR.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range)#

Insert temporal measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_0) – The measurement to insert.
range (Range) – Range of measurement. Corresponds to $PnR.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)#

Return measurement at index.

Parameters:: index (MeasIndex) – Index to retrieve.
Return type:: Optical3_0 | Temporal3_0
Raises:: IndexError – If index not found

measurement_named(name)#

Return measurement with name.

Parameters:

name (Shortname) – 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, scale=1.0)#

Push optical measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_0) – The measurement to push.
range (Range) – Range of measurement. Corresponds to $PnR.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range)#

Push temporal measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_0) – The measurement to push.
range (Range) – Range of measurement. Corresponds to $PnR.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)#

Remove a measurement with a given index.

Parameters:: index (MeasIndex) – Index to remove.
Returns:: Index, measurement object, and range.
Return type:: tuple[Shortname | None, Optical3_0 | Temporal3_0, Range, OpticalScale3_0 | None]
Raises:: IndexError – If index not found

remove_measurement_by_name(name)#

Remove a measurement with a given name.

Parameters:

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

Returns:

Name, measurement object, and range.

Return type:

tuple[MeasIndex, Optical3_0 | Temporal3_0, Range, OpticalScale3_0 | None]

Raises:

ParseKeywordValueError – if name is "" or contains commas
IndexError – If name not found

rename_temporal(name)#

Rename temporal measurement if present.

Parameters:

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

Returns:

Previous name if present.

Return type:

Shortname | None

Raises:

ParseKeywordValueError – if name is "" or contains commas
RelationalError – if name is already present

replace_optical_at(index, meas)#

Replace measurement at index with given optical measurement.

Parameters:

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

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_0]

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)#

Replace named measurement with given optical measurement.

Parameters:

name (Shortname) – Name to replace. Corresponds to $PnN.
meas (Optical3_0) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_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 (MeasIndex) – Index to replace.
meas (Temporal3_0) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_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 (Shortname) – Name to replace. Corresponds to $PnN.
meas (Temporal3_0) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_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_schema(measurements, data_schema)#

Set all measurements and data schema at once.

Length of measurements must match number of columns in data_schema .

Parameters:

measurements (list[Optical3_0 | Temporal3_0]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.

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 data schema.

Parameters:

measurements (Measurements3_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.

set_named_measurements_and_data_schema(measurements, data_schema, allow_shared_names=False, skip_index_check=False)#

Set all measurements, names, and data schema at once.

Length of measurements must match number of columns in data_schema .

Parameters:

measurements (Measurements3_0) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.
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.

set_temporal(name, timestep, allow_loss='false')#

Set the temporal measurement to a given name.

Parameters:

name (Shortname) – Name to set to temporal. Corresponds to $PnN.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

Raises:

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 (MeasIndex) – Index to set.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

set_timestep(timestep)#

Set the $TIMESTEP if time measurement is present.

Parameters:: timestep (Timestep) – The timestep to set. Must be greater than zero.
Returns:: Previous $TIMESTEP if present.
Return type:: Timestep | None

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal3_0] | None

timestep#

The value of $TIMESTEP (read-only).

Return type:: Timestep | None

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

Convert to a dataset object.

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

Parameters:

data (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 schema but mismatches may result in truncation.
analysis (AnalysisBytes) – Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – A list of (byte) strings encoding the OTHER segments. Defaults to [].

Return type:

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:

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:

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:

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

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0. Keywords which reference any $PnN must not be set.

unset_temporal()#

Convert the temporal measurement to an optical measurement.

Returns:: Value of $TIMESTEP if time measurement was present.
Return type:: Timestep | None

version#

Show the FCS version (read-only).

Return type:: FCSVersion

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

tuple[CoreTEXT3_1, StdTEXTDiagnostics, RepairDiagnostics]

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. 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 ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreTEXT3_1(measurements, data_schema, 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 (Measurements3_1) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema) – (read-write) Schema to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.
mode (Mode) – (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 (Spillover | None) – (read-write) Value of $SPILLOVER. Each measurement name must correspond to a $PnN. 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 (Originality | 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 (CsvFlags) – (read-write) Subset flags (combined values of $CSVnFLAG and $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 (Trigger | None) – (read-write) Value of $TR. The measurement name which must match a $PnN. Defaults to None.
applied_gates (AppliedGates3_0) – (read-write) Value for $Gm*/$Rn*/$GATING/$GATE keywords. Defaults to ([], {}, None).
nonstandard_keywords (NonStdKeywords) – (read-write) Pairs of non-standard keyword values. Keys must not start with "$". Defaults to {}.

Raises:

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

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[Calibration3_1 | 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[Display | 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_peak_bins#

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

Return type:: list[int | None]

all_peak_sizes#

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 and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

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[OpticalScale3_0]

all_shortnames#

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

Strings are unique and cannot contain commas.

Return type:: list[Shortname]

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, dedup_measurement_names=False, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time='false', force_linear_scale='none', ignore_optical_only_keys=[], process_optical_only_keys='demote_warn', date_pattern=None, time_pattern=None, datetime_pattern=None, last_modified_pattern=None, allow_other_feature=False, process_pseudostandard='error', process_hyper_par='error', process_other_version='error', process_extra_timestep='error', fix_log_scale_offsets=False, add_missing_timestep=None, spillover_measurement_mode='named', ignore_standard_keys=[], promote_to_standard=[], demote_from_standard=[], rename_standard_keys={}, replace_standard_key_values={}, append_standard_keywords={}, substitute_standard_key_values={}, allow_repair_non_unique='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='error', allow_missing_required_offsets='false', process_optional_failure='error', disallow_range_truncation='false', warnings_are_errors=False, hide_warnings=False)#

Make new instance from keywords.

Parameters:

std (StdKeywords) – 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 (NonStdKeywords) – Non-Standard keywords.
dedup_measurement_names (bool) – If True, force all $PnN to be unique by appending "~X" to each duplicate and incrementing X starting at 0. Defaults to False.
trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as "," and ";" within keyword value strings. Defaults to False.
time_meas_pattern (Selector[str | None]) – A pattern to match the $PnN of the time measurement. If "NoTime", do not try to find a time measurement. Defaults to "^(TIME|Time)$".
allow_missing_time (TriFlag) – Choose what to do when time measurement is be missing. If "false", raise RelationalError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
force_linear_scale (ForceLinearScale) – Force $PnE to be linear for certain measurements. Affected measurements will never fail. Defaults to "none".
ignore_optical_only_keys (list[OpticalOnlyKey]) – Ignore optical keys in temporal measurement. These keys are $PnG which is explicitly forbidden by the standard but allowed in this library to be set to 1.0 (noop), or others which are nonsensical for time measurements but are not explicitly forbidden in the the standard (such as $PnL). Provided keys are the string after the "Pn" in the "PnX" keywords. Defaults to [].
process_optical_only_keys (ProcessOpticalOnlyKeys) – Choose how to handle optical keys found in temporal measurements. Does nothing unless keys are specified in ignore_optical_only_keys. Defaults to "demote_warn".
date_pattern (Selector[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 (Selector[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.
datetime_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $BEGINDATETIME and $ENDDATETIME. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed as ISO timestamps with optional timezone. Defaults to None.
last_modified_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $LAST_MODIFIED. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed according to the default pattern which is "%d-%b-%Y %H:%M:%S" possibly with centiseconds after. Defaults to None.
allow_other_feature (bool) – If True, allow $PnFEATURE to be a value other than "Area", "Width", or "Height". Defaults to False.
process_pseudostandard (ProcessKeywordFailure) – Process non-standard keywords with a leading "$". The presence of such keywords often means the version in HEADER is incorrect. Defaults to "error".
process_hyper_par (ProcessKeywordFailure) – Process measurement keywords whose index is greater than $PAR. Defaults to "error".
process_other_version (ProcessKeywordFailure) – Process standard keywords from different FCS versions. Defaults to "error".
process_extra_timestep (ProcessKeywordFailure) – Process $TIMESTEP to be present which may indicate a time measurement is present but not identified. Defaults to "error".
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.
add_missing_timestep (Timestep | None) – Set $TIMESTEP if it is not present and required. This will do nothing on FCS2.0 files since this version does not specify $TIMESTEP. Defaults to None.
spillover_measurement_mode (SpilloverMeasurementMode) – Choose how to interpret measurement strings in $SPILLOVER. Defaults to "named".
ignore_standard_keys (AppendableSelector[KeyPatterns]) – Remove standard keys from TEXT. The leading "$" is implied so do not include it. Defaults to [].
promote_to_standard (AppendableSelector[KeyPatterns]) – Promote nonstandard keys to standard keys in TEXT. Defaults to [].
demote_from_standard (AppendableSelector[KeyPatterns]) – Demote nonstandard keys from standard keys in TEXT. Defaults to [].
rename_standard_keys (AppendableSelector[KeyStringPairs]) – Rename standard keys in TEXT. Keys matching the first part of the pair will be replaced by the second. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
replace_standard_key_values (AppendableSelector[KeyStringValues]) – Replace values for standard keys in TEXT. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
append_standard_keywords (AppendableSelector[KeyStringValues]) – Append standard key/value pairs to TEXT. All keys and values will be included as they appear here. The leading "$" is implied so do not include it. Defaults to {}.
substitute_standard_key_values (AppendableSelector[SubPatterns]) – Apply sed-like substitution operation on matching standard keys. The leading "$" is implied when matching keys. Defaults to {}.
allow_repair_non_unique (TriFlag) – Choose how to handle key collisions when repairing keywords. Non-unique keywords will not be kept in the final FCS file since each list of standard and non-standard keywords must be unique. If "false", raise ConfigError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
text_data_correction (OffsetCorrection) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).
text_analysis_correction (OffsetCorrection) – 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 (AllowHeaderTextOffsetMismatch) – Choose what to do if HEADER and TEXT offsets are different. Exception will be FileLayoutError if emitted. Defaults to "error".
allow_missing_required_offsets (TriFlag) – Choose what happens when required DATA and ANALYSIS offsets in TEXT are be missing. If missing, fall back to offsets from HEADER. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
process_optional_failure (ProcessKeywordFailure) – Process optional keys which cause an error. Defaults to "error".
disallow_range_truncation (TriFlag) – Choose how to handle $PnR values that need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. If "false", throw warning. If "true", raise RelationalError. If "silent", do nothing. 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:

Raises:

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 not dropped by some other option

insert_optical(index, name, meas, range, scale=1.0)#

Insert optical measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_1) – The measurement to insert.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range)#

Insert temporal measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_1) – The measurement to insert.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)#

Return measurement at index.

Parameters:: index (MeasIndex) – Index to retrieve.
Return type:: Optical3_1 | Temporal3_1
Raises:: IndexError – If index not found

measurement_named(name)#

Return measurement with name.

Parameters:

name (Shortname) – 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, scale=1.0)#

Push optical measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_1) – The measurement to push.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range)#

Push temporal measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_1) – The measurement to push.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)#

Remove a measurement with a given index.

Parameters:: index (MeasIndex) – Index to remove.
Returns:: Index, measurement object, and range.
Return type:: tuple[Shortname, Optical3_1 | Temporal3_1, Range, OpticalScale3_0 | None, ByteWidth | None]
Raises:: IndexError – If index not found

remove_measurement_by_name(name)#

Remove a measurement with a given name.

Parameters:

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

Returns:

Name, measurement object, and range.

Return type:

tuple[MeasIndex, Optical3_1 | Temporal3_1, Range, OpticalScale3_0 | None, ByteWidth | None]

Raises:

ParseKeywordValueError – if name is "" or contains commas
IndexError – If name not found

rename_temporal(name)#

Rename temporal measurement if present.

Parameters:

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

Returns:

Previous name if present.

Return type:

Shortname | None

Raises:

ParseKeywordValueError – if name is "" or contains commas
RelationalError – if name is already present

replace_optical_at(index, meas)#

Replace measurement at index with given optical measurement.

Parameters:

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

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_0]

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)#

Replace named measurement with given optical measurement.

Parameters:

name (Shortname) – Name to replace. Corresponds to $PnN.
meas (Optical3_1) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_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 (MeasIndex) – Index to replace.
meas (Temporal3_1) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_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 (Shortname) – Name to replace. Corresponds to $PnN.
meas (Temporal3_1) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_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_schema(measurements, data_schema)#

Set all measurements and data schema at once.

Length of measurements must match number of columns in data_schema .

Parameters:

measurements (list[Optical3_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema) – The new data schema.

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 data schema.

Parameters:

measurements (Measurements3_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.

set_named_measurements_and_data_schema(measurements, data_schema, allow_shared_names=False, skip_index_check=False)#

Set all measurements, names, and data schema at once.

Length of measurements must match number of columns in data_schema .

Parameters:

measurements (Measurements3_1) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema) – The new data schema.
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.

set_temporal(name, timestep, allow_loss='false')#

Set the temporal measurement to a given name.

Parameters:

name (Shortname) – Name to set to temporal. Corresponds to $PnN.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

Raises:

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 (MeasIndex) – Index to set.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

set_timestep(timestep)#

Set the $TIMESTEP if time measurement is present.

Parameters:: timestep (Timestep) – The timestep to set. Must be greater than zero.
Returns:: Previous $TIMESTEP if present.
Return type:: Timestep | None

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal3_1] | None

timestep#

The value of $TIMESTEP (read-only).

Return type:: Timestep | None

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

Convert to a dataset object.

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

Parameters:

data (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 schema but mismatches may result in truncation.
analysis (AnalysisBytes) – Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – A list of (byte) strings encoding the OTHER segments. Defaults to [].

Return type:

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:

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:

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:

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

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0. Keywords which reference any $PnN must not be set.

unset_temporal()#

Convert the temporal measurement to an optical measurement.

Returns:: Value of $TIMESTEP if time measurement was present.
Return type:: Timestep | None

version#

Show the FCS version (read-only).

Return type:: FCSVersion

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

tuple[CoreTEXT3_2, StdTEXTDiagnostics, RepairDiagnostics]

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. 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 ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreTEXT3_2(measurements, data_schema, 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 (Measurements3_2) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema | MixedDataSchema) – (read-write) Schema to describe data encoding. Represents $PnB, $PnR, $BYTEORD, $DATATYPE, and $PnDATATYPE
cyt (str) – (read-write) Value of $CYT.
mode (Mode3_2 | 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 (Spillover | None) – (read-write) Value of $SPILLOVER. Each measurement name must correspond to a $PnN. 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 (Originality | 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 (UnstainedCenters) – (read-write) Value of $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 (Trigger | None) – (read-write) Value of $TR. The measurement name which must match a $PnN. Defaults to None.
applied_gates (AppliedGates3_2) – (read-write) Value for $Rn*/$GATING keywords. Defaults to ({}, None).
nonstandard_keywords (NonStdKeywords) – (read-write) Pairs of non-standard keyword values. Keys must not start with "$". Defaults to {}.

Raises:

InvalidKeywordValueError – if cyt is empty
InvalidKeywordValueError – if vol is negative, NaN, inf, or -inf

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_awh_features#

Value of $PnFEATURE (area/width/height) for all measurements.

This should be the preferred way to get and set this keyword if one knows that only "Area", "Width", and "Height" will be used for this dataset since it has a well-defined type.

() will be returned for the time measurement.

This attribute is read-write.

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

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[Calibration3_2 | 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[Display | 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[str | 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_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_other_features#

Value of $PnFEATURE (not area/width/height) for all measurements.

Values which are not "Area", "Width", and "Height" will be returned as None.

() will be returned for the time measurement.

This attribute is read-only.

Return type:: list[str | tuple[()] | 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 and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

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[OpticalScale3_0]

all_shortnames#

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

Strings are unique and cannot contain commas.

Return type:: list[Shortname]

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, dedup_measurement_names=False, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time='false', force_linear_scale='none', ignore_optical_only_keys=[], process_optical_only_keys='demote_warn', date_pattern=None, time_pattern=None, datetime_pattern=None, last_modified_pattern=None, allow_other_feature=False, process_pseudostandard='error', process_hyper_par='error', process_other_version='error', process_extra_timestep='error', fix_log_scale_offsets=False, add_missing_timestep=None, spillover_measurement_mode='named', disallow_localtime=False, ignore_standard_keys=[], promote_to_standard=[], demote_from_standard=[], rename_standard_keys={}, replace_standard_key_values={}, append_standard_keywords={}, substitute_standard_key_values={}, allow_repair_non_unique='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='error', allow_missing_required_offsets='false', process_optional_failure='error', disallow_range_truncation='false', warnings_are_errors=False, hide_warnings=False)#

Make new instance from keywords.

Parameters:

std (StdKeywords) – 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 (NonStdKeywords) – Non-Standard keywords.
dedup_measurement_names (bool) – If True, force all $PnN to be unique by appending "~X" to each duplicate and incrementing X starting at 0. Defaults to False.
trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as "," and ";" within keyword value strings. Defaults to False.
time_meas_pattern (Selector[str | None]) – A pattern to match the $PnN of the time measurement. If "NoTime", do not try to find a time measurement. Defaults to "^(TIME|Time)$".
allow_missing_time (TriFlag) – Choose what to do when time measurement is be missing. If "false", raise RelationalError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
force_linear_scale (ForceLinearScale) – Force $PnE to be linear for certain measurements. Affected measurements will never fail. Defaults to "none".
ignore_optical_only_keys (list[OpticalOnlyKey]) – Ignore optical keys in temporal measurement. These keys are $PnG which is explicitly forbidden by the standard but allowed in this library to be set to 1.0 (noop), or others which are nonsensical for time measurements but are not explicitly forbidden in the the standard (such as $PnL). Provided keys are the string after the "Pn" in the "PnX" keywords. Defaults to [].
process_optical_only_keys (ProcessOpticalOnlyKeys) – Choose how to handle optical keys found in temporal measurements. Does nothing unless keys are specified in ignore_optical_only_keys. Defaults to "demote_warn".
date_pattern (Selector[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 (Selector[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.
datetime_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $BEGINDATETIME and $ENDDATETIME. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed as ISO timestamps with optional timezone. Defaults to None.
last_modified_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $LAST_MODIFIED. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed according to the default pattern which is "%d-%b-%Y %H:%M:%S" possibly with centiseconds after. Defaults to None.
allow_other_feature (bool) – If True, allow $PnFEATURE to be a value other than "Area", "Width", or "Height". Defaults to False.
process_pseudostandard (ProcessKeywordFailure) – Process non-standard keywords with a leading "$". The presence of such keywords often means the version in HEADER is incorrect. Defaults to "error".
process_hyper_par (ProcessKeywordFailure) – Process measurement keywords whose index is greater than $PAR. Defaults to "error".
process_other_version (ProcessKeywordFailure) – Process standard keywords from different FCS versions. Defaults to "error".
process_extra_timestep (ProcessKeywordFailure) – Process $TIMESTEP to be present which may indicate a time measurement is present but not identified. Defaults to "error".
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.
add_missing_timestep (Timestep | None) – Set $TIMESTEP if it is not present and required. This will do nothing on FCS2.0 files since this version does not specify $TIMESTEP. Defaults to None.
spillover_measurement_mode (SpilloverMeasurementMode) – Choose how to interpret measurement strings in $SPILLOVER. Defaults to "named".
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.
ignore_standard_keys (AppendableSelector[KeyPatterns]) – Remove standard keys from TEXT. The leading "$" is implied so do not include it. Defaults to [].
promote_to_standard (AppendableSelector[KeyPatterns]) – Promote nonstandard keys to standard keys in TEXT. Defaults to [].
demote_from_standard (AppendableSelector[KeyPatterns]) – Demote nonstandard keys from standard keys in TEXT. Defaults to [].
rename_standard_keys (AppendableSelector[KeyStringPairs]) – Rename standard keys in TEXT. Keys matching the first part of the pair will be replaced by the second. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
replace_standard_key_values (AppendableSelector[KeyStringValues]) – Replace values for standard keys in TEXT. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
append_standard_keywords (AppendableSelector[KeyStringValues]) – Append standard key/value pairs to TEXT. All keys and values will be included as they appear here. The leading "$" is implied so do not include it. Defaults to {}.
substitute_standard_key_values (AppendableSelector[SubPatterns]) – Apply sed-like substitution operation on matching standard keys. The leading "$" is implied when matching keys. Defaults to {}.
allow_repair_non_unique (TriFlag) – Choose how to handle key collisions when repairing keywords. Non-unique keywords will not be kept in the final FCS file since each list of standard and non-standard keywords must be unique. If "false", raise ConfigError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
text_data_correction (OffsetCorrection) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).
text_analysis_correction (OffsetCorrection) – 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 (AllowHeaderTextOffsetMismatch) – Choose what to do if HEADER and TEXT offsets are different. Exception will be FileLayoutError if emitted. Defaults to "error".
allow_missing_required_offsets (TriFlag) – Choose what happens when required DATA offsets in TEXT are be missing. If missing, fall back to offsets from HEADER. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
process_optional_failure (ProcessKeywordFailure) – Process optional keys which cause an error. Defaults to "error".
disallow_range_truncation (TriFlag) – Choose how to handle $PnR values that need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. If "false", throw warning. If "true", raise RelationalError. If "silent", do nothing. 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:

Raises:

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 not dropped by some other option

insert_optical(index, name, meas, range, scale=1.0)#

Insert optical measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_2) – The measurement to insert.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range)#

Insert temporal measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_2) – The measurement to insert.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)#

Return measurement at index.

Parameters:: index (MeasIndex) – Index to retrieve.
Return type:: Optical3_2 | Temporal3_2
Raises:: IndexError – If index not found

measurement_named(name)#

Return measurement with name.

Parameters:

name (Shortname) – 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, scale=1.0)#

Push optical measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_2) – The measurement to push.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range)#

Push temporal measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_2) – The measurement to push.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)#

Remove a measurement with a given index.

Parameters:: index (MeasIndex) – Index to remove.
Returns:: Index, measurement object, and range.
Return type:: tuple[Shortname, Optical3_2 | Temporal3_2, Range, OpticalScale3_0 | None, AnyType | None]
Raises:: IndexError – If index not found

remove_measurement_by_name(name)#

Remove a measurement with a given name.

Parameters:

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

Returns:

Name, measurement object, and range.

Return type:

tuple[MeasIndex, Optical3_2 | Temporal3_2, Range, OpticalScale3_0 | None, AnyType | None]

Raises:

ParseKeywordValueError – if name is "" or contains commas
IndexError – If name not found

rename_temporal(name)#

Rename temporal measurement if present.

Parameters:

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

Returns:

Previous name if present.

Return type:

Shortname | None

Raises:

ParseKeywordValueError – if name is "" or contains commas
RelationalError – if name is already present

replace_optical_at(index, meas)#

Replace measurement at index with given optical measurement.

Parameters:

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

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_0]

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)#

Replace named measurement with given optical measurement.

Parameters:

name (Shortname) – Name to replace. Corresponds to $PnN.
meas (Optical3_2) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_0]

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 (MeasIndex) – Index to replace.
meas (Temporal3_2) – Temporal measurement to replace measurement at index.
allow_loss (TriFlag) – Choose what happens if conversion from temporal measurement to optical measurement is necessary and data loss will occur. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. Defaults to "false".

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_0]

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 (Shortname) – Name to replace. Corresponds to $PnN.
meas (Temporal3_2) – Temporal measurement to replace measurement at name.
allow_loss (TriFlag) – Choose what happens if conversion from temporal measurement to optical measurement is necessary and data loss will occur. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. Defaults to "false".

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_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_schema(measurements, data_schema)#

Set all measurements and data schema at once.

Length of measurements must match number of columns in data_schema .

Parameters:

measurements (list[Optical3_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema | MixedDataSchema) – The new data schema.

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 data schema.

Parameters:

measurements (Measurements3_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.

set_named_measurements_and_data_schema(measurements, data_schema, allow_shared_names=False, skip_index_check=False)#

Set all measurements, names, and data schema at once.

Length of measurements must match number of columns in data_schema .

Parameters:

measurements (Measurements3_2) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema | MixedDataSchema) – The new data schema.
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.

set_temporal(name, timestep, allow_loss='false')#

Set the temporal measurement to a given name.

Parameters:

name (Shortname) – Name to set to temporal. Corresponds to $PnN.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

Raises:

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 (MeasIndex) – Index to set.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

set_timestep(timestep)#

Set the $TIMESTEP if time measurement is present.

Parameters:: timestep (Timestep) – The timestep to set. Must be greater than zero.
Returns:: Previous $TIMESTEP if present.
Return type:: Timestep | None

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal3_2] | None

timestep#

The value of $TIMESTEP (read-only).

Return type:: Timestep | None

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

Convert to a dataset object.

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

Parameters:

data (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 schema but mismatches may result in truncation.
analysis (AnalysisBytes) – Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – A list of (byte) strings encoding the OTHER segments. Defaults to [].

Return type:

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:

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:

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:

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

This is equivalent to deleting all $Pn* keywords and setting $PAR to 0. Keywords which reference any $PnN must not be set.

unset_temporal(allow_loss='false')#

Convert the temporal measurement to an optical measurement.

Parameters:: allow_loss (TriFlag) – Choose what happens if temporal measurement cannot be converted to optical without data loss. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
Returns:: Value of $TIMESTEP if time measurement was present.
Return type:: Timestep | None

version#

Show the FCS version (read-only).

Return type:: FCSVersion

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

tuple[CoreDataset2_0, NewStdDatasetFromKwsOutput]

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

classmethod write_texts(path, datasets, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. 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 ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end 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 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, data_schema, 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='', others=[])#

Represents one dataset in an FCS 2.0 file.

Parameters:

measurements (Measurements2_0) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – (read-write) Schema to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.
data (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 schema but mismatches may result in truncation.
mode (Mode) – (read-write) Value of $MODE. Defaults to "L".
cyt (str) – (read-write) Value of $CYT. Defaults to "".
comp (Compensation | 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 (Trigger | None) – (read-write) Value of $TR. The measurement name which must match a $PnN. Defaults to None.
applied_gates (AppliedGates2_0) – (read-write) Value for $Gm*/$Rn*/$GATING/$GATE keywords. Defaults to ([], {}, None).
nonstandard_keywords (NonStdKeywords) – (read-write) Pairs of non-standard keyword values. Keys must not start with "$". Defaults to {}.
analysis (AnalysisBytes) – (read-write) Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – (read-write) A list of (byte) strings encoding the OTHER segments. Defaults to [].

Raises:

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

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_peak_bins#

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

Return type:: list[int | None]

all_peak_sizes#

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[OpticalScale2_0 | None]

all_shortnames#

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

Strings are unique and cannot contain commas.

Return type:: list[Shortname]

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[Shortname | 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]

check_ranges(over_bitmask_action='trunc_warn', over_range_action='warn')#

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".

Returns:

The columns that were overrange. List indices correspond to columns. None is returned is not truncated. Index of first overrange row is returned.

Return type:

list[int | None]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout data_schema

classmethod from_kws(path, header, std, nonstd, dedup_measurement_names=False, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time='false', force_linear_scale='none', ignore_optical_only_keys=[], process_optical_only_keys='demote_warn', date_pattern=None, time_pattern=None, datetime_pattern=None, last_modified_pattern=None, allow_other_feature=False, process_pseudostandard='error', process_hyper_par='error', process_other_version='error', process_extra_timestep='error', fix_log_scale_offsets=False, ignore_standard_keys=[], promote_to_standard=[], demote_from_standard=[], rename_standard_keys={}, replace_standard_key_values={}, append_standard_keywords={}, substitute_standard_key_values={}, allow_repair_non_unique='false', process_optional_failure='error', int_width_override='never', byteord_override='none', disallow_range_truncation='false', data_remainder_limit=0, allow_uneven_event_width='false', allow_tot_mismatch='false', over_bitmask_action='trunc_warn', over_range_action='warn', read_intra_segment_dark_bytes=False, read_post_dataset_dark_bytes=False, row_buffer_size=28000, warnings_are_errors=False, hide_warnings=False, dataset_offset=0, dataset_len=None)#

Make new instance from keywords.

Parameters:

path (Path) – Path to be read.
header (HeaderAndSuppOffsets) – The HEADER and supplemental TEXT offsets from parsed file
std (StdKeywords) – Standard keywords.
nonstd (NonStdKeywords) – Non-Standard keywords.
dedup_measurement_names (bool) – If True, force all $PnN to be unique by appending "~X" to each duplicate and incrementing X starting at 0. Defaults to False.
trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as "," and ";" within keyword value strings. Defaults to False.
time_meas_pattern (Selector[str | None]) – A pattern to match the $PnN of the time measurement. If "NoTime", do not try to find a time measurement. Defaults to "^(TIME|Time)$".
allow_missing_time (TriFlag) – Choose what to do when time measurement is be missing. If "false", raise RelationalError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
force_linear_scale (ForceLinearScale) – Force $PnE to be linear for certain measurements. Affected measurements will never fail. Defaults to "none".
ignore_optical_only_keys (list[OpticalOnlyKey]) – Ignore optical keys in temporal measurement. These keys are $PnG which is explicitly forbidden by the standard but allowed in this library to be set to 1.0 (noop), or others which are nonsensical for time measurements but are not explicitly forbidden in the the standard (such as $PnL). Provided keys are the string after the "Pn" in the "PnX" keywords. Defaults to [].
process_optical_only_keys (ProcessOpticalOnlyKeys) – Choose how to handle optical keys found in temporal measurements. Does nothing unless keys are specified in ignore_optical_only_keys. Defaults to "demote_warn".
date_pattern (Selector[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 (Selector[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.
datetime_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $BEGINDATETIME and $ENDDATETIME. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed as ISO timestamps with optional timezone. Defaults to None.
last_modified_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $LAST_MODIFIED. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed according to the default pattern which is "%d-%b-%Y %H:%M:%S" possibly with centiseconds after. Defaults to None.
allow_other_feature (bool) – If True, allow $PnFEATURE to be a value other than "Area", "Width", or "Height". Defaults to False.
process_pseudostandard (ProcessKeywordFailure) – Process non-standard keywords with a leading "$". The presence of such keywords often means the version in HEADER is incorrect. Defaults to "error".
process_hyper_par (ProcessKeywordFailure) – Process measurement keywords whose index is greater than $PAR. Defaults to "error".
process_other_version (ProcessKeywordFailure) – Process standard keywords from different FCS versions. Defaults to "error".
process_extra_timestep (ProcessKeywordFailure) – Process $TIMESTEP to be present which may indicate a time measurement is present but not identified. Defaults to "error".
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.
ignore_standard_keys (AppendableSelector[KeyPatterns]) – Remove standard keys from TEXT. The leading "$" is implied so do not include it. Defaults to [].
promote_to_standard (AppendableSelector[KeyPatterns]) – Promote nonstandard keys to standard keys in TEXT. Defaults to [].
demote_from_standard (AppendableSelector[KeyPatterns]) – Demote nonstandard keys from standard keys in TEXT. Defaults to [].
rename_standard_keys (AppendableSelector[KeyStringPairs]) – Rename standard keys in TEXT. Keys matching the first part of the pair will be replaced by the second. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
replace_standard_key_values (AppendableSelector[KeyStringValues]) – Replace values for standard keys in TEXT. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
append_standard_keywords (AppendableSelector[KeyStringValues]) – Append standard key/value pairs to TEXT. All keys and values will be included as they appear here. The leading "$" is implied so do not include it. Defaults to {}.
substitute_standard_key_values (AppendableSelector[SubPatterns]) – Apply sed-like substitution operation on matching standard keys. The leading "$" is implied when matching keys. Defaults to {}.
allow_repair_non_unique (TriFlag) – Choose how to handle key collisions when repairing keywords. Non-unique keywords will not be kept in the final FCS file since each list of standard and non-standard keywords must be unique. If "false", raise ConfigError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
process_optional_failure (ProcessKeywordFailure) – Process optional keys which cause an error. Defaults to "error".
int_width_override (IntWidthOverride) – Override $PnB. Only affects integer layouts in FCS 2.0/3.0. Defaults to "never".
byteord_override (ByteordOverride) – Override $BYTEORD. Only affects integer layouts in FCS 2.0/3.0. Defaults to "none".
disallow_range_truncation (TriFlag) – Choose how to handle $PnR values that need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. If "false", throw warning. If "true", raise RelationalError. If "silent", do nothing. Defaults to "false".
data_remainder_limit (int) – Limit by which ending DATA offset can be truncated if its length modulo event width produces a remainder. Defaults to 0.
allow_uneven_event_width (TriFlag) – Choose what to do when event width does not perfectly divide length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
allow_tot_mismatch (TriFlag) – Choose what happens when $TOT does not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".
read_intra_segment_dark_bytes (bool) – If True read bytes which are between segments. Defaults to False.
read_post_dataset_dark_bytes (bool) – If True read bytes between the end of the current dataset and the next. Defaults to False.
row_buffer_size (int) – Set the size in bytes for the internal buffer used to read DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
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.
dataset_len (int | None) – The length of the dataset to be read; should correspond to $NEXTDATA or end of file (whichever is lesser) minus the starting offset of the dataset. Defaults to None.

Return type:

Raises:

ParseKeywordValueError – If any keyword values could not be read from their string encoding
RelationalError – If keywords are incompatible with indicated data schema for 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 not dropped by some other option

insert_optical(index, name, meas, range, col, scale=())#

Insert optical measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical2_0) – The measurement to insert.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale2_0 | None) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to ().

Raises:

ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, col)#

Insert temporal measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal2_0) – The measurement to insert.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)#

Return measurement at index.

Parameters:: index (MeasIndex) – Index to retrieve.
Return type:: Optical2_0 | Temporal2_0
Raises:: IndexError – If index not found

measurement_named(name)#

Return measurement with name.

Parameters:

name (Shortname) – 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, col, scale=())#

Push optical measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical2_0) – The measurement to push.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale2_0 | None) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to ().

Raises:

ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, col)#

Push temporal measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal2_0) – The measurement to push.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)#

Remove a measurement with a given index.

Parameters:: index (MeasIndex) – Index to remove.
Returns:: Index, measurement object, data, and range.
Return type:: tuple[Shortname | None, Optical2_0 | Temporal2_0, Series, Range, OpticalScale2_0 | None]
Raises:: IndexError – If index not found

remove_measurement_by_name(name)#

Remove a measurement with a given name.

Parameters:

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

Returns:

Name, measurement object, data, and range.

Return type:

tuple[MeasIndex, Optical2_0 | Temporal2_0, Series, Range, OpticalScale2_0 | None]

Raises:

ParseKeywordValueError – if name is "" or contains commas
IndexError – If name not found

rename_temporal(name)#

Rename temporal measurement if present.

Parameters:

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

Returns:

Previous name if present.

Return type:

Shortname | None

Raises:

ParseKeywordValueError – if name is "" or contains commas
RelationalError – if name is already present

replace_optical_at(index, meas)#

Replace measurement at index with given optical measurement.

Parameters:

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

Returns:

Replaced measurement object.

Return type:

Optical2_0 | tuple[Temporal2_0, OpticalScale2_0 | None]

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)#

Replace named measurement with given optical measurement.

Parameters:

name (Shortname) – Name to replace. Corresponds to $PnN.
meas (Optical2_0) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | tuple[Temporal2_0, OpticalScale2_0 | None]

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 (MeasIndex) – Index to replace.
meas (Temporal2_0) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | tuple[Temporal2_0, OpticalScale2_0 | None]

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 (Shortname) – Name to replace. Corresponds to $PnN.
meas (Temporal2_0) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical2_0 | tuple[Temporal2_0, OpticalScale2_0 | None]

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 (DataFrame) – The new data.

set_measurements_and_data_schema(measurements, data_schema)#

Set all measurements and data schema at once.

Length of measurements must match number of columns in data_schema 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.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.

set_measurements_data_schema_and_data(measurements, data_schema, data)#

Set measurements, data schema, and data at once.

Length of measurements and data_schema 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_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.
data (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 data schema and dataframe.

Parameters:

measurements (Measurements2_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.

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 (Measurements2_0) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data (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.

set_named_measurements_and_data_schema(measurements, data_schema, allow_shared_names=False, skip_index_check=False)#

Set all measurements, names, and data schema at once.

Length of measurements must match number of columns in data_schema and both must match number of columns in existing dataframe.

Parameters:

measurements (Measurements2_0) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.
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.

set_temporal(name, allow_loss='false')#

Set the temporal measurement to a given name.

Parameters:

name (Shortname) – Name to set to temporal. Corresponds to $PnN.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

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 (MeasIndex) – Index to set.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal2_0] | None

to_version_3_0(allow_loss='false')#

Convert to FCS 3.0.

Parameters:

Returns:

A new class conforming to FCS 3.0.

Return type:

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:

Returns:

A new class conforming to FCS 3.1.

Return type:

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:

Returns:

A new class conforming to FCS 3.2.

Return type:

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_data()#

Remove all measurements and their data.

This is equivalent to deleting all $Pn* keywords, setting $PAR to 0, and setting DATA to an empty dataframe. Keywords which reference any $PnN must not be set.

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:: FCSVersion

write_dataset(path, delim=30, big_other=False, compute_crc=False, override_fil=False, allow_over_bitmask='false', disallow_over_range='false', row_buffer_size=28000, appendable=False, append=False)#

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as present in 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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
allow_over_bitmask (TriFlag) – Choose how to report integer event values in DATA which exceed bitmask. If "false", raise EventDataError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
disallow_over_range (TriFlag) – Choose how to report event values in DATA which exceed $PnR. If "false", throw warning. If "true", raise EventDataError. If "silent", do nothing. Defaults to "false".
row_buffer_size (int) – Set the size in bytes for the internal buffer used to write DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append 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:

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT, DATA, or ANALYSIS end offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

tuple[CoreDataset3_0, NewStdDatasetFromKwsOutput]

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT, DATA, or ANALYSIS end offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreDataset3_0(measurements, data_schema, 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='', others=[])#

Represents one dataset in an FCS 3.0 file.

Parameters:

measurements (Measurements3_0) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – (read-write) Schema to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.
data (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 schema but mismatches may result in truncation.
mode (Mode) – (read-write) Value of $MODE. Defaults to "L".
cyt (str) – (read-write) Value of $CYT. Defaults to "".
comp (Compensation | 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 (Unicode | 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 (CsvFlags) – (read-write) Subset flags (combined values of $CSVnFLAG and $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 (Trigger | None) – (read-write) Value of $TR. The measurement name which must match a $PnN. Defaults to None.
applied_gates (AppliedGates3_0) – (read-write) Value for $Gm*/$Rn*/$GATING/$GATE keywords. Defaults to ([], {}, None).
nonstandard_keywords (NonStdKeywords) – (read-write) Pairs of non-standard keyword values. Keys must not start with "$". Defaults to {}.
analysis (AnalysisBytes) – (read-write) Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – (read-write) A list of (byte) strings encoding the OTHER segments. Defaults to [].

Raises:

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

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_peak_bins#

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

Return type:: list[int | None]

all_peak_sizes#

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 and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

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[OpticalScale3_0]

all_shortnames#

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

Strings are unique and cannot contain commas.

Return type:: list[Shortname]

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[Shortname | 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]

check_ranges(over_bitmask_action='trunc_warn', over_range_action='warn')#

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".

Returns:

The columns that were overrange. List indices correspond to columns. None is returned is not truncated. Index of first overrange row is returned.

Return type:

list[int | None]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout data_schema

classmethod from_kws(path, header, std, nonstd, allow_pseudoempty=False, dataset_overflow_limit=0, overlap_correction_limit=0, dedup_measurement_names=False, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time='false', force_linear_scale='none', ignore_optical_only_keys=[], process_optical_only_keys='demote_warn', date_pattern=None, time_pattern=None, datetime_pattern=None, last_modified_pattern=None, allow_other_feature=False, process_pseudostandard='error', process_hyper_par='error', process_other_version='error', process_extra_timestep='error', fix_log_scale_offsets=False, add_missing_timestep=None, ignore_standard_keys=[], promote_to_standard=[], demote_from_standard=[], rename_standard_keys={}, replace_standard_key_values={}, append_standard_keywords={}, substitute_standard_key_values={}, allow_repair_non_unique='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='error', allow_missing_required_offsets='false', process_optional_failure='error', int_width_override='never', byteord_override='none', disallow_range_truncation='false', data_remainder_limit=0, allow_uneven_event_width='false', allow_tot_mismatch='false', over_bitmask_action='trunc_warn', over_range_action='warn', allow_missing_crc='false', allow_mismatch_crc='false', compute_crc='never', read_intra_segment_dark_bytes=False, read_post_dataset_dark_bytes=False, row_buffer_size=28000, warnings_are_errors=False, hide_warnings=False, dataset_offset=0, dataset_len=None)#

Make new instance from keywords.

Parameters:

path (Path) – Path to be read.
header (HeaderAndSuppOffsets) – The HEADER and supplemental TEXT offsets from parsed file
std (StdKeywords) – Standard keywords.
nonstd (NonStdKeywords) – Non-Standard keywords.
allow_pseudoempty (bool) – If True, allow offsets like X,X-1. Some files will denote an “empty” offset as 0,-1 or 1000,999, which is logically correct since the last offset points to the last byte, thus 0,0 is actually 1 byte long. If this flat is set, such offsets will be treated as if they were 0,0. Defaults to False.
dataset_overflow_limit (int) – Limit by which offsets can be truncated if they exceed end of file or $NEXTDATA. Defaults to 0.
overlap_correction_limit (int) – Limit by which ending segment offset can be truncated if they overlap another offset. Defaults to 0.
dedup_measurement_names (bool) – If True, force all $PnN to be unique by appending "~X" to each duplicate and incrementing X starting at 0. Defaults to False.
trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as "," and ";" within keyword value strings. Defaults to False.
time_meas_pattern (Selector[str | None]) – A pattern to match the $PnN of the time measurement. If "NoTime", do not try to find a time measurement. Defaults to "^(TIME|Time)$".
allow_missing_time (TriFlag) – Choose what to do when time measurement is be missing. If "false", raise RelationalError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
force_linear_scale (ForceLinearScale) – Force $PnE to be linear for certain measurements. Affected measurements will never fail. Defaults to "none".
ignore_optical_only_keys (list[OpticalOnlyKey]) – Ignore optical keys in temporal measurement. These keys are $PnG which is explicitly forbidden by the standard but allowed in this library to be set to 1.0 (noop), or others which are nonsensical for time measurements but are not explicitly forbidden in the the standard (such as $PnL). Provided keys are the string after the "Pn" in the "PnX" keywords. Defaults to [].
process_optical_only_keys (ProcessOpticalOnlyKeys) – Choose how to handle optical keys found in temporal measurements. Does nothing unless keys are specified in ignore_optical_only_keys. Defaults to "demote_warn".
date_pattern (Selector[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 (Selector[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.
datetime_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $BEGINDATETIME and $ENDDATETIME. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed as ISO timestamps with optional timezone. Defaults to None.
last_modified_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $LAST_MODIFIED. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed according to the default pattern which is "%d-%b-%Y %H:%M:%S" possibly with centiseconds after. Defaults to None.
allow_other_feature (bool) – If True, allow $PnFEATURE to be a value other than "Area", "Width", or "Height". Defaults to False.
process_pseudostandard (ProcessKeywordFailure) – Process non-standard keywords with a leading "$". The presence of such keywords often means the version in HEADER is incorrect. Defaults to "error".
process_hyper_par (ProcessKeywordFailure) – Process measurement keywords whose index is greater than $PAR. Defaults to "error".
process_other_version (ProcessKeywordFailure) – Process standard keywords from different FCS versions. Defaults to "error".
process_extra_timestep (ProcessKeywordFailure) – Process $TIMESTEP to be present which may indicate a time measurement is present but not identified. Defaults to "error".
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.
add_missing_timestep (Timestep | None) – Set $TIMESTEP if it is not present and required. This will do nothing on FCS2.0 files since this version does not specify $TIMESTEP. Defaults to None.
ignore_standard_keys (AppendableSelector[KeyPatterns]) – Remove standard keys from TEXT. The leading "$" is implied so do not include it. Defaults to [].
promote_to_standard (AppendableSelector[KeyPatterns]) – Promote nonstandard keys to standard keys in TEXT. Defaults to [].
demote_from_standard (AppendableSelector[KeyPatterns]) – Demote nonstandard keys from standard keys in TEXT. Defaults to [].
rename_standard_keys (AppendableSelector[KeyStringPairs]) – Rename standard keys in TEXT. Keys matching the first part of the pair will be replaced by the second. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
replace_standard_key_values (AppendableSelector[KeyStringValues]) – Replace values for standard keys in TEXT. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
append_standard_keywords (AppendableSelector[KeyStringValues]) – Append standard key/value pairs to TEXT. All keys and values will be included as they appear here. The leading "$" is implied so do not include it. Defaults to {}.
substitute_standard_key_values (AppendableSelector[SubPatterns]) – Apply sed-like substitution operation on matching standard keys. The leading "$" is implied when matching keys. Defaults to {}.
allow_repair_non_unique (TriFlag) – Choose how to handle key collisions when repairing keywords. Non-unique keywords will not be kept in the final FCS file since each list of standard and non-standard keywords must be unique. If "false", raise ConfigError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
text_data_correction (OffsetCorrection) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).
text_analysis_correction (OffsetCorrection) – 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 (AllowHeaderTextOffsetMismatch) – Choose what to do if HEADER and TEXT offsets are different. Exception will be FileLayoutError if emitted. Defaults to "error".
allow_missing_required_offsets (TriFlag) – Choose what happens when required DATA and ANALYSIS offsets in TEXT are be missing. If missing, fall back to offsets from HEADER. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
process_optional_failure (ProcessKeywordFailure) – Process optional keys which cause an error. Defaults to "error".
int_width_override (IntWidthOverride) – Override $PnB. Only affects integer layouts in FCS 2.0/3.0. Defaults to "never".
byteord_override (ByteordOverride) – Override $BYTEORD. Only affects integer layouts in FCS 2.0/3.0. Defaults to "none".
disallow_range_truncation (TriFlag) – Choose how to handle $PnR values that need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. If "false", throw warning. If "true", raise RelationalError. If "silent", do nothing. Defaults to "false".
data_remainder_limit (int) – Limit by which ending DATA offset can be truncated if its length modulo event width produces a remainder. Defaults to 0.
allow_uneven_event_width (TriFlag) – Choose what to do when event width does not perfectly divide length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
allow_tot_mismatch (TriFlag) – Choose what happens when $TOT does not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".
allow_missing_crc (TriFlag) – Choose what to do when CRC is missing from the end of a dataset. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
allow_mismatch_crc (TriFlag) – Choose what to do when computed CRC and CRC at the end of a dataset do not match. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
compute_crc (ComputeCRC) – Choose when to compute the CRC for a dataset. Defaults to "never".
read_intra_segment_dark_bytes (bool) – If True read bytes which are between segments. Defaults to False.
read_post_dataset_dark_bytes (bool) – If True read bytes between the end of the current dataset and the next. Defaults to False.
row_buffer_size (int) – Set the size in bytes for the internal buffer used to read DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
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.
dataset_len (int | None) – The length of the dataset to be read; should correspond to $NEXTDATA or end of file (whichever is lesser) minus the starting offset of the dataset. Defaults to None.

Return type:

Raises:

ParseKeywordValueError – If any keyword values could not be read from their string encoding
RelationalError – If keywords are incompatible with indicated data schema for 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 not dropped by some other option

insert_optical(index, name, meas, range, col, scale=1.0)#

Insert optical measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_0) – The measurement to insert.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, col)#

Insert temporal measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_0) – The measurement to insert.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)#

Return measurement at index.

Parameters:: index (MeasIndex) – Index to retrieve.
Return type:: Optical3_0 | Temporal3_0
Raises:: IndexError – If index not found

measurement_named(name)#

Return measurement with name.

Parameters:

name (Shortname) – 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, col, scale=1.0)#

Push optical measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_0) – The measurement to push.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, col)#

Push temporal measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_0) – The measurement to push.
range (Range) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)#

Remove a measurement with a given index.

Parameters:: index (MeasIndex) – Index to remove.
Returns:: Index, measurement object, data, and range.
Return type:: tuple[Shortname | None, Optical3_0 | Temporal3_0, Series, Range, OpticalScale3_0 | None]
Raises:: IndexError – If index not found

remove_measurement_by_name(name)#

Remove a measurement with a given name.

Parameters:

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

Returns:

Name, measurement object, data, and range.

Return type:

tuple[MeasIndex, Optical3_0 | Temporal3_0, Series, Range, OpticalScale3_0 | None]

Raises:

ParseKeywordValueError – if name is "" or contains commas
IndexError – If name not found

rename_temporal(name)#

Rename temporal measurement if present.

Parameters:

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

Returns:

Previous name if present.

Return type:

Shortname | None

Raises:

ParseKeywordValueError – if name is "" or contains commas
RelationalError – if name is already present

replace_optical_at(index, meas)#

Replace measurement at index with given optical measurement.

Parameters:

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

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_0]

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)#

Replace named measurement with given optical measurement.

Parameters:

name (Shortname) – Name to replace. Corresponds to $PnN.
meas (Optical3_0) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_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 (MeasIndex) – Index to replace.
meas (Temporal3_0) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_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 (Shortname) – Name to replace. Corresponds to $PnN.
meas (Temporal3_0) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_0 | tuple[Temporal3_0, OpticalScale3_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 (DataFrame) – The new data.

set_measurements_and_data_schema(measurements, data_schema)#

Set all measurements and data schema at once.

Length of measurements must match number of columns in data_schema 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.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.

set_measurements_data_schema_and_data(measurements, data_schema, data)#

Set measurements, data schema, and data at once.

Length of measurements and data_schema 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_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.
data (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 data schema and dataframe.

Parameters:

measurements (Measurements3_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.

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 (Measurements3_0) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data (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.

set_named_measurements_and_data_schema(measurements, data_schema, allow_shared_names=False, skip_index_check=False)#

Set all measurements, names, and data schema at once.

Length of measurements must match number of columns in data_schema and both must match number of columns in existing dataframe.

Parameters:

measurements (Measurements3_0) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | OrderedUintDataSchema | OrderedF32DataSchema | OrderedF64DataSchema) – The new data schema.
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.

set_temporal(name, timestep, allow_loss='false')#

Set the temporal measurement to a given name.

Parameters:

name (Shortname) – Name to set to temporal. Corresponds to $PnN.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

Raises:

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 (MeasIndex) – Index to set.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

set_timestep(timestep)#

Set the $TIMESTEP if time measurement is present.

Parameters:: timestep (Timestep) – The timestep to set. Must be greater than zero.
Returns:: Previous $TIMESTEP if present.
Return type:: Timestep | None

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal3_0] | None

timestep#

The value of $TIMESTEP (read-only).

Return type:: Timestep | None

to_version_2_0(allow_loss='false')#

Convert to FCS 2.0.

Parameters:

Returns:

A new class conforming to FCS 2.0.

Return type:

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:

Returns:

A new class conforming to FCS 3.1.

Return type:

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:

Returns:

A new class conforming to FCS 3.2.

Return type:

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_data()#

Remove all measurements and their data.

This is equivalent to deleting all $Pn* keywords, setting $PAR to 0, and setting DATA to an empty dataframe. Keywords which reference any $PnN must not be set.

unset_temporal()#

Convert the temporal measurement to an optical measurement.

Returns:: Value of $TIMESTEP if time measurement was present.
Return type:: Timestep | None

version#

Show the FCS version (read-only).

Return type:: FCSVersion

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as present in 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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
allow_over_bitmask (TriFlag) – Choose how to report integer event values in DATA which exceed bitmask. If "false", raise EventDataError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
disallow_over_range (TriFlag) – Choose how to report event values in DATA which exceed $PnR. If "false", throw warning. If "true", raise EventDataError. If "silent", do nothing. Defaults to "false".
row_buffer_size (int) – Set the size in bytes for the internal buffer used to write DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append 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:

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

tuple[CoreDataset3_1, NewStdDatasetFromKwsOutput]

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreDataset3_1(measurements, data_schema, 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='', others=[])#

Represents one dataset in an FCS 3.1 file.

Parameters:

measurements (Measurements3_1) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema) – (read-write) Schema to describe data encoding. Represents $PnB, $PnR, $BYTEORD, and $DATATYPE.
data (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 schema but mismatches may result in truncation.
mode (Mode) – (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 (Spillover | None) – (read-write) Value of $SPILLOVER. Each measurement name must correspond to a $PnN. 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 (Originality | 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 (CsvFlags) – (read-write) Subset flags (combined values of $CSVnFLAG and $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 (Trigger | None) – (read-write) Value of $TR. The measurement name which must match a $PnN. Defaults to None.
applied_gates (AppliedGates3_0) – (read-write) Value for $Gm*/$Rn*/$GATING/$GATE keywords. Defaults to ([], {}, None).
nonstandard_keywords (NonStdKeywords) – (read-write) Pairs of non-standard keyword values. Keys must not start with "$". Defaults to {}.
analysis (AnalysisBytes) – (read-write) Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – (read-write) A list of (byte) strings encoding the OTHER segments. Defaults to [].

Raises:

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

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[Calibration3_1 | 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[Display | 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_peak_bins#

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

Return type:: list[int | None]

all_peak_sizes#

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 and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

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[OpticalScale3_0]

all_shortnames#

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

Strings are unique and cannot contain commas.

Return type:: list[Shortname]

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[()]]

check_ranges(over_bitmask_action='trunc_warn', over_range_action='warn')#

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".

Returns:

The columns that were overrange. List indices correspond to columns. None is returned is not truncated. Index of first overrange row is returned.

Return type:

list[int | None]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout data_schema

classmethod from_kws(path, header, std, nonstd, allow_pseudoempty=False, dataset_overflow_limit=0, overlap_correction_limit=0, dedup_measurement_names=False, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time='false', force_linear_scale='none', ignore_optical_only_keys=[], process_optical_only_keys='demote_warn', date_pattern=None, time_pattern=None, datetime_pattern=None, last_modified_pattern=None, allow_other_feature=False, process_pseudostandard='error', process_hyper_par='error', process_other_version='error', process_extra_timestep='error', fix_log_scale_offsets=False, add_missing_timestep=None, spillover_measurement_mode='named', ignore_standard_keys=[], promote_to_standard=[], demote_from_standard=[], rename_standard_keys={}, replace_standard_key_values={}, append_standard_keywords={}, substitute_standard_key_values={}, allow_repair_non_unique='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='error', allow_missing_required_offsets='false', process_optional_failure='error', disallow_range_truncation='false', data_remainder_limit=0, allow_uneven_event_width='false', allow_tot_mismatch='false', over_bitmask_action='trunc_warn', over_range_action='warn', allow_missing_crc='false', allow_mismatch_crc='false', compute_crc='never', read_intra_segment_dark_bytes=False, read_post_dataset_dark_bytes=False, row_buffer_size=28000, warnings_are_errors=False, hide_warnings=False, dataset_offset=0, dataset_len=None)#

Make new instance from keywords.

Parameters:

path (Path) – Path to be read.
header (HeaderAndSuppOffsets) – The HEADER and supplemental TEXT offsets from parsed file
std (StdKeywords) – Standard keywords.
nonstd (NonStdKeywords) – Non-Standard keywords.
allow_pseudoempty (bool) – If True, allow offsets like X,X-1. Some files will denote an “empty” offset as 0,-1 or 1000,999, which is logically correct since the last offset points to the last byte, thus 0,0 is actually 1 byte long. If this flat is set, such offsets will be treated as if they were 0,0. Defaults to False.
dataset_overflow_limit (int) – Limit by which offsets can be truncated if they exceed end of file or $NEXTDATA. Defaults to 0.
overlap_correction_limit (int) – Limit by which ending segment offset can be truncated if they overlap another offset. Defaults to 0.
dedup_measurement_names (bool) – If True, force all $PnN to be unique by appending "~X" to each duplicate and incrementing X starting at 0. Defaults to False.
trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as "," and ";" within keyword value strings. Defaults to False.
time_meas_pattern (Selector[str | None]) – A pattern to match the $PnN of the time measurement. If "NoTime", do not try to find a time measurement. Defaults to "^(TIME|Time)$".
allow_missing_time (TriFlag) – Choose what to do when time measurement is be missing. If "false", raise RelationalError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
force_linear_scale (ForceLinearScale) – Force $PnE to be linear for certain measurements. Affected measurements will never fail. Defaults to "none".
ignore_optical_only_keys (list[OpticalOnlyKey]) – Ignore optical keys in temporal measurement. These keys are $PnG which is explicitly forbidden by the standard but allowed in this library to be set to 1.0 (noop), or others which are nonsensical for time measurements but are not explicitly forbidden in the the standard (such as $PnL). Provided keys are the string after the "Pn" in the "PnX" keywords. Defaults to [].
process_optical_only_keys (ProcessOpticalOnlyKeys) – Choose how to handle optical keys found in temporal measurements. Does nothing unless keys are specified in ignore_optical_only_keys. Defaults to "demote_warn".
date_pattern (Selector[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 (Selector[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.
datetime_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $BEGINDATETIME and $ENDDATETIME. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed as ISO timestamps with optional timezone. Defaults to None.
last_modified_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $LAST_MODIFIED. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed according to the default pattern which is "%d-%b-%Y %H:%M:%S" possibly with centiseconds after. Defaults to None.
allow_other_feature (bool) – If True, allow $PnFEATURE to be a value other than "Area", "Width", or "Height". Defaults to False.
process_pseudostandard (ProcessKeywordFailure) – Process non-standard keywords with a leading "$". The presence of such keywords often means the version in HEADER is incorrect. Defaults to "error".
process_hyper_par (ProcessKeywordFailure) – Process measurement keywords whose index is greater than $PAR. Defaults to "error".
process_other_version (ProcessKeywordFailure) – Process standard keywords from different FCS versions. Defaults to "error".
process_extra_timestep (ProcessKeywordFailure) – Process $TIMESTEP to be present which may indicate a time measurement is present but not identified. Defaults to "error".
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.
add_missing_timestep (Timestep | None) – Set $TIMESTEP if it is not present and required. This will do nothing on FCS2.0 files since this version does not specify $TIMESTEP. Defaults to None.
spillover_measurement_mode (SpilloverMeasurementMode) – Choose how to interpret measurement strings in $SPILLOVER. Defaults to "named".
ignore_standard_keys (AppendableSelector[KeyPatterns]) – Remove standard keys from TEXT. The leading "$" is implied so do not include it. Defaults to [].
promote_to_standard (AppendableSelector[KeyPatterns]) – Promote nonstandard keys to standard keys in TEXT. Defaults to [].
demote_from_standard (AppendableSelector[KeyPatterns]) – Demote nonstandard keys from standard keys in TEXT. Defaults to [].
rename_standard_keys (AppendableSelector[KeyStringPairs]) – Rename standard keys in TEXT. Keys matching the first part of the pair will be replaced by the second. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
replace_standard_key_values (AppendableSelector[KeyStringValues]) – Replace values for standard keys in TEXT. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
append_standard_keywords (AppendableSelector[KeyStringValues]) – Append standard key/value pairs to TEXT. All keys and values will be included as they appear here. The leading "$" is implied so do not include it. Defaults to {}.
substitute_standard_key_values (AppendableSelector[SubPatterns]) – Apply sed-like substitution operation on matching standard keys. The leading "$" is implied when matching keys. Defaults to {}.
allow_repair_non_unique (TriFlag) – Choose how to handle key collisions when repairing keywords. Non-unique keywords will not be kept in the final FCS file since each list of standard and non-standard keywords must be unique. If "false", raise ConfigError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
text_data_correction (OffsetCorrection) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).
text_analysis_correction (OffsetCorrection) – 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 (AllowHeaderTextOffsetMismatch) – Choose what to do if HEADER and TEXT offsets are different. Exception will be FileLayoutError if emitted. Defaults to "error".
allow_missing_required_offsets (TriFlag) – Choose what happens when required DATA and ANALYSIS offsets in TEXT are be missing. If missing, fall back to offsets from HEADER. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
process_optional_failure (ProcessKeywordFailure) – Process optional keys which cause an error. Defaults to "error".
disallow_range_truncation (TriFlag) – Choose how to handle $PnR values that need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. If "false", throw warning. If "true", raise RelationalError. If "silent", do nothing. Defaults to "false".
data_remainder_limit (int) – Limit by which ending DATA offset can be truncated if its length modulo event width produces a remainder. Defaults to 0.
allow_uneven_event_width (TriFlag) – Choose what to do when event width does not perfectly divide length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
allow_tot_mismatch (TriFlag) – Choose what happens when $TOT does not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".
allow_missing_crc (TriFlag) – Choose what to do when CRC is missing from the end of a dataset. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
allow_mismatch_crc (TriFlag) – Choose what to do when computed CRC and CRC at the end of a dataset do not match. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
compute_crc (ComputeCRC) – Choose when to compute the CRC for a dataset. Defaults to "never".
read_intra_segment_dark_bytes (bool) – If True read bytes which are between segments. Defaults to False.
read_post_dataset_dark_bytes (bool) – If True read bytes between the end of the current dataset and the next. Defaults to False.
row_buffer_size (int) – Set the size in bytes for the internal buffer used to read DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
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.
dataset_len (int | None) – The length of the dataset to be read; should correspond to $NEXTDATA or end of file (whichever is lesser) minus the starting offset of the dataset. Defaults to None.

Return type:

Raises:

ParseKeywordValueError – If any keyword values could not be read from their string encoding
RelationalError – If keywords are incompatible with indicated data schema for 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 not dropped by some other option

insert_optical(index, name, meas, range, col, scale=1.0)#

Insert optical measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_1) – The measurement to insert.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, col)#

Insert temporal measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_1) – The measurement to insert.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)#

Return measurement at index.

Parameters:: index (MeasIndex) – Index to retrieve.
Return type:: Optical3_1 | Temporal3_1
Raises:: IndexError – If index not found

measurement_named(name)#

Return measurement with name.

Parameters:

name (Shortname) – 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, col, scale=1.0)#

Push optical measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_1) – The measurement to push.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, col)#

Push temporal measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_1) – The measurement to push.
range (MaybeTypedVariableBitmask) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)#

Remove a measurement with a given index.

Parameters:: index (MeasIndex) – Index to remove.
Returns:: Index, measurement object, data, and range.
Return type:: tuple[Shortname, Optical3_1 | Temporal3_1, Series, Range, OpticalScale3_0 | None, ByteWidth | None]
Raises:: IndexError – If index not found

remove_measurement_by_name(name)#

Remove a measurement with a given name.

Parameters:

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

Returns:

Name, measurement object, data, and range.

Return type:

tuple[MeasIndex, Optical3_1 | Temporal3_1, Series, Range, OpticalScale3_0 | None, ByteWidth | None]

Raises:

ParseKeywordValueError – if name is "" or contains commas
IndexError – If name not found

rename_temporal(name)#

Rename temporal measurement if present.

Parameters:

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

Returns:

Previous name if present.

Return type:

Shortname | None

Raises:

ParseKeywordValueError – if name is "" or contains commas
RelationalError – if name is already present

replace_optical_at(index, meas)#

Replace measurement at index with given optical measurement.

Parameters:

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

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_0]

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)#

Replace named measurement with given optical measurement.

Parameters:

name (Shortname) – Name to replace. Corresponds to $PnN.
meas (Optical3_1) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_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 (MeasIndex) – Index to replace.
meas (Temporal3_1) – Temporal measurement to replace measurement at index.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_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 (Shortname) – Name to replace. Corresponds to $PnN.
meas (Temporal3_1) – Temporal measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_1 | tuple[Temporal3_1, OpticalScale3_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_1 | Temporal3_1]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.
data (DataFrame) – The new data.

set_measurements_and_data_schema(measurements, data_schema)#

Set all measurements and data schema at once.

Length of measurements must match number of columns in data_schema 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.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema) – The new data schema.

set_measurements_data_schema_and_data(measurements, data_schema, data)#

Set measurements, data schema, and data at once.

Length of measurements and data_schema 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_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema) – The new data schema.
data (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 data schema and dataframe.

Parameters:

measurements (Measurements3_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.

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 (Measurements3_1) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data (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.

set_named_measurements_and_data_schema(measurements, data_schema, allow_shared_names=False, skip_index_check=False)#

Set all measurements, names, and data schema at once.

Length of measurements must match number of columns in data_schema and both must match number of columns in existing dataframe.

Parameters:

measurements (Measurements3_1) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema) – The new data schema.
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.

set_temporal(name, timestep, allow_loss='false')#

Set the temporal measurement to a given name.

Parameters:

name (Shortname) – Name to set to temporal. Corresponds to $PnN.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

Raises:

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 (MeasIndex) – Index to set.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

set_timestep(timestep)#

Set the $TIMESTEP if time measurement is present.

Parameters:: timestep (Timestep) – The timestep to set. Must be greater than zero.
Returns:: Previous $TIMESTEP if present.
Return type:: Timestep | None

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal3_1] | None

timestep#

The value of $TIMESTEP (read-only).

Return type:: Timestep | None

to_version_2_0(allow_loss='false')#

Convert to FCS 2.0.

Parameters:

Returns:

A new class conforming to FCS 2.0.

Return type:

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:

Returns:

A new class conforming to FCS 3.0.

Return type:

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:

Returns:

A new class conforming to FCS 3.2.

Return type:

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_data()#

Remove all measurements and their data.

This is equivalent to deleting all $Pn* keywords, setting $PAR to 0, and setting DATA to an empty dataframe. Keywords which reference any $PnN must not be set.

unset_temporal()#

Convert the temporal measurement to an optical measurement.

Returns:: Value of $TIMESTEP if time measurement was present.
Return type:: Timestep | None

version#

Show the FCS version (read-only).

Return type:: FCSVersion

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as present in 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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
allow_over_bitmask (TriFlag) – Choose how to report integer event values in DATA which exceed bitmask. If "false", raise EventDataError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
disallow_over_range (TriFlag) – Choose how to report event values in DATA which exceed $PnR. If "false", throw warning. If "true", raise EventDataError. If "silent", do nothing. Defaults to "false".
row_buffer_size (int) – Set the size in bytes for the internal buffer used to write DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append 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:

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type:

tuple[CoreDataset3_2, NewStdDatasetFromKwsOutput]

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

class pyreflow.CoreDataset3_2(measurements, data_schema, 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='', others=[])#

Represents one dataset in an FCS 3.2 file.

Parameters:

measurements (Measurements3_2) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.

Variables:

data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema | MixedDataSchema) – (read-write) Schema to describe data encoding. Represents $PnB, $PnR, $BYTEORD, $DATATYPE, and $PnDATATYPE
data (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 schema but mismatches may result in truncation.
cyt (str) – (read-write) Value of $CYT.
mode (Mode3_2 | 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 (Spillover | None) – (read-write) Value of $SPILLOVER. Each measurement name must correspond to a $PnN. 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 (Originality | 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 (UnstainedCenters) – (read-write) Value of $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 (Trigger | None) – (read-write) Value of $TR. The measurement name which must match a $PnN. Defaults to None.
applied_gates (AppliedGates3_2) – (read-write) Value for $Rn*/$GATING keywords. Defaults to ({}, None).
nonstandard_keywords (NonStdKeywords) – (read-write) Pairs of non-standard keyword values. Keys must not start with "$". Defaults to {}.
analysis (AnalysisBytes) – (read-write) Contents of the ANALYSIS segment. Defaults to "".
others (list[OtherBytes]) – (read-write) A list of (byte) strings encoding the OTHER segments. Defaults to [].

Raises:

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

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_awh_features#

Value of $PnFEATURE (area/width/height) for all measurements.

This should be the preferred way to get and set this keyword if one knows that only "Area", "Width", and "Height" will be used for this dataset since it has a well-defined type.

() will be returned for the time measurement.

This attribute is read-write.

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

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[Calibration3_2 | 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[Display | 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[str | 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_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_other_features#

Value of $PnFEATURE (not area/width/height) for all measurements.

Values which are not "Area", "Width", and "Height" will be returned as None.

() will be returned for the time measurement.

This attribute is read-only.

Return type:: list[str | tuple[()] | 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 and/or $PnG for all measurements (read-write).

Collectively these keywords correspond to scale transforms.

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[OpticalScale3_0]

all_shortnames#

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

Strings are unique and cannot contain commas.

Return type:: list[Shortname]

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[()]]

check_ranges(over_bitmask_action='trunc_warn', over_range_action='warn')#

Coerce all values in DATA to fit within types specified in layout.

This will always create a new copy of DATA in-place.

Parameters:

over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".

Returns:

The columns that were overrange. List indices correspond to columns. None is returned is not truncated. Index of first overrange row is returned.

Return type:

list[int | None]

Raises:

DataLossError – If any values in DATA segment need to be truncated to fit layout data_schema

classmethod from_kws(path, header, std, nonstd, allow_pseudoempty=False, dataset_overflow_limit=0, overlap_correction_limit=0, dedup_measurement_names=False, trim_intra_value_whitespace=False, time_meas_pattern='^(TIME|Time)$', allow_missing_time='false', force_linear_scale='none', ignore_optical_only_keys=[], process_optical_only_keys='demote_warn', date_pattern=None, time_pattern=None, datetime_pattern=None, last_modified_pattern=None, allow_other_feature=False, process_pseudostandard='error', process_hyper_par='error', process_other_version='error', process_extra_timestep='error', fix_log_scale_offsets=False, add_missing_timestep=None, spillover_measurement_mode='named', disallow_localtime=False, ignore_standard_keys=[], promote_to_standard=[], demote_from_standard=[], rename_standard_keys={}, replace_standard_key_values={}, append_standard_keywords={}, substitute_standard_key_values={}, allow_repair_non_unique='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='error', allow_missing_required_offsets='false', process_optional_failure='error', disallow_range_truncation='false', data_remainder_limit=0, allow_uneven_event_width='false', allow_tot_mismatch='false', over_bitmask_action='trunc_warn', over_range_action='warn', allow_missing_crc='false', allow_mismatch_crc='false', compute_crc='never', read_intra_segment_dark_bytes=False, read_post_dataset_dark_bytes=False, row_buffer_size=28000, warnings_are_errors=False, hide_warnings=False, dataset_offset=0, dataset_len=None)#

Make new instance from keywords.

Parameters:

path (Path) – Path to be read.
header (HeaderAndSuppOffsets) – The HEADER and supplemental TEXT offsets from parsed file
std (StdKeywords) – Standard keywords.
nonstd (NonStdKeywords) – Non-Standard keywords.
allow_pseudoempty (bool) – If True, allow offsets like X,X-1. Some files will denote an “empty” offset as 0,-1 or 1000,999, which is logically correct since the last offset points to the last byte, thus 0,0 is actually 1 byte long. If this flat is set, such offsets will be treated as if they were 0,0. Defaults to False.
dataset_overflow_limit (int) – Limit by which offsets can be truncated if they exceed end of file or $NEXTDATA. Defaults to 0.
overlap_correction_limit (int) – Limit by which ending segment offset can be truncated if they overlap another offset. Defaults to 0.
dedup_measurement_names (bool) – If True, force all $PnN to be unique by appending "~X" to each duplicate and incrementing X starting at 0. Defaults to False.
trim_intra_value_whitespace (bool) – If True, trim whitespace between delimiters such as "," and ";" within keyword value strings. Defaults to False.
time_meas_pattern (Selector[str | None]) – A pattern to match the $PnN of the time measurement. If "NoTime", do not try to find a time measurement. Defaults to "^(TIME|Time)$".
allow_missing_time (TriFlag) – Choose what to do when time measurement is be missing. If "false", raise RelationalError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
force_linear_scale (ForceLinearScale) – Force $PnE to be linear for certain measurements. Affected measurements will never fail. Defaults to "none".
ignore_optical_only_keys (list[OpticalOnlyKey]) – Ignore optical keys in temporal measurement. These keys are $PnG which is explicitly forbidden by the standard but allowed in this library to be set to 1.0 (noop), or others which are nonsensical for time measurements but are not explicitly forbidden in the the standard (such as $PnL). Provided keys are the string after the "Pn" in the "PnX" keywords. Defaults to [].
process_optical_only_keys (ProcessOpticalOnlyKeys) – Choose how to handle optical keys found in temporal measurements. Does nothing unless keys are specified in ignore_optical_only_keys. Defaults to "demote_warn".
date_pattern (Selector[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 (Selector[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.
datetime_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $BEGINDATETIME and $ENDDATETIME. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed as ISO timestamps with optional timezone. Defaults to None.
last_modified_pattern (Selector[str | None]) – If supplied, will be used as an alternative pattern when parsing $LAST_MODIFIED. The pattern must follow the format outlined in chrono. If not supplied, these will be parsed according to the default pattern which is "%d-%b-%Y %H:%M:%S" possibly with centiseconds after. Defaults to None.
allow_other_feature (bool) – If True, allow $PnFEATURE to be a value other than "Area", "Width", or "Height". Defaults to False.
process_pseudostandard (ProcessKeywordFailure) – Process non-standard keywords with a leading "$". The presence of such keywords often means the version in HEADER is incorrect. Defaults to "error".
process_hyper_par (ProcessKeywordFailure) – Process measurement keywords whose index is greater than $PAR. Defaults to "error".
process_other_version (ProcessKeywordFailure) – Process standard keywords from different FCS versions. Defaults to "error".
process_extra_timestep (ProcessKeywordFailure) – Process $TIMESTEP to be present which may indicate a time measurement is present but not identified. Defaults to "error".
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.
add_missing_timestep (Timestep | None) – Set $TIMESTEP if it is not present and required. This will do nothing on FCS2.0 files since this version does not specify $TIMESTEP. Defaults to None.
spillover_measurement_mode (SpilloverMeasurementMode) – Choose how to interpret measurement strings in $SPILLOVER. Defaults to "named".
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.
ignore_standard_keys (AppendableSelector[KeyPatterns]) – Remove standard keys from TEXT. The leading "$" is implied so do not include it. Defaults to [].
promote_to_standard (AppendableSelector[KeyPatterns]) – Promote nonstandard keys to standard keys in TEXT. Defaults to [].
demote_from_standard (AppendableSelector[KeyPatterns]) – Demote nonstandard keys from standard keys in TEXT. Defaults to [].
rename_standard_keys (AppendableSelector[KeyStringPairs]) – Rename standard keys in TEXT. Keys matching the first part of the pair will be replaced by the second. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
replace_standard_key_values (AppendableSelector[KeyStringValues]) – Replace values for standard keys in TEXT. Comparisons are case insensitive. The leading "$" is implied so do not include it. Defaults to {}.
append_standard_keywords (AppendableSelector[KeyStringValues]) – Append standard key/value pairs to TEXT. All keys and values will be included as they appear here. The leading "$" is implied so do not include it. Defaults to {}.
substitute_standard_key_values (AppendableSelector[SubPatterns]) – Apply sed-like substitution operation on matching standard keys. The leading "$" is implied when matching keys. Defaults to {}.
allow_repair_non_unique (TriFlag) – Choose how to handle key collisions when repairing keywords. Non-unique keywords will not be kept in the final FCS file since each list of standard and non-standard keywords must be unique. If "false", raise ConfigError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
text_data_correction (OffsetCorrection) – Corrections for DATA offsets in TEXT. Defaults to (0, 0).
text_analysis_correction (OffsetCorrection) – 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 (AllowHeaderTextOffsetMismatch) – Choose what to do if HEADER and TEXT offsets are different. Exception will be FileLayoutError if emitted. Defaults to "error".
allow_missing_required_offsets (TriFlag) – Choose what happens when required DATA offsets in TEXT are be missing. If missing, fall back to offsets from HEADER. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
process_optional_failure (ProcessKeywordFailure) – Process optional keys which cause an error. Defaults to "error".
disallow_range_truncation (TriFlag) – Choose how to handle $PnR values that need to be truncated to match the number of bytes specified by $PnB and $DATATYPE. If "false", throw warning. If "true", raise RelationalError. If "silent", do nothing. Defaults to "false".
data_remainder_limit (int) – Limit by which ending DATA offset can be truncated if its length modulo event width produces a remainder. Defaults to 0.
allow_uneven_event_width (TriFlag) – Choose what to do when event width does not perfectly divide length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
allow_tot_mismatch (TriFlag) – Choose what happens when $TOT does not match number of events as computed by the event width and length of DATA. Does not apply to delimited ASCII data schema. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
over_bitmask_action (OverLimitAction) – Choose what to do with event integer values in DATA which exceed bitmask. Defaults to "trunc_warn".
over_range_action (OverLimitAction) – Choose what to do with event values in DATA which exceed $PnR. Defaults to "warn".
allow_missing_crc (TriFlag) – Choose what to do when CRC is missing from the end of a dataset. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
allow_mismatch_crc (TriFlag) – Choose what to do when computed CRC and CRC at the end of a dataset do not match. If "false", raise FileLayoutError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
compute_crc (ComputeCRC) – Choose when to compute the CRC for a dataset. Defaults to "never".
read_intra_segment_dark_bytes (bool) – If True read bytes which are between segments. Defaults to False.
read_post_dataset_dark_bytes (bool) – If True read bytes between the end of the current dataset and the next. Defaults to False.
row_buffer_size (int) – Set the size in bytes for the internal buffer used to read DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
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.
dataset_len (int | None) – The length of the dataset to be read; should correspond to $NEXTDATA or end of file (whichever is lesser) minus the starting offset of the dataset. Defaults to None.

Return type:

Raises:

ParseKeywordValueError – If any keyword values could not be read from their string encoding
RelationalError – If keywords are incompatible with indicated data schema for 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 not dropped by some other option

insert_optical(index, name, meas, range, col, scale=1.0)#

Insert optical measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_2) – The measurement to insert.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

insert_temporal(index, name, meas, range, col)#

Insert temporal measurement at position in measurement vector.

Parameters:

index (MeasIndex) – Position at which to insert new measurement.
name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_2) – The measurement to insert.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

measurement_at(index)#

Return measurement at index.

Parameters:: index (MeasIndex) – Index to retrieve.
Return type:: Optical3_2 | Temporal3_2
Raises:: IndexError – If index not found

measurement_named(name)#

Return measurement with name.

Parameters:

name (Shortname) – 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, col, scale=1.0)#

Push optical measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Optical3_2) – The measurement to push.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.
scale (OpticalScale3_0) – The scale to insert. Must be compatible with the datatype of the column to be inserted. Defaults to 1.0.

Raises:

InvalidKeywordValueError – if scale has log scale floats which are not both positive
ParseKeywordValueError – if name is "" or contains commas

push_temporal(name, meas, range, col)#

Push temporal measurement to end of measurement vector.

Parameters:

name (Shortname) – Name of new measurement. Corresponds to $PnN.
meas (Temporal3_2) – The measurement to push.
range (MaybeTypedMixedRange) – Range of measurement. Corresponds to $PnR.
col (Series) – Data for measurement. Must be same length as existing columns.

Raises:

ParseKeywordValueError – if name is "" or contains commas

remove_measurement_by_index(index)#

Remove a measurement with a given index.

Parameters:: index (MeasIndex) – Index to remove.
Returns:: Index, measurement object, data, and range.
Return type:: tuple[Shortname, Optical3_2 | Temporal3_2, Series, Range, OpticalScale3_0 | None, AnyType | None]
Raises:: IndexError – If index not found

remove_measurement_by_name(name)#

Remove a measurement with a given name.

Parameters:

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

Returns:

Name, measurement object, data, and range.

Return type:

tuple[MeasIndex, Optical3_2 | Temporal3_2, Series, Range, OpticalScale3_0 | None, AnyType | None]

Raises:

ParseKeywordValueError – if name is "" or contains commas
IndexError – If name not found

rename_temporal(name)#

Rename temporal measurement if present.

Parameters:

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

Returns:

Previous name if present.

Return type:

Shortname | None

Raises:

ParseKeywordValueError – if name is "" or contains commas
RelationalError – if name is already present

replace_optical_at(index, meas)#

Replace measurement at index with given optical measurement.

Parameters:

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

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_0]

Raises:

IndexError – If index does not exist.

replace_optical_named(name, meas)#

Replace named measurement with given optical measurement.

Parameters:

name (Shortname) – Name to replace. Corresponds to $PnN.
meas (Optical3_2) – Optical measurement to replace measurement at name.

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_0]

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 (MeasIndex) – Index to replace.
meas (Temporal3_2) – Temporal measurement to replace measurement at index.
allow_loss (TriFlag) – Choose what happens if conversion from temporal measurement to optical measurement is necessary and data loss will occur. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. Defaults to "false".

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_0]

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 (Shortname) – Name to replace. Corresponds to $PnN.
meas (Temporal3_2) – Temporal measurement to replace measurement at name.
allow_loss (TriFlag) – Choose what happens if conversion from temporal measurement to optical measurement is necessary and data loss will occur. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. Defaults to "false".

Returns:

Replaced measurement object.

Return type:

Optical3_2 | tuple[Temporal3_2, OpticalScale3_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_2 | Temporal3_2]) – Measurements corresponding to columns in FCS file. Temporal must be given zero or one times.
data (DataFrame) – The new data.

set_measurements_and_data_schema(measurements, data_schema)#

Set all measurements and data schema at once.

Length of measurements must match number of columns in data_schema 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.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema | MixedDataSchema) – The new data schema.

set_measurements_data_schema_and_data(measurements, data_schema, data)#

Set measurements, data schema, and data at once.

Length of measurements and data_schema 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_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema | MixedDataSchema) – The new data schema.
data (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 data schema and dataframe.

Parameters:

measurements (Measurements3_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.

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 (Measurements3_2) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data (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.

set_named_measurements_and_data_schema(measurements, data_schema, allow_shared_names=False, skip_index_check=False)#

Set all measurements, names, and data schema at once.

Length of measurements must match number of columns in data_schema and both must match number of columns in existing dataframe.

Parameters:

measurements (Measurements3_2) – The new measurements. The first member of the tuple corresponds to the measurement name and the second is the measurement object.
data_schema (FixedAsciiDataSchema | DelimAsciiDataSchema | VariableUintDataSchema | SingleUintDataSchema | BigLittleF32DataSchema | BigLittleF64DataSchema | MixedDataSchema) – The new data schema.
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.

set_temporal(name, timestep, allow_loss='false')#

Set the temporal measurement to a given name.

Parameters:

name (Shortname) – Name to set to temporal. Corresponds to $PnN.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

Raises:

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 (MeasIndex) – Index to set.
timestep (Timestep) – The value of $TIMESTEP to use.
allow_loss (TriFlag) – Choose what happens if optical-specific metadata (detectors, lasers, etc) are found. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. 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:

set_timestep(timestep)#

Set the $TIMESTEP if time measurement is present.

Parameters:: timestep (Timestep) – The timestep to set. Must be greater than zero.
Returns:: Previous $TIMESTEP if present.
Return type:: Timestep | None

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 (ReqOrOpt) – Selects if required, optional, or both keywords should be returned
root_or_meas (RootOrMeas) – Selects if required, optional, or both keywords should be returned

Returns:

A list of standard keywords.

Return type:

temporal#

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

Returns:: Index, name, and measurement or None.
Return type:: tuple[MeasIndex, Shortname, Temporal3_2] | None

timestep#

The value of $TIMESTEP (read-only).

Return type:: Timestep | None

to_version_2_0(allow_loss='false')#

Convert to FCS 2.0.

Parameters:

Returns:

A new class conforming to FCS 2.0.

Return type:

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:

Returns:

A new class conforming to FCS 3.0.

Return type:

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:

Returns:

A new class conforming to FCS 3.1.

Return type:

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_data()#

Remove all measurements and their data.

This is equivalent to deleting all $Pn* keywords, setting $PAR to 0, and setting DATA to an empty dataframe. Keywords which reference any $PnN must not be set.

unset_temporal(allow_loss='false')#

Convert the temporal measurement to an optical measurement.

Parameters:: allow_loss (TriFlag) – Choose what happens if temporal measurement cannot be converted to optical without data loss. If "false", raise ConversionError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
Returns:: Value of $TIMESTEP if time measurement was present.
Return type:: Timestep | None

version#

Show the FCS version (read-only).

Return type:: FCSVersion

Write data as an FCS file.

The resulting file will include HEADER, TEXT, DATA, ANALYSIS, and OTHER as present in 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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
allow_over_bitmask (TriFlag) – Choose how to report integer event values in DATA which exceed bitmask. If "false", raise EventDataError. If "true", throw warning. If "silent", do nothing. Defaults to "false".
disallow_over_range (TriFlag) – Choose how to report event values in DATA which exceed $PnR. If "false", throw warning. If "true", raise EventDataError. If "silent", do nothing. Defaults to "false".
row_buffer_size (int) – Set the size in bytes for the internal buffer used to write DATA. This is a performance parameter that balances read syscalls (too low) and cache misses (too high). It should generally be 90% of the CPU’s L1D cache size. Defaults to 28000.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append 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:

Raises:

ConfigError – if delim is not between 1 and 126
OverflowError – If TEXT ending offset is greater than 99,999,999 bytes
OverflowError – If any OTHER end offsets are greater than 99,999,999 and big_other is False

write_text(path, delim=30, big_other=False, compute_crc=False, override_fil=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.
compute_crc (bool) – If True compute the CRC when writing. Defaults to False.
override_fil (bool) – If True, replace $FIL with the name of the output path. Defaults to False.
appendable (bool) – If True, set $NEXTDATA in written dataset so it points to the next dataset. This assumes the next dataset is written, which will require another call to this method with appendable 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 append set to True so that $NEXTDATA is properly set. Defaults to False.

Returns:

the value of $NEXTDATA as written to the dataset

Return type: