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)