Getting started: from a terminal to your first result

Home and reading order · Next: test walkthrough

What you will do

Install MP on a Linux computer, activate its software environment, run a small included example, and open a report. You do not need a Pathway Tools license for the first example. Add pathway inference after the example works.

If you already have a working MP installation, go directly to the test walkthrough. If your lab manages the software centrally, ask for the activation command and MPDB path rather than installing a second copy.

Before typing commands

A terminal accepts commands. A working directory is the folder relative paths refer to. pwd displays it; ls lists its contents; cd DIRECTORY changes it. ~ means your home directory. /data/project/sample.fasta is an absolute path; sample.fasta means a file in the working directory. Linux distinguishes SampleA from samplea.

Copy commands inside the code blocks, without Markdown backticks or a shell prompt. A backslash at the end of a line continues the command on the next line: do not put spaces after it. Values such as /path/to/MPDB are placeholders; replace them with real paths. Use simple project and sample names without spaces or shell punctuation, because some legacy tool wrappers construct shell commands.

An environment is a collection of compatible software. Activating it makes your terminal find the intended MP and tool executables. Activate it again in each new terminal. It does not require setting an MP-specific environment variable.

On a remote server, the analysis commands run in the SSH terminal on that server. Your web browser normally runs on your own computer. The SSH report instructions connect the two. For a long run, use your site’s persistent terminal/session practice so disconnecting SSH does not interrupt your controller.

Install on Linux x86-64

Choose one route, in this order:

  1. Conda package with Mamba — preferred for local servers and HPC. Install the package and activate the environment before each session. Workflow helpers are included.

  2. Quay Docker or Apptainer — use a versioned image and the container-specific three-sample instructions. References and outputs must be writable; the public MP image does not contain licensed Pathway Tools.

  3. Local installation from GitHub — build the supporting Mamba environment, then install MP with pip from your checkout. Use this route to install from a local checkout or make changes to MP.

Windows and macOS users can connect to a Linux server. These instructions do not claim a tested native Windows, Apple Silicon, or WSL installation. If Mamba is not installed, follow the official Miniforge instructions or your HPC’s software setup instructions. No MP-specific environment variable is required.

The source installation makes a fixed copy of the checked-out code. After updating the checkout, reinstall with python -m pip install .. Record git rev-parse HEAD alongside metapathways version. Developers may explicitly choose an editable installation with -e .. Do not update an installation while it is running an analysis.

Confirm the installation:

which python
which metapathways
metapathways version
metapathways analysis_wf --help
nextflow -version
java -version
apptainer --version
magsplitter --help

which should point into your activated environment, or to an intentional site-managed executable. analysis_wf --help should list manifest and resource options. A help command does not run an analysis. If a command is missing, first confirm you activated the correct environment. On hosts that restrict user namespaces, Apptainer setup may require an administrator; see Pathway Tools build prerequisites.

First installation check

Follow the three-sample test walkthrough. It uses the same analysis_wf command as a real analysis, with small bundled references, assemblies, paired reads and genome maps. It exercises annotation, read abundance, genome splitting and the reports without requiring Pathway Tools. Database preparation downloads enzyme and taxonomy support records, so internet access is required.

The older run --test K12 example remains available for compatibility, but it does not exercise the complete workflow and is not the complete workflow test.

Your first real assembly

The tiny test references are only for the example. Build or obtain a production MPDB before interpreting your own data:

metapathways build_db -d ~/MPDB --func swissprot -a fast
metapathways run -i /path/to/sample.fasta -o ~/mp-results -d ~/MPDB \
  --threads 8 --max_cpus 8 --max_memory '32 GB'

The assembly goes through quality control, gene/RNA prediction, reference searches, and annotation. Without reads, there is no measured read abundance. Without a separate ptools step, there are no inferred PGDB pathways. A single analysis_wf command can combine these steps once the inputs and licensed container are ready.

Continue with the test walkthrough, command cookbook, and input organization.

Terms used in the guides

Term

Meaning in MP

Assembly / contig

DNA sequences assembled from reads; each FASTA record is a contig

FASTA / FASTQ

Sequence file / read file with per-base quality scores

Paired / interleaved

Two mate files / one file with alternating mate records

ORF

Predicted protein-coding region; RNA features are also retained in relevant outputs

MAG / genome bin

A group of contigs assigned to a genome; MP consumes assignments, not a binning algorithm

MPDB

MP’s reference sequences, indexes, taxonomy and functional mapping tables

MetaCyc

Reference pathways/reactions and associated proteins; not a sample’s pathway predictions

PGDB

Pathway/Genome Database inferred for one community or genome bin

SIF

An Apptainer image containing the licensed Pathway Tools installation

Nextflow / task

Scheduler behind MP / one scheduled unit of work

Manifest

A TSV listing sample IDs and exact input paths

Receipt

MP’s record used to decide whether a completed task can be reused

TSV / CSV

Table with tab-separated / comma-separated fields