convert

On this page we provide a brief tutorial on how you can use the amdirt command-line-interface (CLI) of the convert command.

This tutorial assumes you are on a UNIX based operating system and has internet access. It also assumes you have already installed amdirt.

We will show how given a pre-filtered samples or libraries table (e.g. via command line tools or in an R session), in much the same way as the graphical-based GUI command, you can use the command-line interface to convert the table to various formats such as download scripts or prepared input sample sheets for ancient metagenomic pipelines.

In this case we will want to download all metagenomic sequencing data of ancient dental calculus samples from Germany, and prepare a sample sheet for the nf-core/eager pipeline.

Data

We will take use one of the previous releases of AncientMetagenomeDir as an example dataset. You can download the dataset from the following link.

mkdir amdirt-convert-tutorial
cd amdirt-convert-tutorial
amdirt download --table ancientmetagenome-hostassociated --table_type samples -r v23.09.0

Filter a sample metadata table

Next we can filter the ancient metagenome ‘host-associated’ sample sheet for all dental calculus tables from Germany.

cat ancientmetagenome-hostassociated_samples_v23.09.0.tsv | grep -e '^project_name' -e 'dental calculus' | grep -e '^project_name' -e 'Germany' > germany_dentalcalculus.tsv

⚠ The command above is not robust and is only used for system portability and demonstration purposes. For example the Germany string could be in a site name. In practice, you should use more robust filtering methods such more specific grep expressions or in R.

Now we can use the convert command to provide a download script, a nf-core/eager samplesheet, the AncientMetagenomeDir library metadata, and a citations file.

amdirt convert --curl --eager --librarymetadata --bibliography germany_dentalcalculus.tsv ancientmetagenome-hostassociated

This will create the following files:

AncientMetagenomeDir_bibliography.bib: A BiBTeX file with the citations of the samples in the filtered table supplied to convert
AncientMetagenomeDir_curl_download_script.sh: A curl download script to download all associated FASTQ files of the samples in the filtered table
AncientMetagenomeDir_filtered_libraries.tsv: A AncientMetagenomeDir library metadata table of the samples in the filtered table
AncientMetagenomeDir_nf_core_eager_input_table.tsv: A nf-core/eager input table for the samples and FASTQ files downloaded from the curl script in the filtered table

You could then supply run the curl script to download the FASTQ files, and then run the nf-core/eager pipeline with the input table.

bash AncientMetagenomeDir_curl_download_script.sh
nextflow run nf-core/eager -profile docker --input AncientMetagenomeDir_nf_core_eager_input_table.tsv <...>

Filter a library metadata table

The convert command is not just for sample metadata! You can also use it to filter AncientMetagenomeDir library metadata tables.

Let’s say of the samples we just downloaded, you realised you only wanted to use the libraries that were with sequenced with a paired-end sequencing kit. We can filter the previously downloaded library metadata table in the same manner as above.

 grep -e '^project_name' -e 'PAIRED' AncientMetagenomeDir_filtered_libraries.tsv > germany_dentalcalculus_libraries_pe.tsv

⚠ The command above is not robust and is only used for system portability and demonstration purposes. For example the Germany string could be in a site name. In practice, you should use more robust filtering methods such more specific grep expressions or in R.

We can then again use the convert command to provide an updated download script, nf-core/eager samplesheet, and an citations file.

amdirt convert --curl --eager --bibliography --libraries germany_dentalcalculus_libraries_pe.tsv germany_dentalcalculus.tsv ancientmetagenome-hostassociated

ℹ It’s important to note that you still need a (full or filtered) AncientMetagenomeDir samples sheet even when supplying --libraries.

Once again you will have similar output as above (minus the libraries metadata table), you can than download in this case just the FASTQ files and run these through nf-core eager:

AncientMetagenomeDir_bibliography.bib: A BiBTeX file with the citations of the samples in the filtered table supplied to convert
AncientMetagenomeDir_curl_download_script.sh: A curl download script to download all associated FASTQ files of the samples in the filtered table
AncientMetagenomeDir_nf_core_eager_input_table.tsv: A nf-core/eager input table for the samples and FASTQ files downloaded from the curl script in the filtered table

You could then supply run the curl script to download the FASTQ files, and then run the nf-core/eager pipeline with the input table.

bash AncientMetagenomeDir_curl_download_script.sh
nextflow run nf-core/eager -profile docker --input AncientMetagenomeDir_nf_core_eager_input_table.tsv <...>

Clean up

Once you’ve completed this tutorial, simply leave the amdirt-convert-tutorial directory and remove it.

For example:

cd ..
rm -r amdirt-convert-tutorial/