Quickstart#

readfcs is a lightweight open-source Python package for loading fcs files into AnnData objects.

  • Simply use read to get started.

  • Use ReadFCS class to access advanced features such as compensation.

  • Use view to inspect the raw content of the FCS file and debug failures in reading.

import readfcs

Data#

Here we use an example .fcs file.

datapath = readfcs.datasets.example()
datapath
'example.fcs'

High level read() function: fcs -> AnnData#

adata = readfcs.read(datapath)

Metadata is stored as a dictionary in adata.uns.meta

adata
AnnData object with n_obs × n_vars = 65016 × 16
    var: 'n', 'channel', 'marker', '$PnB', '$PnR', '$PnG'
    uns: 'meta'
adata.var
n channel marker $PnB $PnR $PnG
FSC-A 1 FSC-A 32 262207 1
FSC-H 2 FSC-H 32 262207 1
SSC-A 3 SSC-A 32 261588 1
KI67 4 B515-A KI67 32 261588 1
CD3 5 R780-A CD3 32 261588 1
CD28 6 R710-A CD28 32 261588 1
CD45RO 7 R660-A CD45RO 32 261588 1
CD8 8 V800-A CD8 32 261588 1
CD4 9 V655-A CD4 32 261588 1
CD57 10 V585-A CD57 32 261588 1
CD14 11 V450-A CD14 32 261588 1
CCR5 12 G780-A CCR5 32 261588 1
CD19 13 G710-A CD19 32 261588 1
CD27 14 G660-A CD27 32 261588 1
CCR7 15 G610-A CCR7 32 261588 1
CD127 16 G560-A CD127 32 261588 1
adata.uns["meta"]["spill"]
KI67 CD3 CD28 CD45RO CD8 CD4 CD57 CD14 CCR5 CD19 CD27 CCR7 CD127
KI67 1.000000 0.000000 0.000000 0.000088 0.000249 0.000645 0.007198 0.0 0.000000 0.000131 0.000067 0.000582 0.002520
CD3 0.000000 1.000000 0.071188 0.148448 0.338903 0.009717 0.000000 0.0 0.301380 0.007478 0.012354 0.000000 0.000000
CD28 0.000000 0.331405 1.000000 0.061965 0.120979 0.004053 0.000000 0.0 0.109117 0.100314 0.005832 0.000000 0.000000
CD45RO 0.000000 0.088621 0.389424 1.000000 0.029759 0.065553 0.000000 0.0 0.031294 0.039306 0.091375 0.000396 0.000057
CD8 0.000000 0.136618 0.010757 0.000000 1.000000 0.000156 0.000000 0.0 0.483235 0.014858 0.000000 0.000000 0.000000
CD4 0.000000 0.000124 0.019463 0.218206 0.004953 1.000000 0.003583 0.0 0.001311 0.029646 0.408902 0.006506 0.000119
CD57 0.000000 0.000000 0.000000 0.000000 0.001056 0.002287 1.000000 0.0 0.000389 0.000194 0.000000 0.062551 0.132484
CD14 0.000000 0.000000 0.000000 0.000000 0.000000 0.008118 0.170066 1.0 0.000000 0.000000 0.000000 0.000000 0.000000
CCR5 0.003122 0.008526 0.001024 0.001163 0.125401 0.018142 0.193646 0.0 1.000000 0.066898 0.161456 0.286823 1.238037
CD19 0.002015 0.069645 0.194715 0.001008 0.151611 0.001270 0.007133 0.0 1.150032 1.000000 0.016077 0.014674 0.055352
CD27 0.001685 0.054340 0.277852 0.343008 0.061753 0.077523 0.004263 0.0 0.497488 0.743923 1.000000 0.010329 0.037635
CCR7 0.000000 0.008713 0.048213 0.073190 0.150563 0.386293 0.101896 0.0 0.370277 0.613490 1.218024 1.000000 0.065211
CD127 0.001684 0.000000 0.000000 0.000095 0.003463 0.015712 0.174122 0.0 0.023802 0.049474 0.132511 0.239216 1.000000
adata.write("example.h5ad")

Using FCSFile class for accessing attributes and compensation#

ReadFCS class offers additional functionalities such as .compensate

fcsfile = readfcs.ReadFCS(datapath)

Data is stored as a DataFrane in .data

fcsfile.data.iloc[:5, 5:10]
R710-A R660-A V800-A V655-A V585-A
0 2.364107e-29 6.250796e+02 1.917992e+03 5.473881e-37 4.061506e-19
1 -1.186825e+29 -1.480446e+00 -1.186825e+29 -1.483879e+00 -4.861563e-02
2 -1.186809e+29 2.956976e-29 -4.832434e-02 -1.170649e-01 -1.186809e+29
3 5.760625e+04 2.030161e+02 2.190984e+03 -1.170649e-01 1.989365e+02
4 -1.186825e+29 -1.478666e+00 -1.483879e+00 -3.937183e-02 -1.186825e+29

Metadata is stored as a dict in .meta

This equals to adata.uns['meta']

fcsfile.meta.get("$CYT")
'Main Aria (FACSAria)'

Perform compensation.

fcsfile.compensate()

Check the compensated data.

fcsfile.data.iloc[:5, 5:10]
R710-A R660-A V800-A V655-A V585-A
0 8.041768e+26 4.222514e+28 -1.104851e+27 7.053192e+27 -1.051221e+27
1 -1.323991e+29 -2.789157e+28 -7.523200e+28 3.923784e+28 1.280475e+28
2 -1.241347e+29 3.461693e+27 8.560203e+26 1.224060e+26 -1.013959e+29
3 5.182068e+26 4.225973e+28 1.516424e+28 7.262089e+27 -3.875044e+27
4 -1.236074e+29 4.617892e+28 1.596080e+28 6.197030e+27 -1.259902e+29

View the FCS file content#

When reading in FCS file fails, you may view the content of the file to debug:

meta, data = readfcs.view(datapath)