.. _raxml:

=====
RAxML
=====

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

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

According to the `page of RAxML <https://cme.h-its.org/exelixis/web/software/raxml/>`_, RAxML (Randomized Axelerated Maximum Likelihood) is a popular program for phylogenetic analyses of large datasets under maximum likelihood.

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

* raxml/8.2.11 (default)

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

.. code-block:: bash

   # Load RAxML
   module load raxml/8.2.11

   # Check available executables
   ls $RAXML_DIR

Serial Job Submission
=====================

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

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

   export INPUT="alignment.phy"
   export OUTPUT="RAxML_*"

   module load raxml/8.2.11

   job-nanny raxmlHPC-PTHREADS-SSE3 -T $SLURM_CPUS_PER_TASK \
                    -p 12345 -m PROTGAMMAWAG -s alignment.phy \
                    -n raxml_output -# 100

MPI Job Submission
==================

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

   #!/bin/bash
   #SBATCH -J raxml_mpi
   #SBATCH -N 2
   #SBATCH --ntasks-per-node=28
   #SBATCH -t 48:00:00
   #SBATCH --mem-per-cpu=2G

   export INPUT="alignment.phy"
   export OUTPUT="RAxML_*"

   module load raxml/8.2.11

   job-nanny srun -n $SLURM_NTASKS raxmlHPC-MPI-SSE3 \
                    -p 12345 -m PROTGAMMAWAG -s alignment.phy \
                    -n raxml_mpi -# 100

Job Submission with Bootstrap
=============================

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

   #!/bin/bash
   #SBATCH -J raxml_boot
   #SBATCH -N 2
   #SBATCH --ntasks-per-node=28
   #SBATCH -t 72:00:00
   #SBATCH --mem-per-cpu=2G

   export INPUT="alignment.phy"
   export OUTPUT="RAxML_*"

   module load raxml/8.2.11

   # Step 1: Best tree search
   job-nanny srun -n $SLURM_NTASKS raxmlHPC-MPI-SSE3 \
                    -p 12345 -m PROTGAMMAWAG -s alignment.phy \
                    -n best_tree -# 20

   # Step 2: Bootstrap
   job-nanny srun -n $SLURM_NTASKS raxmlHPC-MPI-SSE3 \
                    -p 12345 -b 12345 -m PROTGAMMAWAG -s alignment.phy \
                    -n bootstrap -# 100

   # Step 3: Consensus tree
   job-nanny raxmlHPC-SSE3 -m PROTGAMMAWAG -J MR -z RAxML_bootstrap.bootstrap \
                    -n consense_tree

Example Input File (PHYLIP)
===========================

.. code-block:: text
   :caption: alignment.phy

   4 100
   Taxa1      ATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCG...
   Taxa2      ATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCG...
   Taxa3      ATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCG...
   Taxa4      ATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCG...

Main Options
============

.. list-table:: RAxML Options
   :header-rows: 1
   :widths: 20 80

   * - Option
     - Description
   * - ``-s``
     - Alignment file
   * - ``-n``
     - Run name (suffix for output files)
   * - ``-m``
     - Evolution model (PROTGAMMAWAG, GTRGAMMA, etc.)
   * - ``-p``
     - Random seed for parsimony
   * - ``-b``
     - Random seed for bootstrap
   * - ``-#``
     - Number of searches/replicates
   * - ``-T``
     - Number of threads (PTHREADS version)
   * - ``-f a``
     - Rapid bootstrap and best tree search
   * - ``-f b``
     - Draw bipartitions on tree
   * - ``-f j``
     - Calculate consensus tree
   * - ``-x``
     - Seed for rapid bootstrap

Rapid Analysis with Bootstrap
=============================

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

   #!/bin/bash
   #SBATCH -J raxml_fast
   #SBATCH -N 2
   #SBATCH --ntasks-per-node=28
   #SBATCH -t 48:00:00
   #SBATCH --mem-per-cpu=2G

   export INPUT="alignment.phy"
   export OUTPUT="RAxML_*"

   module load raxml/8.2.11

   # Option -f a: complete analysis with bootstrap
   job-nanny srun -n $SLURM_NTASKS raxmlHPC-MPI-SSE3 \
                    -f a -x 12345 -p 12345 -# 100 \
                    -m PROTGAMMAWAG -s alignment.phy \
                    -n complete_analysis

Job Array for Multiple Genes
============================

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

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

   GENES=(
       "gene1.phy"
       "gene2.phy"
       "gene3.phy"
       "gene4.phy"
       "gene5.phy"
       "gene6.phy"
       "gene7.phy"
       "gene8.phy"
       "gene9.phy"
       "gene10.phy"
   )

   GENE=${GENES[$SLURM_ARRAY_TASK_ID-1]}
   export INPUT="$GENE"
   export OUTPUT="raxml_${GENE%.phy}/"

   module load raxml/8.2.11

   mkdir -p raxml_${GENE%.phy}
   cd raxml_${GENE%.phy}
   cp ../$GENE .

   job-nanny raxmlHPC-PTHREADS-SSE3 -T $SLURM_CPUS_PER_TASK \
                    -p 12345 -m PROTGAMMAWAG -s $GENE \
                    -n ${GENE%.phy} -# 100

Results Analysis
================

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

   #!/bin/bash
   #SBATCH -J analyze_raxml
   #SBATCH -N 1
   #SBATCH -n 1
   #SBATCH -t 01:00:00
   #SBATCH --mem=2G

   # Extract final likelihood
   grep "Final GAMMA" RAxML_*.out | awk '{print $6}' > likelihoods.txt

   # Extract bootstrap support
   grep "bootstrap" RAxML_bipartitions.* > bootstrap_support.txt

   # Convert to Newick (already in format)
   cat RAxML_bestTree.* > best_trees.nwk

   # Generate statistics
   echo "Analysis statistics:" > stats.txt
   echo "==========================" >> stats.txt
   
   for tree in RAxML_bestTree.*; do
       echo "File: $tree" >> stats.txt
       echo "Length:" $(grep -o ")" $tree | wc -l) "branches" >> stats.txt
       echo "" >> stats.txt
   done

References
==========

- Documentation: https://cme.h-its.org/exelixis/web/software/raxml/
- Manual: https://cme.h-its.org/exelixis/resource/download/NewManual.pdf
- Tutorial: https://cme.h-its.org/exelixis/web/software/raxml/hands_on.html

.. seealso::

   - :ref:`raxml-ng` - Newer version
   - :ref:`beast` - Bayesian analysis
   - :ref:`exabayes` - Bayesian alternative
   - :ref:`running_simulations` - How to submit jobs