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 $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