Malaria genomics analysis tools • PGEcore

An R package for malaria genomics analysis. PGEcore does two things:

Wraps existing tools (for example dcifer, moire, coiaf) behind a consistent R API and CLI, with shared TSV inputs and outputs so steps are easy to chain.
Adds extra analyses that are not just thin wrappers. This includes naive methods for COI / frequency / prevalence estimation, filters, format converters, summaries, and similar helpers.

Analyses are available both as R functions and as command-line tools, so you can use PGEcore interactively, in your own scripts, or as a shared library across workflow pipelines (for example Nextflow or WDL).

Package documentation (reference + vignettes): https://plasmogenepi.github.io/PGEcore/

PGEcore does not install the specialised software it wraps. Optional dependencies (for example the dcifer package) must be installed separately when you need those tools.

Install

# install.packages("pak")  # if you do not have it yet

# From GitHub
pak::pak("PlasmoGenEpi/PGEcore")

# From a local clone (also installs dependencies)
pak::local_install(".")

Two ways to run every tool

An R function — interactive analysis, notebooks, or other R code
A CLI under exec/ — shell scripts or batch jobs

Flags and file formats match between the two.

From R

library(PGEcore)

count_samples_by_coi("my_coi_table.tsv", output = "coi_distribution.tsv")

# Specialist wrappers use the same file paths as the CLI
# dcifer_slaf_wrapper(allele_table = "alleles.tsv", slaf_output = "slaf.tsv")

help(package = "PGEcore")
browseVignettes("PGEcore")
# vignette("getting-started", package = "PGEcore")
# vignette("input-formats", package = "PGEcore")

Command line

Installing the package does not put the executables on PATH, so ask R where they landed and add that directory:

PGECORE_EXEC="$(Rscript -e 'cat(system.file("exec", package="PGEcore"))')"
export PATH="$PGECORE_EXEC:$PATH"

count_samples_by_coi \
  --coi_table my_coi_table.tsv \
  --output coi_distribution.tsv

In a source checkout the scripts run in place — exec/count_samples_by_coi --coi_table inst/extdata/example_coi_table.tsv --output coi_distribution.tsv. Bundled examples for trying formats live in inst/extdata/. More detail: vignette("getting-started", package = "PGEcore").

Standard input formats

Tools share a small set of TSV layouts so outputs from one step can feed the next. Required columns (minimum):

Format (CLI / R arg)	Required columns	Example file
COI table (`coi_table`)	`specimen_name`, `coi`	`inst/extdata/example_coi_table.tsv`
SNP calls (`snp_calls`)	`specimen_name`, `snp_name`, `reads`, `seq_base`	`inst/extdata/example_collapsed_snp_calls.tsv`
Allele table (`allele_table`)	`specimen_name`, `target_name`, `seq`, `reads`	`inst/extdata/example_allele_table.tsv`
AA calls (`aa_calls`)	`specimen_name`, `gene_id`, `aa_position`, `aa`, `reads` (+ often `target_name`, `aa_locus`, …)	`inst/extdata/example_aa_calls.tsv`
Loci groups (`loci_groups`)	`group_id`, `gene_id`, `aa_position`	`inst/extdata/example_loci_groups.tsv`
Allele frequency (MLAF)	`group_id`, `variant`, `freq`	`inst/extdata/example_mlaf.tsv`
Population MAF (PLMAF)	`snp_name`, `seq_base`, `plmaf`	`inst/extdata/example_coiaf_plmaf.tsv`

FreqEstimationModel_wrapper is the exception for COI: its --coi argument accepts either a path to a COI table or a single numeric average COI.

Full column notes and which tools consume each format: vignette input-formats.

Available tools

CLI / function	Kind	Optional dependency
`count_samples_by_coi`	Pure R	—
`estimate_coi_naive`	Pure R	—
`estimate_allele_frequency_naive`	Pure R	—
`estimate_allele_prevalence_naive`	Pure R	—
`allele_per_locus_summary`	Pure R	—
`coiaf_wrapper`	Wrapper	`coiaf`
`filter_biallelic_calls`	Pure R	—
`filter_to_highest_diversity_independent_snp_call`	Pure R	—
`slaf_from_mhaps_freqs`	Pure R	—
`slaf_from_stave_mlaf`	Wrapper	`variantstring`
`multilocus_prevfreq_naive`	Pure R	—
`multilocus_prevfreq_naive_variantstring`	Wrapper	`variantstring`
`snp_calls_to_vcf`	Wrapper	`Biostrings`
`vcf_to_snp_calls`	Pure R	—
`add_ref_seqs_with_targeted_ref_fasta`	Wrapper	`Biostrings`
`add_ref_seqs_with_full_genome_ref_fasta`	Wrapper	`Biostrings`
`pileup_specific_snps`	Wrapper	`Biostrings`, `pwalign`
`translate_loci_of_interest`	Wrapper	`Biostrings`, `pwalign`
`per_locus_popgen_summary`	Wrapper	`ape`, `msa`, `pegas` (+ Muscle/Clustal on PATH)
`calculate_fws_from_vcf`	Wrapper	`moimix`, `SeqArray`
`moire_wrapper`	Wrapper	`moire`, `posterior`
`malariaem_wrapper`	Wrapper	`malaria.em`
`dcifer_slaf_wrapper`	Wrapper	`dcifer`
`dcifer_ibd_wrapper`	Wrapper	`dcifer` (+ parallel helpers)
`snpslice_wrapper`	Wrapper	`snp.slicer`, `variantstring`
`FreqEstimationModel_wrapper`	Wrapper	`FreqEstimationModel`, `posterior` (+ helpers)
`IDM_wrapper`	Vendored algorithm	`Rmpfr`, `openxlsx`
`MultiLociBiallelicModel_wrapper`	Vendored algorithm	`variantstring`
`THEREALMcCOIL_wrapper`	Vendored C (`src/`)	`posterior`

Use the name in the first column from R (library(PGEcore); moire_wrapper(...)) or from the CLI (moire_wrapper ...). A few wrappers also expose an in-memory helper if you already have objects in R rather than files: run_coiaf, run_moire, and run_malariaem (see ?run_moire).

Optional dependencies

Wrappers that call another R package list that package under Suggests. See PGEforge for more details on individual packages. Install only what you need, for example:

install.packages(
  "dcifer",
  repos = c("https://plasmogenepi.r-universe.dev", "https://cloud.r-project.org")
)

dcifer is also available on Conda. A minimal environment might look like:

dependencies:
  - r-base
  - r-pgecore
  - r-dcifer    # only if you use dcifer_slaf_wrapper or dcifer_ibd_wrapper

Package layout

PGEcore/
├── R/              # Exported API and helpers
├── exec/           # Thin CLIs (same flags as the R API)
├── src/            # THEREALMcCOIL C (compiled at install)
├── inst/extdata/   # Example inputs (standard formats)
├── vignettes/      # Getting started + input formats
├── man/
└── tests/

Contribute

PRs go to develop (Gitflow). To add a tool:

Implement in R/ (validate → prepare → run → format).
Export one high-level function; keep helpers internal.
Put specialised deps in Suggests and use check_suggested_pkg().
Add a thin exec/ CLI with the same optparse flags.
Add tests and document formats in the input-formats vignette if you introduce a new shared table layout.