Quick start

This is a guide written to the new user or everyday running of Magphi.

Installation

Conda installation

conda install -c bioconda magphi

Pip install

Make sure you have the right versions of Samtools and Bedtools installed
pip install Magphi

Dependencies

Constructing seed sequence file

Seed sequences are what define a region in which the user is interested. These sequences can be core genes, or known stretches of DNA that surround a specific region in genomes. From Magphi v2.0.0 seed sequences can also be amino acid sequences (using -p), allowing for search across more diverse genomes using tblastn. It is recommended that seed sequences are no less than 100 bp (~30 amino acid residues), as BLAST does not work well for smaller query sequences.

Rules to follow for seed sequences

Seed sequences should be no less than 100 bp (~30 amino acid residues)
Names should be unique for each pair of seed sequences
Each name of a seed sequence in a pair should be appended with a unique tag (i.e. _1 or _2) to make them unique within the pair.
If a seed sequences is used twice it should be duplicated in the fasta file and given two unique names

Example seed sequence file:

>phageA_1
CTGGTCGGTTGGTATATAGTGTTCGCACTG.....
>phageA_2
CACTTGTAACACAACCAGACCCCCCCGGAA.....
>spec_phage1
CACTTGTAACACAACCAGACCCCCCCGGAA.....
>spec_phage2
TGCAGTTCCCCATGGGGTGTAGGTGTAACG.....

Genomes

Genomes should be in either Fasta format or GFF3 format with the genome appended in the end of the file, with the ##FASTA line separating the annotations from the appended fasta genome. Only a single file format (either Fasta or GFF) is allowed in a single run. Files can be Gzipped, but a mix of Gzipped and non-Gzipped files are not allowed.

Rules to follow for input genomes

Fasta or GFF3 format with appended genome
Exclusively Fasta or GFF files for a single run, no mixing
Genomes can be Gzipped, but only Gzipped or not for a single run.

Results

For each seed sequence pair given as input a subfolder in the output folder will be created. In a seed sequence subfolder extracted genetic sequences and annotations can be found.

Additional outputs are tables summarising findings from the Magphi run. Besides seed_pairing.tsv the output tables all contain the name of genomes given as the first column. The subsequent column headers are the seed sequences identified for the run.

Summary tables

seed_pairing.tsv - Gives the common name identified for a seed sequence pair and the two seed sequences found in the pair. Can be used to check if Magphi identified seed sequence pairs as intended by the user.
contig_hit_matrix.csv - Indicates the number of locations a pair of seed sequences were identified to map in a given genome by BLAST. Can be used to evaluate seed specificity.
inter_seed_distance.csv - Genomic distance in base pairs between merged seed sequences in a pair. Additional columns will be added for each seed sequence that is found to be next to a sequence break. - Can be used to evaluate insertions of genetic material between seed sequences or varying distance between genomic features.
annotation_num_matrix.csv - The number of annotated features extracted from a GFF file, if any can be found between merged seed sequences. This can be used to evaluate changes in gene/genetic feature content between seed sequences. This is useful for searching insertion sites of mobile genetic elements.
master_seed_evidence.csv - Overview of how each seed sequence pair was found to map, merge, and extract features for a specific genome. This is easily the most useful output for evaluating seed sequence quality, and large scale impression of output quality.

Outputs to expect

The standard outputs listed above are to be expected for all Mapghi runs. Additional outputs related to extracted fasta sequences and gff annotations can be expected in some instances. When running with:

Default parameters (no -b or -n arguments to Magphi), Fasta outputs can be expected for evidence levels 5B and 5C. A Gff output can be expected with evidence level 5C.
When -b is given to Magphi, Fasta outputs can be expected for evidence levels mentioned above, and 4B and 4C. Gff outputs can be expected for 4C as well.
No output is expected when -n is given as a parameter.
As a default output fasta and Gff files are oriented so that the first seed in a pair (see seed_pairing.tsv file) is at the beginning of the sequence

-n and -b are mutually exclusive as they both alter the expected output and therefore Magphi does not allow both to be given in a single command.

Evidence level overview

One or no seed sequence hit the genome
Multiple seed sequences hit with no overlap
Multiple seed sequences hit with multiple connections
Seed(s) deleted due to overlap or placed at end of contig and seeds are excluded
A. Two Seed sequences hit on seperate contigs - No connection

B. Two Seed sequences hit on seperate contigs - with connection no annotations

C. Two Seed sequences hit on seperate contigs - with connection and annotations
A. Two seed sequences hit on same contig - not connected

B. Two seed sequences hit on same contig - connected no annotations

C. Two seed sequences hit on same contig - connected with annotations

Improvements

Depending on the evidence level some changes can be made to improve a Magphi run. Below are some points to consider:

Evidence level of 0 can indicate a bad selection of seed sequences or poor quality of assembly.
Too small maximum distance or poor seed sequences can result in an evidence level of 1
Too large a maximum distance may result in draft genomes having an evidence level of 2, however decreasing the max distance may result in false region being extracted
When 3 is given as evidence level try -ip to see the resulting evidence level, to examine if seed sequences overlap or fall on edge of contig.
Evidence level = 4 can give output if -b is given as an argument to Mapghi.
Dividing seed sequence pairs with similar max distance into separate runs is a good trick to maximise likelihood of good extractions.
For large datasets consider using -n to save memory, if your analysis is not interested in the sequence itself.

Post processing

Depending on the analysis multiple post processing steps can be conducted. The .csv files produced by Magphi can be loaded into Phandango and illustrated against a phylogeny for quick and easy visual inspection. GFF output files can along with their matching fasta file be used as input into Clinker for visual inspection of gene annotations. CD-hit can also be used to cluster output fasta files to identify regions with similar nucleotide identity and length using cd-hit-est. The above points are just examples and many other methods can be used depending on your research question.