Runs a pathogen build in the Nextstrain build environment.
The build directory should contain a Snakefile, which will be run with snakemake.
The default build environment is inside an ephemeral Docker container which has all the necessary Nextstrain components available. You may instead run the build in the native ambient environment by passing the –native flag, but all dependencies must already be installed and configured. For larger builds, you may want to use the –aws-batch flag to launch jobs on AWS Batch instead of running locally (if the required AWS resources are configured in your AWS account).
You can test if Docker, native, or AWS Batch build environments are properly supported on your computer by running:
The nextstrain build command is designed to cleanly separate the Nextstrain build interface from provisioning a build environment, so that running builds is as easy as possible. It also lets us more seamlessly make environment changes in the future as desired or necessary.
usage: nextstrain build [options] <directory> [...] nextstrain build --help
Path to pathogen build directory
Additional arguments to pass to the executed program
- --help, -h
Show a brief help message of common options and exit
Run the build in the background, detached from your terminal. Re-attach later using –attach. Currently only supported when also using –aws-batch.
Re-attach to a –detach’ed build to view output and download results. Currently only supported when also using –aws-batch.
Number of CPUs/cores/threads/jobs to utilize at once. Limits containerized (Docker, AWS Batch) builds to this amount. Informs Snakemake’s resource scheduler when applicable. Informs the AWS Batch instance size selection. By default, no constraints are placed on how many CPUs are used by a build; builds may use all that are available if they’re able to.
Amount of memory to make available to the build. Units of b, kb, mb, gb, kib, mib, gib are supported. Limits containerized (Docker, AWS Batch) builds to this amount. Informs Snakemake’s resource scheduler when applicable. Informs the AWS Batch instance size selection.
Only download new or modified files matching <pattern> from the remote build. Basic shell-style globbing is supported, but be sure to escape wildcards or quote the whole pattern so your shell doesn’t expand them. May be passed more than once. Currently only supported when also using –aws-batch. Default is to download every new or modified file.
Do not download any files from the remote build when it completes. Currently only supported when also using –aws-batch.
runner selection options
Select the method for running a Nextstrain computing environment, if the default is not suitable.
Run commands inside a container image using Docker. (default)
Run commands on the native host, outside of any container image.
Run commands remotely on AWS Batch inside the Nextstrain container image.
These should generally be unnecessary unless you’re developing Nextstrain.
Container image name to use for the Nextstrain computing environment
Program to run inside the build environment
development options for –docker
Replace the image’s copy of augur with a local copy
Replace the image’s copy of auspice with a local copy
Replace the image’s copy of fauna with a local copy
Replace the image’s copy of sacra with a local copy
Additional arguments to pass to docker run
development options for –aws-batch
See <https://docs.nextstrain.org/projects/cli/page/aws-batch> for more information.
Name of the AWS Batch job definition to use
Name of the AWS Batch job queue to use
Name of the AWS S3 bucket to use as shared storage
Number of vCPUs to request for job
Amount of memory in MiB to request for job