Classes

class AGClasses.AGExperiment(experimentRoot, *args, **kwargs)

Overview

The AGExperiment object is where you define several rules and options for your analysis. It orchestrates how your custom strategy will interact with the flow data and handles optional settings like automatic QC.

Members

filters, list-like

List-like of str. Inclusive filter that will be passed on to AGFileSystem.CollectFiles.

ignoretype, list-like

List-like of str. Exclusive filter that will be passed on to AGFileSystem.CollectFiles.

mask, list-like

List-like of str. Exclusive filter that will be passed on to AGFileSystem.CollectFiles.

markers, list-like

List-like of str. Both inclusive and exclusive filter that will be passed on to AGFileSystem.loadFCS. Any marker labels encountered in a .fcs file must exist in this filter, otherwise sample is skipped.

NOTE: Forwardscatters, sidescatters and time should not be included.

compensation_exceptions, list-like

List like of str. Contains absolute filepaths to .fcs files that should be compensated in a different way than the rest of the samples.

comp_matrix, ndarray

Optional comp_matrix that can be passed and used for applying compensation manually.

resultHeader, list-like

List-like of str. A custom header to be used for the output file.

bQC, bool

Flag if any type of QC has been requested. This will automatically trigger post-analysis PCA, print figures and save a pandas DataFrame with the results.

nOfEvents, int, defaultNone

Number of maximum events to be collected from each fcs file in experiment. Default is None, which means all events are read from the .fcs file.

Internal members

fcsList, list-like

List like of str filepath. Collected through an internal call to AGFileSystem.CollectFiles

sampleList, list-like

List-like of AGClasses.AGSample objects. Created and expanded as a batch experiment runs. Note that these are not fully-fletched AGSampled object, but rather slimmed versions, with only enough information to recreate an identical sample object to save memory.

man_comp, bool

Flag recognizing if a sample should be compensated manually with the compensation matrix stored in comp_matrix.

flaggedSamples, list-like

List-like of list-like. Two-by-n list with [samplename, flagged_population].

resultMatrix, list-like

Matrix with reported statistics, one sample per row.

normaliseLevel, str

Experimental feature, for plate normalisation. Not fully implemented.

nOfPlates, int

Count of plates, used for plate normalisation. Not fully implemented.

normalise, bool

Flag for plate normalisation. Not fully implemented.

plateList, list-like

List-like of str filepaths. Used for plate normalisation. Not fully implemented.

HDF5Fileset, bool

Flag for loading pre-processed HDF5 datasets created with create_HDF5_files.

Methods

apply(strategy, *args, **kwargs)

Main method where you apply your custom strategy to all .fcs files in an experiment.

Any arguments defined in *args or **kwargs will be passed on to your strategy, this way you can pass on and parse custom arguments to your strategy function. See sample notebooks for how to build a strategy.

NOTE: The AGExperiment object checks if the passed strategy seems to be a function by checking for a __call__ attribute, this means that you can pass a function, a class or similar as a strategy. The requirement other than that is that the strategy should accept an AGSample object and return an AGSample object.

Internal Methods

TODO

Examples

None currently.

Notes

On AGSample objects:

The sample object for each .fcs file only exists while it’s being gated.

After a strategy has been applied the populations are stored in a less memory intensive way and the sample object deconstructed.

This means that you cannot access the same AGSample object that was gated previously. However, if set up properly, the AGExperiment can recreate an identical AGSample object quickly.

class AGClasses.AGSample(fcsDF, filePath, sampleName=<object object>, sampling_resolution=32)

Overview

The AGSample object contains the data-matrix from the .fcs file input. It also keeps a list of all the AGgate objects that has been applied to it.

Any user-made strategy should accept an AGSample as input, apply gate functions to it and then return the modified AGSample back to AliGater

The Pandas DataFrame (the fcsDF member) should never be interacted with directly by the user. If python supported const, it would be const. See notes for more on this.

Members

sample, str, optional, default: See below

User-given sample name.

Notes on default behaviour:

If no explicit sample name is given, the name will default to the filename plus the name of its two parent folders.

I.e. if a .fcs file is located in /C/project_name/fcs_files/plate_3/my_fcs_file.fcs it would get the name ‘fcs_files/plate_3/my_fcs_file.fcs’

Settings to tweak this default behaviour will be implemented.

Internal members

vGates

List-like of AGgate objects that belong to this sample.

filePath

Absolute str path to the fcs file.

NOTE: if .fcs file paths are changed during runtime, an error will be raised.

fcsDF

The loaded fcs data stored as a pandas DataFrame.

Methods

__call__(name)

This function can be used to get the full ungated dataframe if no name is given, otherwise can return a specific earlier gate.

See sample notebooks for uses.

update(gate, QC=False)

gate, AGClasses.AGgate

A gate object that should be added to the samples gate list.

QC, bool, default: False

A flag deciding if a downsampled picture of the gating view should be saved. Should be set to True if:

1. You want QC post-analysis through PCA and inspection of the downsampled gating views.

And

2. Not for intermediate gating steps (these will be worthless in your post-analysis QC).

See example notebook on QC for best practice

report()

Function that reports a quick summary of this saples total events and the gates that have been applied to it.

Internal Methods

These are used by other, internal, AliGater functions and are not ment to be interacted with.

__init__(fcsDF, filePath, sampleName)

Initialization method. Intended to either be called by an AGExperiment object or through the AGFileSystem.loadFCS function.

printData(file, precision=4, header=True)

Function for printing formatted content to a filehandle.

printStats(output=None, overwrite=False, precision=4, header=True)

Wrapper function for printData that does file checking, and sets options like overwriting vs appending.

resultVector(order=None, precision=’.3f’)

Function that creates a list- or matrix-like table of reported ratios and events in this sample. Called by an AGExperiment object.

Examples

None currently.

Notes

On the fcsDF member:

To ensure that no changes has been made to the fcsDF, inadvertently or intentionally, it would be possible for AliGater to store a copy and make a comparison with that copy after each user-strategy has been applied.

This can have a significant performance impact depending on how many events have been recorded in each sample and has thus been left out by design.

update(gate, xlim=[0, 500000], ylim=[0, 500000], QC=False, scale='linear', xscale='linear', yscale='linear', T=1000, MFI=False, MFI_type='current', extra_MFI=None)

*Overview* Core function of the AGSample that should be used to save the results of a gate, e.g. CD3 positives out of CD45 positives. The only mandatory argument is an aligater.AGGate object. *Keyword arguments*

QC, bool, optional, default: False

If set, a downsampled view of the gate will be stored for later image-segmentation analysis. The gating view gets stored in flattened numpy.array format. The view limits are always fixed and can be set using the ylim and xlim arguments.

ylim, list, optional, default: [0, 500000]

Fixed y-limit of downsampled views of this gate, only relevant if QC is True

xlim, list, optional, default: [0, 500000]

Fixed x-limit of downsampled views of this gate, only relevant if QC is True

scale, str, optional, default: ‘linear’

The scale used in the gating view, relevant for downsampled image views if QC is set to True. This argument sets both axis, but can be overriden by xscale or yscale for the specific axis.

xscale, str, optional, default: ‘linear’

The scale used in the gating view’s x-axis, relevant for downsampled image views if QC is set to True. This will override the option set in scale

yscale, str, optional, default: ‘linear’

The scale used in the gating view’s y-axis, relevant for downsampled image views if QC is set to True. This will override the option set in scale

T, int, optional, default: 1000

The threshold for the linear-logarithmic transition used in logicle scales.

MFI, bool, optional, default: False

Flag indicating that MFIs should be stored for this gate. See MFI_type for modifying behavior.

MFI_type, str, optional, default: ‘current’

If MFI is stored, which type should be saved, options are; ‘current’, ‘all’, ‘all_with_scatter’

‘current’ saves MFIs for the current gating axis. Including scatter columns if they are used. ‘all’ saves MFIs for the current axis, then this gate’s parent’s axis and continuing up the hierarchy until no parent gate is found. Forward and side scatter columns are ignored. ‘all_with_scatter’ similar to ‘all’, but includes MFI of scatter columns

extra_MFI, list, optional, default: None

List of str names of markers to save MFIs of. Must match exactly, case sensitive.

class AGClasses.AGgate(gate, parentGate, xCol, yCol, name=None, RatioGate=False, IgnoreCellLimit=False)

Overview

Object for containing results from a gating operation.

In essence it contains information on which events belong to a gated population and the name of it’s parent population.

Optionally it can hold additional information such as which markers labels where on the x- and y-axis’, and a downsampled version of the pre-gate view.

Such additional information is useful for automating formatted output from a batch gating experiment.

Members

current, list-like

List-like index tracking rows(events) correspond to a gated population in a AGClasses.AGSample.

parent, list-like, optional, default: None

List-like index tracking rows(events) correspond to a population’s parent population in a AGClasses.AGSample.

If not passed, assumes that the parent population is the ungated sample.

xCol, str, optional, default: None

User-input string name of the x-axis marker label.

NOTE: Will not raise on non-str input, instead sets to None.

yCol, str, optional, default: None

User-input string name of the y-axis marker label.

NOTE: Will not raise on non-str input, instead sets to None.

name, str

User-input string name of the gated population.

Raises an exception on non-str input.

parentName, str or None, default: None

User-input string name of the gated population’s parent population.

RatioGate, bool, optional, default: False

If True, only report the percent-of-parent population for this gate (i.e. the ratio between the two input populations)

It will also ignore the checks to the minCells limit.

IgnoreCellLimit, bool, optional, default: False

If True, will bypass the check to the minCells limit

Useful for late gates that are known to have small number events but still should be gated, perhaps with fix unflexible gates.

This makes it harder to quality control larger sets of samples for this gate, use carefully.

Internal members

These are used by other, internal, AliGater functions and are not ment to be interacted with.

m_downSample

Container for a downsampled heatmap of the pre-gating view.

bInvalid

Invalid flag, used for differentiating between a depleted population (0-events) that should be considered and an invalid population that should be disregarded.

NOTE: Will be set to True in any gate objects if number of events in parentGate is inclusive less than the threshold agconf.minCells.

See examples.

bNoparent

Flag for identifying samples with no parent. If true, these gate objects are assumed to stem from the ungated full sample.

Methods

__init__(self, gate, parentGate, xCol, yCol, name)

Initialization method, see examples.

__call__(self)

Function for access to the current member with checks for flags and no data.

Should be preferred over direct access of the current member.

changeParent(self, parent, name)

parent, AGClasses.AGgate

Parent population, expects another AGClasses.AGgate object.

name, str, optional, default: None

Name of parent population.

getParent(self)

Function for access to the parent member with checks for flags and no data.

Similar to the __call__ function this is the preferred method for access to the parent member.

reportStats(self)

Function that prints a formatted report of the AGgate objects content.

Useful when exploring data, but is not ment to be used for printing gating results in larger batch experiments.

For reporting gating results of an experiment see AGClasses.AGExperiment and it’s printExperiment function.

Internal Methods

These are used by other, internal, AliGater functions and are not ment to be interacted with.

downSample

Function that creates and stores a downsampled version of the gating view.

setInvalid

Sets the bInvalid member to True

Examples

None currently.

class AGClasses.AGQC(downSamplingBins=32, *args, **kwargs)

Overview Object that manages downsampled images while AliGater is running. It can also be used to load previously saved downsampled images to do quality control.

While an AGExperiment is running with active QC the downsampled images are saved in temporary files as np arrays. After a run is completed they are reloaded, and stored as one bigger HDF5 object with metadata for simpler loading at a later time.

Members

TODO

Internal members

TODO

Methods

TODO

Internal Methods

TODO

Examples

None currently.