An automated flow-, spectral-flow- and mass-cytometry platform.
Currently, FACSPy is in beta phase. A pypi distribution will be available once the beta phase is completed.
To install, first clone this repository to your local drive via your terminal:
>>> git clone https://github.com/rgb-lab/FACSPy.gitIt is recommended to choose conda as your package manager. Conda can be obtained, e.g., by installing the Miniconda distribution, for detailed instructions, please refer to the respective documentation.
With conda installed, open your terminal and create a new environment by executing the following commands.
>>> conda create -n facspy python=3.10
>>> conda activate facspyNavigate to the folder where you cloned the repository in and run:
>>> pip install .This installs FACSPy and all dependencies.
To install jupyter, run:
>>> conda install jupyterOpen a notebook by running
>>> jupyter-notebookTo test if everything went successfull open a python console and import FACSPy:
>>> python
>>> import FACSPy as fpPlease refer to the documentation. Examples are found under "Vignettes" and currently include:
Code examples are found under "vignettes" and currently include:
-
Dataset Creation and Transformation
-
Dataset Gating: Unsupervised Gating
-
Data Analysis: Fluorescence intensity and Frequency of Parents
-
Data Analysis: Cell frequency analysis
-
Data Analysis: Samplewise Analysis
-
Data Analysis: Single cell analysis
-
Data Analysis: Interacting with R packages
-
The Panel object
-
The Metadata object
-
The CofactorTable object
-
The FACSPy dataset: Structure
-
The FACSPy dataset: Gate Handling
Currently, the following features are implemented:
Accompanying Metadata (tabular metadata, the panel information, asinh-transformation cofactors and a FlowJo- or Diva-Workspace) are internally represented to gather pre-existing information!
import FACSPy as fp
metadata = fp.dt.Metadata("../metadata.csv")
panel = fp.dt.Panel("../panel.csv")
workspace = fp.dt.FlowJoWorkspace("../workspace.wsp")The dataset is created using one single function
import FACSPy as fp
dataset = fp.dt.create_dataset(
metadata = metadata,
panel = panel,
workspace = workspace
)
The asinh transform requires cofactors, which are calculated automatically:
fp.dt.calculate_cofactors(dataset)Plotting is realized through a dedicated plotting module:
fp.pl.transformation_plot(
dataset,
sample_identifier = "2",
marker = "CD38"
)
The dataset is then transformed using asinh-transformation, logicle, hyperlog or normal log transformation.
fp.dt.transform(
dataset,
transform = "asinh",
cofactor_table = dataset.uns["cofactors"],
key_added = "transformed",
layer = "compensated"
)fp.pl.biax(
dataset,
gate = "CD45+",
x_channel = "CD3",
y_channel = "SSC-A",
color = "density"
)
fp.pl.biax(
dataset,
gate = "CD45+",
x_channel = "CD3",
y_channel = "SSC-A",
color = "CD4",
vmin = 1,
vmax = 4e4
)
fp.pl.biax(
dataset,
gate = "CD45+",
x_channel = "CD3",
y_channel = "SSC-A",
color = "CD8",
vmin = 1,
vmax = 4e4
)
fp.pl.cell_counts(
dataset,
gate = "live",
groupby = "diag_main",
figsize = (2,4)
)
fp.pl.cell_counts(
dataset,
gate = "live",
groupby = "diag_main",
splitby = "organ",
stat_test = False,
figsize = (2,4)
)
fp.tl.gate_frequencies(dataset)
fp.pl.gate_frequency(
dataset,
gate = "CD45+",
groupby = "diag_main",
freq_of = "parent",
figsize = (2,4)
)
fp.pl.gate_frequency(
dataset,
gate = "CD45+",
groupby = "diag_main",
splitby = "organ",
freq_of = "parent",
figsize = (2,4)
)
Gating can be accomplished using a conventional FlowJo-Workspace, unsupervised Gating via Clustering (manually or automated) or supervised Gating using pre-gated example files.
Here, we gate NK cells by looking at the CD16+ and CD56+ clusters manually:
fp.convert_cluster_to_gate(
dataset,
obs_column = "CD45+_transformed_leiden",
positive_cluster = ["10", "17", "2"],
population_name = "NK_cells",
parent_name = "CD45+"
)
fp.convert_gate_to_obs(
dataset,
"NK_cells"
)
We can also used the unsupervisedGating class:
gating_strategy = {
"T_cells": ["CD45+", ["CD3+", "CD45+"]],
"CD4_T_cells": ["T_cells", ["CD3+", "CD4+", "CD8-", "CD45+"]],
"CD8_T_cells": ["T_cells", ["CD3+", "CD4-", "CD8+", "CD45+"]]
}
clf = fp.ml.unsupervisedGating(
dataset,
gating_strategy = gating_strategy,
clustering_algorithm = "leiden",
layer = "transformed",
cluster_key = None
)
clf.identify_populations()
fp.convert_gate_to_obs(dataset, "T_cells")
fp.convert_gate_to_obs(dataset, "CD4_T_cells")
fp.convert_gate_to_obs(dataset, "CD8_T_cells")
Common Flow Cytometry metrics like MFI and FOP (frequency of parent) can be plotted:
fp.pl.mfi(
dataset,
groupby = "organ",
marker = "PD-1_(CD279)",
colorby = "diag_main",
figsize = (2,4)
)
fp.pl.fop(
dataset,
groupby = "organ",
marker = "PD-1_(CD279)",
colorby = "diag_main",
figsize = (2,4)
)
FACSPy offers samplewise dimensionality reductions as well as single cell dimensionality reductions!
fp.tl.mfi(dataset)
fp.pl.pca_samplewise(
dataset,
groupby = "organ"
)
fp.pl.mds_samplewise(
dataset,
groupby = "organ"
)
fp.pl.umap_samplewise(
dataset,
groupby = "organ"
)
fp.pl.tsne_samplewise(
dataset,
groupby = "organ"
)
fp.tl.umap(dataset)
fp.tl.tsne(dataset)
fp.tl.diffmap(dataset)
fp.tl.pca(dataset)
fp.pl.pca(
dataset,
color = "organ"
)
fp.pl.umap(
dataset,
color = "organ"
)
fp.pl.tsne(
dataset,
color = "organ"
)
fp.pl.diffmap(
dataset,
color = "organ"
)
Currently, PARC, PhenoGraph, Leiden and FlowSOM are implemented:
fp.tl.parc(dataset)
fp.tl.phenograph(dataset)
fp.tl.leiden(dataset)
fp.tl.flowsom(dataset)
fp.pl.umap(
dataset,
color = "CD45+_transformed_leiden",
legend_loc = "on data"
)
fp.pl.umap(
dataset,
color = "CD45+_transformed_parc"
legend_loc = "on data"
)
fp.pl.umap(
dataset,
color = "CD45+_transformed_flowsom"
legend_loc = "on data"
)
fp.pl.umap(
dataset,
color = "CD45+_transformed_phenograph"
legend_loc = "on data"
)
FACSPy implements heatmap visualizations for expression data as well as correlation plots for marker and samples
fp.pl.expression_heatmap(
dataset,
metadata_annotation = ["organ", "diag_main", "diag_fine"],
plot_annotate = "HLA_DR",
figsize = (5,8)
)
fp.pl.marker_correlation(
dataset,
y_label_fontsize = 8
figsize = (6,6)
)
fp.pl.sample_correlation(
dataset,
metadata_annotation = ["organ", "diag_main", "diag_fine"],
metaclusters = 2,
corr_method = "spearman",
label_metaclusters_in_dataset = True,
label_metaclusters_key = "sample_corr_metaclusters"
)
fp.pl.sample_distance(
dataset,
metadata_annotation = ["organ", "diag_main", "diag_fine"],
metaclusters = 2,
corr_method = "spearman",
label_metaclusters_in_dataset = True,
label_metaclusters_key = "sample_dist_metaclusters"
)
Differential expression testing is visualized as a fold change plot:
fp.pl.fold_change(
dataset,
layer = "compensated",
groupby = "organ",
group1 = "PB",
group2 = "organ2",
figsize = (2,6)
)
FACSPy will continue to be developed!
If you have any feature requests, please open an issue on GitHub. To ensure efficient treament of feature requests, please make sure to check if an issue regarding you request hasn't already been created.
For the near future, the following features are meant to be implemented:
- data integration
- minimal spanning trees
- t.b.a.
If you have any requests regarding example analyses or analysis strategies, submit an issue!
Your contributions are welcome!
Please submit an issue or pull request via Github! Pull requests with updated documentation and accompanying unit tests are preferred but not obligate!
