Session Class

class flowkit.Session(gating_strategy=None, fcs_samples=None)

The Session class enables the programmatic creation of a gating strategy or for importing GatingML compliant documents. A Session combines multiple Sample instances with a single GatingStrategy. The gates in the gating strategy can be customized per sample.

Parameters:: fcs_samples – str or list. If given a string, it can be a directory path or a file path. If a directory, any .fcs files in the directory will be loaded. If a list, then it must be a list of file paths or a list of Sample instances. Lists of mixed types are not supported.

Public Methods:

`__init__`([gating_strategy, fcs_samples])
`__repr__`()	Return repr(self).
`add_samples`(fcs_samples)	Adds FCS samples to the session.
`get_sample_ids`()	Retrieve the list of Sample IDs in the Session.
`get_gate_ids`()	Retrieve the list of gate IDs defined for the Session's gating strategy.
`add_gate`(gate, gate_path[, sample_id])	Add a Gate instance to the gating strategy.
`remove_gate`(gate_name[, gate_path, ...])	Remove a gate from the gate tree.
`add_transform`(transform)	Add a Transform instance to use in the gating strategy.
`get_transforms`()	Retrieve the list of Transform instances stored in the gating strategy.
`get_transform`(transform_id)	Retrieve a Transform stored in the gating strategy by its ID.
`add_comp_matrix`(matrix)	Add a Matrix instance to use in the gating strategy.
`get_comp_matrices`()	Retrieve the list of compensation Matrix instances stored in the gating strategy.
`get_comp_matrix`(matrix_id)	Retrieve a compensation Matrix instance stored in the gating strategy by its ID.
`find_matching_gate_paths`(gate_name)	Find all gate paths in the gating strategy matching the given gate name.
`get_child_gate_ids`(gate_name[, gate_path])	Retrieve list of child gate IDs given the parent gate name (and path if ambiguous) in the gating strategy.
`get_gate`(gate_name[, gate_path, sample_id])	Retrieve a gate instance by its gate ID (and sample ID for custom sample gates).
`get_sample_gates`(sample_id)	Retrieve all gates for a sample in the gating strategy.
`get_gate_hierarchy`([output])	Retrieve the hierarchy of gates in the gating strategy.
`export_gml`(file_handle[, sample_id])	Export a GatingML 2.0 file for the gating strategy.
`export_wsp`(file_handle, group_name)	Export a FlowJo 10 workspace file (.wsp) for the gating strategy.
`get_sample`(sample_id)	Retrieve a Sample instance from the Session.
`analyze_samples`([sample_id, cache_events, ...])	Process gating strategy for samples.
`get_gating_results`(sample_id)	Retrieve analyzed gating results gates for a sample.
`get_analysis_report`()	Retrieve the report for the analyzed samples as a pandas DataFrame.
`get_gate_membership`(sample_id, gate_name[, ...])	Retrieve a boolean array indicating gate membership for the events in the specified sample.
`get_gate_events`(sample_id[, gate_name, ...])	Retrieve a pandas DataFrame containing only the events within the specified gate.
`plot_gate`(sample_id, gate_name[, gate_path, ...])	Returns an interactive plot for the specified gate.
`plot_scatter`(sample_id, x_dim, y_dim[, ...])	Returns an interactive scatter plot for the specified channel data.

add_samples(fcs_samples)

Adds FCS samples to the session.

Parameters:: fcs_samples – str or list. If given a string, it can be a directory path or a file path. If a directory, any .fcs files in the directory will be loaded. If a list, then it must be a list of file paths or a list of Sample instances. Lists of mixed types are not supported.
Returns:: None

get_sample_ids()

Retrieve the list of Sample IDs in the Session.

Returns:: list of Sample ID strings

get_gate_ids()

Retrieve the list of gate IDs defined for the Session’s gating strategy. The gate ID is a 2-item tuple where the first item is a string representing the gate name and the second item is a tuple of the gate path.

Returns:: list of gate ID tuples

add_gate(gate, gate_path, sample_id=None)

Add a Gate instance to the gating strategy. The gate ID and gate path must be unique in the gating strategy. Custom sample gates may be added by specifying an optional sample ID. Note, the gate & gate path must already exist prior to adding custom sample gates.

Parameters:

gate – an instance of a Gate subclass
gate_path – complete tuple of gate IDs for unique set of gate ancestors
sample_id – text string for specifying given gate as a custom Sample gate

Returns:

None

remove_gate(gate_name, gate_path=None, keep_children=False)

Remove a gate from the gate tree. Any descendant gates will also be removed unless keep_children=True. In all cases, if a BooleanGate exists that references the gate to remove, a GateTreeError will be thrown indicating the BooleanGate must be removed prior to removing the gate.

Parameters:

gate_name – text string of a gate name
gate_path – complete tuple of gate IDs for unique set of gate ancestors. Required if gate_name is ambiguous
keep_children – Whether to keep child gates. If True, the child gates will be remapped to the removed gate’s parent. Default is False, which will delete all descendant gates.

Returns:

None

add_transform(transform)

Add a Transform instance to use in the gating strategy.

Parameters:: transform – an instance of a Transform subclass
Returns:: None

get_transforms()

Retrieve the list of Transform instances stored in the gating strategy.

Returns:: list of Transform instances

get_transform(transform_id)

Retrieve a Transform stored in the gating strategy by its ID.

Parameters:: transform_id – a text string representing a Transform ID
Returns:: an instance of a Transform subclass

add_comp_matrix(matrix)

Add a Matrix instance to use in the gating strategy.

Parameters:: matrix – an instance of the Matrix class
Returns:: None

get_comp_matrices()

Retrieve the list of compensation Matrix instances stored in the gating strategy.

Returns:: list of Matrix instances

get_comp_matrix(matrix_id)

Retrieve a compensation Matrix instance stored in the gating strategy by its ID.

Parameters:: matrix_id – a text string representing a Matrix ID
Returns:: a Matrix instance

find_matching_gate_paths(gate_name)

Find all gate paths in the gating strategy matching the given gate name.

Parameters:: gate_name – text string of a gate name
Returns:: list of gate paths (list of tuples)

get_child_gate_ids(gate_name, gate_path=None)

Retrieve list of child gate IDs given the parent gate name (and path if ambiguous) in the gating strategy.

Parameters:

gate_name – text string of a gate name
gate_path – complete tuple of gate IDs for unique set of gate ancestors. Required if gate.gate_name is ambiguous

Returns:

list of Gate IDs (tuple of gate name plus gate path). Returns an empty list if no child gates exist.

Raises:

GateReferenceError – if gate ID is not found in gating strategy or if gate name is ambiguous

get_gate(gate_name, gate_path=None, sample_id=None)

Retrieve a gate instance by its gate ID (and sample ID for custom sample gates).

Parameters:

gate_name – text string of a gate ID
gate_path – tuple of gate IDs for unique set of gate ancestors. Required if gate_name is ambiguous
sample_id – a text string representing a Sample instance. If None, the template gate is returned.

Returns:

Subclass of a Gate object

get_sample_gates(sample_id)

Retrieve all gates for a sample in the gating strategy. This returns custom sample gates for the specified sample ID.

Parameters:: sample_id – a text string representing a Sample instance
Returns:: list of Gate subclass instances

get_gate_hierarchy(output='ascii', **kwargs)

Retrieve the hierarchy of gates in the gating strategy. Output is available in several formats, including text, dictionary, or JSON. If output == ‘json’, extra keyword arguments are passed to json.dumps

Parameters:: output – Determines format of hierarchy returned, either ‘ascii’, ‘dict’, or ‘JSON’ (default is ‘ascii’)
Returns:: gate hierarchy as a text string or a dictionary

export_gml(file_handle, sample_id=None)

Export a GatingML 2.0 file for the gating strategy. Specify the sample ID to use that sample’s custom gates in the exported file, otherwise the template gates will be exported.

Parameters:

file_handle – file handle for exporting data
sample_id – an optional text string representing a Sample instance

Returns:

None

export_wsp(file_handle, group_name)

Export a FlowJo 10 workspace file (.wsp) for the gating strategy.

Parameters:

file_handle – file handle for exporting data
group_name – a text string representing the sample group to add to the WSP file

Returns:

None

get_sample(sample_id)

Retrieve a Sample instance from the Session.

Parameters:: sample_id – a text string representing the Sample to retrieve
Returns:: a Sample instance

analyze_samples(sample_id=None, cache_events=False, use_mp=True, verbose=False)

Process gating strategy for samples. After running, results can be retrieved using the get_gating_results, get_report, and get_gate_membership, methods.

Parameters:

sample_id – optional sample ID, if specified only this sample will be processed
cache_events – Whether to cache pre-processed events (compensated and transformed). This can be useful to speed up processing of gates that share the same pre-processing instructions for the same channel data, but can consume significantly more memory space. See the related clear_cache method for additional information. Default is False.
use_mp – Controls whether multiprocessing is used to gate samples (default is True). Multiprocessing can fail for large workloads (lots of samples & gates) due to running out of memory. If encountering memory errors, set use_mp to False (processing will take longer, but will use significantly less memory).
verbose – if True, print a line for every gate processed (default is False)

Returns:

None

get_gating_results(sample_id)

Retrieve analyzed gating results gates for a sample.

Parameters:: sample_id – a text string representing a Sample instance
Returns:: GatingResults instance

get_analysis_report()

Retrieve the report for the analyzed samples as a pandas DataFrame.

Returns:: pandas DataFrame

get_gate_membership(sample_id, gate_name, gate_path=None)

Retrieve a boolean array indicating gate membership for the events in the specified sample. Note, the same gate ID may be found in multiple gate paths, i.e. the gate ID can be ambiguous. In this case, specify the full gate path to retrieve gate indices.

Parameters:

sample_id – a text string representing a Sample instance
gate_name – text string of a gate name
gate_path – complete tuple of gate IDs for unique set of gate ancestors. Required if gate_name is ambiguous

Returns:

NumPy boolean array (length of sample event count)

get_gate_events(sample_id, gate_name=None, gate_path=None, matrix=None, transform=None)

Retrieve a pandas DataFrame containing only the events within the specified gate. If an optional compensation matrix and/or a transform is provided, the returned event data will be compensated or transformed. If both a compensation matrix and a transform is provided the event data will be both compensated and transformed.

Parameters:

sample_id – a text string representing a Sample instance
gate_name – text string of a gate name. If None, all Sample events will be returned (i.e. un-gated)
gate_path – complete tuple of gate IDs for unique set of gate ancestors. Required if gate_name is ambiguous
matrix – an instance of the Matrix class
transform – an instance of a Transform subclass

Returns:

pandas DataFrame containing only the events within the specified gate

plot_gate(sample_id, gate_name, gate_path=None, subsample_count=10000, random_seed=1, x_min=None, x_max=None, y_min=None, y_max=None, color_density=True, bin_width=4)

Returns an interactive plot for the specified gate. The type of plot is determined by the number of dimensions used to define the gate: single dimension gates will be histograms, 2-D gates will be returned as a scatter plot.

Parameters:

sample_id – The sample ID for the FCS sample to plot
gate_name – Gate name to filter events (only events within the given gate will be plotted)
gate_path – tuple of gate names for full set of gate ancestors. Required if gate_name is ambiguous
subsample_count – Number of events to use as a sub-sample. If the number of events in the Sample is less than the requested sub-sample count, then the maximum number of available events is used for the sub-sample.
random_seed – Random seed used for sub-sampling events
x_min – Lower bound of x-axis. If None, channel’s min value will be used with some padding to keep events off the edge of the plot.
x_max – Upper bound of x-axis. If None, channel’s max value will be used with some padding to keep events off the edge of the plot.
y_min – Lower bound of y-axis. If None, channel’s min value will be used with some padding to keep events off the edge of the plot.
y_max – Upper bound of y-axis. If None, channel’s max value will be used with some padding to keep events off the edge of the plot.
color_density – Whether to color the events by density, similar to a heat map. Default is True.
bin_width – Bin size to use for the color density, in units of event point size. Larger values produce smoother gradients. Default is 4 for a 4x4 grid size.

Returns:

A Bokeh Figure object containing the interactive scatter plot.

plot_scatter(sample_id, x_dim, y_dim, gate_name=None, gate_path=None, subsample_count=10000, random_seed=1, color_density=True, bin_width=4, x_min=None, x_max=None, y_min=None, y_max=None)

Returns an interactive scatter plot for the specified channel data.

Parameters:

sample_id – The sample ID for the FCS sample to plot
x_dim – Dimension instance to use for the x-axis data
y_dim – Dimension instance to use for the y-axis data
gate_name – Gate name to filter events (only events within the given gate will be plotted)
gate_path – tuple of gate names for full set of gate ancestors. Required if gate_name is ambiguous
subsample_count – Number of events to use as a sub-sample. If the number of events in the Sample is less than the requested sub-sample count, then the maximum number of available events is used for the sub-sample.
random_seed – Random seed used for sub-sampling events
color_density – Whether to color the events by density, similar to a heat map. Default is True.
bin_width – Bin size to use for the color density, in units of event point size. Larger values produce smoother gradients. Default is 4 for a 4x4 grid size.
x_min – Lower bound of x-axis. If None, channel’s min value will be used with some padding to keep events off the edge of the plot.
x_max – Upper bound of x-axis. If None, channel’s max value will be used with some padding to keep events off the edge of the plot.
y_min – Lower bound of y-axis. If None, channel’s min value will be used with some padding to keep events off the edge of the plot.
y_max – Upper bound of y-axis. If None, channel’s max value will be used with some padding to keep events off the edge of the plot.

Returns:

A Bokeh Figure object containing the interactive scatter plot.