CAT_pack
v6.0.1
A Contig Annotation Tool (CAT) e a Bin Annotation Tool (BAT) são pipelines para a classificação taxonômica de longas sequências de DNA e genomas montados em metagenoma (MAGs/bins) de microrganismos conhecidos e (altamente) desconhecidos, conforme gerado por estudos metagenômicos contemporâneos. O algoritmo central de ambos os programas envolve chamada de genes, mapeamento de ORFs previstas em um banco de dados de proteínas e classificação baseada em votação de todo o contig/MAG com base na classificação das ORFs individuais. CAT e BAT podem ser executados a partir de etapas intermediárias se os arquivos estiverem formatados adequadamente.
Um artigo que descreve o algoritmo juntamente com benchmarks extensos pode ser encontrado em https://doi.org/10.1186/s13059-019-1817-x. Se você usa CAT ou BAT em sua pesquisa, seria ótimo se você pudesse nos citar:
A Read Annotation Tool (RAT) estima a composição taxonômica dos metagenomas usando resultados CAT e BAT. Um manuscrito descrevendo o RAT com benchmarks pode ser encontrado em https://doi.org/10.1038/s41467-024-47155-1. Se você usar RAT em sua pesquisa, seria ótimo se você pudesse citar:
Para citar o próprio código:
Python 3, https://www.python.org/.
DIAMANTE, https://github.com/bbuchfink/diamond.
Pródigo, https://github.com/hyattpd/Prodigal.
O RAT exige ainda (não é necessário para CAT e BAT):
BWA, https://github.com/lh3/bwa.
SAMtools, http://www.htslib.org/download/.
CAT, BAT e RAT foram exaustivamente testados em sistemas Linux e também devem ser executados no macOS.
Nenhuma instalação é necessária. Você pode executar CAT, BAT e RAT fornecendo o caminho absoluto:
$ ./CAT_pack/CAT_pack --help
Alternativamente, se você adicionar os arquivos no diretório CAT_pack à sua variável $PATH , poderá executar CAT, BAT e RAT de qualquer lugar:
$ CAT_pack --version
Para começar a usar CAT/BAT/RAT, você precisará obter os arquivos de banco de dados em seu sistema. Você pode baixar arquivos de banco de dados pré-construídos ou gerá-los você mesmo.
Para baixar os arquivos do banco de dados, encontre a versão mais recente em tbb.bio.uu.nl/tina/CAT_pack_prepare/, baixe e extraia, e você está pronto para começar!
Para o número do NCBI:
$ wget tbb.bio.uu.nl/tina/CAT_pack_prepare/20240422_CAT_nr.tar.gz
$ tar -xvzf 20240422_CAT_nr.tar.gz
Para GTDB:
$ wget tbb.bio.uu.nl/tina/CAT_pack_prepare/20231120_CAT_gtdb.tar.gz # release 214
$ tar -xvzf 20231120_CAT_gtdb.tar.gz
Em vez de usar o banco de dados pré-construído, você mesmo pode construir um novo banco de dados. O módulo download pode ser usado para baixar e processar dados brutos, em preparação para a construção de um novo banco de dados de pacotes CAT. Isso garantirá que todas as dependências de entrada sejam atendidas e formatadas corretamente para CAT_pack prepare .
Atualmente, dois bancos de dados são suportados, o nr do NCBI e as proteínas Genome Taxonomy Database (GTDB).
$ CAT_pack download -db nr -o path/to/nr_data_dir
Irá baixar o arquivo fasta com as sequências de proteínas, seu mapeamento para um taxid e as informações de taxonomia do site ftp do NCBI.
$ CAT_pack download -db gtdb -o path/to/gtdb_data_dir
Os arquivos necessários para construir um banco de dados de pacotes CAT são fornecidos pela página de downloads do GTDB.
CAT_pack download busca os arquivos necessários e faz algum processamento adicional para prepará-los para CAT_pack prepare :
nodes.dmp e names.dmp no estilo NCBI.gtdb_proteins_aa_reps.tar.gz e submetidas a uma rodada de desduplicação. A desduplicação reduz a redundância no banco de dados DIAMOND, simplificando assim o processo de alinhamento. Sequências duplicadas exatas são identificadas com base em uma combinação da soma MD5 das sequências proteicas e seu comprimento. Apenas uma sequência representativa é mantida, com todas as duplicatas codificadas no cabeçalho fasta. Esta informação é usada posteriormente pelo CAT_pack prepare para atribuir o LCA da sequência da proteína apropriadamente no arquivo .fastaid2LCAtaxid .root , para produzir um arquivo all.tree . Este arquivo não é usado pelo pacote CAT, mas pode ser útil para análises posteriores. Quando o download e o processamento dos arquivos forem concluídos com sucesso, você poderá construir um banco de dados CAT pack com CAT_pack prepare .
Para todas as opções de linha de comando disponíveis, consulte
$ CAT_pack download -h
e
$ CAT_pack prepare -h
Para um banco de dados de pacote CAT customizado, você deve ter a seguinte entrada pronta antes de iniciar uma execução CAT_pack prepare .
Um arquivo fasta contendo todas as sequências de proteínas que você deseja incluir em seu banco de dados.
Um names.dmp que contém mapeamentos de taxids para suas fileiras e nomes científicos. O formato deve ser igual ao names.dmp padrão do NCBI.dmp (usa t|t como separador de campo).
Um exemplo é assim:
1 | root | scientific name |
2 | Bacteria | scientific name |
562 | Escherichia coli | scientific name |
nodes.dmp que descreve o relacionamento filho-pai dos nós na árvore de taxonomia e sua classificação (oficial). O formato deve ser igual ao nodes.dmp padrão do NCBI (usa t|t como separador de campo).Um exemplo é assim:
1 | 1 | root |
2 | 1 | superkingdom |
1224 | 2 | phylum |
1236 | 1224 | class |
91437 | 1236 | order |
543 | 91347 | family |
561 | 543 | genus |
562 | 561 | species |
Para obter mais informações sobre os arquivos nodes.dmp e names.dmp , consulte NCBI taxdump_readme.txt.
accession.version taxid .Um exemplo é assim
accession.version taxid
protein_1 562
protein_2 123456
Depois que todos os requisitos acima forem atendidos, você poderá executar CAT_pack prepare . Todas as entradas precisam ser especificadas explicitamente para que CAT_pack prepare funcione, por exemplo:
$ CAT_pack prepare
--db_fasta path/to/fasta
--names path/to/names.dmp
--nodes path/to/nodes.dmp
--acc2tax path/to/acc2taxid.txt.gz
--db_dir path/to/output_dir
criará um output_dir parecido com este
output_dir
├── 2023-11-05_CAT_pack.log
├── db
│ ├── 2023-11-05_CAT_pack.dmnd
│ ├── 2023-11-05_CAT_pack.fastaid2LCAtaxid
│ └── 2023-11-05_CAT_pack.taxids_with_multiple_offspring
└── tax
├── names.dmp
└── nodes.dmp
Notas:
db e tax que contêm todos os arquivos necessários.nodes.dmp e names.dmp no diretório tax são copiados de seu local original. Isso é para garantir que o sinalizador -t de CAT, BAT e RAT funcione.<YYYY-MM-DD>_CAT_pack . Você pode personalizá-lo com a opção --common_prefix .Para todas as opções de linha de comando disponíveis, consulte
$ CAT_pack prepare -h
Os arquivos de banco de dados são necessários em execuções CAT/BAT/RAT subsequentes. Eles só precisam ser gerados/baixados uma vez ou sempre que você quiser atualizar o banco de dados.
Para executar CAT/BAT/RAT, respectivamente:
$ CAT_pack contigs # Runs CAT.
$ CAT_pack bins # Runs BAT.
$ CAT_pack reads # Runs RAT.
Se não tiver certeza de quais opções um programa possui, você pode adicionar --help a um comando. Esta é uma ótima maneira de começar com CAT, BAT ou RAT.
$ CAT_pack --help
$ CAT_pack contigs --help
$ CAT_pack summarise --help
Se você não tiver certeza sobre quais arquivos de entrada são necessários, basta executar CAT/BAT/RAT, pois as mensagens de erro apropriadas serão geradas se a formatação estiver incorreta.
Depois de obter os arquivos do banco de dados em seu sistema, você pode executar o CAT para anotar seu conjunto contig:
$ CAT_pack contigs -c {contigs fasta} -d {database folder} -t {taxonomy folder}
Vários arquivos de saída e um arquivo de log serão gerados. Os arquivos de classificação final serão denominados out.CAT.ORF2LCA.txt e out.CAT.contig2classification.txt .
Alternativamente, se você já possui um arquivo fasta de proteínas previstas e/ou uma tabela de alinhamento, por exemplo, de execuções anteriores, você pode fornecê-los ao CAT, que irá pular as etapas que já foram executadas e começar a partir daí:
$ CAT_pack contigs -c {contigs fasta} -d {database folder} -t {taxonomy folder} -p {predicted proteins fasta} -a {alignment file}
Os cabeçalhos no arquivo fasta de proteínas previstas devem ser assim >{contig}_{ORFnumber} , para que o CAT possa acoplar contigs a ORFs. O arquivo de alinhamento deve ser separado por tabulações, com ORF consultado na primeira coluna, número de acesso da proteína na segunda e pontuação de bits na 12ª.
Para executar o BAT em um conjunto de MAGs:
$ CAT_pack bins -b {bin folder} -d {database folder} -t {taxonomy folder}
Alternativamente, o BAT pode ser executado em um único MAG:
$ CAT_pack bins -b {bin fasta} -d {database folder} -t {taxonomy folder}
Vários arquivos de saída e um arquivo de log serão gerados. Os arquivos de classificação final serão denominados out.BAT.ORF2LCA.txt e out.BAT.bin2classification.txt .
Da mesma forma que o CAT, o MTD pode ser executado a partir de etapas intermediárias se a previsão e o alinhamento dos genes já tiverem sido realizados uma vez:
$ CAT_pack bins -b {bin folder} -d {database folder} -t {taxonomy folder} -p {predicted proteins fasta} -a {alignment file}
Se você já executou o CAT no conjunto de contigs dos quais os MAGs se originam, você pode usar a proteína prevista anteriormente e os arquivos de alinhamento para classificar os MAGs.
$ CAT_pack contigs -c {contigs fasta} -d {database folder} -t {taxonomy folder}
$ CAT_pack bins -b {bin folder} -d {database folder} -t {taxonomy folder} -p {predicted proteins fasta from contig run} -a {alignment file from contig run}
Esta é uma ótima maneira de executar CAT e BAT em um conjunto de MAGs sem precisar fazer previsão e alinhamento de proteínas duas vezes!
A saída ORF2LCA é semelhante a esta:
| ORF | número de acertos (r: 10) | linhagem | pontuação de bits |
|---|---|---|---|
| contig_1_ORF1 | 7 | 1;131567;2;1783272 | 574,7 |
Onde a linhagem é a linhagem taxonômica completa da classificação da ORF, e a pontuação de bits é a pontuação de bits mais atingida que é atribuída à ORF para votação. O arquivo de saída BAT ORF2LCA possui uma coluna extra onde os ORFs são vinculados ao MAG no qual são encontrados.
A saída contig2classification e bin2classification é semelhante a esta:
| contig ou bin | classificação | razão | linhagem | pontuações de linhagem (f: 0,3) |
|---|---|---|---|---|
| contig_1 | taxi atribuído | com base em ORFs 14/15 | 1;131567;2;1783272 | 1,00; 1,00; 1,00; 0,78 |
| contig_2 | taxi atribuído (1/2) | com base em ORFs 10/10 | 1;131567;2;1783272;17id98711;1117;307596;307595;1890422;33071;1416614;1183438* | 1,00;1,00;1,00;1,00;1,00;1,00;1,00;1,00;1,00;1,00;0,23;0,23 |
| contig_2 | taxi atribuído (2/2) | com base em ORFs 10/10 | 1;131567;2;1783272;1798711;1117;307596;307595;1890422;33071;33072 | 1,00;1,00;1,00;1,00;1,00;1,00;1,00;1,00;1,00;1,00;0,77 |
| contig_3 | nenhum taxi atribuído | nenhum ORF encontrado |
Onde as pontuações de linhagem representam a fração do suporte de pontuação de bits para cada classificação. contig_2 possui duas classificações. Isso pode acontecer se o parâmetro f for escolhido abaixo de 0,5. Para obter uma explicação da classificação com estrela , consulte Marcando atribuições taxonômicas sugestivas com um asterisco.
Para adicionar nomes aos taxids em qualquer arquivo de saída, execute:
$ CAT_pack add_names -i {ORF2LCA / classification file} -o {output file} -t {taxonomy folder}
Isso mostrará que, por exemplo, contig_1 é classificado como grupo Terrabacteria. Para obter apenas a classificação oficial ( ou seja , super-reino, filo, ...):
$ CAT_pack add_names -i {ORF2LCA / classification file} -o {output file} -t {taxonomy folder} --only_official
Ou, alternativamente:
$ CAT_pack add_names -i {ORF2LCA / classification file} -o {output file} -t {taxonomy folder} --only_official --exclude_scores
Se você nomeou um arquivo de classificação CAT ou BAT com nomes oficiais, poderá obter um resumo da classificação, onde o comprimento total e o número de ORFs que suportam um táxon são calculados para contigs, e o número de MAGs por táxon encontrado para classificação MAG:
$ CAT_pack summarise -c {contigs fasta} -i {named CAT classification file} -o {output file}
$ CAT_pack summarise -i {named BAT classification file} -o {output file}
CAT_pack summarise atualmente não suporta arquivos de classificação em que alguns contigs/MAGs têm classificações múltiplas (como contig_2 acima).
Quando queremos descer com confiança ao nível taxonômico mais baixo possível para uma classificação, uma suposição importante é que nesse nível poderia ter surgido conflito entre classificações. Ou seja, se houvesse classificações conflitantes, o algoritmo teria tornado a classificação mais conservadora ao subir um nível. Como isso não aconteceu, podemos confiar na classificação de baixo nível. No entanto, nem sempre é possível surgir conflito, porque em alguns casos nenhuma outra sequência do clado está presente no banco de dados. Isto é verdade, por exemplo, para a família Dehalococcoidaceae, que nas nossas bases de dados é a única representante da ordem Dehalococcoidales. Assim, aqui não podemos afirmar com segurança que uma classificação ao nível da família é mais correta do que uma classificação ao nível da ordem. Para estes casos, CAT e BAT marcam a linhagem com asteriscos, começando pelo nível de classificação mais baixo até o nível onde o conflito poderia ter surgido porque o clado contém múltiplos táxons com entradas no banco de dados. O usuário é aconselhado a examinar os táxons estrelados com mais cuidado, por exemplo, analisando a identidade da sequência entre ORFs previstos e ocorrências, ou mover a linhagem para uma classificação confiável (ou seja, a primeira classificação sem asterisco).
Se você não quiser os asteriscos em seus arquivos de saída, poderá adicionar o sinalizador --no_stars ao CAT ou BAT.
CAT e BAT podem demorar um pouco para serem executados e podem usar bastante RAM e espaço em disco. Dependendo do que você mais valoriza, você pode ajustar CAT e BAT para maximizar um e minimizar outros. O algoritmo de classificação em si é rápido e amigável em memória e espaço em disco. A etapa mais cara é o alinhamento com DIAMOND, portanto, o ajuste dos parâmetros de alinhamento terá o maior impacto:
-n / --nproc permite escolher o número de núcleos a serem implantados.--sensitive . Isto aumentará a sensibilidade, mas tornará o alinhamento consideravelmente mais lento.--block_size para um valor mais baixo diminuirá o uso de memória e de espaço temporário em disco. Definir um valor mais alto aumentará o desempenho.--index_chunks como 1 (atualmente o padrão). Este parâmetro não afeta o uso temporário do espaço em disco.--tmpdir .Obtendo ajuda para executar o utilitário de preparação:
$ CAT_pack prepare --help
Execute CAT em um conjunto contig com configurações de parâmetros padrão, implantando 16 núcleos para alinhamento DIAMOND. Nomeie a saída da classificação contig com nomes oficiais e crie um resumo:
$ CAT_pack contigs -c contigs.fasta -d db/ -t tax/ -n 16 --out_prefix first_CAT_run
$ CAT_pack add_names -i first_CAT_run.contig2classification.txt -o first_CAT_run.contig2classification.official_names.txt -t tax/ --only_official
$ CAT_pack summarise -c contigs.fasta -i first_CAT_run.contig2classification.official_names.txt -o CAT_first_run.summary.txt
Execute o BAT no conjunto de MAGs que foi armazenado nesses contigs, reutilizando as previsões de proteínas e o arquivo de alinhamento DIAMOND gerado anteriormente durante a classificação do contig:
$ CAT_pack bins -b bins/ -d db/ -t tax/ -p first_CAT_run.predicted_proteins.faa -a first_CAT_run.alignment.diamond -o first_BAT_run
Execute o algoritmo de classificação contig novamente com configurações de parâmetros personalizados e nomeie a saída com todos os nomes da linhagem, excluindo as pontuações:
$ CAT_pack contigs --range 5 --fraction 0.1 -c contigs.fasta -d db/ -t tax/ -p first_CAT_run.predicted_proteins.faa -a first_CAT_run.alignment.diamond -o second_CAT_run
$ CAT_pack add_names -i second_CAT_run.contig2classification.txt -o second_CAT_run.contig2classification.names.txt -t tax/ --exclude_scores
Execute BAT no conjunto de MAGs com configurações de parâmetros personalizados, suprimindo o detalhamento e não gravando um arquivo de log. A seguir, adicione nomes ao arquivo de saída ORF2LCA:
$ CAT_pack bins -r 3 -f 0.1 -b bins/ -s .fa -d db/ -t tax/ -p first_CAT_run.predicted_proteins.faa -a first_CAT_run.alignment.diamond --o second_BAT_run --quiet --no_log
$ CAT_pack add_names -i second_BAT_run.ORF2LCA.txt -o second_BAT_run.ORF2LCA.names.txt -t tax/
Freqüentemente usamos a combinação CAT/BAT para explorar uma possível contaminação dentro de um MAG.
$ CAT_pack contigs -c ../bins/interesting_MAG.fasta -d db/ -t tax/ -o CAT.interesting_MAG
$ CAT_pack bins -b ../bins/interesting_MAG.fasta -d db/ -t tax/ -p CAT.interesting_MAG.predicted_proteins.faa -a CAT.interesting_MAG.alignment.diamond -o BAT.interesting_MAG
Contigs que possuem um sinal taxonômico diferente da classificação MAG provavelmente são contaminação.
Alternativamente, você pode observar a contaminação da perspectiva do MAG, definindo o parâmetro f para um valor baixo:
$ CAT_pack bins -f 0.01 -b ../bins/interesting_MAG.fasta -d db/ -t tax/ -o BAT.interesting_MAG
$ CAT_pack add_names -i BAT.interesting_MAG.bin2classification.txt -o BAT.interesting_MAG.bin2classification.names.txt -t tax/
BAT produzirá qualquer sinal taxonômico com pelo menos 1% de suporte. Sinais divergentes de baixa pontuação são sinais claros de contaminação!
O RAT estima a composição taxonômica dos metagenomas integrando sinais taxonômicos de MAGs, contigs e leituras. RAT foi adicionado ao pacote CAT a partir da versão 6.0. Para usar o RAT, você precisa dos arquivos de banco de dados do pacote CAT (consulte Introdução para obter mais informações).
O RAT cria um perfil integrado usando MAGs/bins, contigs e leituras. Para especificar quais elementos devem ser integrados, use o argumento --mode . As letras possíveis para --mode são m (para MAGs), c (para contigs) e r (para leituras). Todas as combinações das três letras são possíveis, exceto apenas r . Para executar o fluxo de trabalho completo do RAT, especifique o modo, os arquivos de leitura, os arquivos contig, a pasta bin e os arquivos de banco de dados:
$ CAT_pack reads --mode mcr -b bin_folder/ -c contigs.fasta -1 forward_reads.fq.gz -2 reverse_reads.fq.gz -d db/ -t tax/
Atualmente, o RAT suporta arquivos de leitura única, bem como arquivos de leitura emparelhados. Arquivos de leitura entrelaçados não são suportados atualmente. O RAT executará CAT e BAT nos contigs e MAGs, mapeará as leituras de volta aos contigs e, em seguida, tentará anotar separadamente quaisquer leituras não mapeadas. Se você já possui um arquivo de mapeamento classificado, você pode fornecê-lo e o RAT irá pular a etapa de mapeamento:
$ CAT_pack reads --mode mcr -b bin_folder/ -c contigs.fasta --bam1 mapping_file_sorted.bam -1 forward_reads.fq.gz -2 reverse_reads.fq.gz -d db/ -t tax/
Se CAT e/ou BAT já tiverem sido executados em seus dados, você poderá fornecer os arquivos de saída ao RAT para ignorar as execuções de CAT e BAT:
$ CAT_pack reads --mode mcr -b bin_folder/ -c contigs.fasta -1 forward_reads.fq.gz -2 reverse_reads.fq.gz -d db/ -t tax/ --c2c CAT_contig2classification_file.txt --b2c BAT_bin2classification_file.txt
Da mesma forma, se uma execução anterior do RAT travou após as leituras não mapeadas já terem sido alinhadas ao banco de dados com diamante, você poderá fornecer os arquivos intermediários para continuar a execução:
$ CAT_pack reads --mode mcr -b bin_folder/ -c contigs.fasta -1 forward_reads.fq.gz -2 reverse_reads.fq.gz -d db/ -t tax/ --c2c CAT_contig2classification_file.txt --b2c BAT_bin2classification_file.txt --alignment_unmapped unmapped_alignment_file.diamond
Após a conclusão de uma execução RAT, você pode executar add_names nos arquivos de abundância (apenas para execuções RAT com banco de dados nr):
$ CAT_pack add_names -i RAT.completete_abundance_file.txt -o RAT.completete_abundance_file_with_names.txt -t tax/
Semelhante ao CAT e BAT, os caminhos para todas as dependências podem ser fornecidos através de um argumento:
$ CAT_pack reads --mode mcr -b bin_folder/ -c contigs.fasta -1 forward_reads.fq.gz -2 reverse_reads.fq.gz -d db/ -t tax/ --path_to_samtools /path/to/samtools
A saída RAT consiste em:
r em --mode ).
