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)