.. _faststructure:

=============
fastStructure
=============

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

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

According to the `page of fastStructure <https://rajanil.github.io/fastStructure/>`_, fastStructure is an algorithm for inferring population structure from large SNP genotype data. It is based on a variational Bayesian framework for posterior inference and is written in Python.

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

* fastStructure/1.0 (default)

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

.. code-block:: bash

   # Load fastStructure
   module load fastStructure/1.0

   # Verify installation
   python structure.py -h

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

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

   #!/bin/bash
   #SBATCH -J faststructure
   #SBATCH -N 1
   #SBATCH -n 1
   #SBATCH -t 24:00:00
   #SBATCH --mem=8G

   export INPUT="testdata"
   export OUTPUT="testoutput_simple"

   module load fastStructure/1.0

   job-nanny python structure.py -K 3 --input=testdata \
                 --output=testoutput_simple --full --seed=100

Analysis for Multiple K Values
==============================

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

   #!/bin/bash
   #SBATCH -J faststructure_k
   #SBATCH -N 1
   #SBATCH -n 1
   #SBATCH -t 48:00:00
   #SBATCH --mem=16G

   export INPUT="genotypes"
   export OUTPUT="results/"

   module load fastStructure/1.0

   mkdir -p results

   # Run for K from 1 to 10
   for K in {1..10}; do
       job-nanny python structure.py -K $K --input=genotypes \
                     --output=results/output_K${K} --full --seed=100
   done

Job Array for Different K Values
================================

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

   #!/bin/bash
   #SBATCH -J faststructure_array
   #SBATCH --array=1-10
   #SBATCH -N 1
   #SBATCH -n 1
   #SBATCH -t 12:00:00
   #SBATCH --mem=8G

   export INPUT="genotypes"
   export OUTPUT="results_K${SLURM_ARRAY_TASK_ID}/"

   module load fastStructure/1.0

   K=$SLURM_ARRAY_TASK_ID
   mkdir -p results_K${K}

   job-nanny python structure.py -K $K --input=genotypes \
                 --output=results_K${K}/output --full --seed=100

Choosing the Best K
===================

After running for several K values, use the ``chooseK.py`` tool to select the best:

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

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

   export INPUT="results_*"
   export OUTPUT="k_selection.txt"

   module load fastStructure/1.0

   job-nanny python chooseK.py --input=results_K* > k_selection.txt

Input Data Format
=================

fastStructure expects files in PLINK format:

.. code-block:: text

   genotypes.bed
   genotypes.bim
   genotypes.fam

Or the provided example format can be used.

Results Visualization
=====================

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

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

   export INPUT="results_K* output_simple_meanQ"
   export OUTPUT="plots/"

   module load fastStructure/1.0
   module load anaconda3

   source activate plotting_env  # Environment with matplotlib

   # Python script for plotting
   cat > plot.py << 'EOF'
   import numpy as np
   import matplotlib.pyplot as plt
   import sys
   import glob
   import os

   # Create directory for plots
   os.makedirs('plots', exist_ok=True)

   # For each K value
   for k in range(1, 11):
       # Search for results file
       pattern = f'results_K{k}/output.{k}.meanQ'
       files = glob.glob(pattern)
       
       if files:
           Q = np.loadtxt(files[0])
           
           # Create figure
           plt.figure(figsize=(10, 4))
           plt.imshow(Q, aspect='auto', cmap='viridis', interpolation='nearest')
           plt.colorbar()
           plt.title(f'Population structure - K={k}')
           plt.xlabel('Population')
           plt.ylabel('Individual')
           plt.tight_layout()
           
           # Save
           output_file = f'plots/K{k}_structure.png'
           plt.savefig(output_file, dpi=150)
           plt.close()
           print(f"Plot saved: {output_file}")
       else:
           print(f"File not found for K={k}")
   EOF

   job-nanny python plot.py

References
==========

- Documentation: https://rajanil.github.io/fastStructure/
- GitHub: https://github.com/rajanil/fastStructure
- Tutorial: https://rajanil.github.io/fastStructure/tutorial.html

.. seealso::

   - :ref:`structure` - Original Structure program
   - `ADMIXTURE <https://dalexander.github.io/admixture/>`_ - Alternative for population structure
   - :ref:`running_simulations` - How to submit jobs