Package: phammseqs
PhaMMseqsThe PhaMMseqs package facilitates pham assembly usingMMseqs2. Default parameters have
been carefully tuned for rapid, accurate exploration of the bacteriophage protein sequence space.Conda installationThe easiest way to install the phammseqs package and its dependencies is through the Anaconda/Miniconda package manager:conda create -n phammseqs-env python=3.9 -y && conda activate phammseqs-env
conda install -c bioconda -c conda-forge mmseqs2=13.45111 clustalo -y
pip3 install phammseqsConda installation (Apple Silicon)Macintosh computers purchased in the last couple of years no longer have Intel CPUs, instead sporting some flavor of Apple
Silicon. These processors have a different architecture (arm64) that is not natively compatible with most of the recipes
in the bioconda or conda-forge channels. We can run these programs using Apple's Rosetta2 emulator by modifying the conda
installationas indicated here.CONDA_SUBDIR=osx-64 conda create -n phammseqs-env python=3.9 -y && conda activate phammseqs-env
conda env config vars set CONDA_SUBDIR=osx-64
conda install -c bioconda -c conda-forge mmseqs2=13.45111 clustalo -y
pip3 install phammseqsAfter the second command you may be prompted to reactivate the environment for changes to take effect. This is easily achieved
by running this sequence of commands before you install any packages into the environment:conda deactivate && conda activate phammseqs-envManual installationIf you don't have some flavor of conda available (and don't want to install it...) you may follow the instructionshereto manually installmmseqs. An optional dependency,clustalocan be manually installed following the instructionshere.
Most modern operating systems also ship with Python3, the programming language used to develop this package, and
required to run it. However, if your system does not have Python 3.7 or higher, you will need to obtain ithere.Once all that is done, you can obtain the phammseqs package from PyPI using pip:pip3 install phammseqsUsing PhaMMseqs at the command lineIf you installed phammseqs and its dependencies using either of the Conda approaches, you will need to activate the
environment before usingphammseqs(substitutephammseqs-envwith whatever you named the environment):conda activate phammseqs-envYou can invokephammseqswith the-hoption to print the help menu:phammseqs -hWhich should print something like:usage: phammseqs [-h] [--identity] [--coverage] [--evalue] [--sensitivity] [--cluster-mode] [--cluster-steps] 
[--hmm-identity] [--hmm-coverage] [--hmm-evalue] [--hmm-sensitivity] [--hmm-cluster-mode] [--hmm-cluster-steps] 
[--skip-hmm] [-v] [-d] [-a] [-p] [-c CPUS] [-o OUTDIR] infile [infile ...]

Assort phage protein sequences into phamilies of homologs using MMseqs2.

positional arguments:
  infile                path to input file(s) in FASTA or Genbank flatfile format

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         print progress messages to the console
  -d, --debug           run in debug mode
  -a, --align-phams     use Clustal Omega to align phams (could take awhile...)
  -p, --pangenome       pangenome analysis à la Roary (only meaningful if given one input file per genome)
  -c , --cpus           number of threads to use [default: 4]
  -o , --outdir         path to directory where output files should go

MMseqs2 sequence-sequence clustering arguments:
  --identity            percent identity for sequence-sequence clustering [default: 35.0%]
  --coverage            percent coverage for sequence-sequence clustering [default: 80.0%]
  --evalue              E-value threshold for sequence-sequence clustering [default: 0.001]
  --sensitivity         sensitivity: 1 favors speed, 7 favors sensitivity [default: 7]
  --cluster-mode        clustering algorithm [default: 0]
  --cluster-steps       number of steps for sequence-sequence clustering to proceed in [default: 1]

MMseqs2 profile-sequence clustering arguments:
  --hmm-identity        percent identity for profile-consensus clustering [default: 15.0%]
  --hmm-coverage        percent coverage for profile-consensus clustering [default: 70.0%]
  --hmm-evalue          E-value threshold for profile-consensus clustering [default: 0.001]
  --hmm-sensitivity     sensitivity: 1 favors speed, 7 favors sensitivity [default: 7]
  --hmm-cluster-mode    clustering algorithm [default: 0]
  --hmm-cluster-steps   number of steps for profile-consensus clustering to proceed in [default: 3]
  --skip-hmm            do not perform profile-consensus clustering

Steinegger M. and Söding J. MMseqs2 enables sensitive protein sequence searching for the analysis of massive data 
sets. Nature Biotechnology, 2017. doi: 10.1038/nbt.3988The only required argument is the path to a single multiple-FASTA file, for example:phammseqs my_genes.faaThis will perform pham assembly, and write each resultant pham to a FASTA file found in a new folder in the working
directory calledphammseqs__[day]_[month]_[year](this will resolve to the date on which pham assembly was performed).An alternate output path can be specified with the-oargument:phammseqs my_genes.faa -o ~/Desktop/phammseqs_resultsThis will do the same as before, the output files will be now found in~/Desktop/phammseqs_resultsrather than the
directory the program was invoked from.If your dataset is a pangenome or metagenome with many FASTA files (e.g. one file per genome), you can specify multiple
input files by simply putting their paths one after the next:phammseqs genome1.faa genome2.faa genome3.faa ... genomeN.faa -o ~/Desktop/phammseqs_resultsor if all these genomes are in the same directory:phammseqs /path/to/genome/fastas/*.faa -o ~/Desktop/phammseqs_resultsEach input file is treated separately, so you can even mix FASTA and Genbank flatfiles in the same run:phammseqs /path/to/genome/fastas/*.faa /path/to/genome/genbanks/*.gbk -o ~/Desktop/phammseqs_resultsIf you want to produce a multiple sequence alignment for each pham, the phammseqs program can accomplish this using
a local copy of the programclustalo- simply use the-a/--align-phamsargument:phammseqs my_genes.faa -o ~/Desktop/phammseqs_results -a -vThe-vargument will make the program print progress messages to the console as it runs, for example:Parsing protein sequences from input files...
Found 404954 translations in 1 file(s)...
Creating MMseqs2 database...
Performing sequence-sequence clustering...
Parsing sequence-sequence phams...
Building profiles from sequence-sequence phams...
Extracting consensus sequences from profiles...
Performing profile-consensus clustering...
Parsing profile-consensus phams...
Found 27358 phamilies in dataset...
Computing phamily alignments with Clustal Omega...
[############                                     ] 25%This may be especially helpful on very large or highly diverse datasets.Using PhaMMseqs as a libraryFor most simple use cases, the following import statement should suffice.from phammseqs import *This will import two classes and two high-level functions into the namespace:SequenceDB,Pham,assemble_phams,
andmerge_seq_hmm_phams. Initialize aSequenceDBto begin:db = SequenceDB()Load the contents of a FASTA file into a SequenceDB instance like this:db.load("/path/to/file.fasta")The FASTA parser does not care if your file is in 2-line or multi-line/wrapped FASTA format (or mixed). So long as the
file does not contain duplicate headers, theload()function should work. If your FASTA file contains duplicate
headers, aValueErrorwill be raised, so this alternate database load strategy can be used:from phammseqs.fileio import read_fasta

for header, sequence in read_fasta("/path/to/file.fasta"):
    try:
        db.add_gene(header, sequence)
    except ValueError as err:
        print(err)      # will print the error message but keep adding genes to dbThe size of the database can be queried two different ways:len(db)                 # number of genes in the database
len(db.translations)    # number of non-redundant genes in the databaseThe complete database can be iterated over like so:for geneid, translation in db:
    print(f">{geneid}\n{translation}\n")Alternatively, just the non-redundant sequences can be iterated:for geneid, translation in db.nr_genes:
    print(f">{geneid}\n{translation}\n")A FASTA file can be written containing just the non-redundant sequences like this:db.write("/path/to/file.fasta", nr=True)    # nr=False for all genesPham assembly is pretty easy with theassemble_phamsfunction. You'll need to define the clustering parameters in two
dictionaries (one for sequence-sequence clustering, one for profile-consensus clustering):seq_params = {"identity": 35, "coverage": 80, "evalue": 0.001,
              "sensitivity": 7, "cluster_mode": 0, "cluster_steps": 1}
hmm_params = {"identity": 15, "coverage": 70, "evalue": 0.001,
              "sensitivity": 7, "cluster_mode": 0, "cluster_steps": 3}

phams = assemble_phams(db, seq_params, hmm_params)If profile-consensus clustering is not needed, simply omit the hmm_params:phams = assemble_phams(db, seq_params)phamsis a list ofPhamobjects, which have a few useful attributes and functions in addition to all those found
in the parent class (SequenceDB), for example:pham = phams[0]
pham.minimum_length     # return length of shortest gene -> int
pham.average_length     # return average gene length     -> float
pham.maximum_length     # return length of longest gene  -> int
pham.is_orpham          # is this pham an orpham?        -> boolIf one has reason to do so, phams can easily be merged:first, second = phams[0], phams[1]
len(first), len(second) # 775, 682
first.merge(second)     # copies every sequence from second into firstFar more advanced workflows can be built leveraging the other submodules in phammseqs. For example, one can directly
invoke MMseqs2 pipelines, or run ClustalO to generate MSAs of individual FASTA files of interest.