Raymond Parcon

Moving Files and Navigating SMS Lab Filesystems in Sapelo2

Raymond Parcon — Thu, 09 Jul 2026 00:00:00 GMT

Overview

This guide introduces basic command-line navigation and file movement on Sapelo2 for users working in the SMS Lab filesystem. It covers how to log in using PuTTY, move around the /home/, /work/, /scratch/, and /project/ directories, and safely copy or back up files using the transfer node.

The examples below use username as a placeholder. Replace it with your own UGA MyID.

1. Essential Linux Commands

Command	Purpose
`pwd`	Prints the current directory you are in
`ls -l`	Lists files and directories in long format
`cd`	Changes directory
`mkdir`	Creates a new directory
`mv`	Moves or renames files and directories

Check your current location with `pwd`

After logging in, use:

pwd

Example:

username@ss-sub1 ~$ pwd
/home/username

This shows that you are currently in your home directory.

List files with `ls -l`

To view the files and directories in your current location:

ls -l

This shows file permissions, ownership, size, date modified, and file or directory names.

Change directories with `cd`

To move into another directory, use:

cd /path/to/directory

For example, to access the SMS Lab work directory:

cd /work/smslab/directory-name

After changing directories, confirm your location:

pwd

Create a directory with `mkdir`

To create a new directory:

mkdir new_directory_name

For example:

mkdir genome_assembly_backup

Move or rename files with `mv`

To move a file into another directory:

mv file.txt /work/smslab/directory-name/

To rename a file:

mv old_name.txt new_name.txt

To move a directory:

mv old_directory /work/smslab/directory-name/

2. Logging in to Sapelo2 with PuTTY

Open PuTTY and enter the appropriate server address in the Host Name field.

Transfer node

Use this when moving large files between filesystems or when working with storage locations such as /project/.

username@xfer.gacrc.uga.edu

The transfer node is intended for file movement, not for running computational jobs.

3. Starting in the Home Directory

After logging in to Sapelo2, you usually start in your home directory.

Example:

username@ss-sub1 ~$ pwd
/home/username

Your home directory is useful for small scripts, configuration files, and lightweight work. Large datasets and computational outputs should usually be stored in /work/, /scratch/, or /project/, depending on the purpose.

4. Navigating to the SMS Lab Work Directory

To move into the SMS Lab work directory:

cd /work/smslab/directory-name

Then confirm your location:

pwd

Example:

pwd
/work/smslab/directory-name

You can also list the contents of the directory:

ls -l

5. Navigating to Scratch

The same navigation commands apply to the /scratch/ directory.

For example:

cd /scratch/username

Then confirm your location:

pwd

Warning

The /scratch/ filesystem is intended for temporary files and active computational work. Files that have not been accessed or modified for more than 30 days, as per GACRC guidelines, may be automatically deleted. Do not treat /scratch/ as permanent storage.

How to Run STRUCTURE on HPC (Sapelo2) Using Structure_threader and Visualize Results Using R

Raymond Parcon — Sat, 27 Jun 2026 00:00:00 GMT

Background

STRUCTURE is a powerful tool for inferring population structure from multilocus genotype data, including single-nucleotide polymorphisms (SNPs). However, getting STRUCTURE to run efficiently is not always straightforward. It can be computationally intensive, requires careful data preparation and parameter selection, and often involves long processing times. As the number of samples, markers, and model parameters increases, the computational demand also increases substantially. In some cases, analyses can take weeks or even months to complete.

As someone still learning population genomics and bioinformatics back then, I quickly found myself facing this challenge. I needed to find a practical way to run STRUCTURE more efficiently using the high-performance computing cluster at the University of Georgia. Fortunately, I came across Structure_threader, a tool designed to help parallelize STRUCTURE runs. Even then, the process involved a considerable amount of troubleshooting.

By documenting this workflow, I hope to show the key steps I learned along the way and provide a practical guide for running STRUCTURE with the help of Structure_threader in an HPC environment. My goal is not to cover every possible scenario, but to lay out the basics clearly enough to make the process more approachable and efficient for anyone who may find themselves in the same situation I was before.

Workflow

I will describe how to run a model-based Bayesian population structure analysis using STRUCTURE through Structure_threader on the University of Georgia Sapelo2 high-performance computing environment. The workflow assumes that filtered SNPs are available in variant call format (.vcf) and will be converted to STRUCTURE format (.str) using PGDSpider.

The example below follows the analysis settings I used for my SNP dataset:

STRUCTURE version: 2.3.4
Structure_threader version: 1.3.10
Input format: haploid STRUCTURE file (.str)
Burn-in: 500000
MCMC iterations after burn-in: 1000000
Maximum number of populations tested: K = 25
Replicates per K: 10
HPC environment: UGA Sapelo2

Required files

Before running Structure_threader, place the following files in the same HPC working directory:

File	Required filename?	Purpose
`*.str`	No	STRUCTURE-formatted SNP input file
`mainparams`	Yes	Main STRUCTURE configuration file
`extraparams`	Yes	Extra STRUCTURE configuration file
`strthreader.sh`	No	SLURM job script used to run Structure_threader

Warning

The files mainparams and extraparams should keep these exact filenames. STRUCTURE expects them by name in the working directory.

Step 1. Convert VCF to STRUCTURE format using PGDSpider

Use PGDSpider to convert the filtered SNP VCF file to STRUCTURE format.

PGDSpider VCF parser settings

Use the following settings for a haploid SNP dataset:

PGDSpider VCF parser question	Recommended answer
Is the dataset haploid?	`Yes`
Exclude loci with only missing data?	`No`
Is `PL` or `GL` given in the genotype field?	`Yes`
Include non-polymorphic SNPs?	`No`
Select population definition file?	Use a population map file

The population definition file should be a plain text file with one isolate per line:

isolate001 GA
isolate002 GA
isolate003 MS
isolate004 AL

The required format is:

isolatepopulation

PGDSpider STRUCTURE writer settings

PGDSpider STRUCTURE writer question	Recommended answer
Compatible with fastSTRUCTURE format?	`No`
Include inter-marker distances?	`No`
Data type	`SNP`

The fastSTRUCTURE-compatible option should be set to No because this workflow uses haploid STRUCTURE input for STRUCTURE version 2.3.4.

Step 2. Transfer the `.str` file to Sapelo2

After conversion, transfer the .str file to the HPC working directory using FTP servers or scp

After logging in to Sapelo2, make the file UNIX-readable:

cd /full/path/to/working/directory
dos2unix <filename>.str

If mainparams, extraparams, or the SLURM script were edited on Windows, also run:

dos2unix mainparams extraparams strthreader.sh

Step 3. Prepare `mainparams`

There are two acceptable ways to prepare mainparams.

Option A. Generate `mainparams` using the STRUCTURE graphical interface

Open STRUCTURE locally.
Create a new project using the .str file.
Check the .str file in a text editor before importing.
Confirm the following:
- the missing genotype value is correct, usually -9 or 0;
- there is a row of marker names, if exported that way by PGDSpider;
- data for each individual are stored in a single line;
- individual IDs are included;
- putative population origin is included.
Export or copy the generated mainparams.
Upload mainparams to the HPC working directory.
Modify mainparams if needed.

Option B. Copy an existing `mainparams` and edit dataset-specific values

Edit at least the following fields:

#define NUMINDS    178
#define NUMLOCI    3470
#define PLOIDY     1
#define MISSING    -9
#define ONEROWPERIND 1
#define LABEL      1
#define POPDATA    1
#define MARKERNAMES 1
#define MAPDISTANCES 0
#define MAXPOPS    25
#define BURNIN     500000
#define NUMREPS    1000000

Adjust these values for each dataset:

Field	Meaning
`NUMINDS`	Number of isolates or individuals
`NUMLOCI`	Number of SNP loci
`PLOIDY`	Use `1` for haploid data
`MISSING`	Missing genotype code in the `.str` file
`MAXPOPS`	Maximum number of populations tested
`BURNIN`	Burn-in iterations
`NUMREPS`	MCMC iterations after burn-in

Important

The MAXPOPS value in mainparams must match the -K value in the Structure_threader command. For example, if MAXPOPS is 25, use -K 25.

Step 4. Prepare `extraparams`

Use the default extraparams file unless there is a specific reason to modify the STRUCTURE model. In this workflow, all remaining STRUCTURE parameters are left at their default settings.

Place extraparams in the same HPC working directory as:

mainparams
.str
strthreader.sh

Step 5. Create the Structure_threader SLURM script

Save the following script as strthreader.sh.

Revise the user-specific paths, email address, dataset name, CPU count, memory, and runtime as needed.

#!/bin/bash
#SBATCH --job-name=StructureThreader
#SBATCH --partition=batch
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=64
#SBATCH --mem=15G
#SBATCH --time=7-00:00:00
#SBATCH --output=/home/yourUGAMyID/logs/structure/%x_%j.out
#SBATCH --error=/home/yourUGAMyID/logs/structure/%x_%j.err
#SBATCH --mail-user=yourUGAMyID@uga.edu
#SBATCH --mail-type=ALL

# -------------------------
# User-defined variables
# -------------------------

WORKDIR="/full/path/to/working/directory"
DATASET=""

MAXK=25
REPS=10
THREADS=${SLURM_CPUS_PER_TASK}

INPUT_STR="${WORKDIR}/${DATASET}.str"
OUTDIR="${DATASET}_results_${MAXK}pop"

# -------------------------
# Load modules
# -------------------------

ml structure_threader/1.3.10-foss-2022a
ml Structure/2.3.4-GCC-11.3.0

# -------------------------
# Run Structure_threader
# -------------------------

cd "${WORKDIR}"

structure_threader run \
  -K "${MAXK}" \
  -R "${REPS}" \
  -t "${THREADS}" \
  -i "${INPUT_STR}" \
  -o "${OUTDIR}" \
  -st "${EBROOTSTRUCTURE}/bin/structure" \
  --log 1

Meaning of key Structure_threader arguments

Argument	Meaning
`-K 25`	Test K values from 1 to 25
`-R 10`	Run 10 replicate STRUCTURE analyses per K
`-t 64`	Use 64 parallel threads
`-i`	Input `.str` file
`-o`	Output directory name
`-st`	Absolute path to the STRUCTURE executable
`--log 1`	Write Structure_threader log information

Note

The number of threads should be consistent across the SLURM request and Structure_threader command. If #SBATCH --cpus-per-task=64, then Structure_threader should also use -t 64 or THREADS=${SLURM_CPUS_PER_TASK}.

Step 6. Check the working directory before submission

From the working directory, run:

pwd
ls -lh

Confirm that these files are present:

ls -lh <filename>.str mainparams extraparams strthreader.sh

Check the relevant STRUCTURE settings:

grep -E "NUMINDS|NUMLOCI|PLOIDY|MISSING|MAXPOPS|BURNIN|NUMREPS" mainparams

Check that the log directory exists:

mkdir -p /home/yourUGAMyID/logs/structure

Check that the modules are available:

ml spider structure_threader
ml spider structure

Step 7. Submit the job

Submit the Structure_threader job with:

sbatch strthreader.sh

Check the job status:

squeue --me

Check log files while the job is running or after it finishes:

tail -f /home/yourUGAMyID/logs/structure/StructureThreader_JOBID.out
tail -f /home/yourUGAMyID/logs/structure/StructureThreader_JOBID.err

The JOBID is automatically generated based on SLURM job number.

Step 8. Inspect output files

After the run finishes, check the output directory:

cd /full/path/to/working/directory
ls -lh ${DATASET}_results_${MAXK}pop

A complete run should contain output files for each K value and replicate. With -K 25 and -R 10, the expected number of STRUCTURE runs is:

25 K values × 10 replicates = 250 STRUCTURE runs

If some runs failed, check:

the SLURM .err file;
the Structure_threader log;
whether MAXPOPS in mainparams matches -K;
whether NUMINDS, NUMLOCI, PLOIDY, and MISSING are correct;
whether the .str file has UNIX line endings.

Step 9. Transfer results for visualization

After the run completes, transfer the files in the output directory to the local machine for visualization in RStudio using FTP servers or scp

Step 10. Visualize STRUCTURE results using R

Install and load the required R packages:

install.packages(c("ggplot2", "reshape2", "gridExtra"))
install.packages("pophelper")

Load packages:

library(pophelper)
library(ggplot2)
library(reshape2)
library(gridExtra)

Read STRUCTURE output files:

outdir <- "_results_25pop"

# Adjust the pattern depending on the exact output filenames.
# Keep only STRUCTURE result files, not SLURM logs or Structure_threader logs.
structure_files <- list.files(
  path = outdir,
  full.names = TRUE,
  recursive = TRUE
)

# Read STRUCTURE Q matrices.
qlist <- readQ(files = structure_files)

Summarize and plot Q matrices:

# Summarize runs by K.
summariseQ(qlist)

# Plot individual ancestry coefficients.
plotQ(
  qlist,
  imgoutput = "join",
  returnplot = TRUE,
  exportplot = TRUE,
  basesize = 10,
  showindlab = FALSE,
  splab = paste0("K=", sapply(qlist, ncol))
)

If isolate labels or population labels are available, import metadata and use them to order or annotate individuals before plotting.

Common problems and fixes

Problem	Likely cause	Fix
STRUCTURE fails immediately	`mainparams` or `extraparams` missing	Confirm both files are in the working directory
K values do not run as expected	`MAXPOPS` and `-K` do not match	Set both to the same maximum K
Threading does not work correctly	SLURM CPUs and `-t` differ	Use `THREADS=${SLURM_CPUS_PER_TASK}`
Input file is unreadable	Windows line endings	Run `dos2unix *.str mainparams extraparams strthreader.sh`
Wrong number of individuals or loci	Incorrect `NUMINDS` or `NUMLOCI`	Recheck `.str` file and edit `mainparams`
Missing data interpreted incorrectly	Incorrect `MISSING` value	Confirm whether missing genotypes are coded as `-9` or `0`
Job stops due to wall time	Runtime too short	Increase `#SBATCH --time`
Job stops due to memory	Memory too low	Increase `#SBATCH --mem`

Minimal final checklist

Before submitting:

The .vcf file has been converted to .str using the haploid PGDSpider settings.
The .str file is in the HPC working directory.
dos2unix has been run on input and configuration files.
mainparams is present and correctly edited.
extraparams is present.
MAXPOPS in mainparams matches -K in the Structure_threader command.
#SBATCH --cpus-per-task matches the Structure_threader thread count.
The STRUCTURE executable path is provided using ${EBROOTSTRUCTURE}/bin/structure.
The output and error log directories exist.
The job is submitted using sbatch strthreader.sh.

There you have it. I hope this workflow saves you some time and frustration in figuring out how to run STRUCTURE in an HPC environment. Please do not forget to cite the brilliant minds behind the software, modules, and R packages mentioned here. Proper citation is one small but important way we can acknowledge and thank the people who develop and maintain these tools for the research community. 😊

Honored to have been recognized in Georgia Association of Plant Pathologists 2026 Meeting

Ray Parcon — Wed, 13 May 2026 00:00:00 GMT

I’m honored to be recognized as the top oral presenter among the amazing presentations at the recently concluded Georgia Association of Plant Pathologists 2026 Meeting. I’m also proud to have shared the moment with my lab mate, Sai, who also won in the poster category. Our hearts are full to represent the research that we do, and the support and encouragement we receive from the Smith lab. 🔬🧬

I’m especially grateful to my advisors, Dr. Shavannor Smith and Dr. James Buck for their encouragement and for trusting me with this research to be able to share it, and to the UGA Department of Plant Pathology for fostering events like this where we can connect with our peers and share ideas.

And finally, to my colleagues and friends who have made the experience amazing! To have shared with them the beach sands of Cumberland and Jekyll Islands playing the Filipino game ‘patintero,’ drinking probably one too many Bahama Mama 🍹, and simply making the whole experience so unforgettable! 😍

Cheers to agriculture! 👨🏽‍🌾🌱

Had a great time doing my first research oral presentation

Ray Parcon — Wed, 11 Mar 2026 00:00:00 GMT

I’m grateful for the opportunity to share my research and the work I’m doing at the 2026 American Phytopathological Society Southern Division Meeting in Athens, Georgia.

Being surrounded by people who share the same passion for plant pathology makes the experience even more meaningful. It’s inspiring to know that the research we do has the potential to make a real impact, especially for the communities and the growers who rely on it the most. 👨🏽‍🌾🌱

I’m also deeply thankful for the support and mentorship of my advisors, who inspire me to keep growing and to take on new challenges. 💪🏽

From Science Fair to International Conferences

Ray Parcon — Wed, 06 Aug 2025 00:00:00 GMT

I vividly remember how I kept on wishing to win in our science high school fair, hoping for a chance to present our little science project at regional level. Having earned the opportunity twice, it was one of the few moments that gave me a sense of being good at something, in a time when all I carried was self-doubt.

That kid, proud and grateful for making into regionals, had no idea he would one day share his passion for research on an international stage, beside scientists he once thought only exist in textbooks.

I’m incredibly thankful for the opportunity to attend my first and second national scientific conferences to present my PhD research,

🧬 Soy 2025: 19th Biennial Conference on Molecular & Cellular Biology of Soybean 📅 July 23–26, 2025 🏫 University of Wisconsin–Madison 📍 Madison, Wisconsin

🌱 Plant Health 2025: International Annual Meeting of the American Phytopathological Society 📅 August 2–5, 2025 🌺 Hawaii Convention Center 📍 Honolulu, Hawaii

I’m deeply grateful to my research mentors, Dr. Shavannor Smith and Dr. James Buck, for their encouragement and support, to UGA Plant Pathology Department for defraying Plant Health 2025 registration, and to the UGA Graduate School for awarding me an International Travel Grant. These moments only strengthen my drive to pursue meaningful, translatable research for the benefit of the growers and the agricultural community. 🌱🔬🧬

Cheers! 🍻

Stoked to be awarded with the Graduate School 2025 Summer Research Grant

Ray Parcon — Fri, 11 Apr 2025 00:00:00 GMT

I am grateful to receive funding support from the Graduate School for my research this summer! Definitely a motivation to believe in and continue the work. A timely, great news as my virulence phenotyping assays are underway!

Excited to share my research with the public for the first time!

Ray Parcon — Tue, 04 Mar 2025 00:00:00 GMT

I had the opportunity to be one of the poster presenters at the recently concluded GAPP 2025. Listening to plenary speakers about their research was informative and inspiring, and talking to fellow plant pathologists about my research was exciting and fun!

Raymond Parcon

Moving Files and Navigating SMS Lab Filesystems in Sapelo2

Overview

1. Essential Linux Commands

Check your current location with pwd

List files with ls -l

Change directories with cd

Create a directory with mkdir

Move or rename files with mv

2. Logging in to Sapelo2 with PuTTY

Sapelo2 login node

Transfer node

3. Starting in the Home Directory

4. Navigating to the SMS Lab Work Directory

5. Navigating to Scratch

How to Run STRUCTURE on HPC (Sapelo2) Using Structure_threader and Visualize Results Using R

Background

Workflow

Required files

Step 1. Convert VCF to STRUCTURE format using PGDSpider

PGDSpider VCF parser settings

PGDSpider STRUCTURE writer settings

Step 2. Transfer the .str file to Sapelo2

Step 3. Prepare mainparams

Option A. Generate mainparams using the STRUCTURE graphical interface

Option B. Copy an existing mainparams and edit dataset-specific values

Step 4. Prepare extraparams

Step 5. Create the Structure_threader SLURM script

Meaning of key Structure_threader arguments

Step 6. Check the working directory before submission

Step 7. Submit the job

Step 8. Inspect output files

Step 9. Transfer results for visualization

Step 10. Visualize STRUCTURE results using R

Common problems and fixes

Minimal final checklist

Honored to have been recognized in Georgia Association of Plant Pathologists 2026 Meeting

Had a great time doing my first research oral presentation

From Science Fair to International Conferences

Stoked to be awarded with the Graduate School 2025 Summer Research Grant

Excited to share my research with the public for the first time!

Check your current location with `pwd`

List files with `ls -l`

Change directories with `cd`

Create a directory with `mkdir`

Move or rename files with `mv`

Step 2. Transfer the `.str` file to Sapelo2

Step 3. Prepare `mainparams`

Option A. Generate `mainparams` using the STRUCTURE graphical interface

Option B. Copy an existing `mainparams` and edit dataset-specific values

Step 4. Prepare `extraparams`