QC Report

This interactive notebook generates a summary of QC statistics to assess the success of a Mad4hatter run.

To proceed, you must provide the results directory from the Mad4hatter pipeline, which should include the following files:

  • sample_coverage.txt
  • amplicon_coverage.txt
  • allele_data.txt
  • panel_information/amplicon_info.tsv

If present, allele_data_collapsed.txt and the resistance_marker_module tables are also filtered and written out.

Additionally, a sample manifest is required. This file must contain the following fields:

  • sample_name – Unique identifier for each sample.
  • SampleType – Specifies whether the entry is a sample, positive control, or negative control.
  • Batch – Identifies a group of samples processed simultaneously by the same individual.
  • Column – The well column where the sample was placed in the plate.
  • Row – The well row where the sample was placed in the plate.
  • Parasitemia – The qPCR value for the sample.

The notebook provides the following analyses:

  • Plate Layout: Location of samples and controls on the plate
  • Primer Dimer Content: Input reads vs. % attributed to primer dimers
  • Balancing Across Batches: Swarm plot of reads output by the pipeline by batch
  • Control Summary, including:
    • Polyclonality of Positive Controls
    • Read Summary for Negative Controls
    • Contamination Maps for Negative Controls
  • Successul Amplification summary, including:
    • Sample Reads vs. Number of Successfully Amplified Targets
    • Parasitemia vs. Number of Successfully Amplified Targets
  • Amplification Plate Maps, including:
    • Reads Heatmap
    • Successful Amplification Heatmap
  • QC Summary by Batch, including:
    • Proportion of samples for each status of QC (Pass, Repool, or Reprep)

Note: A target is considered successfully amplified if it has more than read_threshold reads, where read_threshold is a report parameter.

Setup

============================================
USER CONFIGURATION SUMMARY
============================================
Results Directory: /home/runner/work/_temp/Library/ampseqQC/extdata/tutorial/results 
Manifest File: /home/runner/work/_temp/Library/ampseqQC/extdata/tutorial/manifest.csv 
Read Threshold for Successful Amplification: 100 
Minimum Reads per ASV (Positive Control Filter): 0 
Minimum Allele Frequency per ASV (Positive Control Filter): 0.01 
Allele Column: pseudocigar_masked 
============================================

Here we filter out two types of targets for QC calculations only:

  • Targets listed in the panel settings, by default the species identification targets, which are expected to amplify only if the species is present.

  • Long amplicons (>long_target_threshold bp, including primers), which tend to underperform due to their length.

These targets should not be considered when assessing the success of a sequencing run, but will still be included in the final allele_data output.

Long targets being removed:
Pf3D7_02_v3-0320675-0320924
Pf3D7_03_v3-0240989-0241224
Pf3D7_05_v3-0615411-0615646
Pf3D7_06_v3-0857486-0857720
Pf3D7_11_v3-1294305-1294547
Pf3D7_13_v3-1465035-1465280
Pf3D7_13_v3-2840473-2840721
Pf3D7_13_v3-2841410-2841661
Pf3D7_13_v3-2844354-2844599

Target count summary:
  Total targets in amplicon_coverage: 243 
  Targets used for QC (after filtering): 229 
  Excluded targets will still appear in final allele_data_filtered.txt output

Pools are read from the panel information in the results directory and assigned to mPCR reactions using the panel settings. Targets shared by pools in different reactions are counted in each reaction.

pool reaction n_targets
D1 1 170
R1 1 47
R2 2 31
reaction nreactionloci
1 205
2 24

Sample Summary

Mad4hatter only writes a sample to the allele data when at least one allele remains after DADA2 and post-processing. Samples with no final reads, such as clean negative controls or failed samples, are therefore expected to be missing from the allele data even though they are in the coverage files.

File Samples Samples also in manifest
Manifest 184 184
Sample coverage 184 184
Amplicon coverage 184 184
Allele data 181 181
Allele data (QC targets only) 181 181 
3 sample(s) in the manifest are not in the allele data:
Sample type Reason Samples
negative No alleles after DADA2 and post-processing 3
Sample Batch Sample type Reason
B1_NEG1 Batch1 negative No alleles after DADA2 and post-processing
B1_NEG2 Batch1 negative No alleles after DADA2 and post-processing
B2_NEG2 Batch2 negative No alleles after DADA2 and post-processing

Plate Layout

The plate layout provides a visual representation of sample organization, including the placement of positive and negative controls. This is allows verification that controls are positioned correctly to validate assay performance with later plots.

Primer Dimer Content

Here we visualise the proportion of sequencing reads that are classified as primer dimers, which occur when primers anneal to each other instead of the target DNA. This plot is useful for assessing the efficiency of the amplification process, as high primer dimer levels can indicate suboptimal reaction conditions, reduced sequencing efficiency, and potential issues with sample quality or reagent performance.

Balancing Across Batches

Here we show the distribution of total reads per sample across different batches, helping to assess whether sequencing depth is consistent. This plot is useful when you have multiple batches in the same sequencing run to identify imbalances in sequencing, which can arise due to variations in library preparation, loading efficiency, or sequencing conditions.

Control Summary

Multiallelic Targets in Positive Controls

Here we inspect the positive controls, ensuring that the positive controls perform as expected without contamination or unwanted diversity. For example, if the control you included was monoclonal you would expect little to no targets reported as having more than one allele (multiallelic). In some cases you may allow for some level of false positive detection within a monoclonal control. Note that WSAF and total reads per allele filters (as set by default or modified by user) are applied.

sample_name target_name pseudocigar_masked reads AlleleFreq NumASVs_Meeting_Threshold Category
B1_POS1 Pf3D7_05_v3-0668787-0668979 . 406 0.9689737 2 2 Alleles
B1_POS1 Pf3D7_05_v3-0668787-0668979 23T 13 0.0310263 2 2 Alleles
B1_POS1 Pf3D7_07_v3-0405597-0405815 . 606 0.9696000 2 2 Alleles
B1_POS1 Pf3D7_07_v3-0405597-0405815 19T 19 0.0304000 2 2 Alleles
B1_POS1 Pf3D7_14_v3-0421354-0421514 . 2945 0.9605349 2 2 Alleles
B1_POS1 Pf3D7_14_v3-0421354-0421514 20A 121 0.0394651 2 2 Alleles

Negative Control Contamination

Read Summary per Negative Control

In an ideal scenario, negative controls should have minimal or no amplification. If a negative control shows a high number of targets amplified with significant reads, it suggests potential contamination. By plotting the number of reads against the number of targets for each sample, any outliers or unexpected amplification in negative controls can be easily flagged. Reads are the final reads per target after DADA2 and post-processing (OutputPostprocessing in the amplicon coverage).

Negative controls by batch:
Batch n_controls
Batch1 2
Batch2 2 
Total batches with negative controls: 2 
Total batches with negative controls that had reads: 1

No reads present in any negative controls in this batch — nothing to plot.

Plotting reads for 1/2 negative controls (1 had no reads)

Summary of negative control targets with reads above threshold ( 50 )
sample_name target_name OutputPostprocessing
B2_NEG1 Pf3D7_03_v3-0653993-0654177 55
B2_NEG1 Pf3D7_05_v3-1322131-1322313 59
B2_NEG1 Pf3D7_07_v3-0729507-0729725 53
B2_NEG1 Pf3D7_11_v3-0115945-0116151 60
B2_NEG1 Pf3D7_13_v3-1233117-1233299 57

Aggregated Reads per Target

This plot aggregates the total reads for each target across all negative controls in all batches, using the same final reads as the plots and table above. In negative controls, if there is an unexpected spike in reads for specific targets, it could indicate contamination in the form of cross-sample contamination or environmental contamination. Analyzing these total summed reads helps pinpoint specific targets where contamination might have occurred, offering insights into which steps in the process might have introduced contaminants.

Successul Amplification

Parasitemia vs. Number of Successfully Amplified Targets

This plot examines the relationship between a sample’s parasitemia (qPCR-determined parasite load) and the number of targets that successfully amplified. This plot helps assess whether lower parasitemia samples struggle with amplification, which can indicate potential limitations in sensitivity.

Sample Reads vs. Number of Successfully Amplified Targets

This illustrates the relationship between the total number of reads per sample and the number of targets that passed the amplification threshold for that sample. This plot helps evaluate whether samples with higher read counts achieve better amplification success and can reveal potential issues such as insufficient sequencing depth or inefficient amplification. Ideally, a positive correlation should be observed, where higher read counts result in more successfully amplified targets.

Warning in ggplot2::scale_x_log10(): log-10 transformation introduced infinite values.
log-10 transformation introduced infinite values.

Warning in ggplot2::scale_x_log10(): log-10 transformation introduced infinite values.
log-10 transformation introduced infinite values.

sample_name Batch SampleType reaction status reason reads_per_reaction prop_good_loci
B1_S02 Batch1 sample 1 reprep < reprep threshold 0.5 13661 0.1609756
B1_S02 Batch1 sample 2 reprep < reprep threshold 0.5 1692 0.2500000
B1_S12 Batch1 sample 1 reprep < reprep threshold 0.5 16866 0.2780488
B1_S12 Batch1 sample 2 reprep < reprep threshold 0.5 1871 0.2500000
B1_S20 Batch1 sample 1 reprep < reprep threshold 0.5 15019 0.2243902
B1_S20 Batch1 sample 2 reprep < reprep threshold 0.5 1751 0.1250000
B1_S24 Batch1 sample 1 reprep < reprep threshold 0.5 9005 0.0634146
B1_S24 Batch1 sample 2 reprep < reprep threshold 0.5 947 0.0833333
B1_S36 Batch1 sample 1 reprep < reprep threshold 0.5 22856 0.4292683
B1_S36 Batch1 sample 2 reprep < reprep threshold 0.5 2828 0.4583333
B1_S66 Batch1 sample 1 reprep < reprep threshold 0.5 14524 0.1951220
B1_S66 Batch1 sample 2 reprep < reprep threshold 0.5 1553 0.1250000
B1_S71 Batch1 sample 1 reprep < reprep threshold 0.5 10181 0.0878049
B1_S71 Batch1 sample 2 reprep < reprep threshold 0.5 997 0.0416667
B1_S74 Batch1 sample 1 reprep < reprep threshold 0.5 26926 0.4878049
B1_S74 Batch1 sample 2 reprep < reprep threshold 0.5 2904 0.4583333
B1_S83 Batch1 sample 1 reprep < reprep threshold 0.5 22291 0.3853659
B1_S83 Batch1 sample 2 reprep < reprep threshold 0.5 2606 0.4166667
B1_S90 Batch1 sample 1 reprep < reprep threshold 0.5 3817 0.0097561
B1_S90 Batch1 sample 2 reprep < reprep threshold 0.5 490 0.0000000
B2_S05 Batch2 sample 2 reprep < reprep threshold 0.5 401 0.0000000
B2_S06 Batch2 sample 2 reprep < reprep threshold 0.5 442 0.0000000
B2_S16 Batch2 sample 1 reprep < reprep threshold 0.5 14137 0.1658537
B2_S16 Batch2 sample 2 reprep < reprep threshold 0.5 1685 0.1666667
B2_S19 Batch2 sample 1 reprep < reprep threshold 0.5 4666 0.0097561
B2_S19 Batch2 sample 2 reprep < reprep threshold 0.5 605 0.0000000
B2_S22 Batch2 sample 1 reprep < reprep threshold 0.5 22141 0.3951220
B2_S22 Batch2 sample 2 reprep < reprep threshold 0.5 2723 0.4166667
B2_S27 Batch2 sample 1 reprep < reprep threshold 0.5 9842 0.0975610
B2_S27 Batch2 sample 2 reprep < reprep threshold 0.5 1134 0.1250000
B2_S30 Batch2 sample 1 reprep < reprep threshold 0.5 17215 0.2487805
B2_S30 Batch2 sample 2 reprep < reprep threshold 0.5 2012 0.3750000
B2_S36 Batch2 sample 1 reprep < reprep threshold 0.5 27401 0.4829268
B2_S40 Batch2 sample 1 reprep < reprep threshold 0.5 3653 0.0000000
B2_S40 Batch2 sample 2 reprep < reprep threshold 0.5 486 0.0000000
B2_S57 Batch2 sample 1 reprep < reprep threshold 0.5 21876 0.3756098
B2_S57 Batch2 sample 2 reprep < reprep threshold 0.5 2366 0.3750000
B2_S63 Batch2 sample 1 reprep < reprep threshold 0.5 27030 0.4780488
B2_S64 Batch2 sample 1 reprep < reprep threshold 0.5 4757 0.0097561
B2_S64 Batch2 sample 2 reprep < reprep threshold 0.5 452 0.0000000
B2_S67 Batch2 sample 1 reprep < reprep threshold 0.5 3771 0.0000000
B2_S67 Batch2 sample 2 reprep < reprep threshold 0.5 426 0.0000000
B2_S71 Batch2 sample 2 reprep < reprep threshold 0.5 3350 0.4583333
B2_S76 Batch2 sample 1 reprep < reprep threshold 0.5 21332 0.3707317
B2_S81 Batch2 sample 1 reprep < reprep threshold 0.5 11207 0.1219512
B2_S81 Batch2 sample 2 reprep < reprep threshold 0.5 1286 0.1250000
B2_S84 Batch2 sample 1 reprep < reprep threshold 0.5 11998 0.1512195
B2_S84 Batch2 sample 2 reprep < reprep threshold 0.5 1423 0.2500000
B1_S03 Batch1 sample 1 repool < repool threshold 0.75 30071 0.5658537
B1_S03 Batch1 sample 2 repool < repool threshold 0.75 3535 0.5000000
B1_S64 Batch1 sample 1 repool < repool threshold 0.75 43599 0.6926829
B1_S64 Batch1 sample 2 repool < repool threshold 0.75 5112 0.7083333
B1_S76 Batch1 sample 1 repool < repool threshold 0.75 29594 0.5658537
B1_S76 Batch1 sample 2 repool < repool threshold 0.75 2938 0.6250000
B2_S08 Batch2 sample 1 repool < repool threshold 0.75 45067 0.7317073
B2_S08 Batch2 sample 2 repool < repool threshold 0.75 5048 0.6250000
B2_S15 Batch2 sample 1 repool < repool threshold 0.75 38165 0.6439024
B2_S15 Batch2 sample 2 repool < repool threshold 0.75 4886 0.7083333
B2_S20 Batch2 sample 1 repool < repool threshold 0.75 48365 0.7268293
B2_S26 Batch2 sample 1 repool < repool threshold 0.75 37892 0.6487805
B2_S26 Batch2 sample 2 repool < repool threshold 0.75 4509 0.6250000
B2_S32 Batch2 sample 1 repool < repool threshold 0.75 43409 0.7121951
B2_S36 Batch2 sample 2 repool < repool threshold 0.75 3111 0.6250000
B2_S51 Batch2 sample 1 repool < repool threshold 0.75 41203 0.6780488
B2_S63 Batch2 sample 2 repool < repool threshold 0.75 3109 0.5416667
B2_S71 Batch2 sample 1 repool < repool threshold 0.75 27986 0.5268293
B2_S74 Batch2 sample 1 repool < repool threshold 0.75 34415 0.5707317
B2_S74 Batch2 sample 2 repool < repool threshold 0.75 3649 0.5000000
B2_S75 Batch2 sample 1 repool < repool threshold 0.75 33446 0.6000000
B2_S75 Batch2 sample 2 repool < repool threshold 0.75 3602 0.6250000
B2_S76 Batch2 sample 2 repool < repool threshold 0.75 2388 0.5000000
B2_S79 Batch2 sample 1 repool < repool threshold 0.75 44045 0.6878049
B2_S79 Batch2 sample 2 repool < repool threshold 0.75 4448 0.7083333 
Overall QC Summary (samples counted once by their worst reaction status):
  Reprep: 27 
  Repool: 12 
  Pass: 137 
  Pass percentage: 77.8 %

Amplification Plate Maps

Reads Heatmap

The reads heatmap provides a visual representation of read distribution across the plate, helping to identify inconsistencies in sequencing efficiency. This can highlight potential issues such as edge effects, batch effects, or pipetting errors that may impact data quality and interpretation.

Successful Amplification Heatmap

Here we visualise the success rate of amplification across the plate, allowing for the identification of poorly amplified regions or wells. This is useful for assessing the quality of the PCR process, ensuring that targets across all samples are adequately amplified, and helping to spot potential issues with specific wells or sample groups.

Save Output Files

Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/reprep_repool_summary.csv 
Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/positive_control_polyclonal_info.csv 
Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/negative_control_amplified_targets.csv 
Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/samples_to_repool.csv ( 25 samples needing repool)
Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/samples_to_reprep.csv ( 48 samples needing reprep)
Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/missing_samples_report.csv ( 0 samples in manifest not found in allele data)
Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/allele_data_filtered.txt 
Skipped: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/allele_data_collapsed_filtered.txt (input not found in results directory)
Skipped: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/resmarker_table_filtered.txt (input not found in results directory)
Skipped: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/resmarker_microhaplotype_table_filtered.txt (input not found in results directory)
  (Includes ALL targets, including those excluded from QC calculations)
  Filtered by: Reads > 0 AND WSAF > 0.01 
Saved: /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/missing_targets_report.csv 

Missing Targets Report

The following targets are present in the pool file but missing from the allele data:
No target_name pool chrom
1 PKNH_12_v2-0198893-0199083 D1 PKNH_12_v2
2 PmUG01_12_v1-1398020-1398213 D1,R1 PmUG01_12_v1
3 PocGH01_12_v1-1106482-1106671 D1,R1 PocGH01_12_v1

QC Summary by Batch

This visualization shows the overall QC pass rate by batch, with stacked bars representing the percentage of samples passing, requiring repool, or requiring reprep. This helps identify batches with systematic issues.

Each sample is counted once, using its worst status across reactions: a sample needing reprep in any reaction is counted as reprep, otherwise a sample needing repool in any reaction is counted as repool, and only samples passing every reaction are counted as pass. The status of each reaction is given in the repool and reprep output files and the amplification plots.

Batch Pass Repool Reprep Total Pass Rate (%)
Batch1 79 3 10 92 85.9
Batch2 58 9 17 84 69.0

Summary

ImportantReport Summary

This unified QC report has processed data and generated the following standardized outputs:

  1. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/reprep_repool_summary.csv - Combined reprep/repool classification for all samples
  2. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/samples_to_repool.csv - Samples requiring repool
  3. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/samples_to_reprep.csv - Samples requiring reprep
  4. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/positive_control_polyclonal_info.csv - Polyclonality information for positive controls
  5. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/negative_control_amplified_targets.csv - Contamination detected in negative controls
  6. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/allele_data_filtered.txt - Filtered allele data meeting read/AF thresholds (includes all targets)
  7. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/missing_targets_report.csv - Targets in pool file but absent from data (if applicable)
  8. /home/runner/work/ampseq-qc/ampseq-qc/docs/example-report/missing_samples_report.csv - Samples in manifest but not found in allele data

Key Points

  • Targets filtered for QC: 23 targets were excluded from QC calculations
  • QC metrics: Reprep/repool classifications based on 229 QC-relevant targets
  • Final output: allele_data_filtered.txt includes ALL targets (both QC and excluded) meeting thresholds
  • Pass rate: 77.8%