.. _faststructure:

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

.. contents:: Nesta seção:
   :local:
   :depth: 2

Descrição
==========

De acordo com a `página do fastStructure <https://rajanil.github.io/fastStructure/>`_, fastStructure é um algoritmo para inferir estrutura populacional a partir de dados de genótipo SNP em larga escala. É baseado em uma estrutura Bayesiana variacional para inferência posterior e é escrito em Python.

Versões Disponíveis
====================

* fastStructure/1.0 (default)

Carregando o Módulo
====================

.. code-block:: bash

   # Carregar fastStructure
   module load fastStructure/1.0

   # Verificar instalação
   python structure.py -h

Submissão de Jobs Seriais
==========================

.. 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

Análise para Múltiplos K
=========================

.. 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 results/"
   export OUTPUT="results/"

   module load fastStructure/1.0

   mkdir -p results

   # Executar para K de 1 a 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 para Diferentes Valores de K
========================================

.. 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

Escolhendo o Melhor K
=======================

Após executar para vários K, use a ferramenta ``chooseK.py`` para selecionar o melhor:

.. 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

Formato dos Dados de Entrada
==============================

O fastStructure espera arquivos no formato PLINK:

.. code-block:: text

   genotypes.bed
   genotypes.bim
   genotypes.fam

Ou pode usar o formato de exemplo fornecido.

Visualização dos Resultados
=============================

.. 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 plot.py"
   export OUTPUT="plots/"

   module load fastStructure/1.0
   module load anaconda3

   source activate plotting_env  # Ambiente com matplotlib

   # Script Python para plotar
   cat > plot.py << 'EOF'
   import numpy as np
   import matplotlib.pyplot as plt
   import sys
   import glob
   import os

   # Criar diretório para plots
   os.makedirs('plots', exist_ok=True)

   # Para cada valor de K
   for k in range(1, 11):
       # Procurar arquivo de resultados
       pattern = f'results_K{k}/output.{k}.meanQ'
       files = glob.glob(pattern)
       
       if files:
           Q = np.loadtxt(files[0])
           
           # Criar figura
           plt.figure(figsize=(10, 4))
           plt.imshow(Q, aspect='auto', cmap='viridis', interpolation='nearest')
           plt.colorbar()
           plt.title(f'Estrutura populacional - K={k}')
           plt.xlabel('População')
           plt.ylabel('Indivíduo')
           plt.tight_layout()
           
           # Salvar
           output_file = f'plots/K{k}_structure.png'
           plt.savefig(output_file, dpi=150)
           plt.close()
           print(f"Plot salvo: {output_file}")
       else:
           print(f"Arquivo não encontrado para K={k}")
   EOF

   job-nanny python plot.py

Referências
============

- Documentação: https://rajanil.github.io/fastStructure/
- GitHub: https://github.com/rajanil/fastStructure
- Tutorial: https://rajanil.github.io/fastStructure/tutorial.html

.. seealso::

   - :ref:`structure` - Programa original Structure
   - `ADMIXTURE <https://dalexander.github.io/admixture/>`_ - Alternativa para estrutura populacional
   - :ref:`processando_simulacoes` - Como submeter jobs