Skip to main content

fcs

class WSP​

A class to parse a FlowJo WSP file following the Gating-ML 2.0 standard.    Contains methods
for extracting gates, table output structure, population statistics, and compensation
matrices from WSP file.

>>> wsp = WSP(wsp_bytes)

View gates​

>>> wsp.gates

View population statistics computed in FlowJo​

>>> wsp.stats_flowjo

View table output structure, as configured in Table Editor in FlowJo​

>>> wsp.table_output_structure

Generate output table based on table output structure and FlowJo population statistics​

>>> WSP.apply_table_output_structure(
      wsp.table_output_structure["Table"][["gate", "value_type", "statistic", "rename"]], 
      wsp.stats_flowjo)

With corresponding FCS files, you can calculate population counts from FCS events data using
the apply_compensation and calculate_population_counts methods.

function WSP.__init__​

Setup parsed WSP object, which contains gates, population statistics, and
table output structure as configured in Table Editor in FlowJo

Parameters​

wsp_bytes : bytes or file_like object
        FlowJo Workspace file in bytes

function WSP.get_population_stats​

Retrieve population statistics from WSP file

Returns​

pd.DataFrame
        Population statistics as a DataFrame

function WSP.get_gates​

Retrieve gates from WSP file

Returns​

pd.DataFrame
        Gates as a DataFrame

function WSP.get_single_well_stats​

Retrieve populations for a given well from a WSP file.    To use this method, loop through the
wells in the WSP file and pass the node corresponding to the well to this method, making
sure to capture the unique identifier for each well in the loop.

Parameters​

node : node
        Node to start looking in, typically node corresponding to well
method : str
        Method to use to retrieve population counts.
        'gates' will retrieve gates from WSP file
        'flowjo_stats' will parse stats from WSP file

Returns​

dict
        Dictionary containing single well stats requested

function WSP.get_table_output_structure​

Retrieve table structure as specified in Table Editor of FlowJo

Parameters​

node : etree.Element
        Node to search for table editor, typically root node

Returns​

pd.DataFrame
        DataFrame consisting of gate and tables

function WSP.apply_table_output_structure​

Apply table structure as specified in Table Editor of FlowJo to get population proportions

Parameters​

df_table_structure : pd.DataFrame
        DataFrame containing table structure; Should contain the following fields:
        gate (series of gates applied to determine population)
        value_type (type of value (e.g. statistic, keyword, etc.))
        rename (name of column in output table)
        table_name (name of table)
df_population_stats : pd.DataFrame
        DataFrame containing gating stats; Should contain the following fields
        population (series of gates applied to determine population)
        statistic_name (name of statistic (e.g. count, MFI, etc.))
        statistic_value (value of statistic)
unique_id : list[str] | str
        Unique identifying column names(s) for single flow run. Commonly, this would be well position,
        well position + timestamp, or filename.

Returns​

pd.DataFrame
        DataFrame containing population proportions with the following fields
        table_name (name of table)
        unique_id (unique identifier for well; name will vary depending on chosen identifier)
        population (population name (e.g. - CD3, Cells, etc.))
        statistic_name (type of statistic (e.g. freqof, freqofparent, freqofgrandparent, etc.))
        statistic_value (value of statistic)

Examples​

>>> wsp = WSP(wsp_bytes)  
>>> WSP.apply_table_output_structure(wsp.table_output_structure,  
                                     wsp.stats_flowjo,  
                                     unique_id="filename")

function WSP.get_gating_order​

Convenience method to get the order in which gating was conducted from the list of gates
observed in file

Parameters​

population_name : list[str]
        List of populations, delimited by '/'

Returns​

list[str]
        List of populations in order

Example​

>>> get_gating_order(["All Events",  
                      "All Events/Single Cells/Live Cells",  
                      "All Events/Single Cells"])  
  
["All Events", "All Events/Single Cells", "All Events/Single Cells/Live Cells"]

function WSP.get_gate_structure​

Retrieve gate structure as a nested dict from a WSP file

Parameters​

node : etree.Element
        XML node to start traversal in, typically node corresponding to well

function WSP.get_compensation_matrices​

Retrieve compensation matrices from WSP file as a DataFrame

Returns​

dict[str, pd.DataFrame]
        Dictionary of compensation matrices, keyed by matrix name

function WSP.apply_compensation​

Adjust flow cytometry data for compensation

Parameters​

data : pd.DataFrame
        DataFrame containing FCS event data
compensation_matrix : pd.DataFrame
        DataFrame containing compensation matrix; rows are from, columns are to
compensation_channels : list[str] | None
        Fluorescent channels to adjust for compensation

Returns​

pd.DataFrame
        DataFrame containing compensated events

function WSP.calculate_population_counts​

Calculate population counts from FCS events data, using compensation matrix

Parameters​

wsp_gates : pd.DataFrame
        Pandas DataFrame with the following fields
        population_name (full nesting of population)
        gate_sort_order (order of points for polygon)
        rect_min (min cutoff for rectangle gate)
        rect_max (max cutoff for rectangle gate)
        x (x coordinate for polygon gate)
        y (y coordinate for polygon gate),
        x_dimension (X dimension for laser)
        y_dimension (Y dimension for laser)
        gate_type
        filename corresponding to well

compensation_matrix : pd.DataFrame
        Compensation matrix as a DataFrame; rows are from labels, columns are to labels

fcs_files_dict : dict[str, bytes]
        Dictionary of FCS files as bytes, keyed by filename

Returns​

pd.DataFrame
        DataFrame containing filename, population name, and counts

class FCS​

A class to represent an FCS (Flow Cytometry Standard) file.

Attributes​

data : pd.DataFrame
        The data contained in the FCS file.
metadata_file : pd.DataFrame
        The metadata contained in the FCS file header.
metadata_fcs : pd.DataFrame
        The system metadata contained in the FCS file.
metadata_channels : pd.DataFrame
        The characteristics for each channel in the FCS file.
metadata_channel_names : Tuple
        The names of the flow cytometer channels.

Methods​

parse_metadata(metadata: dict)
        Parses FCS file metadata.

function FCS.parse_metadata​

Parses FCS file metadata

Parameters​

metadata : dict
        Metadata contained within FCS file, as parsed by the fcsparser python package

Returns​

dict
        FCS metadata

Notes​

FCS metadata is returned as a dictionary with the following components

header: dict
        describes FCS version and byte offsets of TEXT, DATA, and ANALYSIS segments in FCS file
system_metadata: dict
        contains system metadata as specified by the FCS file format
channels: pd.DataFrame
        describes characteristics for each channel
channel_names: Tuple
        contains flow cytometer channel names

function FCS.gate_population_polygon​

Gate FCS file using a polygon

Parameters​

data : pd.DataFrame
        DataFrame containing FCS event data
polygon : np.ndarray
        2D Numpy array containing polygon vertices
x_dimension : str
        Name of x dimension
y_dimension : str
        Name of y dimension

Returns​

pd.DataFrame
        DataFrame containing gated population events

function FCS.gate_population_limit​

Gate FCS file using a limit

Parameters​

data : pd.DataFrame
        DataFrame containing FCS event data
dim : str
        Name of dimension to gate on
min_val : float
        Minimum value to gate on
max_val : float
        Maximum value to gate on

Returns​

pd.DataFrame
        DataFrame containing gated population events

function FCS.create_comp_matrix_xml​

Creates XML representation of compensation matrix

Parameters​

df : pd.DataFrame
        Pandas DataFrame containing compensation matrix.    Rows are from, columns are to
comp_matrix_name : str
        Name of compensation matrix
spillover_mat_attr : dict[str, str], optional
        spillover matrix definition, by default None

Raises​

GanymedeException
        If rows and columns are not in the same order

Example​

For a WSP object, insert a compensation matrix into the XML tree by executing the steps shown below:  
  
>>>> xml_comp_mat = WSP.create_comp_matrix_xml(df_comp_matrix)  
>>>> matrix = xml_comp_mat.xpath("./transforms:spilloverMatrix", namespaces=WSP.ns_transforms).pop()  
>>>> wsp_obj.wsp_root.xpath("./Matrices")[0].append(xml_comp_mat)  
  
In this example, df_comp_matrix is a Pandas DataFrame with a format mirroring an element  
from an item in the 'compensation_matrices' dictionary returned by the 'get_compensation_matrices' method.  
  
Writing wsp_obj to a file will now include the added compensation matrix in the WSP file, which  
can be opened in FlowJo.

function parse_fcs​

Parse an FCS file and return a dict of metadata and numpy arrays of the data.

Parameters​

fcs_bytes : bytes
        Contents of an FCS file

Returns​

FCS
        An FCS object containing the data and metadata from the FCS file