Quickstart¶
readfcs is a lightweight open-source Python package for loading fcs files into AnnData objects.
Simply use
readto get started.Use
ReadFCSclass to access advanced features such as compensation.Use
viewto 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 | $PnE | $PnV | $PnG | |
|---|---|---|---|---|---|---|---|---|
| FSC-A | 1 | FSC-A | 262144 | 32 | 0,0 | 510 | 1.0 | |
| FSC-H | 2 | FSC-H | 262144 | 32 | 0,0 | 510 | 1.0 | |
| FSC-W | 3 | FSC-W | 262144 | 32 | 0,0 | 510 | 1.0 | |
| SSC-A | 4 | SSC-A | 262144 | 32 | 0,0 | 310 | 1.0 | |
| SSC-H | 5 | SSC-H | 262144 | 32 | 0,0 | 310 | 1.0 | |
| SSC-W | 6 | SSC-W | 262144 | 32 | 0,0 | 310 | 1.0 | |
| CD95 | 7 | R660-A | CD95 | 262144 | 32 | 0,0 | 490 | 1.0 |
| CD8 | 8 | R780-A | CD8 | 262144 | 32 | 0,0 | 475 | 1.0 |
| CD27 | 9 | B515-A | CD27 | 262144 | 32 | 0,0 | 470 | 1.0 |
| CXCR4 | 10 | B710-A | CXCR4 | 262144 | 32 | 0,0 | 417 | 1.0 |
| CCR7 | 11 | V450-A | CCR7 | 262144 | 32 | 0,0 | 400 | 1.0 |
| LIVE/DEAD | 12 | V545-A | LIVE/DEAD | 262144 | 32 | 0,0 | 495 | 1.0 |
| CD4 | 13 | V605-A | CD4 | 262144 | 32 | 0,0 | 400 | 1.0 |
| CD45RA | 14 | V655-A | CD45RA | 262144 | 32 | 0,0 | 375 | 1.0 |
| CD3 | 15 | V800-A | CD3 | 262144 | 32 | 0,0 | 400 | 1.0 |
| CD49B | 16 | G560-A | CD49B | 262144 | 32 | 0,0 | 400 | 1.0 |
| CD14/19 | 17 | G610-A | CD14/19 | 262144 | 32 | 0,0 | 415 | 1.0 |
| CD69 | 18 | G660-A | CD69 | 262144 | 32 | 0,0 | 470 | 1.0 |
| CD103 | 19 | G780-A | CD103 | 262144 | 32 | 0,0 | 435 | 1.0 |
| Time | 20 | Time | 262144 | 32 | 0,0 | 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