====== Structure ======

Structure is a free software package for using multi-locus genotype data to investigate population structure.

===== Information =====

  * Latest version: 2.3.4
  * Added: June, 2014
  * Link: https://web.stanford.edu/group/pritchardlab/structure.html

===== Usage =====

See which versions are available:
<code>$ module avail structure</code>

Load one version into your environment and run it:
<code>$ module load structure/2.3.4
$ structure</code>

==== Sample Script =====

Here's a script to run structure using the SLURM job scheduler whereby each structure iteration is submitted as a separate SLURM batch job:

<code>#!/bin/env bash

## shell script to run structure in the background using SLURM job scheduler
##      - each structure repetition is a submitted as separate slurm batch job
##      - when running the script, provide population size(K) and full path to 
##        mainparams, extraparams and input files

## usage: run-structure.sh K /path/to/mainparams /path/to/extraparams
## where:
##      k: population size(integer)
## example: run-structure.sh 5 /home/joguya/structure/mainparams /home/joguya/structure/extraparams

# defaults
readonly PROGNAME=$(basename $0)
readonly SCRATCH_DIR="/var/scratch/$USER/structure-$(date +%Y-%m-%d)"

## show script usage
function show_usage() {
    cat <<-EOF
Usage: $PROGNAME K /path/to/mainparams /path/to/extraparams /path/to/inputfile
where: K is a number representing the population size

Example: $PROGNAME 5 /home/joguya/structure/mainparams /home/joguya/structure/extraparams /home/joguya/structure/241SNPs-struct.in
EOF

    exit 1
}

## parse input
num_re='^[0-9]+$'
if ! [[ $1 =~ $num_re ]]; then
    echo "The population size(K): $1 is not a number. Please provide a number."
    show_usage
elif [[ ! -f $2 ]]; then
    echo "The mainparams file: $2 doesn't exist."
    show_usage
elif [[ ! -f $3 ]]; then
    echo "The extraparams file: $3 doesn't exist."
    show_usage
elif [[ ! -f $4 ]]; then
    echo "The input file: $4 doesn't exist."
    show_usage
else
    readonly POPULATION=$1
    readonly REPS=$POPULATION
    readonly MAINPARAMS=$2
    readonly EXTRAPARAMS=$3
    readonly INFILE=$4
fi

readonly CWD=$PWD

for rep in $(seq 1 $REPS)
do
        for pop in $(seq 1 $POPULATION)
        do
	echo "REP: $rep POP: $pop"
    outfile="$SCRATCH_DIR/$(basename $INFILE)_K${pop}-rep${rep}"
                sbatch <<BATCH_SCRIPT
#!/bin/env bash
#SBATCH -n 1
#SBATCH -J structure
#SBATCH -p batch
#SBATCH -w mammoth

module load structure/2.3.4

# create working dir
mkdir -p $SCRATCH_DIR

# make sure output is going to /var/scratch
cd $SCRATCH_DIR

# run structure with a different random seed for each run
structure-gcc492 -m $MAINPARAMS -e $EXTRAPARAMS -K $POPULATION  -D $RANDOM -i $INFILE -o $outfile

# copy back results to data dir.
mv -v ${SCRATCH_DIR} $CWD

echo "Your results are in: $CWD directory"

BATCH_SCRIPT

        done
done</code>

Usage:

<code>./run-structure.sh 5 /home/joguya/structure/mainparams /home/joguya/structure/extraparams /home/joguya/structure/241SNPs-struct.in</code>

===== Installation =====
Notes from the sysadmin during installation:

<code>$ cd /tmp
$ wget https://web.stanford.edu/group/pritchardlab/structure_software/release_versions/v2.3.4/structure_kernel_source.tar.gz
$ tar xf structure_kernel_source.tar.gz 
$ cd structure_kernel_src
$ make
$ sudo cp structure /export/apps/structure/2.3.4/bin</code>