Help

DNA / RNA / protein searches

• DNA/RNA: Use nucleotide FASTA. Start with Exact; if identity is low or variants are expected, toggle Alignment.
• Proteins: Use the UniParc index for amino‑acid sequences.

Filters & parameters

• Mode: Exact (fast) vs Alignment (sensitive).
• Top labels: Limit the number of accessions returned.
• Discovery threshold: The minimum fraction of k-mers that must match. Lower thresholds (lenient) return more hits; higher thresholds (strict) return fewer, higher-confidence hits. Adjust this parameter to balance sensitivity and specificity.

Choosing databases

See the Databases page for live coverage and whether an index includes counts or coordinates.

Results Overview

MetaGraph returns hits organized by database and accession. Similar to BLAST, results are ranked by relevance, but instead of E-values, MetaGraph uses discovery threshold and k-mer matching to identify significant matches.

Key Result Metrics

• Identity — Fraction of query bases identical in the matched path. In alignment mode, this shows the percentage of exact matches between your query and the target sequence. Higher identity (closer to 100%) indicates a closer match.
• Coverage — Fraction of the query covered by matches/alignments. This tells you how much of your input sequence was found in the database. For RNA-seq data with counts, coverage approximates expression profiles across samples.
• Discovery Threshold — The minimum fraction of k-mers that must match. Lower thresholds (lenient) return more hits; higher thresholds (strict) return fewer, higher-confidence hits. Adjust this parameter to balance sensitivity and specificity.
• Matched Accessions / Labels — Each hit corresponds to a specific sample, genome, or protein record in the database. Click on accession numbers to view the original sequence record (when available).

Additional Information (Database-Dependent)

• Counts — Available for some databases. Shows per-k-mer/sample abundances, useful for quantifying expression levels in RNA-seq or metagenomic data. Higher counts suggest higher abundance in the source sample.
• Coordinates — Available for reference genome databases (e.g., RefSeq). Shows genomic positions where your query matches, enabling precise localization on assembled chromosomes or contigs.
• Taxonomy — Provided when databases are organized by taxonomic classification. Helps identify which organisms or taxonomic groups contain your query sequence. Use the AI Organism Identification feature for automated species inference.

Result Table Navigation

• Sort columns — Click column headers to sort by identity, coverage, or other metrics.
• Filter results — Use the search box to filter by accession name or taxonomic group.
• Pagination — Navigate through pages if many hits are found. Adjust rows per page (10, 25, 50, 100) for convenience.
• Export — Download results as CSV or JSON for further analysis.

No Results Found?

If your search returns no hits, consider:

• Lowering the discovery threshold — Try 0.5 or lower for more lenient matching.
• Selecting different databases — Your sequence might be present in databases you haven't searched.
• Checking sequence type — Ensure you've selected "Nucleotide" or "Amino acid" correctly.
• Verifying FASTA format — Make sure your input is properly formatted (see Quick start section).

Minimal Working Example

This example has been tested and verified to work!

curl -X POST "https://metagraph.ethz.ch:8081/search" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "db": "refseq85_coord",
        "q": "ATGCGATCGTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAGCTAG"
      }
    ]
  }'

curl "https://metagraph.ethz.ch:8081/search/{search_id}/status"

curl "https://metagraph.ethz.ch:8081/search/{search_id}/results"

Conda

Install the latest release on Linux or Mac OS X with Anaconda:

conda install -c bioconda -c conda-forge metagraph

Docker

If docker is available on the system, immediately get started with

docker pull ghcr.io/ratschlab/metagraph:master
docker run -v ${HOME}:/mnt ghcr.io/ratschlab/metagraph:master \
    metagraph build -v -k 10 -o /mnt/transcripts_1000 /mnt/transcripts_1000.fa

and replace ${HOME} with a directory on the host system to map it under /mnt in the container.

Typical workflow

1. Build de Bruijn graph from Fasta files, FastQ files, or KMC k-mer counters:
   ./metagraph build
2. Annotate graph using the column compressed annotation:
   ./metagraph annotate
3. Transform the built annotation to a different annotation scheme:
   ./metagraph transform_anno
4. Query annotated graph:
   ./metagraph query

Example

DATA="../tests/data/transcripts_1000.fa"

./metagraph build -k 12 -o transcripts_1000 $DATA

./metagraph annotate -i transcripts_1000.dbg --anno-filename -o transcripts_1000 $DATA

./metagraph query -i transcripts_1000.dbg -a transcripts_1000.column.annodbg $DATA

./metagraph stats -a transcripts_1000.column.annodbg transcripts_1000.dbg