Skip to content

4. Sample identification

Jump to bottom
Benedikt Kuhnhäuser edited this page Jun 23, 2026 · 11 revisions

This page explains all pipeline inputs in detail.

Overview

GeneParliamentID analyses a single sample at a time.
The pipeline takes the following input parameters:

Required arguments:
Sample and reference datasets:
-i: Directory containing multiple genes for a sample of unknown identity
-r: Directory with corresponding BLAST reference databases of each gene for lineage of interest

Calibration files to set pipeline parameters:
-g: Gene performance of each gene (percentage of correctly identified test samples)
-t: Filtering thresholds
-c: Confidence estimates depending on gene support

Optional argument:
-s: User-defined groups of closely related species

Sample directory -i

Directory containing one file per gene for the sample to be identified. Each file contains a single corresponding gene sequence for the sample.
Gene sequences can be retrieved, for example, from raw targeted sequence capture data using HybPiper or CAPTUS.

Requirements:

  • Gene sequences need to be in fasta format and ending with an .FNA suffix
  • The gene files need to be named with the gene name, and nothing else than the gene name should be included before the .FNA suffix
  • Gene names need to match the gene names in the reference dataset.
  • Sample names in each file need to be identical.

Example contents of test sample directory
Gene1.FNA:

>Sample1
TTGGGAGAAAGGCTGCTGTGGCAGCATGTGGGTGATTATGAGGGTTCAAGAGGGAAAAAT
GGGGATATTAAGATGTTGGTTGCCACGCAGAGGTCGGGGACTGCTGCTGATAAAGTGTTT
GCCTTTTGTGTTATGGTCAGGGATAATCCCGCGGCCAATTTGAGGTCGCTAGTTGCGCTT

Gene2.FNA:

>Sample1
AAAACAAAGCAGCCCGATATTGTAAAAGCAGGTGACCCGGTTCTGCATGAACCGGCAGGA

Gene3.FNA:

>Sample1
AATTACGACCCGAATCTTAGACCGCAAGAGAAGGCGGTGGAGTATGTGCGGGCTCTTACT
GCGGCCAAATTAGAGAAGATTTTTGCAAGACCGTTTATTGGAGCAATGGATGGTCATAGA

Reference directory -r

Directory containing BLAST databases of the same genes that were retrieved for the sample of interest. Each database contains representative samples of the lineage of interest. The genes retrieved for the sample may only be a subset of the genes in the reference dataset. For example, the reference directory may contain 300 genes, of which 200 were retrieved for a sample.

The BLAST reference databases need to be built from unaligned gene sequence data files that contain representative samples with known species identity of the lineage of interest. This only needs to be done once. Gene sequences can be retrieved, for example, from raw targeted sequence capture data using HybPiper or CAPTUS.

Building reference databases thus involves two steps:

1) Prepare sequence files in the right format

First, you need to ensure that all sequence data files have the correct format:

  • Gene sequences need to be in fasta format and ending with an .FNA suffix
  • The gene files need to be named with the gene name, and nothing else than the gene name should be included before the .FNA suffix
  • Sample names in each file need to be identical.
  • Each reference sample name needs to start with genus and species name <Genus>_<species>, followed by a unique identifier for the sample.
  • Use underscores _ as separators in the reference sample names

Example reference sequence files:
File Gene1.FNA:

>Entandrophragma_angolense_CQL_22
CTCCCATATAGGGGTGCTTGGTTGTGGGTGGGTTCTGAGATGATTCATTTAATGGAACTT
CCAAATCCAGATCCCTTAACTGGACGACCGGCACATGGTGGTCGAGATCGTCATACTTGT
ATTGCGATTCGAGATGTGTCTAAACTCAAAATAATCCTTGATAAAGCAGGTATTCCTTAC
>Entandrophragma_bussei_CQL_EB42
CTCCCATATAGGGGTGCTTGGTTGTGGGTGGGTTCTGAGATGATTCATTTAATGGAACTT
CCAAATCCAGACCCCTTAACTGGACGACCGGCACATGGTGGTCGAGATCGTCATACTTGT
ATTGCGATTCGAGATGTGTCTAAACTCAAAATAATCCTTGATAAAGCAGGTATTCCTTAC
>Entandrophragma_candollei_CQL_13
CTTCCGTATAGGGGTGCTTGGTTGTGGGTGGGTTCTGAGATGATTCATTTAATGGAACTT
CCAAATCCAGACCCCTTAACGGGACGACCGGCACATGGTGGTCGAGATCGTCATACTTGT
ATTGCGATTCGAGATGTGTCTAAACTGAAAATAATCCTTGACAAAGCAGGTGTTCCTTAC

File Gene2.FNA:

>Entandrophragma_angolense_CQL_22
GTTGGGGATCTACACGGAGACCTTGATCAAGCGAGATGTGCACTTGAGATTGCTGGTGTC
>Entandrophragma_bussei_CQL_EB42
GTTGGGGATCTACACGGAGACCTTGATCAAGCGAGATGTGCACTTGAGATTGCTGGTGTC
>Entandrophragma_candollei_CQL_13
GCTGGGGATCTACATGGAGACCTTGATCAAGCAAGATGTGCACTTGAGATTGCTGGTGTC

File Gene3.FNA:

>Entandrophragma_angolense_CQL_22
GAATCTCAAGGATTAACATCTCGACGATTGTGTCTTACATGTATATGTTCAACTCTAGCT
CTGATTAACAGTTCCGGCACGTTGGTTTCTGTACAAAAGGCAATTGCTTTGGAAGGAAAA
>Entandrophragma_bussei_CQL_EB42
GATATGTGTGGTGGTACAGGAAAATGGAAAGCTCTCAACAGAAAACGTGCTAAAGATGTT
TACGAGTTTACAGAATGTCCAAATTGTTATGGTCGTGGGAAACTTGTGTGTCCGGTTTGC
>Entandrophragma_candollei_CQL_13
GAATCTCAGATATCAACATCTCGCCGTTGGTGCCTTACGTGTATACTTACATGTATATGT
TCAACTCTAGCTCTGATTAACAGTTCCGGCACATTGGTTTCTGTACAAAAGGCAATTGCT

2) Build BLAST reference databases

Once you have ensured that each reference sequence file has the right format, you can build BLAST databases from these files. This only requires a simple command that should run very quickly for each file.

First, create a list of all gene names, one per line:
for f in *.FNA; do echo ${f/.FNA}; done > genelist.txt

Example contents of genelist.txt:

Gene1
Gene2
Gene3
...
Gene353

Second, run a loop to build a database for each gene in the list:
for gene in $(cat genelist.txt); do makeblastdb -in "$gene".FNA -parse_seqids -dbtype nucl; done

This creates a number of additional files for each gene in the reference directory with endings such as .ndb or .njs.

Gene performance -g

File detailing gene performance, i.e. the percentage of correctly identified test samples, for all genes.
This file is automatically produced during Method calibration, with the file name calibration_gene_performance.csv.

Requirements:

  • Comma-separated .csv file
  • First column contains gene name, exactly as in the test and reference samples, e.g. Gene1
  • Second column contains gene performance as a percentage, e.g. 58.82

Example performance file
File calibration_gene_performance.csv:

gene performance
Gene1 88.89
Gene2 45.16
Gene3 62.96

Filtering thresholds -t

File containing thresholds for gene performance, alignment filtering and parliament size.
This file is automatically produced during Method calibration, with the file name calibration_filtering_thresholds.csv.

Requirements:

  • Comma-separated .csv file
  • First row contains variable names
  • Second row contains variable thresholds

Example thresholds file
File calibration_filtering_thresholds.csv:

simimilarity length gap mismatch evalue bitscore gene_performance parliament_size
98 100 1 5 1e-60 200 30 10

Confidence estimates -c

File containing confidence estimates depending on the percentage of genes supporting the identification.
This file is automatically produced during Method calibration, with the file name calibration_confidence_support.csv.

Requirements:

  • Comma-separated .csv file
  • First column contains the range of percentage of support
  • Columns two to four contain the probability of the identification being correct, close or wrong for this range
    • correct: correct identification to species
    • close: correct identification to species group but not to species
    • wrong: incorrect identification to both species and species group

Example confidence file
File calibration_confidence_support.csv:

support correct close wrong
[0,20] 0 0 100
(20,40] 78.57 21.43 0
(40,60] 82.14 17.86 0
(60,80] 100 0 0
(80,100] 100 0 0

Species groups -s (optional)

File specifying for each species to which user-defined group of closely-related species it belongs, such as species complex or genus.

Requirements:

  • Comma-separated .csv file
  • Each row corresponds to a reference species and the corresponding species group
  • First column contains genus and species name
    • Use underscores _ as separator
    • Spelling needs to be exactly as for the reference species
  • Second column contains name of species group

Example species group file
File species_groups.csv:

genus_species species_group
Entandrophragma_angolense Group_A
Entandrophragma_congoense Group_A
Entandrophragma_bussei Group_B
Entandrophragma_candollei Group_B
Entandrophragma_delevoyi Group_B

Clone this wiki locally