Skip to content

Latest commit

 

History

History
173 lines (115 loc) · 6.77 KB

nextalign-cli.md

File metadata and controls

173 lines (115 loc) · 6.77 KB
Raw

Nextalign CLI

Nextalign CLI is a viral genome sequence alignment tool for command line. It uses the same algorithm that is used in Nextclade Web and Nextclade CLI.

You can learn more about the algorithm in the Algorithm: Sequence alignment section.

This section describes:

  • how to install Nextalign CLI - using Docker container and natively
  • how to run Nextalign CLI with sample data
  • what other sections of the documentation are worth checking after that

Installation (with docker)

Container images are available at Docker Hub: 🐋 nextstrain/nextalign

Pull and run the latest version with:

docker pull nextstrain/nextalign:latest
docker run -it --rm nextstrain/nextalign:latest nextalign --help

Pull and run a specific version with:

docker run -it --rm nextstrain/nextalign:1.0.0 nextalign --help

Don't forget to mount necessary volumes to be able to supply the data inside the container and to access the results.

Installation (local)

Download manually

You can download the latest version of Nextalign CLI for your platform using one of these direct links:

All versions and their release notes are available on 🐈 Github Releases.

These executables are self-contained and don't require any dependencies. They can be renamed and moved freely. It is convenient to rename the executable to nextclade and to move to one of the directories included in system $PATH, so that it's available from any directory in the console.

⚠️ Note that macOS executables are not currently signed with a developer certificate (it requires maintaining a paid Apple developer account). Recent versions of macOS might refuse to run the executable. Before invoking Nextalign on command line, follow these steps to add Nextalign to the exclude list: macOS User Guide: Open a Mac app from an unidentified developer, and check Security settings. Refer to the latest macOS documentation if none of this works.

⚠️ Native Windows executables are not available at this time. Windows users can try one of the following:

Download from command line

The following commands can be used to download Nextalign from command line, from shell scripts and inside dockerfiles:

🐧 Linux x86_64 (click to expand)

Download latest version:

curl -fsSL "https://github.com/nextstrain/nextclade/releases/latest/download/nextalign-Linux-x86_64" -o "nextalign" && chmod +x nextalign

Download specific version:

NEXTALIGN_VERSION=1.0.0 curl -fsSL "https://github.com/nextstrain/nextclade/releases/download/nextalign-${NEXTALIGN_VERSION}/nextalign-Linux-x86_64" -o "nextalign" && chmod +x nextalign

🍏 macOS Intel (click to expand)

Download latest version:

curl -fsSL "https://github.com/nextstrain/nextclade/releases/latest/download/nextalign-MacOS-x86_64" -o "nextalign" && chmod +x nextalign

Download specific version:

NEXTALIGN_VERSION=1.0.0 curl -fsSL "https://github.com/nextstrain/nextclade/releases/download/nextalign-${NEXTALIGN_VERSION}/nextalign-MacOS-x86_64" -o "nextalign" && chmod +x nextalign

🍎 macOS Apple Silicon (click to expand)

Download latest version:

curl -fsSL "https://github.com/nextstrain/nextclade/releases/latest/download/nextalign-MacOS-arm64" -o "nextalign" && chmod +x nextalign

Download specific version:

NEXTALIGN_VERSION=1.0.0 curl -fsSL "https://github.com/nextstrain/nextclade/releases/download/nextalign-${NEXTALIGN_VERSION}/nextalign-MacOS-arm64" -o "nextalign" && chmod +x nextalign

Native Windows executables are not available at this time. Windows users can try one of the following:

  • Downloading and running Linux executable from Windows Subsystem for Linux (WSL)
  • Running docker container (see below)
  • Renting a Linux machine, for example at any cloud compute provider

Usage

Refer to help prompt for usage of Nextalign:

nextalign --help

Quick Example

  1. Download the example SARS-CoV-2 data files from GitHub (You can also try other viruses in the data/ directory)

  2. Run:

    nextalign \
 --sequences data/sars-cov-2/sequences.fasta \
 --reference data/sars-cov-2/reference.fasta \
 --genemap data/sars-cov-2/genemap.gff \
 --genes E,M,N,ORF1a,ORF1b,ORF3a,ORF6,ORF7a,ORF7b,ORF8,ORF9b,S \
 --output-dir output/ \
 --output-basename nextalign

    Add --verbose flag to show more information in the console. Add --include-reference flag to also write gap-stripped reference sequence and peptides into outputs.

  3. Find the output files in the output/ directory:

    • nextalign.aligned.fasta - aligned input sequences
    • nextalign.gene.<gene_name>.fasta - aligned peptides corresponding to each gene

What's next?

Congratulations, You have learned how to use Nextalign CLI!

Going further, you might want to learn about the science behind the Nextalign internals in the Algorithm section. The required input data is described in Input files section. And produced files are described in Output files section.

For a more convenient online tool, check out Nextclade Web.

Nextclade is an open-source project. We welcome ideas and contributions. Head to our GitHub repository if you want to obtain source code and contribute to the project.