Analysing many samples on Roihu

An array job runs the same analysis on many samples at once: you list your samples in a file, and Slurm starts one task per line. This page takes you from data in Allas to summary tables, using a template shipped with the dataset project.

It assumes a CSC account and membership of a project with a compute allocation. The examples use the placeholders $project_id and $project_name; replace them with a real CSC project id (of the form project_1234567) and a working directory name that means something to you. For the pipeline itself, and for the choice of partition, cores and memory, see .

1. Open Roihu In Your Browser

Go to and log in with your Haka or CSC account (both need ).

The web interface is easier than a plain SSH connection:

• pick your project in the left-hand panel;
   
• click Open in Terminal for a terminal inside the browser — this is where every command below is typed. Right-click to open it in a new tab;
   
• browse /projappl/ and /scratch/ in the same window, so you can inspect files, open a log, or edit a job script without leaving the page.
   

Keeping the file browser and the terminal in two tabs side by side saves a lot of guessing about what landed where.

2. Make A Working Directory

PROJDIR=/scratch/$project_id/$project_name
mkdir -p $PROJDIR && cd $PROJDIR

Use the same $PROJDIR throughout: reads, results and logs all live here.

Every step below starts by moving to the directory it expects to be run from, so the commands can be copied as they stand. Note that $PROJDIR is only set for the session in which you typed the line above: after logging in again, set it once more before continuing.

3. Fetch Your Reads From Allas

module load allas
allas-conf

allas-conf asks for your CSC password and which project to connect to. The connection lasts for the current session, so repeat these two lines whenever you log in again.

Find your files, then download them:

Files are downloaded into the current directory, so move to the one you want them in first:

mkdir -p $PROJDIR/reads && cd $PROJDIR/reads
a-find --s3 -b $bucket/samples  <term> # search a bucket
a-get --s3 $bucket/samples/<file.fastq.gz> # download one file

For many files, write the list to a file and loop over it:

mkdir -p $PROJDIR/reads && cd $PROJDIR/reads
a-find --s3 -b $bucket/samples <term> 1> myfiles
cat myfiles # check before downloading
for ob in $(cat myfiles); do a-get --s3 $ob; done

Keeping the listing in a file gives you a record of what was on the Allas side at pull time, and lets the loop be re-run to fill in anything that failed.

4. List The Samples

One line per sample, giving the path to its R1 file. R2 is found automatically from the R1 name.

cd $PROJDIR
ls -1 $PROJDIR/reads/*_R1*.fastq.gz 1> array.files
wc -l array.files # how many samples: you need this number next

Open array.files in the file browser and check that it looks right.

5. Copy The Job Template

cd $PROJDIR
cp /dataset/project_2020379/templates/lazypipe.array.bash .

This puts the template in $PROJDIR itself, alongside array.files — not in a subdirectory — which is where later steps expect to find it. Edit it in the web interface: locate /scratch/$project_id/$project_name/lazypipe.array.bash in the file browser, click the drop-down next to the file and select Edit. Three lines need attention:

If you run many samples as an array job, limit how many of them run at the same time. Each running sample holds roughly 20 GB of working files until its clean step, so 47 samples starting at once would need close to 1 TB of scratch space between them.

The limit is the number after the % sign in the array range:

#SBATCH --array=1-47%25 # 47 samples in total, at most 25 running at any moment

Without the %25 part, Slurm starts every sample it can as soon as resources allow. With it, the samples beyond the limit simply wait their turn and start as earlier ones finish. A tight limit makes the array as a whole take longer, so set it as high as your scratch quota allows.

Check the annotation strategy while you are in the file. The template ships with:

ANNS=vi.chain3.env

vi.chain3.env is the recommended default for all sample types; see . Switch to vi.chain3 only when CPU time is the binding constraint.

Finally, check the partition against your data size. Libraries above ~2 GB of compressed reads need the 600 GiB of node-local disk that medium and large provide; on those partitions request the whole node, since it is billed either way. See .

6. Submit And Watch

Submit from $PROJDIR, where the job file and array.files both are — the job script reads the sample list by relative path:

cd $PROJDIR
sbatch lazypipe.array.bash # prints a job id -- record it in the HISTORY section

Useful Slurm commands:

Each task writes a log to logs/, and results appear in results/<sample>/ as tasks finish. If a sample fails, its log is the place to look:

cd $PROJDIR
less logs/lazypipe.array.1.log

For an idea of how long to expect, see : with vi.chain3.env, large libraries take about five to six hours each.

7. Combine The Results

Once the whole array has finished, build summary tables across all samples:

cd $PROJDIR
S=$LAZYPIPE_INSTALL_DIR/scripts
perl $S/batch_sample_summary.pl results 1> summary.samples.csv
perl $S/batch_abund_summary.pl --target vi results 1> summary.abund.vi.csv
perl $S/batch_annot_summary.pl --target vi --minbp 500 --bits 100 results 1> summary.annot.vi.csv

These open directly in Excel. --target takes vi for viruses, ba for bacteria or ph for phages.

It is also worth recording what the array job actually consumed, which is what you will use to size the next run:

cd $PROJDIR
headers="jobid,jobname,state,exitcode,elapsed,elapsedraw,maxrss"
sacct -o $headers --parsable2 --delimiter "," --units M -j | grep "batch" | csvtk add-header -n $headers 1> results/job.stats.csv

8. Save The Results To Allas

Scratch is cleaned automatically every 90 days, so move anything you want to keep. LazypipeX already packs the per-sample files intended for downstream analysis into*.tar.gz, so collect those together with your summaries and the job script — lazypipe.array.bash is already sitting in $PROJDIR, where it was copied to in step 5:

cd $PROJDIR
tar -cvf $project_name.v202609.tar results/*.tar.gz *.csv array.files lazypipe.array.bash

module load allas
allas-conf
a-put --s3 -b $bucket/results $project_name.v202609.tar

Check that the upload arrived before deleting anything locally:

a-find --s3 -b $bucket/results $project_name

The is often easier: log in, select your project, and browse the bucket to confirm the file is there and has a sensible size.

9. Keep A Record

The template ends with a HISTORY block. Add a line there after every submission:

# 2026/08/31 : 47 samples, vi.chain3.env, hostgen=Homo_sapiens,Mus_musculus, jobid=962122, ALL DONE

Keep the edited job file together with your results. With the database versions recorded in each run's output, that is what lets you reconstruct months later exactly how a result was produced.

Getting Help

Write to . Include your job id and the log file of the sample that failed.