Converter XLSX para GCT

Aplicações de genômica, como GSEA e GenePattern, exigem matrizes de expressão no formato GCT, enquanto os laboratórios normalmente recebem essas matrizes como pastas de trabalho do Excel. A conversão da pasta de trabalho é necessária antes que os dados possam ser importados para essas ferramentas, compartilhados como uma matriz simples ou processados de forma reproduzível.

O que é o formato XLSX

XLSX é o formato de pasta de trabalho baseado em XML usado pelo Microsoft Excel, LibreOffice Calc, Apple Numbers e muitos sistemas laboratoriais ou de geração de relatórios. Ele pode conter várias planilhas, fórmulas, formatação, gráficos, células mescladas, metadados e tipos de dados mistos. Uma planilha de expressão normalmente coloca os identificadores de recursos na primeira coluna, as descrições na segunda e as medições das amostras nas colunas restantes.

O que é o formato GCT

Em genômica, GCT significa Gene Cluster Text. É um formato de matriz de texto simples delimitado por tabulações usado pelo Broad GSEA, GenePattern e softwares compatíveis de análise de expressão. Um arquivo GCT 1.2 padrão contém:

• #1.2 na primeira linha;
• o número de linhas de recursos e colunas de amostras na segunda linha;
• um cabeçalho iniciado por Name e Description, seguido pelos nomes das amostras;
• uma linha para cada gene, probe, transcrito ou outro recurso medido.

Os arquivos GCT são menores e mais fáceis de analisar pelo software de análise do que as pastas de trabalho formatadas. Eles não preservam a formatação do Excel, fórmulas, gráficos, células mescladas, várias planilhas ou metadados da pasta de trabalho.

Prepare a planilha

Antes de exportar, selecione a planilha que contém a matriz e remova linhas de título, observações, totais, registros vazios e colunas não relacionadas. Organize os dados da seguinte forma:

• Coluna A: um identificador de recurso estável, como um símbolo de gene, ID de probe ou ID Ensembl;
• Coluna B: uma descrição ou uma coluna vazia caso não haja descrições disponíveis;
• Colunas C em diante: somente valores numéricos das amostras.

Use uma linha por recurso, identificadores de recursos exclusivos quando exigido pelo software de destino e nomes de amostras não vazios, sem tabulações ou quebras de linha. Decida se os valores são contagens brutas, valores normalizados ou valores transformados em log antes da conversão; alterar XLSX para GCT não normaliza nem modifica de outra forma os dados biológicos.

Converta com Python

Python com pandas e openpyxl fornece uma conversão reproduzível e expõe células malformadas em vez de tentar adivinhar silenciosamente seu significado. Instale os pacotes com:

python -m pip install pandas openpyxl

Salve este script como xlsx_to_gct.py. Ele pressupõe que a primeira planilha tenha o layout descrito acima.

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")

Execute-o com python xlsx_to_gct.py. Abra output.gct em um editor de texto e verifique se a segunda linha contém o número real de linhas de recursos e colunas de amostras e se a primeira linha de dados vem imediatamente após o cabeçalho.

Alternativas para desktop e baseadas na web

Para um fluxo de trabalho gráfico em desktop, use LibreOffice Calc ou Excel para limpar a planilha e exportá-la como um arquivo de texto delimitado por tabulações; em seguida, adicione a linha de versão do GCT, a linha de dimensões e os cabeçalhos Name/Description com um editor de texto ou script de conversão. Salvar diretamente como TSV não é suficiente, a menos que essas linhas específicas do GCT sejam adicionadas.

O servidor web do GenePattern inclui módulos de conversão de conjuntos de dados e pré-processamento nas instalações que os disponibilizam. Exporte primeiro a planilha para TSV e, em seguida, use o fluxo de trabalho ConvertDataset aplicável para produzir ou validar a saída GCT. Os nomes dos módulos e os formatos de entrada aceitos variam conforme a configuração do servidor.

Serviços online gerais, como conversores de formatos de arquivo, normalmente não entendem o cabeçalho GCT necessário nem a semântica da matriz de expressão. Eles também podem expor dados genômicos a terceiros. Use um serviço online somente quando ele oferecer suporte explícito à versão GCT necessária e os dados puderem sair do seu ambiente; caso contrário, use Python localmente, Excel/Calc ou GenePattern.

Compatibilidade e verificações de qualidade

O GCT 1.2 espera valores numéricos na matriz. Textos como NA, vírgulas usadas como separadores de milhares, unidades, fórmulas ou colunas de anotação devem ser limpos antes da conversão. Se a pasta de trabalho contiver fórmulas, recalcule-a e salve-a no Excel ou LibreOffice antes de lê-la; alguns leitores usam resultados armazenados em cache para as fórmulas e, caso contrário, podem retornar valores vazios ou desatualizados.

As contagens de linhas e colunas na segunda linha excluem as colunas Name e Description. Não adicione uma linha vazia extra, vírgulas de CSV ou uma marca de ordem de bytes UTF-8, a menos que o software de destino documente suporte para esses elementos. Se o aplicativo de destino solicitar GCT 1.3 ou outra variante, gere exatamente essa versão em vez de presumir que o GCT 1.2 seja intercambiável. A extensão .gct também é usada por programas não relacionados; portanto, verifique se o destino espera Gene Cluster Text.