Structure

Description

structure est un logiciel gratuit qui utilise les données de génotypage de locus multiples dans la recherche en structure génétique des populations. Il est utilisé pour inférer la présence de populations distinctes, assigner des individus à des populations, étudier les zones hybrides, identifier les individus migrants et estimer la fréquence des allèles dans les populations avec individus migrants. structure peut être employé avec la plupart des marqueurs génétiques couramment utilisés dont SNPS, RFLP, AFLP et les microsatellites.

Versions installées

Consultez la liste des logiciels disponibles pour connaître la version à jour du module structure (structure/2.3.4 en date de janvier 2019).

Utilisation

Au démarrage en ligne de commande sans options, structure s’attend à trouver les trois fichiers suivants dans le répertoire courant :

• mainparams (exemples),
• extraparams(exemples),
• fichier de données; le fichier peut être identifié par le paramètre INFILE de mainparams ou en ligne de commande avec -i.

Pour la description des paramètres et des formats de fichiers, consultez la documentation au chapitre 7, Running structure from the command line. La section 7.4 décrit plusieurs options pour modifier les paramètres.

Voici un exemple d’un script de soumission :

File : structure_job.sh

#!/bin/bash
#SBATCH --time=0-0:30           # time limit (D-HH:MM)
module load structure
structure -i data_file1  -o results1

Exécution parallèle : StrAuto et StructureHarvester

structure n’est pas conçu pour travailler en parallèle; cependant, pour travailler avec la méthode Evanno les outils StrAuto et StructureHarvester sont utilisés pour automatiser la préparation de processus multiples et l’agrégation des résultats.

Considérations pratiques

Le chapitre 8 du manuel de l’utilisateur pour StrAuto montre un exemple de tâches exécutées sur des grappes de CHP avec l’ordonnanceur Slurm. Cet exemple fonctionne mieux lorsque le nombre total de processus est un multiple du nombre de cœurs demandés. Si ce n’est pas le cas, certains des CPU qui ont été alloués ne seront pas utilisés pendant que les derniers processus structure sont exécutés, ce qui n’est pas une utilisation maximale des ressources de calcul.

De plus, le temps d’exécution demandé doit être suffisant pour tenir compte des multiples processus structure qui vont suivre. Ceci est un choix raisonnable dans le cas de processus qui exigent un temps d’exécution relativement court, mais les tâches plus longues resteront plus longtemps en attente en raison de la politique d'ordonnancement.

Exécution de processus de longue durée

Le script create_strauto_slurm_scripts.py au bas de cette section est conçu pour vous aider à exécuter des tâches Structure ordonnancées par Slurm sur les grappes de Calcul Canada. Les outils requis sont Structure, StrAuto et StructureHarvester.

Utilisation :

• Placez le script create_strauto_slurm_scripts.py dans un répertoire avec

• strauto_1.py et input.py de StrAuto;
• structureHarvester.py et harvesterCore.py de StructureHarvester;
• le fichier de données. my_dataset.str.

• Rendez create_strauto_slurm_scripts.py exécutable avec

[name@server ~]$ chmod u+x create_strauto_slurm_scripts.py

* Vous devriez maintenant avoir les fichiers suivants :

[name@server ~]$ ls -F
create_strauto_slurm_scripts.py*  harvesterCore.py  
input.py                          my_dataset.str  
strauto_1.py*                     structureHarvester.py*

• Modifiez les paramètres de input.py tel que décrit dans le manuel StrAutol.

• Assurez-vous de configurer l'option parallel = True (question 23).

• Ajustez les paramètres (lignes 65-70) :

• Définissez une valeur appropriée pour max_jobtime, soit une durée minimale pour l’exécution d’un processus structure unique.
• Utilisez slurm_account pour indiquer dans quel compte Slurm soumettre la tâche.
• Définissez une valeur appropriée pour submit_delay afin d’éviter de surcharger l’ordonnanceur.

• Exécutez les commandes suivantes :

[name@server ~]$ module load python/2.7

[name@server ~]$ ./strauto_1.py
input.py found. Proceeding!
----------------------------------------------------------------------
  Finished entering data for 'my_dataset'.  Verify your information.
----------------------------------------------------------------------
              Maximum number of assumed populations :   4
                                   Number of burnin :   1000
                                Number of MCMC reps :   1000
                                    Name of dataset :   my_dataset
[...]
             Run Structure Harvester automatically? :   True
----------------------------------------------------------------------
                  (a)ccept to start writing output files.
                     (q)uit if you find errors above.
            Then correct the input file and rerun this script
>> a
Preparing to write...
Now writing 'mainparams' file for my_dataset!
Now writing 'extraparams' with default values for my_dataset!
-------------------------------
Checking for Structure binary
-----------------------------------------
Now writing 'runstructure' shell script

[name@server ~]$ ./create_strauto_slurm_scripts.py
Creating SLURM job scripts...
created 40 job scripts.

Creating directories...done!

Creating submission helper script...
created helper script: "submit_strauto_jobs.sh"

Creating postprocessing script...
created post-script: "post_strauto.sh"

• Soumettez les tâches avec

[name@server ~]$ bash submit_strauto_jobs.sh
Submitted batch job 12345001
Submitted batch job 12345002
[...]
Submitted batch job 12345040

• Lorsque toutes les tâches sont terminées, lancez bash post_strauto.sh pour effectuer l’agrégation des résultats et exécuter StructureHarvester.

Script 'create_strauto_slurm_scripts.py'

File : create_strauto_slurm_scripts.py

#!/usr/bin/env python
''' 
create_strauto_slurm_scripts.py
===============================

This script is designed to be a supplement to running Structure[1] jobs on
Compute Canada HPC clusters that are using the Slurm Workload manager.
It is meant to be used with Structure, StrAuto[2] and StructureHarvester[3].

Usage:
******

* Place this script 'create_strauto_slurm_scripts.py' into a directory along with
    * 'strauto_1.py' and 'input.py' from StrAuto[2].
    * 'structureHarvester.py' and 'harvesterCore.py' from StructureHarvester[3]
    * The file with the Structure dataset e.g. 'sim.str'.
* Edit the settings in 'input.py' as described in the StrAuto User Manual.
    * Make sure to set the option 'parallel = True' (question 23).
* Adjust the parameters in this file (ca. lines 65-70):
    * Set 'max_jobtime' to a duration where you can be reasonably sure that no
      individual Structure run takes longer than this.
    * In cases where a user can submit under multiple Slurm-accounts
      'slurm_account' can be used to specify under which account to submit.
    * To avoid overloading the Scheduler, the submission helper script delays
      each submission by a time defined by 'submit_delay'.
* Run the following commands:
    * ./strauto_1.py
    * ./create_strauto_slurm_scripts.py
* Submit the jobs with:
    * ./submit_strauto_jobs.sh
* After all jobs have completed, run './post_strauto.sh' to aggregate the
  results and run StructureHarvester.

[1] Structure: http://web.stanford.edu/group/pritchardlab/structure.html
[2] StrAuto:   http://www.crypticlineage.net/pages/software.html
[3] Harvester: http://alumni.soe.ucsc.edu/~dearl/software/structureHarvester/
               https://github.com/dentearl/structureHarvester

LICENSE:
========
This program is licensed under the conditions of the "MIT License".

Copyright 2017-2020 Oliver Stueker <ostueker(a)ace-net.ca>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
'''
from __future__ import print_function
import re, os, sys
##############################################################################
### Please adjust the following parameters:
##############################################################################
max_jobtime = '1-0:00:0' # format: d-hh:mm:ss
slurm_account = None     # e.g.: slurm_account='def-somegroup'
submit_delay = '0.5s'    # pause this long between job submissions
job_prefix = None        # (optional) e.g.: job_prefix='strauto'

##############################################################################
### Don't make any changes below this line:
##############################################################################
template = '''#!/bin/bash
#SBATCH --ntasks=1
#SBATCH --time={MAXTIME:}              # d-hh:mm:ss
#SBATCH --job-name={JOBNAME:}
#SBATCH --chdir={DIRECTORY:}
#SBATCH --output=%x_%j_slurm.out
{SLURM_ACCT:}
module load structure/2.3.4

{STRUCTURE_COMMAND}
'''

post_template = '''#!/bin/bash
mv {KLIST:} results_f/
mkdir harvester_input
cp results_f/k*/*_f harvester_input
echo "The structure runs have finished."

# Run structureHarvester.py
./structureHarvester.py --dir harvester_input --out harvester --evanno --clumpp
echo 'structureHarvester run has finished.'

# Clean up Harvester input files.
zip {DATASET:}_Harvester_Upload.zip harvester_input/*
mv {DATASET:}_Harvester_Upload.zip harvester/
rm -rf harvester_input
'''

if __name__ == '__main__':
    if not os.path.exists('structureCommands'):
        print('ERROR: File "structureCommands" does not exist!')
        print('You need to run "./strauto_1.py" before running "{}".'
              .format(os.path.basename(sys.argv[0])))
        sys.exit(1)
    # initialize some variables
    scripts_dir = 'slurm_scripts'
    job_directory = os.getcwd()
    if slurm_account:
        slurm_account = '#SBATCH --account='+slurm_account
    else:
        slurm_account = ''
    re_jobname = re.compile(r'-o (k\d+)/((.+)_\1_run\d+) ')
    job_scripts = []
    klist = set()
    
    with open('structureCommands', 'r') as structureCommands:
        print("Creating SLURM job scripts...")
        for line in structureCommands:
            match = re_jobname.search(line)
            if match:
                kn = match.group(1)
                jobname = match.group(2)
                dataset = match.group(3)

                klist.add(kn)
                if job_prefix:
                    jobname = '_'.join([job_prefix, jobname])

                line = line.replace('./structure', 'structure')

                job_script_content = template.format(
                        SLURM_ACCT=slurm_account,
                        MAXTIME=max_jobtime,
                        JOBNAME=jobname,
                        DIRECTORY=job_directory,
                        STRUCTURE_COMMAND=line,
                    )

                if not ( os.path.exists(scripts_dir) and
                         os.path.isdir(scripts_dir) ):
                    os.mkdir(scripts_dir)

                job_script_name = os.path.join( scripts_dir,
                                    'slurm_job_{:}.sh'.format(jobname))
                with open(job_script_name, 'w') as slurm_script:
                    slurm_script.write(job_script_content)
                job_scripts.append(job_script_name)
        print("created {:} job scripts.\n".format(len(job_scripts)))

    print("Creating directories...", end='')
    directories = ['results_f', 'log', 'harvester']
    for kn in sorted(klist):
        directories.append(kn)
        directories.append(os.path.join('log', kn))
    print('done!', end='\n\n')

    for directory in directories:
        if not os.path.exists(directory):
            os.mkdir(directory)

    print('Creating submission helper script...')
    helper_script_name='submit_strauto_jobs.sh'
    with open(helper_script_name, 'w') as helper_script:
        helper_script.write('#!/bin/bash\n')
        for job_script in job_scripts:
            helper_script.write('sleep 0.5s ; sbatch {:}\n'.format(job_script))
    print('created helper script: "{:}"\n'.format(helper_script_name))

    print('Creating postprocessing script...')
    post_script_name='post_strauto.sh'
    with open(post_script_name, 'w') as pst_script:
        pst_script.write(post_template.format(KLIST=' '.join(sorted(klist)),
                                              DATASET=dataset))
    print('created post-script: "{:}"\n'.format(post_script_name))