Workflow

pyreflow supports the following general workflow as shown below:

Legend:

1. fcs_read_header()

2. fcs_read_flat_text()

3. fcs_read_std_text()

4. fcs_read_flat_dataset()

5. fcs_read_std_dataset()

6. fcs_read_flat_dataset_with_keywords()

7. CoreTEXT*.from_kws() (see CoreTEXT*)

8. CoreDataset*.from_kws() (see CoreDataset*)

9. CoreTEXT*.to_dataset() (see CoreTEXT*)

10. CoreTEXT*.write_text() (see CoreTEXT*)

11. CoreDataset*.write_dataset() (see CoreDataset*)

12. CoreTEXT*.version_*() (see CoreTEXT*)

13. CoreDataset*.version_*() (see CoreDataset*)

Flat vs standardized mode

“Flat mode” refers to parsing TEXT as a flat list of key/value pairs (both strings) with no further processing. Only when parsing DATA will a subset of keywords be interpreted ($DATATYPE, $PnB, etc); everything else will be left as-is, and no futher checks for standards compliance will be performed.

“Flat mode” is similar to how many other FCS libraries (flowCore et al) parse FCS files.

In “standard” or “standardized mode” (abbreviated “std” in function names above), each keyword will be parsed and stored in a class called CoreTEXT* (for TEXT) or CoreDataset* (for all segments) where the * indicates FCS version. These are internally validated, thus non-conforming keywords will trigger an error if present upon creation. These classes themselves have an API which allows reading/writing internal elements of an FCS file. They can also be written back to disk.

“Flat mode” has the advantage of being slightly faster, while “standard mode” has the advantage of compliant parsing and type-safe data manipulation.

Repairing Files

Many FCS files do not conform to the standards they claim to follow. pyreflow offers several ways to deal with these.

First, see the arguments for the functions in Reader Functions; most of these are flags or other options to control parsing, alter keywords, fix offsets, etc. These should address most needs.

For extreme cases where these flags are not enough, the recommended strategy is to first use fcs_read_flat_text() to get a keyword dictionary. These can then be fixed using arbitrary python code (“offline manipulation” above). Finally, these can be parsed again using fcs_read_flat_dataset_with_keywords() or fcs_read_std_dataset_with_keywords().