Convert XLSX to GCT

Genomics applications such as GSEA and GenePattern require expression matrices in GCT format, while laboratories commonly receive those matrices as Excel workbooks. Converting the workbook is necessary before the data can be imported into these tools, shared as a plain matrix, or processed reproducibly.

What the XLSX format is

XLSX is the XML-based workbook format used by Microsoft Excel, LibreOffice Calc, Apple Numbers, and many laboratory or reporting systems. It can contain multiple worksheets, formulas, formatting, charts, merged cells, metadata, and mixed data types. An expression worksheet typically places feature identifiers in the first column, descriptions in the second, and sample measurements in the remaining columns.

What the GCT format is

In genomics, GCT means Gene Cluster Text. It is a tab-delimited plain-text matrix format used by Broad GSEA, GenePattern, and compatible expression-analysis software. A standard GCT 1.2 file contains:

• #1.2 on the first line;
• the number of feature rows and sample columns on the second line;
• a header beginning with Name and Description, followed by sample names;
• one row for each gene, probe, transcript, or other measured feature.

GCT files are smaller and easier for analysis software to parse than formatted workbooks. They do not preserve Excel formatting, formulas, charts, merged cells, multiple worksheets, or workbook metadata.

Prepare the worksheet

Before exporting, select the worksheet that contains the matrix and remove title rows, notes, totals, blank records, and unrelated columns. Arrange the data as follows:

• Column A: a stable feature identifier such as a gene symbol, probe ID, or Ensembl ID;
• Column B: a description, or an empty column if no descriptions are available;
• Columns C onward: numeric sample values only.

Use one row per feature, unique feature identifiers where required by the destination software, and nonempty sample names without tabs or line breaks. Decide whether the values are raw counts, normalized values, or log-transformed values before conversion; changing XLSX to GCT does not normalize or otherwise alter the biological data.

Convert with Python

Python with pandas and openpyxl provides a repeatable conversion and exposes malformed cells instead of silently guessing their meaning. Install the packages with:

python -m pip install pandas openpyxl

Save this script as xlsx_to_gct.py. It assumes the first worksheet has the layout described above.

import pandas as pd

source = "input.xlsx"
target = "output.gct"
df = pd.read_excel(source, sheet_name=0)

if df.shape[1] < 3:
    raise ValueError("The worksheet needs ID, Description, and at least one sample column")

ids = df.iloc[:, 0]
descriptions = df.iloc[:, 1].fillna("").astype(str)
samples = df.iloc[:, 2:].apply(pd.to_numeric, errors="coerce")

if ids.isna().any() or ids.astype(str).str.strip().eq("").any():
    raise ValueError("Feature identifiers cannot be blank")
if ids.astype(str).duplicated().any():
    raise ValueError("Feature identifiers must be unique")
if samples.isna().any().any():
    raise ValueError("Sample columns contain blank or nonnumeric values")
if any("\t" in str(x) or "\n" in str(x) for x in list(ids) + list(samples.columns)):
    raise ValueError("Identifiers and sample names cannot contain tabs or line breaks")

with open(target, "w", encoding="utf-8", newline="") as file:
    file.write("#1.2\n")
    file.write(f"{len(df)}\t{len(samples.columns)}\n")
    file.write("Name\tDescription\t" + "\t".join(str(x) for x in samples.columns) + "\n")
    for row in range(len(df)):
        values = "\t".join(str(x) for x in samples.iloc[row])
        file.write(f"{ids.iloc[row]}\t{descriptions.iloc[row]}\t{values}\n")

Run it with python xlsx_to_gct.py. Open output.gct in a text editor and check that the second line contains the actual number of feature rows and sample columns, and that the first data row follows the header immediately.

Desktop and web-based alternatives

For a graphical desktop workflow, use LibreOffice Calc or Excel to clean the worksheet and export it as a tab-delimited text file, then add the GCT version line, dimension line, and Name/Description headers with a text editor or conversion script. Saving directly as TSV is not sufficient unless those GCT-specific lines are added.

GenePattern's web server includes dataset-conversion and preprocessing modules in installations that provide them. Export the worksheet to TSV first, then use the applicable ConvertDataset workflow to produce or validate GCT output. Module names and accepted input formats vary by server configuration.

General online services such as file-format converters usually do not understand the required GCT header and expression-matrix semantics. They may also expose genomic data to a third party. Use an online service only when it explicitly supports the required GCT version and the data is permitted to leave your environment; otherwise use local Python, Excel/Calc, or GenePattern.

Compatibility and quality checks

GCT 1.2 expects numeric matrix values. Text such as NA, commas used as thousands separators, units, formulas, or annotation columns must be cleaned before conversion. If the workbook contains formulas, recalculate and save it in Excel or LibreOffice before reading it; some readers use cached formula results and may otherwise return blank or stale values.

The row and column counts in the second line exclude the Name and Description columns. Do not add an extra blank line, CSV commas, or a UTF-8 byte-order mark unless the destination software documents support for them. If the target application requests GCT 1.3 or another variant, generate that exact version rather than assuming that GCT 1.2 is interchangeable. The .gct extension is also used by unrelated programs, so verify that the destination expects Gene Cluster Text.