File Exchange

image thumbnail

fca_readfcs

version 2020.04.11 (6.46 KB) by Laszlo Balkay

Laszlo Balkay (view profile)
Read FCS 2.0, FCS 3.0 and FCS3.1 format flow cytometry files
4.6
17 Ratings

12 Downloads

Updated 14 Apr 2020

View License

[fcsdat, fcshdr, fcsdatscaled, fcsdat_comp] = fca_readfcs(filename);
Read FCS 2.0, FCS 3.0 and FCS 3.1 type flow cytometry data file and creates fcsdat array with the size of [NumOfPar TotalEvents].

Some important header data are also stored in the fcshdr structure:
TotalEvents, NumOfPar, starttime, stoptime and specific info for parameters
as name, range, bitdepth, logscale(yes-no) and number of decades.
[fcsdat, fcshdr] = fca_readfcs;
Without filename input the user can select the desired file using the standard open file dialog box.

[fcsdat, fcshdr, fcsdatscaled] = fca_readfcs(filename);
Supplying the third output the fcsdatscaled array contains also the scaled parameters. It might be useful for logscaled parameters.
[fcsdat, fcshdr, fcsdatscaled, fcsdat_comp] = fca_readfcs(filename);
In that case the script calculates the compensated fluorescence
intensities (fcsdat_comp) as well, if spillover data exist in the header
The program should work also in the case of Becton EPics DLM FCS2.0, CyAn Summit FCS3.0, FACSDiva, BD LSR-II, Partec, Accuri, Luminex, Attune NxT and Biorad ZE5 type list mode files. Not sure if it is fully FCS3.1 compliant.
If you find unsupported LM file type please email me.

Cite As

Laszlo Balkay (2020). fca_readfcs (https://www.mathworks.com/matlabcentral/fileexchange/9608-fca_readfcs), MATLAB Central File Exchange. Retrieved .

Comments and Ratings (30)

Caleb Stoltzfus

Caleb Stoltzfus (view profile)

Laszlo Balkay

Laszlo Balkay (view profile)

Hi Joydeb,

Could you share with me test files to check the error, please?
(balkay.laszlo@med.unideb.hu or any other transfer option would be ok)

kind regards
Laszlo

Joydeb Sinha

Joydeb Sinha (view profile)

Great work on this resource Laszlo! It's worked well for FCS 3.0 data from our old Beckman CytoflexS, however, I get the errors when loading FCS 3.1 files from the Biorad ZE5 cytometer (a new instrument we just bought). I can provide you with a sample fcs file if you would like to take a look. Here is the error.

Output argument "mneval" (and maybe others) not assigned during call to
"fca_readfcs>get_mnemonic_value". Error in fca_readfcs (line 177)
fcshdr.TotalEvents = str2num(get_mnemonic_value('$TOT',fcsheader_main,
mnemonic_separator));

Laszlo Balkay

Laszlo Balkay (view profile)

Hi Jake,

Could you sent me a test file to check and fix the problem you commented, please?
(balkay.laszlo@med.unideb.hu)

all the best
Laszlo

Jake Beal

Jake Beal (view profile)

I have found a bug that needs fixing: in the line "comp = get_mnemonic_value('SPILL',fcsheader_main,mnemonic_separator);", the value should be "SPILLOVER" rather than "SPILL" per FCS 3.1 standard. I just ran into a file using SPILLOVER and the current version crashes since it's trying to parse "VER" as the spillover matrix.

Tianmin Wang

Tianmin Wang (view profile)

Great work, enjoying it now!

Bharat Ravi

Bharat Ravi (view profile)

RecBCD

RecBCD (view profile)

Krystian Fita

Krystian Fita (view profile)

Works great! Thank you so much for that wonderful piece of software!

Sebastian Bech-Terkilsen

Sebastian Bech-Terkilsen (view profile)

Dear Laszlo, this worked like a charm for data produced by a BD FacsJAZZ system (fsc3.0). Well done!

Mikhail Monakhov

Mikhail Monakhov (view profile)

Laszlo Balkay

Laszlo Balkay (view profile)

Hi Edwin,
Thanks for your comment and the suggested solution. Could you send me an example file for this, please?
Laszlo
(laszlo.balkay@med.unideb.hu)

Edwin Wintermute

Edwin Wintermute (view profile)

Thanks so much for this!
I had a bug reading fcs 3.1 files from a Gallios machine running Kaluza software.
Non-finite endpoints or increment for colon operator in
index (line 198) fcshdr.CompLabels=compcell(2:nc+1);

I was able to fix this by altering line 191 to reference the mnemonic value 'SPILLOVER' instead of 'SPILL'
comp = get_mnemonic_value('SPILLOVER',fcsheader_main,mnemonic_separator);

This was just a kludge, as I know nothing about fcs formats. But it is working for me now.

John-William Sidhom

John-William Sidhom (view profile)

Great piece of code. Just having one issue. When I import compensated data (that has been compensated post-acquisition on DIVA), the code just takes in the raw data, not the compensated data. Unfortunately, the compdata output is empty as well. Thoughts on how to import compensated data from an fcs file, not the raw data.

Thanks,

John-William Sidhom

John-William Sidhom (view profile)

romain kinet

romain kinet (view profile)

FCS 3.0 data from Attune NxT flow cytometer cannot be read either

romain kinet

romain kinet (view profile)

Hi every one! Is somebody was able to open an FCS 3.1 format file from the Attune NxT ? I applied correction provided by Matteo below but it doesn't work. fca_readfcs results in an empty matrix. Thank you

Laszlo Balkay

Laszlo Balkay (view profile)

Hi Matteo! I'v never tested the FCS 3.1 format with the fca_readfcs.m. If you could send a test file I'm going to try it. (via balkay.laszlo@med.unideb.hu or any cluod).

Matteo Ferla

Matteo Ferla (view profile)

I have a FCS3.1 file and it works perfectly once I opened the file (`>> open fca_readfcs`) and did search for `strcmp(fcsheader_type,'FCS3.0')` and adding a `|| strcmp(fcsheader_type,'FCS3.0')` after it on both instances.

Laszlo Balkay

Laszlo Balkay (view profile)

Hi Ariel! I have not worked with fcs file including multiple data set. If you sent (or share with) me your file I going to try to fix this.

Ariel L

Ariel L (view profile)

Should this code be able to extract multiple data sets from the FCS file? I can only get it to extract the first data set in a FCS 3.0 file. Thank you.

William

William (view profile)

Thank you for this code.

I had some trouble with it, because I had an FCS 3.0 file that had some parameters which were 16 bit and some which were 32 bit. As far as I can tell, that kind of mixing is allowed FCS 3.0, so I tried to change the code to handle it correctly.

In the part that actually reads the data, I changed

fcsdat = fread(fid,[fcshdr.NumOfPar fcshdr.TotalEvents],'uint16',machineformat)';

to

fcsdat = fread(fid,[sum([fcshdr.par.bit]/16) fcshdr.TotalEvents],'uint16',machineformat)';

and that seemed to take care of it. You may want to upgrade the other datatypes to use that same method, or some other even better method.

Also, my file used linefeed, ASCII code 10, as the mnemonic separator.

Thanks again!

Irena Kuzmanovska

Irena Kuzmanovska (view profile)

Thanks a lot for the script!
I was wondering if it is suitable for reading fcs files exported with the FlowJo software. Somehow I have difficulties reading them. Once read, the data looks different from what I actually see in FlowJo.
Cheers!

Sushant

Sushant (view profile)

I found the script very readable & well commented. Thank you!

If you have some time, I have a question; I have what seems to be a clear-cut header file off a MoFlo XPD. I didn't think the necessary tweaks to the script were iffy in any sense. Still, I'm having trouble reconciling the parsed output with the proprietary MoFlo software's values. There are orders of magnitude differences.

Again, I don't think it's an issue with your script at all.. I'm just a little lost.

I don't want to spam the thread (any further, that is), so I will only PM you more details if you reply.

Malcolm McFarland

Malcolm McFarland (view profile)

I was initially unable to get this code to read BD Influx FCS files created with Sortware software. I found that the mnemonic_separator is 'LF' (line feed) and the data precision is 'uint16'. I modified the get_mnemonic_value subfunction and the section that reads events. It now works well, although I think some header information is missing. Thanks for some very helpful code.

Avaneesh

Avaneesh (view profile)

This code can't be used to read Accuri C6 FCS3.0 files. I find that the mnemonic separator is '/'. Made the required changes in the code, works great.
Great code!

Quanyuan He

It works well, Thank you.

* *

*

Brian Harms

Overall nice file. One small error in the code: in line 181 (which converts log-scale FACS data to linear-scale data), the variable "fscdat" needs to be changed from uint16 to double in order for the code to work properly.

Ivan Cao-Berg

I find it is an excellent script. But I do have one comment.
In line 64 you can find the following code

fid = fopen(filename,'r','ieee-be');

If you are using a Windows, Matlab will not have a problem. If you are using Linux you should change the line to

fid = fopen(filename,'r','b');

Technically 'ieee-be' and 'b' are to suppose to be the same option. But I had problems and I fixed it that way.

Updates

2020.04.11

Update to read FCS3.1 data from Biorad ZE5
2017.11.1.0

Minor update to read FCS3.1 data of Attune NxT
2017.11.1.0

Minor update to read FCS3.1 data from Attune NxT
2017.6.1.0

The code was modified to read FCS 3.1 file.
1.12.0.0

The FCS 3.0 standard enables the mixture of word lengths in the data, this upgrade modified the code according to. The linefeed (ASCII code 10) as
the mnemonic separator was also added.
Thanks for William Peria /Fred Hutchinson Cancer Researc
1.11.0.0

More accurate compensation correction, gain scaling and appropriate reading for large file size are added. Thanks for Rachel Finck; Garry Nolan's lab at Stanford University and Andrea Pagnani; Politecnico Torino, Human Genetics Foundation.
1.9.0.0

The fluorescence compensation has been implemeted into the code. Thanks for Rick Stanton, J. Craig Venter Institute, La Jolla, San Diego
1.8.0.0

The fluorescence compensation has been implemented into the code. Thanks for Rick Stanton, J. Craig Venter Institute, La Jolla, San Diego
1.6.0.0

Updated to read Luminex 100 data file. Thanks for Ofir Goldberger, Stanford University
1.5.0.0

Additional minor changes on the help section.
1.3.0.0

The help section of the m file was modified.
1.2.0.0

Updated to read the Partec CyFlow format file. Thanks for
Gavin A Price

1.1.0.0

Updated to read the Partec CyFlow format file. Thanks for
Gavin A Price
1.0.0.0

Updated to read the BD LSR II file format and including the comments of Allan Moser (Cira Discovery Sciences, Inc.) Thanks!

Refreshing the code according to the user comments and updating the description.

Repairing the code suggested by Brian Harms and Ivan Cao-Berg at the user reviews. Thanks the comments!

Updated to read Becton EPics DLM FCS2.0 and CyAn Summit FCS3.0 type list mode files
MATLAB Release Compatibility
Created with R2018b
Compatible with any release
Platform Compatibility
Windows macOS Linux
Acknowledgements

Inspired: Ratiometric FRET, CytoMAP, Gating-ML