squigualiser

squigualiser is a tool to Visualise nanopore raw signal-base alignment.

signals (squiggles) + visualiser = squigualiser

Google Chrome is the recommended web browser to visualise these plots.

Watch the video to learn a few tricks to get the best out of the plots.

Squigualiser preprint - https://www.biorxiv.org/content/10.1101/2024.02.19.581111v2

Samarakoon, H., Liyanage, K., Ferguson, J.M., Parameswaran, S., Gamaarachchi, H. and Deveson, I.W., 2024. Interactive visualisation of raw nanopore signal data with Squigualiser. Biorxiv, pp.2024-02.

• Figure - A pileup view of DNA R10.4.1 signals that align to the region chr1:92,783,745-92,783,946.
• Click the link to open it on your browser.
• Go to Section Examples for more examples.

Table of Contents

1. Quickstart
2. Advanced Setup
3. Signal-to-read visualisation
   1. Option 1 - Using f5c resquiggle
   2. Option 2 - Using basecaller move table
   3. Option 3 - Using squigulator signal simulation
4. Signal-to-reference visualisation
   1. Option 1 - Using f5c eventalign
   2. Option 2 - Using basecaller move table
   3. Option 3 - Using squigulator signal simulation
   4. Option 4 - Using uncalled4 align
5. Pileup view
6. Plot multiple tracks
7. BED annotations
8. Squigualiser GUI
9. Visualisation Enhancements
   1. Base shift
   2. Signal scaling
10. Plot conventions
11. Calculate alignment statistics
12. Notes
    1. FAST5 and POD5 support
13. Examples
14. Links to additional docs

Quickstart

The easiest way to setup squigualiser would be to use precompiled binaries. Click on the arrow to expand the snippet of commands for your operating system.

For a quick test run the following:

wget https://hiruna72.github.io/squigualiser/docs/sample_dataset.tar.gz
# or use curl
curl -L https://hiruna72.github.io/squigualiser/docs/sample_dataset.tar.gz -o sample_dataset.tar.gz

tar xf sample_dataset.tar.gz
./squigualiser plot_pileup -f ref.fasta -s reads.blow5 -a eventalign.bam -o dir_out --region chr1:92,778,040-92,782,120 --tag_name "test_0"

export PATH=[path_to_squigualiser_dir]:$PATH to execute squigualiser from any location.

You can take a look at advanced setup below for instructions on installing using pip, conda or source.

Advanced setup

Click on the arrow to expand the relevant section.

Signal-to-read visualisation

This section explains how you can use squigualiser to visualise a raw signal alignment against its basecalled read. Click on the arrow to expand the revalent method.

Option 1 - f5c resquiggle

Option 2 - basecaller move table

Option 3 - Squigulator signal simulation

Signal-to-reference visualisation

This section explains how you can use squigualiser to visualise a raw signal alignment against a reference. Click on the arrow to expand the relevant method.

Option 1: f5c eventalign

Option 2 - basecaller move table

Option 3 - Squigulator signal simulation

Option 4: Uncalled4 align

Pileup view

Similar to IGV pileup view now you can view the signal pileup view. To create a pileup view the following conditions should be met.

1. The plot is a signal-to-reference visualisation, not a signal-to-read.
2. A genomic region should be specified using the argument --region

First, create an alignment file by following the steps mentioned in Signal-to-reference visualisation

REGION=chr1:6811011-6811198
squigualiser plot_pileup -f ${REF} -s ${SIGNAL_FILE} -a ${ALIGNMENT} -o ${OUTPUT_DIR} --region ${REGION} --tag_name "pileup"

Here is an example DNA pileup plot created using the testcase 20.1. Here is an example RNA pileup plot created using the testcase 43.1.

Plot multiple tracks

BED annotations

Plots support BED file annotations. Use argument --bed [BED FILE] to provide the bed file to the plot command.

Here is an example RNA pileup plot created using the testcase 43.1 that supports bed annotations.

Squigualiser GUI

Visualisation Enhancements

Base shift

User can shift the base sequence to the left by n number of bases by providing the argument --base_shift -n to plot and plot_pileup commands. This is helpful to correct the signal level to the base. A negative n value will shift the base sequence to the left. However, the user is adviced to use --profile (documented here) which automatically sets the --base_shift. For more information please refer base_shift and eventalignment and base_shift and reverse mapped reads.

Signal scaling

The commands plot and plot_pileup can take the argument --sig_scale. Provide the argument --sig_scale znorm to zscore normalize, --sig_scale medmad to median MAD normalize, and --sig_scale scaledpA to scale the raw signal to the pore model.

Plot Conventions

• A is a descriptive tag name to identify the plot.
• B indicates whether the positive or negative strand was used as the reference to align the signals. For RNA this will be RNA 3'->5'. Squigualiser only supports RNA reads mapped to the transcriptome.
• C always indicates the region using the positive strand coordinates, regardless of the forward and reverse mapped plots.
• D indicates the true sequencing direction of the signals.

Calculate alignment statistics

Calculate basic statistics of signal-to-read/reference alignments. Check here for the command. Check here for an example.

Notes

1. If your FASTQ file is a multi-line file (not to confuse with multi-read), then install seqtk and use seqtk seq -l0 in.fastq > out.fastq to convert multi-line FASTQ to 4-line FASTQ.
2. The optional argument --kmer-model KMER_MODEL can be used to specify a custom k-mer model if you wish.
3. To plot RNA signal-to-read alignment use the alignment file created using f5c resquiggle --rna -c ${FASTQ} ${SIGNAL_FILE} -o ${ALIGNMENT}. Also, provide the argument --rna to the visualising command. Currently, there exists no RNA kmer model for r10.4.1 chemistry.
4. The input alignment format accepted by squigualiser plot is explained here. This standard format made plotting a lot easier.
5. The argument sig_move_offset is the number of moves n to skip in the signal to correct the start of the alignment. This will not skip bases in the fastq sequence. For example, to align the first move with the first kmer --sig_move_offset 0 should be passed. To align from the second move onwards, --sig_move_offset 1 should be used.
6. Pysam does not allow reading SAM/BAM files without a @SQ line in the header. Hence, squigualiser reform script might error out with NotImplementedError: can not iterate over samfile without header. Add a fake @SQ header line with a zero length reference as follows,

   echo -e fake_reference'\t'0 > fake_reference.fa.fai
   samtools view out.sam -h -t fake_reference.fa.fai -o sq_added_out.sam

7. Squigulator's signal simulation is a good way to understand the nature of the alignments. Please refer to the documentation about real_vs_simulated_signal.
8. For a explanation of the Guppy move table explanation see please refer here.

FAST5 and POD5 support

Squigualiser randomly access signal files from BLOW5. Fast5 and Pod5 do not have such random access functionality. We provide methods to convert FAST5 and POD5 to BLOW5.

1. FAST5 - slow5tools f2s FAST5 -o BLOW5 check here
2. POD5 - blue-crab p2s example.pod5 -o example.blow5 check here

Examples

1. The first read is a signal-to-read alignment using guppy_v.6.3.7 move table annotation (link).
2. The second read is a signal-to-read alignment using f5c resquiggle output (link).
3. The third read is a signal-to-read alignment using the squigulator's simulated output (link).
4. The fourth read (RNA) is a signal-to-read alignment using f5c resquiggle output (link).

• This signal-to-reference alignment aligns a signal to the region chr1:4270161-4271160.
• This is the same plot with a fixed base width.

These examples were generated using the testcases - 1.1, 2.1, 1.11, and 3.2 respectively in test_plot_signal_to_read.sh.

Please refer to the example pipelines to learn how to integrate squigualiser into your analysis.

Links to additional docs

• Base Shift and Event Alignment
• Base Shift of Reverse Mapped Reads
• Basecalling
• Calculate Offsets
• Commands
• Different Alignments
• Metric
• Move Table
• Pipeline Basic
• Pipeline Methylation Detection DNA
• Pipeline Variant Detection Extended
• Pipeline Variant Detection Real
• Pipeline Variant Detection Simulated
• Pore Model
• Profiles
• Real vs Simulated Signal
• Realign
• Reform
• RNA Visualisation

Acknowledgement

Some code snippets have been taken from readpaf, blue-crab, buttery-eel, readfish and bonito