Installation

• Download the UBCG2.zip file. (Go to the download page)
• External programs (See requirements in the download page) must be installed and their path must be designated in the programPath file.
• It has been tested on Linux and Mac OS X 10 or higher. MS Windows is not supported due to the external programs used. Please use a virtual Linux machine such as Virtualbox.
• Unzip the UBCG2.zip file in the desired directory.

A typical structure of directories

• The program's root directory must contain the "UBCG2.jar" and "UBCGtree.jar" file and the programPath file that contains the location information of the external software tools.
• "fasta" directory contains the FASTA format files holding example genome/contig sequences.
• "ucg" directory contains JSON format files (=*.ucg) holding UBCG2 gene sequences with metadata.
• "output" directory contains all output files generated by the UBCG2 tool. Within the "output" directory, results of each run are stored in the separate directory (defined by "-run_id").

Running UBCG2 pipeline

Step 1: Converting genome assemblies or contigs (fasta) to .ucg files

• Command: ex) java -jar UBCG2.jar -i fasta/contigs.fasta -ucg_dir path -label e.coli -hmm hmm/ubcg_v2.hmm
       Extracting the gene sequences, which are included in ubcg_v2.hmm profile, from contig.fasta and save as an ucg file in the path.
        ex) java -jar UBCG2.jar -p cds_protein.fasta -ucg_dir path -label e.coli -hmm hmm/ubcg_v2.hmm
       Extracting gene sequences from a protein CDS file. Only protein sequences are extracted.
        ex) java -jar UBCG2.jar -p cds_protein.fasta -n cds_dna.fasta -ucg_dir path -label "Halobacterium sp." -hmm hmm/uacg.hmm
       Extracting the gene sequences (gene set in uacg.hmm) from nucleotide/protein CDS files. In this case, the target genome is an archaea.
• This command extract core genes from a fasta file and save to an ucg file using prodigal and hmmsearch.
• You are required to designate the following parameters:
  • -i                  : a contig file (fasta format)
  • -p                 : a CDS protein file (fasta format; -i or this option must be entered)
  • -n                 : a CDS nucleotide file (this is optional)
  • -ucg_dir       : directory to save a ucg file. The name of ucg file will be same as the fasta file. (e.g. -ucg_dir ucg)
  • -label            : full label of the strain/genome. If there is a blank, it must be encompassed by single quotes (e.g. -label "Escherichia coli O157 876").
  • -hmm            : profile hmm for the core gene set (ubcg.hmm for bacteria, uacg.hmm for archaea)
• The followings are optional
  • -g                  : translation table for translation. (-g parameter in Prodigal) use this option when you use other genetic code. most bacteria use the 11 table (Default : 11, the bacterial and archaeal code)
  • -t                  : use multi-threads (Default : 1)
• The followings are optional, but useful metadata and these will be used to change labels in trees
  • -taxon_name   : name of species (e.g. -taxon_name "Escherichia coli")
  • -strain_name   : name of the strain (e.g. -strain_name "JC 126")
  • -type    : add this if a strain is the type strain of species or subspecies (e.g. -type)
  • -acc     : accession of a genome sequence. Usually, NCBI's assembly accession is used for public domain data.
  • -uid     : this is a unique integer id. If you do not designate, one will be automatically generated.
  • -taxonomy   : taxonomy of the species
  • -targ_taxon  : target taxon

Step 2: Generating output files from .ucg files

• UBCGtree.jar generates following output files.

  File	Description
  concatenated_gsi(n).nwk	UBCG tree inferred using concatenated (n) gene sequences with GSI instead of bootstrap value.
  concatenated.nwk	UBCG tree inferred using concatenated (n) gene sequences. This tree is same as default output of RAxML/FastTree
  aligned_concatenated.fasta	Concatenated sequence of aligned core genes.
  (gene).nwk	Gene tree inferred from only single gene sequence.
  aligned_(gene).fasta	Aligned single gene sequences.
  (run_id).log	Log file that contains detailed information about the pipeline run
  (run_id).trm	A JSON format file that contains Newick-format trees and metadata of individual core gene trees and a UBCG tree.

• Place all of the .ucg files that you want to include in the analysis into a single directory
• Command: ex) java -jar UBCGtree.jar align -ucg_dir [directory] -run_id mytest1 -leaf uid,label
       Align all of the genes included in the [directory], concatenate, filter gap-rich columns, infer a UBCG tree (leaves are labeled with their uid and label) and save all results in "output/mytest1" directory.
• You are required to designate the following parameters:
  • -ucg_dir  : directory of ucg files that you want to include in the analysis
  • -leaf     : label the leaves' name in output tree and sequences files with selected metadata. Choose at least one from following options (their metadata must be included in .ucg files) 'uid', 'acc', 'label', 'taxon', 'strain', 'type', 'taxonomy'
    ex) -leaf uid : label the leaves' names with their id
    ex) -leaf acc,label,taxon : label the leaves' names with accession, label, taxon_name
    ex) -leaf uid,acc,label,taxon,strain,type,taxonomy : label the leaves' names with all of the metadata
• Optional parameters:
  • -out_dir  : directory for saving the output directory (Default : 'output')
  • -run_id   : run identifier. All of the output files are saved in a directory named as run_id. If you don't designate, one will be generated automatically as a long integer.
    • e.g. john_115, mycoplasma_1
  • -a     : alignment sequence type (Default : codon)
    • nucleotide : nucleotide sequence alignment
    • protein   : amino acid sequence alignment
    • codon  : codon-based alignment (output is nucleotide sequences, but alignment is carried out using amino acid sequences).
    • codon12 : same as "codon" option but only 1st and 2nd nucleotides of a codon are selected. The 3rd position usually shows high variability.
  • -t     : number of threads to be used (Default : 1)
  • -f     : filtering cutoff for gap-rich columns (Default: 50)
    • Enter 0~100
    • 0 to select all alignment positions (do not remove gap-rich columns)
    • 100 to select positions that are present in all of the genomes
    • 50 to select positions that are present in more than a half of genomes
  • -fasttree   : use FastTree for phylogeny reconstruction (Default : use RAxML)
  • -m      : A model used to infer trees
    
    (Default : JTT+CAT for a protein alignment / GTR+CAT for a nucleotide alignment)
    --Models (See RAxML or FastTree manual for the detailed information)
    For RAxML - NUCLEOTIDE sequences
    

    GTRCAT[X], GTRCATI[X], ASC_GTRCAT[X],
    GTRGAMMA[X], ASC_GTRGAMMA[X], GTRGAMMAI[X]
    

    - AMINO ACID sequences
    PROTCATmatrixName[F|X], PROTCATImatrixName[F|X],
    ASC_PROTCATmatrixName[F|X], PROTGAMMAmatrixName[F|X],
    ASC_PROTGAMMAmatrixName[F|X], PROTGAMMAImatrixName[F|X]
    Available aa matrixName: DAYHOFF, DCMUT, JTT, MTREV, WAG, RTREV, CPREV, VT,
    BLOSUM62, MTMAM, LG, MTART, MTZOA, PMB, HIVB, HIVW,
    JTTDCMUT, FLU, STMTREV, DUMMY, DUMMY2, AUTO, LG4M,
    LG4X, PROT_FILE, GTR_UNLINKED, GTR
    (optional appendix "F": Use empirical base frequencies)
    (optional appendix "X": Use a ML estimate of base frequencies)
    

    For FastTree - NUCLEOTIDE sequences
    JCcat, GTRcat, JCgamma, GTRgamma
    - AMINO ACID sequences
    JTTcat, LGcat, WAGcat, JTTgamma, LGgamma, WAGgamma
  • -gsi_threshold: threshold for calculating Gene Support Index (GSI). (1~100)

    Even if the exact bipartition doesn't exist in a gene tree, it is regarded as a supported bipartition based on their similiarity. It is when the number of genomes more than specified threshold (percentage) of all genomes (leaves) support the topology of bipartition. A value of 95 or higher is recommended. (Default: 95)

Getting a gene tree or UBCG tree labelled with replaced leaf names using metadata

• After running the step2, use this when you want to change the labels of leaves in a tree.
• Command: ex) java -jar UBCGtree.jar replace 'run_id'.trm UBCG -taxon -strain
        Making UBCG tree file that uses both taxon_name and strain_name as labels
         ex) java -jar UBCGtree.jar replace 'run_id'.trm rpoB -acc -taxon -type
        Making rpoB tree file that uses accession, taxon_name and strain_name as labels
• You are required to designate the following parameters:
  • "(run_id).trm"
  • "(gene)"
• Labeling options. Add one or more than one parameter. Selected information will be included in leaf names.
  • -uid
  • -acc
  • -label
  • -taxon
  • -strain
  • -type
  • -taxonomy