ISAC’s Classification Results File Format (CLR)

Abstract

Identifying homogenous sets of cell populations in flow cytometry is an important process for sorting and selecting populations of interests for further data acquisition and analysis. Many computational methods are now available to automate this process, with several algorithms partitioning cells based on high-dimensional separation versus the traditional pairwise two-dimensional visualization approach of manual gating. ISAC’s Classification Results File Format (CLR) was developed to exchange the results of both manual gating and algorithmic classification approaches in a standardized way based on per event based classifications, including the potential for soft classifications expressed as the probability of an event being a member of a class.

Introduction

Traditionally, manual gating has been the core of flow cytometry data analysis that is supported by virtually all flow cytometry analysis software. With manual gating, boundaries are drawn to select populations of interest. A standardized way of exchanging unambiguous descriptions of these boundaries is crucial for interoperability among flow cytometry software. This need is being addressed by efforts to develop the Gating-ML [1] specification, which allows for unambiguous gate definitions based on population boundaries in multidimensional space. Recently, the increased amount of high-throughput and high-content flow cytometry data [2] motivated the development of various automated methods to supplement manual gating [3]. The results of these methods are often per event based classifications assigning events (cells) to a certain class (i.e., a cell type). These assignments can include soft classifications expressed as the probability of an event being a member of a class. Often, there are no unambiguous boundaries that would enclose these events. Consequently, Gating-ML is not suitable to capture these algorithmically classified events.

The Classification Results File Format has been developed by the International Society for Advancement of Cytometry (ISAC) Data Standards Task Force to address the need for a standard means for the exchange of the results of cell population classifications, both manual and automated. This format has been developed to be simple to process by any software application written in any programming language as well as to be editable by humans using common spreadsheet programs.

Materials and Methods

The CLR specification was developed reusing the methodology and best practices from international standardization bodies, such as the World Wide Web Consortium (W3C), the Institute of Electrical and Electronics Engineers (IEEE), and the Internet Engineering Task Force (IETF). This is reflected in the standardized terminology used through the specification, the structure of the specification as well as the process of development and ISAC’s approval of the standard. The CLR file format is based on the widely used comma-separated values (CSV) spreadsheet format [4], which ensures compatibility with common spreadsheet programs and maintains simplicity that is allowing for an easy integration in existing tools.

Results

The full specification of the CLR file format is included in the supplemental material and can also be obtained from ISAC. A valid CLR file shall be named with the .csv file name extension and shall follow the requirements of a valid CSV spreadsheet file as specified by RFC 4180 [4]. In the CLR CSV spreadsheet, columns correspond to classes, column headings to class names, and rows to events (e.g., cells). The order of rows in the spreadsheet shall correspond to the order of events in the list mode data file (e.g., FCS file [5]) that has been classified, and there shall be a one-to-one correspondence between rows in the spreadsheet and events in the classified data file. The data in the spreadsheet shall express the probability of the particular event being a member of the particular class.

Line endings

The CSV specification requires that line endings be encoded as a sequence of two characters: CR (Carriage Return, ASCII code 0D hex) and LF (Line Feed, ASCII code 0A hex). Therefore, in order to be fully compliant, line endings in a CLR file should be encoded as a sequence of these two characters. This is a common practice of encoding line endings on the MS Windows platform. Unfortunately, Mac OS X and Linux/Unix-like operating systems use only a single LF character to encode line endings in text based files. Older Apple computers (up to Mac OS version 9) use a single CR character. These platform-specific line endings are also used by some spreadsheet tools when saving CSV files. Consequently, in order to increase interoperability, software applications reading CLR files should be able to handle line endings encoded either as a sequence of CR+LF, or as single LF or CR characters.

Class names

The names of the classes that events are assigned to shall be stated as column headings in the first row of the CLR file. UTF-8 [6] encoding shall be used if characters outside of the standard ASCII [7] character set are required (i.e., if international characters are part of a class name). Class names shall be unique within a single CLR file.

Line breaks, double quotes, or commas that are part of a class name shall be handled according to the CSV specification. Specifically, class names containing line breaks, double quotes, or commas shall be enclosed in double-quotes. If double-quotes are used to enclose a class name, then a double-quote appearing inside the class name shall be escaped by preceding it with another double quote.

Class assignments

Starting on the second row (i.e., after the headings), the fields (cell values) in the spreadsheet shall express the probability of the particular event being a member of the class stated in the corresponding column heading. Let c₁, c₂, …, c_k be the class names stated in the header of the CLR file and let e₁, e₂, …, e_n be the events as in the original datafile (e.g., FCS file) used to perform the classification. Then, the field f_i+1,j (i, j ∈ ℕ, i ∈ [1, n], j ∈ [1, k]) in the CLR file (i.e., the field in the row i + 1 and column j) shall express the probability that the event e_i is a member of class c_j.

For definite class assignments, the value zero (0) shall be used to state that the event is not a member of a specific class according to these classification results. The value shall be ASCII-encoded, i.e., the character ASCII code 30 hex shall be used. The value one (1) encoded as the ASCII code 31 hex shall be used to specify that the event is a member of the class.

For soft classifications, a floating-point number from the interval [0, 1] shall be used to express that an event is a member of a specific class with specified probability. Specifically, the value v, v ∈ ℝ, v ∈ [0, 1], shall be used to state that a specific event is a member of a specific class with the probability of v. Note that the sum of values in any particular row may differ from 1 as the classes are not necessarily mutually exclusive (which can result in a sum greater than 1), and also, classes defined in the CLR file do not necessarily enumerate all possible options (which can lead to a sum less than 1). A floating-point number from the interval [0, 1] may also be used to express fractional class membership.

The value v shall be encoded in ASCII with the point character (ASCII code 2E hex) used as a decimal separator. No other separators shall be used. A leading zero may or may not be used (i.e., the value may start with the decimal separator). There shall be no white space characters in the ASCII representation of the value. The value v may be expressed using the so called E notation [8]. In this form of scientific notation, values are expressed in the form of aEb, where a ∈ ℝ is any real number, b ∈ ℕ is an integer, and the construct shall be interpreted as a * 10^b. Either the character “E” (ASCII code 45 hex) or the character “e” (ASCII code 65 hex) may be used to separate the coefficient a from the exponent b. Both a and b shall be encoded in ASCII with the point character used as a decimal separator. No other separators or white space characters shall be used. Consequently, only the following ASCII characters may be used to encode v in a CLR file: “-”, “.”, “E”, “e”, “0”, “1”, “2”, “3”, “4”, “5”, “6”, “7”, “8” and “9”.

An empty value shall be used to state that the probability of an event being a member of a specific class is not known. An empty value shall be separated from preceding and following values by a comma. Examples of various CLR files with definite and soft classifications, distinct and overlapping classes, E notation, as well as unknown values are included in the supplemental information of this manuscript.

Discussion

A floating-point number may be used to express either membership probability or fractional class membership. However, in flow cytometry (and in other domains), distinguishing between membership probability and fractional membership can become a grey area, or a matter of personal view. For example with respect to T cells, since CD3 is a “defining” antigen, one could make a good case that we are looking at the probability of membership: a cell either expresses CD3, or it does not, and in that sense, it is either a T cell, or it is not. But CD3 becomes downregulated when the cells are activated and therefore, it may be preferable to ask “how T-ish the cell is”. Cell differentiation and oncogenic transformation are other examples where fractional membership can be meaningful. During differentiation, a cell can start in one class and differentiate into another class. During this period, the cell would be expected to show antigens that are associated with the parent as well as the child classes. Similarly, there are intermediate forms during a malignant transformation. Even cell death could be seen as an example of fractional class membership. While a cell can be completely dead or fresh ex vivo and very much alive, cell death is a process with intermediate events that may be better thought of as how far along are the cells in the dying process rather than the probability that they are dead. Generally, the distinction between membership probability and fractional membership can be made on conceptual grounds pertinent to what is being measured, which may be captured by choosing an appropriate class label in the CLR file.

The CLR format does not distinguish between events with unknown class labels and events with intentionally unassigned class labels. The former may indicate that there is not enough information to classify an event, while the latter typically indicates an outlying event that is being ignored in the classification. We recommend defining a separate “outlier” class in applications where such a distinction is required by simply adding a separate “outlier” column in the CLR file.

The CLR file format has been designed as a simple file format that is compatible with common spreadsheet tools, editable by humans using basic text editors (such as Notepad) and easily supported by third party software tools due to the existing support of CSV in virtually every programming language [9]. The format has not been optimized for space or performance purposes (e.g., a quick lookup of all events belonging to a specific class). This is not a problem as CLR is a file interchange format, not the internal representation in software. The use of lossless compression tools, such as ZIP, is recommended in order to reduce the file size for communication and storage purposes. CLR files compress extremely well. For example, a CLR file with a definite classification of 30,000 events into 3 overlapping classes requires approximately 210 kB (7 bytes per event), but it compresses to as little as 3.4 kB using ZIP. ZIP is also automatically used when CLR files are bundled inside the proposed Archival Cytometry Standard (ACS) [10] file format, which is the preferred mechanism of defining a link between FCS data files and CLR results.

The utility of this file format has already been shown by the use of CLR by participants of FlowCAP [3] to submit results of their automated clustering algorithms. While the format is very simple, there are several aspects that need to be unified and formally specified in order to avoid unnecessary variations that would lead to incompatibility. An early standardization in this aspect is critical, especially now that we are experiencing a spike in the development of computational methods to supplement manual gating [11, 12]. Finally, while the CLR format has been developed to address event-based classification in the field of flow cytometry, it is generally applicable in any biological and non-biological domain that needs to capture either soft or unambiguous classifications of any objects.

By publishing this standard, we are aiming to spread awareness of this file format to facilitate its adoption by additional analysis tools. In addition, we wish to avoid unnecessary variations and incompatibility issues as new computational algorithms and tools are being developed in flow cytometry.