Read FCS files#
In this notebook, we load an fcs file into the anndata format, move the forward scatter (FCS) and sideward scatter (SSC) information to the .obs section of the anndata file and perform compensation on the data.
import readfcs
import pytometry as pm
Read data from readfcs package example.
path_data = readfcs.datasets.example()
adata = pm.io.read_fcs(path_data)
/home/runner/work/pytometry/pytometry/.nox/build-3-9/lib/python3.9/site-packages/fcsparser/api.py:440: UserWarning: The default channel names (defined by the $PnS parameter in the FCS file) were not unique. To avoid problems in downstream analysis, the channel names have been switched to the alternate channel names defined in the FCS file. To avoid seeing this warning message, explicitly instruct the FCS parser to use the alternate channel names by specifying the channel_naming parameter.
warnings.warn(msg)
adata
AnnData object with n_obs × n_vars = 65016 × 16
var: 'Channel Number', 'channel', 'marker', '$PnB', '$PnR', '$PnG'
uns: 'meta'
The .var section of the AnnData object contains the channel information. We set the marker names as var_names by default. In addition, we save the channel information in the "channel" column.
adata.var
| Channel Number | 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 |
The .uns['meta'] section contains the header information from the FCS file.
adata.uns["meta"]
{'__header__': {'FCS format': 'FCS2.0',
'text start': 58,
'text end': 5099,
'data start': 5120,
'data end': 4166142,
'analysis start': 0,
'analysis end': 0},
'tot': 65016,
'par': 16,
'mode': 'L',
'byteord': '4,3,2,1',
'fil': '100715.fcs',
'nextdata': 0,
'datatype': 'F',
'beginstext': '0',
'btim': '15:36:28',
'cyt': 'Main Aria (FACSAria)',
'date': '17-JUL-2007',
'endstext': '0',
'etim': '15:38:06',
'inst': ' ',
'op': 'Administrator',
'src': 'Specimen_001',
'sys': 'Windows XP 5.1',
'timestep': '0.08',
'apply compensation': 'TRUE',
'autobs': 'TRUE',
'cd age': '19.6',
'CD CD4, %CM': '.',
'CD CD4, %EM': '.',
'CD CD4, %N': '.',
'CD CD4, %TM': '.',
'cd event censor': '0',
'cd first viral load': '2024',
'cd first viral load date': '11/09/1999',
'CD Gag/100 CD4 Cells': '.',
'CD Gag/100 CM Cells': '.',
'CD Gag/100 EM Cells': '.',
'CD Gag/100 N Cells': '.',
'CD GAG/100 TM CELLS': '.',
'cd seroconversion datae': '04/30/1999',
'cd survival time from seroconversion': '63',
'cd time from seroc to sample': '194',
'cytnum': '1',
'experiment name': '070717_AB02_tb',
'export time': '17-JUL-2007-16:04:38',
'export user name': 'Administrator',
'final pin': '100715',
'FJ_P17R': '262144',
'fj_timestep': '0.01',
'fj_compmatrixname': ' ',
'fsc asf': '0.63',
'guid': '0d8e743a-05fe-4e8b-9ec4-25993c124ee2',
'index': '416',
'LASER1ASF': '0.66',
'LASER1DELAY': '0.00',
'LASER1NAME': 'Blue',
'LASER2ASF': '0.55',
'LASER2DELAY': '-59.80',
'LASER2NAME': 'Red',
'LASER3ASF': '0.48',
'LASER3DELAY': '-24.40',
'LASER3NAME': 'Violet',
'LASER4ASF': '0.53',
'LASER4DELAY': '-82.60',
'LASER4NAME': 'Green',
'live cells recovered': ' ',
'pin': ' ',
'pin check': ' ',
'sort type': 'SORT',
'spill': KI67 CD3 CD28 CD45RO CD8 CD4 CD57 \
KI67 1.000000 0.000000 0.000000 0.000088 0.000249 0.000645 0.007198
CD3 0.000000 1.000000 0.071188 0.148448 0.338903 0.009717 0.000000
CD28 0.000000 0.331405 1.000000 0.061965 0.120979 0.004053 0.000000
CD45RO 0.000000 0.088621 0.389424 1.000000 0.029759 0.065553 0.000000
CD8 0.000000 0.136618 0.010757 0.000000 1.000000 0.000156 0.000000
CD4 0.000000 0.000124 0.019463 0.218206 0.004953 1.000000 0.003583
CD57 0.000000 0.000000 0.000000 0.000000 0.001056 0.002287 1.000000
CD14 0.000000 0.000000 0.000000 0.000000 0.000000 0.008118 0.170066
CCR5 0.003122 0.008526 0.001024 0.001163 0.125401 0.018142 0.193646
CD19 0.002015 0.069645 0.194715 0.001008 0.151611 0.001270 0.007133
CD27 0.001685 0.054340 0.277852 0.343008 0.061753 0.077523 0.004263
CCR7 0.000000 0.008713 0.048213 0.073190 0.150563 0.386293 0.101896
CD127 0.001684 0.000000 0.000000 0.000095 0.003463 0.015712 0.174122
CD14 CCR5 CD19 CD27 CCR7 CD127
KI67 0.0 0.000000 0.000131 0.000067 0.000582 0.002520
CD3 0.0 0.301380 0.007478 0.012354 0.000000 0.000000
CD28 0.0 0.109117 0.100314 0.005832 0.000000 0.000000
CD45RO 0.0 0.031294 0.039306 0.091375 0.000396 0.000057
CD8 0.0 0.483235 0.014858 0.000000 0.000000 0.000000
CD4 0.0 0.001311 0.029646 0.408902 0.006506 0.000119
CD57 0.0 0.000389 0.000194 0.000000 0.062551 0.132484
CD14 1.0 0.000000 0.000000 0.000000 0.000000 0.000000
CCR5 0.0 1.000000 0.066898 0.161456 0.286823 1.238037
CD19 0.0 1.150032 1.000000 0.016077 0.014674 0.055352
CD27 0.0 0.497488 0.743923 1.000000 0.010329 0.037635
CCR7 0.0 0.370277 0.613490 1.218024 1.000000 0.065211
CD127 0.0 0.023802 0.049474 0.132511 0.239216 1.000000 ,
'threshold': 'FSC,27000',
'tube name': 'Tube_025',
'viability': ' ',
'vial id': '100715',
'vrc id': ' ',
'window extension': '3.00',
'creator': 'LYSYS',
'P1BS': '0',
'P1DISPLAY': 'LIN',
'P1MS': '0',
'P2BS': '0',
'P2DISPLAY': 'LIN',
'P2MS': '0',
'P3BS': '0',
'P3DISPLAY': 'LOG',
'P3MS': '0',
'P4BS': '0',
'P4DISPLAY': 'LOG',
'P4MS': '0',
'P5BS': '2926',
'P5DISPLAY': 'LOG',
'P5MS': '0',
'P6BS': '1162',
'P6DISPLAY': 'LOG',
'P6MS': '0',
'P7BS': '1849',
'P7DISPLAY': 'LOG',
'P7MS': '0',
'P8BS': '2029',
'P8DISPLAY': 'LOG',
'P8MS': '0',
'P9BS': '3343',
'P9DISPLAY': 'LOG',
'P9MS': '0',
'P10BS': '331',
'P10DISPLAY': 'LOG',
'P10MS': '0',
'P11BS': '0',
'P11DISPLAY': 'LOG',
'P11MS': '0',
'P12BS': '14511',
'P12DISPLAY': 'LOG',
'P12MS': '0',
'P13BS': '6053',
'P13DISPLAY': 'LOG',
'P13MS': '0',
'P14BS': '9362',
'P14DISPLAY': 'LOG',
'P14MS': '0',
'P15BS': '557',
'P15DISPLAY': 'LOG',
'P15MS': '0',
'P16BS': '9808',
'P16DISPLAY': 'LOG',
'P16MS': '0',
'begindata': ' 5120',
'enddata': ' 4166143',
'_channels_': $PnN $PnS $PnB $PnR $PnG
Channel Number
1 FSC-A 32 262207 1
2 FSC-H 32 262207 1
3 SSC-A 32 261588 1
4 B515-A KI67 32 261588 1
5 R780-A CD3 32 261588 1
6 R710-A CD28 32 261588 1
7 R660-A CD45RO 32 261588 1
8 V800-A CD8 32 261588 1
9 V655-A CD4 32 261588 1
10 V585-A CD57 32 261588 1
11 V450-A CD14 32 261588 1
12 G780-A CCR5 32 261588 1
13 G710-A CD19 32 261588 1
14 G660-A CD27 32 261588 1
15 G610-A CCR7 32 261588 1
16 G560-A CD127 32 261588 1,
'_channel_names_': ['FSC-A',
'FSC-H',
'SSC-A',
'B515-A',
'R780-A',
'R710-A',
'R660-A',
'V800-A',
'V655-A',
'V585-A',
'V450-A',
'G780-A',
'G710-A',
'G660-A',
'G610-A',
'G560-A'],
'header': {'FCS format': 'FCS2.0',
'text start': 58,
'text end': 5099,
'data start': 5120,
'data end': 4166142,
'analysis start': 0,
'analysis end': 0},
'channels': $PnN $PnS $PnB $PnR $PnG
Channel Number
1 FSC-A 32 262207 1
2 FSC-H 32 262207 1
3 SSC-A 32 261588 1
4 B515-A KI67 32 261588 1
5 R780-A CD3 32 261588 1
6 R710-A CD28 32 261588 1
7 R660-A CD45RO 32 261588 1
8 V800-A CD8 32 261588 1
9 V655-A CD4 32 261588 1
10 V585-A CD57 32 261588 1
11 V450-A CD14 32 261588 1
12 G780-A CCR5 32 261588 1
13 G710-A CD19 32 261588 1
14 G660-A CD27 32 261588 1
15 G610-A CCR7 32 261588 1
16 G560-A CD127 32 261588 1}
Missing marker column#
In some FCS files, the marker information does not follow the $P[0-9]S pattern, and reading the FCS file might fail. You can set the reindex=False option when reading the FCS files.
adata = pm.io.read_fcs(path_data, reindex=False)
/home/runner/work/pytometry/pytometry/.nox/build-3-9/lib/python3.9/site-packages/fcsparser/api.py:440: UserWarning: The default channel names (defined by the $PnS parameter in the FCS file) were not unique. To avoid problems in downstream analysis, the channel names have been switched to the alternate channel names defined in the FCS file. To avoid seeing this warning message, explicitly instruct the FCS parser to use the alternate channel names by specifying the channel_naming parameter.
warnings.warn(msg)
adata
AnnData object with n_obs × n_vars = 65016 × 16
var: 'channel', 'marker', '$PnB', '$PnR', '$PnG'
uns: 'meta'
The .var section of the AnnData object contains the channel information. Here we use a running number as var_names. The marker names may be created manually from the channel column.
adata.var
| channel | marker | $PnB | $PnR | $PnG | |
|---|---|---|---|---|---|
| Channel Number | |||||
| 1 | FSC-A | 32 | 262207 | 1 | |
| 2 | FSC-H | 32 | 262207 | 1 | |
| 3 | SSC-A | 32 | 261588 | 1 | |
| 4 | B515-A | KI67 | 32 | 261588 | 1 |
| 5 | R780-A | CD3 | 32 | 261588 | 1 |
| 6 | R710-A | CD28 | 32 | 261588 | 1 |
| 7 | R660-A | CD45RO | 32 | 261588 | 1 |
| 8 | V800-A | CD8 | 32 | 261588 | 1 |
| 9 | V655-A | CD4 | 32 | 261588 | 1 |
| 10 | V585-A | CD57 | 32 | 261588 | 1 |
| 11 | V450-A | CD14 | 32 | 261588 | 1 |
| 12 | G780-A | CCR5 | 32 | 261588 | 1 |
| 13 | G710-A | CD19 | 32 | 261588 | 1 |
| 14 | G660-A | CD27 | 32 | 261588 | 1 |
| 15 | G610-A | CCR7 | 32 | 261588 | 1 |
| 16 | G560-A | CD127 | 32 | 261588 | 1 |