.. _phyluce:

=======
Phyluce
=======

.. contents:: In this section:
   :local:
   :depth: 2

Description
===========

According to the `documentation of Phyluce <http://phyluce.readthedocs.io/en/latest/>`_, phyluce (phy-loo-chee) is a software package initially developed to analyze data collected from ultra-conserved elements (UCEs) in organism genomes.

Available Versions
==================

* phyluce/1.5.0 (default)

Loading the Module
==================

.. code-block:: bash

   # Load Phyluce
   module load phyluce/1.5.0

   # Verify installation
   phyluce --help

Job Submission
==============

.. code-block:: bash
   :caption: submit_phyluce.sh

   #!/bin/bash
   #SBATCH -J phyluce
   #SBATCH -N 1
   #SBATCH -c 12
   #SBATCH -t 7-00:00:00
   #SBATCH --mem=32G

   export INPUT="assembly.conf"
   export OUTPUT="trinity-assemblies/"

   module load phyluce/1.5.0

   job-nanny phyluce_assembly_assemblo_trinity \
       --conf assembly.conf \
       --output trinity-assemblies \
       --clean \
       --cores $SLURM_CPUS_PER_TASK

Example Configuration File
==========================

.. code-block:: text
   :caption: assembly.conf

   [samples]
   sample1:/path/to/sample1_R1.fastq,/path/to/sample1_R2.fastq
   sample2:/path/to/sample2_R1.fastq,/path/to/sample2_R2.fastq
   sample3:/path/to/sample3_R1.fastq,/path/to/sample3_R2.fastq

   [adapters]
   sample1:/path/to/adapters.fasta
   sample2:/path/to/adapters.fasta
   sample3:/path/to/adapters.fasta

Complete UCE Analysis Pipeline
==============================

.. code-block:: bash
   :caption: submit_phyluce_pipeline.sh

   #!/bin/bash
   #SBATCH -J phyluce_pipeline
   #SBATCH -N 1
   #SBATCH -c 12
   #SBATCH -t 14-00:00:00
   #SBATCH --mem=64G

   export INPUT="samples.txt probes.fasta"
   export OUTPUT="uce_results/"

   module load phyluce/1.5.0

   # 1. Trinity assembly
   phyluce_assembly_assemblo_trinity \
       --conf assembly.conf \
       --output 1-assemblies \
       --cores $SLURM_CPUS_PER_TASK

   # 2. Match contigs to probes
   phyluce_assembly_match_contigs_to_probes \
       --contigs 1-assemblies/contigs \
       --probes probes.fasta \
       --output 2-match

   # 3. Extract UCEs
   phyluce_assembly_get_match_counts \
       --locus-db 2-match/probe.matches.sqlite \
       --taxon-list-config 2-match/taxon-set.conf \
       --taxon-group 'all' \
       --output 3-taxon-sets/all-taxa-incomplete.conf

   # 4. Get complete sequences
   phyluce_assembly_get_fastas_from_match_counts \
       --contigs 1-assemblies/contigs \
       --locus-db 2-match/probe.matches.sqlite \
       --match-count-output 3-taxon-sets/all-taxa-incomplete.conf \
       --output 4-uce-fasta \
       --incomplete-matrix

   # 5. Align UCEs
   phyluce_align_seqcap_align \
       --input 4-uce-fasta \
       --output 5-alignments \
       --taxa 5 \
       --aligner mafft \
       --cores $SLURM_CPUS_PER_TASK

   # 6. Clean alignments
   phyluce_align_get_trimal_trimmed_alignments_from_untrimmed \
       --alignments 5-alignments \
       --output 6-trimmed \
       --trim-l Proportion=0.3 \
       --match-threshold 0.5

   # 7. Convert to different formats
   phyluce_align_convert_one_align_to_another \
       --alignments 6-trimmed \
       --output 7-nexus \
       --input-format fasta \
       --output-format nexus

Job Array for Parallel Processing
=================================

.. code-block:: bash
   :caption: submit_phyluce_array.sh

   #!/bin/bash
   #SBATCH -J phyluce_array
   #SBATCH --array=1-10
   #SBATCH -N 1
   #SBATCH -c 8
   #SBATCH -t 24:00:00
   #SBATCH --mem=16G

   SAMPLES=(
       "sample1"
       "sample2"
       "sample3"
       "sample4"
       "sample5"
       "sample6"
       "sample7"
       "sample8"
       "sample9"
       "sample10"
   )

   SAMPLE=${SAMPLES[$SLURM_ARRAY_TASK_ID-1]}
   export INPUT="${SAMPLE}_R1.fastq ${SAMPLE}_R2.fastq"
   export OUTPUT="${SAMPLE}_assembly/"

   module load phyluce/1.5.0

   # Create temporary configuration file
   cat > temp_${SAMPLE}.conf << EOF
   [samples]
   ${SAMPLE}:${SAMPLE}_R1.fastq,${SAMPLE}_R2.fastq
   EOF

   # Run assembly
   phyluce_assembly_assemblo_trinity \
       --conf temp_${SAMPLE}.conf \
       --output ${SAMPLE}_assembly \
       --cores $SLURM_CPUS_PER_TASK

Post-processing Tools
=====================

.. code-block:: bash
   :caption: postprocess_phyluce.sh

   #!/bin/bash
   #SBATCH -J phyluce_post
   #SBATCH -N 1
   #SBATCH -n 1
   #SBATCH -t 02:00:00
   #SBATCH --mem=4G

   module load phyluce/1.5.0
   module load R/4.0.2

   # Generate statistics
   phyluce_assembly_get_trinity_coverage \
       --assembly-dir 1-assemblies \
       --output coverage_stats.csv

   # Calculate completeness
   phyluce_assembly_get_fasta_lengths \
       --input 4-uce-fasta \
       --csv

   # Plot missing data matrix
   phyluce_plot_taxon_coverages \
       --match-counts 3-taxon-sets/all-taxa-incomplete.conf \
       --output missing_data_plot.png

   # Generate completeness heatmap
   cat > plot_coverage.R << 'EOF'
   library(ggplot2)
   library(reshape2)

   data <- read.csv('coverage_stats.csv')
   melted <- melt(data, id.vars='sample')

   p <- ggplot(melted, aes(x=variable, y=sample, fill=value)) +
        geom_tile() +
        scale_fill_gradient(low='white', high='steelblue') +
        theme(axis.text.x = element_text(angle=90, hjust=1))

   ggsave('coverage_heatmap.png', p, width=10, height=8)
   EOF

   Rscript plot_coverage.R

References
==========

- Documentation: http://phyluce.readthedocs.io/
- GitHub: https://github.com/faircloth-lab/phyluce
- Tutorial: http://phyluce.readthedocs.io/en/latest/tutorial.html

.. seealso::

   - :ref:`trinity` - Transcriptome assembly
   - :ref:`pfinderuce-swsc-en` - UCE partitioning
   - :ref:`partitionfinder` - Partition selection
   - :ref:`running_simulations` - How to submit jobs