Package: resmico
IntroductionResMiCo is a deep learning model capable of detecting metagenome assembly errors.
ResMiCo's input is summary data derived from re-aligning reads against the putative
genomes. ResMiCo's output is a number betwen 0 and 1 representing the likelihood that a
particular genome was misassembled.The tool is divided into two main parts:ResMiCo-SMA snakemake pipeline for:creating feature tables from real-world assembliesinput: >=1 fasta of contigs, along with associated Illumina paired-end readsgenerating train/test datasets from reference genomesSee theResMiCo-SM READMEResMiCo (DL)A python package for misassembly detection via deep learningCitationIf using ResMiCo in your work, please cite:ResMiCo: increasing the quality of metagenome-assembled genomes with deep learningInstallationCurrently, please usepipto install, but install the dependencies via mamba (or conda):mambaenvcreate-nresmico_env-f$RESMICO_BASE_DIR/environment.yml
mambaactivateresmico_env
pipinstallresmicoWARNING: the resmico bioconda recipe is currently set to an old version of
resmico. That old version does not match the current user interface
(e.g., lacksresmico bam2feat). So, we do not recommend using
the bioconda recipe for installing resmico at this time.Running the ResMiCo package testsInstallpytestandpytest-console-scripts. For example:mamba install pytest pytest-console-scriptsRun tests withpytestpytest -s --hide-run-results --script-launch-mode=subprocess ./resmico/tests/General usageResMiCo-SM snakemake pipelineUse ResMiCo-SM for creating feature files from real data or simulate new data.See theResMiCo-SM READMENoteresmico bam2featcan also be used to create feature tables from
real data: contig fasta files & associated BAM files (mapped reads)ResMiCo packageMain interface:resmico -hNote: AlthoughResMiCocan be run on a CPU, it is orders of magnitude
slower than on a GPU, so we only recommend running on CPUs for testing.Creating feature tablesSeeresmico bam2feat -hPredicting with existing modelSeeresmico evaluate -hFiltering out misassembled contigsSeeresmico filter -hTraining a new modelSeeresmico train -hExample 1: predicting misassemblies with the "default" modelIf you already have metagenome reads mapped to your contigs,
you can process your own data much like in this example.The model was trained with data produced via mapping Illumina
paired-end reads withBowtie2.Working directorymkdir example1 && cd example1Get the example datasetThe dataset consists of a few UHGG genomes (MAGs) and associated BAM files.
The BAM files were generated by using Bowtie2 to map the associated
metagenome paired-end reads (from which the MAGs were assembled) to the
MAG contigs.So, the input consists of fasta files (contigs) and BAM files (mapped reads).A simple tab-delimited table is used to map the fasta & BAM files.Map file format:* A tab-delim table with the columns (any order is allowed): 
  * `Taxon` => name associated with the fasta file of contigs
  * `Fasta` => path to the fasta file of contigs
  * `Sample` => name associated with the BAM file 
  * `BAM` => path to the BAM file of reads mapped to the contigs in `Fasta`See themap.tsvfile for an example.wget http://ftp.tue.mpg.de/ebio/projects/ResMiCo/UHGG-n9_bam2feat.tar.gz
wget http://ftp.tue.mpg.de/ebio/projects/ResMiCo/UHGG-n9_bam2feat.md5
md5sum --check UHGG-n9_bam2feat.md5
tar -pzxvf UHGG-n9_bam2feat.tar.gz && rm -f UHGG-n9_bam2feat.*Convert BAM files to feature tablesCreate a feature table for each sorted BAM file:resmico bam2feat --outdir features UHGG-n9_bam2feat/map.tsvNote: the parameters are the same as used for creating
the "default" model from Mineeva et al., 2022, which is
critical for getting accurate predictions.Predict misassembliesresmico evaluate \
  --min-avg-coverage 0.01 \
  --save-path predictions \
  --save-name default-model \
  --feature-files-path featuresNote:--min-avg-coverageis set to "0.01" here due to the
abnormally low coverage in these small example BAM files.DO NOTuse such a low coverage cutoff with real data.Filter contigsFilter out contigs predicted to be misassembledresmico filter \
  --outdir filtered predictions/default-model.csv \
  UHGG-n9_bam2feat/*.fna.gzNote: change the--score-cutoffparameter to alter the number
of contigs filtered.Example2: Training & using a new modelWorking directorymkdir example2 && cd example2Get the example datasetTraining data: simulated from 10 genomes in the GTDBwget http://ftp.tue.mpg.de/ebio/projects/ResMiCo/genomes-n10_features.tar.gz
wget http://ftp.tue.mpg.de/ebio/projects/ResMiCo/genomes-n10_features.md5
md5sum --check genomes-n10_features.md5
tar -pzxvf genomes-n10_features.tar.gz && rm -f genomes-n10_features.*Test data: simulated from 9 genomes in the UHGGwget http://ftp.tue.mpg.de/ebio/projects/ResMiCo/UHGG-n9_features.tar.gz
wget http://ftp.tue.mpg.de/ebio/projects/ResMiCo/UHGG-n9_features.md5
md5sum --check UHGG-n9_features.md5
tar -pzxvf UHGG-n9_features.tar.gz && rm -f UHGG-n9_features.*Filter out contigs predicted to be misassembledFilter out contigs with prediction scores below a specific cutoff.resmico filter \
  --outdir filtered-contigs \
  predictions/default-model.csv \
  UHGG-n9_features/fasta/*fna.gzYou may need to adjust the--score-cutoffin order to filter some contigsTraining on the example train dataTrain a new model with the example train dataset.resmico train --log-progress --n-procs 4 --n-epochs 2 \
  --save-path model-n10 --stats-file='' \
  --save-name genomes-n10 \
  --feature-files-path genomes-n10_featuresPredict using the "default" modelUsing the "default" resmico model from the Mineeva et al., 2022 manuscript.
Prediction on the example test data.
This provides a comparison to our newly trained model.resmico evaluate --n-procs 4 \
  --save-path predictions \
  --save-name default-model \
  --feature-files-path UHGG-n9_features/TutorialsSee thewikiNotesBenchmarkingModel evaluationBenchmarkingresmico evaluateon theCAMI2-gutdataset:One GPU (NVIDIA RTX A5000): 108 +/- 0.7 contigs per secondOne CPU (AMD Epyc): 38.7 +/- 10.3 contigs per secondCAMI2-gut metagenome assembly stats:No. of metagemes: 10No. of contigs per sample (1000's): 18 +/- 6.4Avg. contig length (kbp): 4.1 +/- 0.9TrainingWe highly recommend using multiple GPUs for model training on large datasets, as done in the ResMiCo paper.
Training on CPUs with such large datasets is not feasbile.