Jupyter Notebook Binder

Flow cytometry#

Flow cytometry is a technique used to detect and measure physical and chemical characteristics of a population of cells or particles (wiki).

Here, we’ll walk through how to

  1. iteratively ingest datasets

  2. query, search, integrate & analyze datasets


!lamin init --storage ./test-facs --schema bionty
Hide code cell output
✅ saved: User(id='DzTjkKse', handle='testuser1', email='testuser1@lamin.ai', name='Test User1', updated_at=2023-09-26 15:23:17)
✅ saved: Storage(id='CwEfj7mS', root='/home/runner/work/lamin-usecases/lamin-usecases/docs/test-facs', type='local', updated_at=2023-09-26 15:23:17, created_by_id='DzTjkKse')
💡 loaded instance: testuser1/test-facs
💡 did not register local instance on hub (if you want, call `lamin register`)

import lamindb as ln
import lnschema_bionty as lb
import readfcs

lb.settings.species = "human"
💡 loaded instance: testuser1/test-facs (lamindb 0.54.2)
💡 notebook imports: lamindb==0.54.2 lnschema_bionty==0.31.2 pytometry==0.1.4 readfcs==1.1.6 scanpy==1.9.5
💡 Transform(id='OWuTtS4SAponz8', name='Flow cytometry', short_name='facs', version='0', type=notebook, updated_at=2023-09-26 15:23:19, created_by_id='DzTjkKse')
💡 Run(id='S8a5emuCLx77suThbwtw', run_at=2023-09-26 15:23:19, transform_id='OWuTtS4SAponz8', created_by_id='DzTjkKse')

Ingest a first file#

Access #

We start with a flow cytometry file from Alpert et al., Nat. Med. (2019).

Calling the following function downloads the file and pre-populates a few relevant registries:


We use readfcs to read the raw fcs file into memory:

adata = readfcs.read("Alpert19.fcs")
AnnData object with n_obs × n_vars = 166537 × 40
    var: 'n', 'channel', 'marker', '$PnB', '$PnE', '$PnR'
    uns: 'meta'

Transform: normalize #

In this use case, we’d like to ingest & store curated data, and hence, we split signal and normalize using the pytometry package.

import pytometry as pm
2023-09-26 15:23:22,843:INFO - Failed to extract font properties from /usr/share/fonts/truetype/noto/NotoColorEmoji.ttf: In FT2Font: Can not load face (unknown file format; error code 0x2)
2023-09-26 15:23:22,921:INFO - generated new fontManager
pm.pp.split_signal(adata, var_key="channel")
'area' is not in adata.var['signal_type']. Return all.

pm.tl.normalize_arcsinh(adata, cofactor=150)

Validate: cell markers #

First, we validate features in .var using CellMarker:

validated = lb.CellMarker.validate(adata.var.index)
13 terms (32.50%) are not validated for name: Time, Cell_length, Dead, (Ba138)Dd, Bead, CD19, CD4, IgD, CD11b, CD14, CCR6, CCR7, PD-1

We see that many features aren’t validated because they’re not standardized.

Hence, let’s standardize feature names & validate again:

adata.var.index = lb.CellMarker.standardize(adata.var.index)
validated = lb.CellMarker.validate(adata.var.index)
5 terms (12.50%) are not validated for name: Time, Cell_length, Dead, (Ba138)Dd, Bead

The remaining non-validated features don’t appear to be cell markers but rather metadata features.

Let’s move them into adata.obs:

adata.obs = adata[:, ~validated].to_df()
adata = adata[:, validated].copy()

Now we have a clean panel of 35 validated cell markers:

validated = lb.CellMarker.validate(adata.var.index)
assert all(validated)  # all markers are validated

Register: metadata #

Next, let’s register the metadata features we moved to .obs.

For this, we create one feature record for each column in the .obs dataframe:

features = ln.Feature.from_df(adata.obs)

We use the Experimental Factor Ontology through Bionty to create a “FACS” label for the dataset:

lb.ExperimentalFactor.bionty().search("FACS").head(2)  # search the public ontology
ontology_id definition synonyms parents molecule instrument measurement __ratio__
fluorescence-activated cell sorting EFO:0009108 A Flow Cytometry Assay That Provides A Method ... FACS|FAC sorting [] None None None 100.0
BALB/c EFO:0000602 Balb/C Is A Mouse Strain Of Albion Mice. BALB/cJ|C|BALBc [] None None None 90.0
# import the record from the public ontology and save it to the registry

# show the content of the registry
name ontology_id abbr synonyms description molecule instrument measurement bionty_source_id updated_at created_by_id
lh5Cxy8w fluorescence-activated cell sorting EFO:0009108 None FACS|FAC sorting A Flow Cytometry Assay That Provides A Method ... None None None 67aZ 2023-09-26 15:23:25 DzTjkKse

Register: data & annotate with metadata #

modalities = ln.Modality.lookup()
features = ln.Feature.lookup()
efs = lb.ExperimentalFactor.lookup()
species = lb.Species.lookup()
file = ln.File.from_anndata(
    adata, description="Alpert19", field=lb.CellMarker.name, modality=modalities.protein
... storing '$PnE' as categorical
... storing '$PnR' as categorical

Annotate by linking FACS & species labels:

file.labels.add(efs.fluorescence_activated_cell_sorting, features.assay)
file.labels.add(species.human, features.species)

Inspect the registered file#

Inspect features on a high level:

  var: FeatureSet(id='h6CWOy7mwmFQMCFiyW1g', n=35, type='number', registry='bionty.CellMarker', hash='ldY9_GmptHLCcT7Nrpgo', updated_at=2023-09-26 15:23:26, modality_id='TNLbzSee', created_by_id='DzTjkKse')
    'CD161', 'Igd', 'CD16', 'CD38', 'Cd14', 'PD1', 'CD11B', 'CD11c', 'Ccr7', 'CD94', ...
  obs: FeatureSet(id='Bwx907Jh63luRtbKpMSM', n=5, registry='core.Feature', hash='mFEWGCUYY8z_PFlsY_XD', updated_at=2023-09-26 15:23:26, modality_id='ysBOVDQ5', created_by_id='DzTjkKse')
    Dead (number)
    Time (number)
    Cell_length (number)
    Bead (number)
    (Ba138)Dd (number)
  external: FeatureSet(id='mCbwAPm796PpDzuVIWxH', n=2, registry='core.Feature', hash='0eGVbsIp-TGuvrVckI0w', updated_at=2023-09-26 15:23:26, modality_id='ysBOVDQ5', created_by_id='DzTjkKse')
    🔗 assay (1, bionty.ExperimentalFactor): 'fluorescence-activated cell sorting'
    🔗 species (1, bionty.Species): 'human'

Inspect low-level features in .var:

name synonyms gene_symbol ncbi_gene_id uniprotkb_id species_id bionty_source_id updated_at created_by_id
4EojtgN0CjBH CD161 KLRB1 3820 Q12918 uHJU ASG3 2023-09-26 15:23:21 DzTjkKse
0evamYEdmaoY Igd None None None uHJU ASG3 2023-09-26 15:23:21 DzTjkKse
bspnQ0igku6c CD16 FCGR3A 2215 O75015 uHJU ASG3 2023-09-26 15:23:21 DzTjkKse
CR7DAHxybgyi CD38 CD38 952 B4E006 uHJU ASG3 2023-09-26 15:23:21 DzTjkKse
roEbL8zuLC5k Cd14 CD14 4695 O43678 uHJU ASG3 2023-09-26 15:23:21 DzTjkKse

Use auto-complete for marker names:

markers = file.features["var"].lookup()
import scanpy as sc

sc.pl.pca(adata, color=markers.cd14.name)