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 a fcs file from Oetjen18.

datapath = readfcs.datasets.Oetjen18_t1()

datapath

'oetjen18_t1.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 = 241552 × 20
    var: 'n', 'channel', 'marker', '$PnR', '$PnB', '$PnE', '$PnV', '$PnG'
    uns: 'meta'

adata.var

	n	channel	marker	$PnR	$PnB	$PnV	$PnG
FSC-A	1	FSC-A		262144	32	510	1.0
FSC-H	2	FSC-H		262144	32	510	1.0
FSC-W	3	FSC-W		262144	32	510	1.0
SSC-A	4	SSC-A		262144	32	310	1.0
SSC-H	5	SSC-H		262144	32	310	1.0
SSC-W	6	SSC-W		262144	32	310	1.0
CD95	7	R660-A	CD95	262144	32	490	1.0
CD8	8	R780-A	CD8	262144	32	475	1.0
CD27	9	B515-A	CD27	262144	32	470	1.0
CXCR4	10	B710-A	CXCR4	262144	32	417	1.0
CCR7	11	V450-A	CCR7	262144	32	400	1.0
LIVE/DEAD	12	V545-A	LIVE/DEAD	262144	32	495	1.0
CD4	13	V605-A	CD4	262144	32	400	1.0
CD45RA	14	V655-A	CD45RA	262144	32	375	1.0
CD3	15	V800-A	CD3	262144	32	400	1.0
CD49B	16	G560-A	CD49B	262144	32	400	1.0
CD14/19	17	G610-A	CD14/19	262144	32	415	1.0
CD69	18	G660-A	CD69	262144	32	470	1.0
CD103	19	G780-A	CD103	262144	32	435	1.0
Time	20	Time		262144	32		0.01

adata.uns["meta"]["spill"]

	CD95	CD8	CD27	CXCR4	CCR7	LIVE/DEAD	CD4	CD45RA	CD3	CD49B	CD14/19	CD69	CD103
CD95	1.000000	0.097352	0.000000	0.007011	0.003501	0.000000	0.000354	0.040952	0.008773	0.000067	0.001176	0.181536	0.005969
CD8	0.067916	1.000000	0.000000	0.000000	0.023879	0.000257	0.000000	0.003852	0.100139	0.000877	0.000000	0.008990	0.083250
CD27	0.007903	0.000000	1.000000	0.007492	0.010284	0.027712	0.003897	0.001299	0.000216	0.012664	0.002588	0.000000	0.000000
CXCR4	0.054363	0.100434	0.000000	1.000000	0.024458	0.001439	0.000000	0.056397	0.194799	0.000491	0.000000	0.400014	0.119091
CCR7	0.002288	0.000000	0.000000	0.000000	1.000000	0.034874	0.003729	0.000909	0.000282	0.000107	0.000000	0.000000	0.000000
LIVE/DEAD	0.000000	0.000000	0.003884	0.000705	0.014092	1.000000	0.447288	0.144758	0.025271	0.000000	0.000000	0.000000	0.000000
CD4	0.009741	0.000263	0.000000	0.028274	0.080674	0.005858	1.000000	0.434510	0.085092	0.055112	0.390481	0.290524	0.012522
CD45RA	0.275534	0.028670	0.000000	0.015079	0.102571	0.005517	0.180690	1.000000	0.169154	0.000643	0.014777	0.120247	0.005286
CD3	0.022068	0.073814	0.000000	0.000000	0.099510	0.006832	0.000891	0.003268	1.000000	0.000507	0.000000	0.000000	0.027061
CD49B	0.001869	0.000000	0.000000	0.048687	0.002103	0.009783	0.038672	0.008945	0.001060	1.000000	0.400143	0.148085	0.004221
CD14/19	0.006566	0.000262	0.000000	0.177725	0.006049	0.000889	0.065991	0.022692	0.003962	0.124522	1.000000	0.493361	0.019125
CD69	0.191802	0.032179	0.000000	0.396688	0.003517	0.000172	0.000497	0.026221	0.009804	0.022587	0.010298	1.000000	0.050517
CD103	0.005300	0.105676	0.000000	0.016745	0.006381	0.000771	0.000631	0.000561	0.126363	0.049163	0.018982	0.008683	1.000000

adata.write("oetjen18_t1.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]

	SSC-W	R660-A	R780-A	B515-A	B710-A
0	70533.507812	441.750000	3679.349854	2144.219971	653.639954
1	73205.625000	747.839966	5599.679688	560.039978	336.179993
2	71534.648438	727.890015	785.459961	1148.939941	294.839996
3	90882.062500	281.579987	1558.380005	873.599976	250.379990
4	73053.210938	354.540009	47.309998	60.059998	115.439995

Metadata is stored as a dict in .meta

This equals to adata.uns['meta']

fcsfile.meta.get("$CYT")

'LSRFortessa'

Perform compensation.

fcsfile.compensate()

Check the compensated data.

fcsfile.data.iloc[:5, 5:10]

	SSC-W	R660-A	R780-A	B515-A	B710-A
0	70533.507812	148.825683	3467.270412	2136.198753	412.369569
1	73205.625000	157.868760	5301.498694	526.322225	202.245785
2	71534.648438	-200.469627	424.040430	985.303260	89.175059
3	90882.062500	173.088739	1459.551784	870.436857	213.942965
4	73053.210938	343.537853	10.319622	59.458471	-10.948951

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)

meta

{'__header__': {'FCS format': b'FCS3.0',
  'text start': 256,
  'text end': 6333,
  'data start': 6339,
  'data end': 19330498,
  'analysis start': 0,
  'analysis end': 0},
 '$BEGINANALYSIS': '0',
 '$ENDANALYSIS': '0',
 '$BEGINSTEXT': '0',
 '$ENDSTEXT': '0',
 '$BEGINDATA': '6339',
 '$ENDDATA': '19330498           ',
 '$FIL': '2-13-17 T cell Panel_T_E_G05_004.fcs',
 '$SYS': 'Windows 7 6.1',
 '$TOT': 241552,
 '$PAR': 20,
 '$MODE': 'L',
 '$BYTEORD': '4,3,2,1',
 '$DATATYPE': 'F',
 '$NEXTDATA': 0,
 'CREATOR': 'BD FACSDiva Software Version 8.0',
 'TUBE NAME': 'T_E',
 '$SRC': '2-13-17 T cell Panel',
 'EXPERIMENT NAME': 'T_Memory_01-24-17',
 'GUID': '641fcb4b-10df-4636-9325-31d9c563ae6b',
 '$DATE': '10-SEP-2018',
 '$BTIM': '16:02:38',
 '$ETIM': '16:02:38',
 '$CYT': 'LSRFortessa',
 'SETTINGS': 'Cytometer',
 'CYTNUM': 'H64717700086',
 'WINDOW EXTENSION': '10.00',
 'EXPORT USER NAME': 'Administrator',
 'EXPORT TIME': '10-SEP-2018-16:02:38',
 '$OP': 'Administrator',
 'FSC ASF': '0.69',
 'AUTOBS': 'TRUE',
 '$INST': ' ',
 'LASER1NAME': 'Blue',
 'LASER1DELAY': '0.00',
 'LASER1ASF': '0.78',
 'LASER2NAME': 'Green',
 'LASER2DELAY': '129.57',
 'LASER2ASF': '0.75',
 'LASER3NAME': 'Red',
 'LASER3DELAY': '97.14',
 'LASER3ASF': '0.57',
 'LASER4NAME': 'UV',
 'LASER4DELAY': '65.51',
 'LASER4ASF': '0.77',
 'LASER5NAME': 'Violet',
 'LASER5DELAY': '34.39',
 'LASER5ASF': '0.88',
 'PLATE NAME': '2-13-17 T-memory',
 'WELL ID': 'G05',
 'PLATE ID': 'dac8255f-b7a7-4020-97d4-b2f6547e9b8b',
 '$TIMESTEP': '0.01',
 'SPILL': '13,R660-A,R780-A,B515-A,B710-A,V450-A,V545-A,V605-A,V655-A,V800-A,G560-A,G610-A,G660-A,G780-A,1,0.09735204394858232,0,0.007011172658837619,0.0035011622991608943,0,0.00035404250977172716,0.04095187696764509,0.008772588241008515,0.00006718020813517101,0.0011757471425244775,0.18153569419613963,0.005968917221960132,0.06791644502371093,1,0,0,0.023879362252194135,0.00025670476553774226,0,0.0038515097025606584,0.10013933246492365,0.0008770213569619933,0,0.00898974609423693,0.08325038424368773,0.007903499293392215,0,1,0.007492393786301646,0.010283780654816615,0.027712124248782985,0.0038970121720466712,0.0012990020263950173,0.00021629858651356506,0.01266409607946262,0.0025882796145041556,0,0,0.05436312961231171,0.10043354629620793,0,1,0.024457762534528842,0.001438755465565026,0,0.056396675477137725,0.19479870707404334,0.000491448523178251,0,0.40001423048531476,0.1190912528716946,0.002287714239639772,0,0,0,1,0.03487442489089123,0.0037287139545777908,0.0009086773768937114,0.00028199849105311033,0.00010702921799101015,0,0,0,0,0,0.0038836205805840925,0.0007053289300151003,0.014091525138545245,1,0.44728798423591304,0.14475792628516834,0.025271493638284688,0,0,0,0,0.00974125419862363,0.0002632132492050533,0,0.028274442964530383,0.08067419666935374,0.005858194367548331,1,0.434510053021289,0.08509239460644547,0.05511239401998082,0.3904807885835627,0.2905240045157824,0.012521708087597751,0.2755338450115204,0.028669650806175347,0,0.015079483546644151,0.102570606503713,0.005517449433296845,0.18068968375282926,1,0.1691535921475564,0.0006425502129023819,0.014776528843108972,0.12024655594625697,0.005286186820275574,0.022068162838460997,0.07381386891333566,0,0,0.099510015568334,0.006832379999899456,0.0008911834617986114,0.003267506538950563,1,0.0005074772359286441,0,0,0.027061076438995062,0.0018686282052520868,0,0,0.04868731478774934,0.0021034272836935267,0.009782626583969086,0.0386724857643002,0.00894462348769668,0.0010604166688987216,1,0.4001430473835212,0.14808536564415026,0.004220634283512854,0.006566059761305688,0.00026249819602128244,0,0.1777247143714281,0.006048688795358408,0.000888593600713252,0.06599068699071457,0.0226917657843669,0.003962258512920238,0.12452216889188006,1,0.4933609577028777,0.019125294105050362,0.19180239226858745,0.03217920077179705,0,0.3966881695505515,0.0035165238828971284,0.0001720123679770089,0.000496902183943976,0.026221297612479304,0.00980396608434816,0.022587068268836587,0.010298003599584191,1,0.050516820746677044,0.005299504824161491,0.10567559749222866,0,0.016744741148072208,0.006381246196506204,0.0007714156592623044,0.0006311226304001263,0.0005609946143672685,0.1263631034468686,0.049162630766073634,0.01898239672234503,0.008682800049188222,1',
 'APPLY COMPENSATION': 'TRUE',
 'THRESHOLD': 'FSC,5000',
 '$P1N': 'FSC-A',
 '$P1R': '262144',
 '$P1B': 32,
 '$P1E': '0,0',
 '$P1V': '510',
 '$P1G': '1.0',
 'P1DISPLAY': 'LIN',
 'P1BS': '0',
 'P1MS': '0',
 '$P2N': 'FSC-H',
 '$P2R': '262144',
 '$P2B': 32,
 '$P2E': '0,0',
 '$P2V': '510',
 '$P2G': '1.0',
 'P2DISPLAY': 'LIN',
 'P2BS': '0',
 'P2MS': '0',
 '$P3N': 'FSC-W',
 '$P3R': '262144',
 '$P3B': 32,
 '$P3E': '0,0',
 '$P3V': '510',
 '$P3G': '1.0',
 'P3BS': '-1',
 'P3MS': '0',
 '$P4N': 'SSC-A',
 '$P4R': '262144',
 '$P4B': 32,
 '$P4E': '0,0',
 '$P4V': '310',
 '$P4G': '1.0',
 'P4DISPLAY': 'LIN',
 'P4BS': '0',
 'P4MS': '0',
 '$P5N': 'SSC-H',
 '$P5R': '262144',
 '$P5B': 32,
 '$P5E': '0,0',
 '$P5V': '310',
 '$P5G': '1.0',
 'P5DISPLAY': 'LIN',
 'P5BS': '0',
 'P5MS': '0',
 '$P6N': 'SSC-W',
 '$P6R': '262144',
 '$P6B': 32,
 '$P6E': '0,0',
 '$P6V': '310',
 '$P6G': '1.0',
 'P6BS': '-1',
 'P6MS': '0',
 '$P7N': 'R660-A',
 '$P7S': 'CD95',
 '$P7R': '262144',
 '$P7B': 32,
 '$P7E': '0,0',
 '$P7V': '490',
 '$P7G': '1.0',
 'P7DISPLAY': 'LOG',
 'P7BS': '5464',
 'P7MS': '0',
 '$P8N': 'R780-A',
 '$P8S': 'CD8',
 '$P8R': '262144',
 '$P8B': 32,
 '$P8E': '0,0',
 '$P8V': '475',
 '$P8G': '1.0',
 'P8DISPLAY': 'LOG',
 'P8BS': '157',
 'P8MS': '0',
 '$P9N': 'B515-A',
 '$P9S': 'CD27',
 '$P9R': '262144',
 '$P9B': 32,
 '$P9E': '0,0',
 '$P9V': '470',
 '$P9G': '1.0',
 'P9DISPLAY': 'LOG',
 'P9BS': '102',
 'P9MS': '0',
 '$P10N': 'B710-A',
 '$P10S': 'CXCR4',
 '$P10R': '262144',
 '$P10B': 32,
 '$P10E': '0,0',
 '$P10V': '417',
 '$P10G': '1.0',
 'P10DISPLAY': 'LOG',
 'P10BS': '4284',
 'P10MS': '0',
 '$P11N': 'V450-A',
 '$P11S': 'CCR7',
 '$P11R': '262144',
 '$P11B': 32,
 '$P11E': '0,0',
 '$P11V': '400',
 '$P11G': '1.0',
 'P11DISPLAY': 'LOG',
 'P11BS': '682',
 'P11MS': '0',
 '$P12N': 'V545-A',
 '$P12S': 'LIVE/DEAD',
 '$P12R': '262144',
 '$P12B': 32,
 '$P12E': '0,0',
 '$P12V': '495',
 '$P12G': '1.0',
 'P12DISPLAY': 'LOG',
 'P12BS': '177',
 'P12MS': '0',
 '$P13N': 'V605-A',
 '$P13S': 'CD4',
 '$P13R': '262144',
 '$P13B': 32,
 '$P13E': '0,0',
 '$P13V': '400',
 '$P13G': '1.0',
 'P13DISPLAY': 'LOG',
 'P13BS': '2348',
 'P13MS': '0',
 '$P14N': 'V655-A',
 '$P14S': 'CD45RA',
 '$P14R': '262144',
 '$P14B': 32,
 '$P14E': '0,0',
 '$P14V': '375',
 '$P14G': '1.0',
 'P14DISPLAY': 'LOG',
 'P14BS': '2322',
 'P14MS': '0',
 '$P15N': 'V800-A',
 '$P15S': 'CD3',
 '$P15R': '262144',
 '$P15B': 32,
 '$P15E': '0,0',
 '$P15V': '400',
 '$P15G': '1.0',
 'P15DISPLAY': 'LOG',
 'P15BS': '700',
 'P15MS': '0',
 '$P16N': 'G560-A',
 '$P16S': 'CD49B',
 '$P16R': '262144',
 '$P16B': 32,
 '$P16E': '0,0',
 '$P16V': '400',
 '$P16G': '1.0',
 'P16DISPLAY': 'LOG',
 'P16BS': '679',
 'P16MS': '0',
 '$P17N': 'G610-A',
 '$P17S': 'CD14/19',
 '$P17R': '262144',
 '$P17B': 32,
 '$P17E': '0,0',
 '$P17V': '415',
 '$P17G': '1.0',
 'P17DISPLAY': 'LOG',
 'P17BS': '4480',
 'P17MS': '0',
 '$P18N': 'G660-A',
 '$P18S': 'CD69',
 '$P18R': '262144',
 '$P18B': 32,
 '$P18E': '0,0',
 '$P18V': '470',
 '$P18G': '1.0',
 'P18DISPLAY': 'LOG',
 'P18BS': '3799',
 'P18MS': '0',
 '$P19N': 'G780-A',
 '$P19S': 'CD103',
 '$P19R': '262144',
 '$P19B': 32,
 '$P19E': '0,0',
 '$P19V': '435',
 '$P19G': '1.0',
 'P19DISPLAY': 'LOG',
 'P19BS': '225',
 'P19MS': '0',
 '$P20N': 'Time',
 '$P20R': '262144',
 '$P20B': 32,
 '$P20E': '0,0',
 '$P20G': '0.01',
 'P20BS': '0',
 'P20MS': '0',
 'CST SETUP STATUS': 'SUCCESS',
 'CST BEADS LOT ID': '74538',
 'CYTOMETER CONFIG NAME': 'Copy of 5 Lasers UV SORP  2B 6V 2UV 3R 5Gr',
 'CYTOMETER CONFIG CREATE DATE': '2014-01-29T14:36:56-08:00',
 'CST SETUP DATE': '2016-12-21T08:52:55-08:00',
 'CST BASELINE DATE': '2016-10-28T10:11:58-07:00',
 'CST BEADS EXPIRED': 'False',
 'CST PERFORMANCE EXPIRED': '2016-12-22T08:52:55-08:00',
 'CST REGULATORY STATUS': 'RUO Performance Check'}

data

	FSC-A	FSC-H	FSC-W	SSC-A	SSC-H	SSC-W	R660-A	R780-A	B515-A	B710-A	V450-A	V545-A	V605-A	V655-A	V800-A	G560-A	G610-A	G660-A	G780-A	Time
0	19179.240234	18276.0	68774.937500	43136.339844	40080.0	70533.507812	441.750000	3679.349854	2144.219971	653.639954	235.839996	2132.239990	1003.200012	360.799988	923.119995	295.50	1167.00	792.00	1651.50	61.099998
1	83688.031250	74669.0	73451.890625	38744.160156	34685.0	73205.625000	747.839966	5599.679688	560.039978	336.179993	1144.000000	8740.160156	3935.359863	1815.439941	3595.679932	175.50	590.25	502.50	1029.75	61.200001
2	58169.761719	48933.0	77906.796875	42212.820312	38673.0	71534.648438	727.890015	785.459961	1148.939941	294.839996	3211.119873	42273.441406	19789.439453	9136.160156	5287.040039	212.25	723.75	766.50	374.25	61.299999
3	9510.959961	7272.0	85713.734375	24417.898438	17608.0	90882.062500	281.579987	1558.380005	873.599976	250.379990	305.359985	849.200012	380.160004	171.600006	320.320007	158.25	401.25	198.00	728.25	61.299999
4	66329.703125	60608.0	71722.937500	30016.738281	26928.0	73053.210938	354.540009	47.309998	60.059998	115.439995	36.959999	158.399994	123.199997	35.200001	-7.920000	111.00	546.75	395.25	56.25	61.299999
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
241547	8584.979492	8564.0	65696.546875	13915.199219	13840.0	65892.085938	166.440002	1491.689941	687.959961	193.439987	44.880001	616.880005	311.519989	124.080002	308.880005	120.75	607.50	406.50	837.00	9990.500000
241548	14454.120117	13086.0	72387.679688	35351.160156	32494.0	71298.500000	312.929993	1516.199951	1107.599976	354.119995	412.720001	14475.120117	6130.080078	1901.679932	771.760010	116.25	731.25	461.25	684.00	9990.500000
241549	8428.349609	8460.0	65290.824219	5821.919922	5532.0	68970.601562	-14.820000	26.219999	-6.240000	104.519997	8.800000	432.079987	143.440002	63.360001	4.400000	446.25	237.75	240.00	-20.25	9990.500000
241550	130528.679688	116053.0	73710.523438	27892.798828	26453.0	69103.039062	589.380005	108.299995	91.259995	663.779968	1790.800049	550.000000	850.960022	2629.439941	544.719971	264.75	2094.00	1352.25	76.50	9990.599609
241551	109540.953125	98525.0	72863.507812	39645.058594	37977.0	68414.523438	459.419983	58.709999	52.259998	419.639984	805.200012	513.039978	872.080017	2372.479980	440.880005	226.50	1740.00	917.25	49.50	9990.700195

241552 rows × 20 columns

Quickstart#

Data#

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

Using FCSFile class for accessing attributes and compensation#

View the FCS file content#

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