Package 'molpathR'

Description

Appends new data from one or more molpath_parsed objects to an existing molpath_db database. Records are deduplicated after appending.

Usage

mp_add_data(db, parsed)

Arguments

Value

An updated molpath_db object with the new data merged in.

Examples

db <- mp_example_db(n_patients = 5, seed = 1)
new_data <- new_molpath_parsed(
  data = tibble::tibble(patient_id = "P99", os_months = 12,
    os_status = 1L, pfs_months = 6, pfs_status = 1L),
  source_type = "survival", source_file = "new.csv"
)
db <- mp_add_data(db, new_data)

Description

Constructs a unified molpath_db database object from one or more molpath_parsed objects. Each parsed object is categorized by its source_type and merged into the appropriate database table. Raw FASTQ/BAM reads remain available through their readers but cannot be interpreted as variant calls by this function. Unknown gene annotations, pathogenicity and patient links remain missing. Use mp_validate_db() to assess incomplete links.

Usage

mp_build_db(...)

Arguments

Details

Source types map to database tables as follows:

• "vcf" – non-reference GT calls or explicitly normalized variants

• "xml_report" – variants and explicitly identified patients/samples

• "pdf_report" – reports

• "nexus_pathology" – patients and samples

• "nexus_clinical" – clinical

• "survival" – survival

Value

A molpath_db S3 object containing linked patients, samples, variants, reports, clinical, survival, and metadata tables.

Examples

# Build from a molpath_parsed object
surv_parsed <- new_molpath_parsed(
  data = tibble::tibble(
    patient_id = c("P1", "P2"),
    os_months = c(12, 24),
    os_status = c(1L, 0L),
    pfs_months = c(6, 18),
    pfs_status = c(1L, 0L)
  ),
  source_type = "survival",
  source_file = "test.csv"
)
db <- mp_build_db(surv_parsed)

Description

Generates a realistic but entirely synthetic molpath_db object containing patients, samples, variants, reports, clinical data, and survival data. The data set is designed to mirror the structure of a real-world molecular pathology database with plausible clinical correlations, including diagnosis-specific mutation profiles, TNM staging, and survival outcomes.

Usage

mp_example_db(n_patients = 150, seed = 42)

Arguments

Value

A molpath_db object (S3 list) containing:

patients

A tibble with columns patient_id, age, sex, diagnosis, diagnosis_date.

samples

A tibble with columns sample_id, patient_id, sample_type, date, source_file.

variants

A tibble with columns sample_id, gene, variant, variant_type, classification, vaf, chromosome, position, ref_allele, alt_allele.

reports

A tibble with columns sample_id, report_type, report_date, summary_text, source_file.

clinical

A tibble with columns patient_id, parameter, value, date, source.

survival

A tibble with columns patient_id, os_months, os_status, pfs_months, pfs_status.

Examples

db <- mp_example_db()
db$patients
nrow(db$variants)

# Smaller data set for quick tests
db_small <- mp_example_db(n_patients = 20, seed = 123)

Description

Creates a set of realistic mock files that can be used to test the molpathR import pipeline. Files include VCF, XML, text-based PDF-like reports, a survival CSV, and a tiny FASTQ file.

Usage

mp_example_files(
  dir = tempdir(),
  seed = 42,
  reference_date = as.Date("2025-01-01")
)

Arguments

Value

A named list of file paths:

vcf

Character vector of 5 VCF file paths.

xml

Character vector of 5 XML report file paths.

pdf

Character vector of 5 text-based mock PDF report paths.

survival

Path to the survival CSV file.

fastq

Path to the sample FASTQ file.

Examples

files <- mp_example_files()
readLines(files$vcf[1], n = 5)

Description

Returns a named list containing all data layers for the given patient, including samples, variants (via sample linkage), reports, clinical data, and survival data.

Usage

mp_get_patient(db, patient_id)

Arguments

Value

A named list with elements: patient, samples, variants, reports, clinical, survival.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
pat <- mp_get_patient(db, db$patients$patient_id[1])
pat$samples

Description

Reads an RDS file, verifies it contains a valid molpath_db object, and prints a summary of the loaded database. Known legacy zero-column empty tables and one-row metadata tibbles are normalized explicitly. Malformed schemas or values are rejected; incomplete foreign-key links remain visible through mp_validate_db() rather than being invented.

Usage

mp_load_db(path)

Arguments

Value

A molpath_db object.

Examples

db <- mp_example_db(n_patients = 5, seed = 1)
tmp <- tempfile(fileext = ".rds")
mp_save_db(db, tmp)
db2 <- mp_load_db(tmp)
unlink(tmp)

Description

Combines all tables from two molpath_db objects into a single unified database. Records are deduplicated after merging. Metadata source files are combined as a union. Identical primary-key rows are deduplicated and missing attributes may be filled from the other source. Conflicting observed patient, sample or survival attributes require explicit reconciliation and cause an error.

Usage

mp_merge_db(db1, db2)

Arguments

Value

A new molpath_db object containing merged data from both inputs.

Examples

db1 <- mp_example_db(n_patients = 5, seed = 1)
db2 <- db1
db1$survival <- db1$survival[0, ]
db_combined <- mp_merge_db(db1, db2)

Description

Returns a list of four ggplot objects summarising the database: diagnosis distribution, age by sex, sample types, and top mutated genes. Arrange with patchwork or cowplot as needed.

Usage

mp_plot_cohort_overview(db)

Arguments

Value

A named list of four ggplot2::ggplot objects: diagnosis, age, sample_types, top_genes.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
plots <- mp_plot_cohort_overview(db)
plots$diagnosis

Description

Bar chart of SNV substitution types (C>A, C>G, C>T, T>A, T>C, T>G).

Usage

mp_plot_mutation_spectrum(db, sample_id = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_plot_mutation_spectrum(db)

Description

Creates Kaplan-Meier curves from the survival table. Optionally stratifies by a clinical variable or gene mutation status.

Usage

mp_plot_survival(db, group_by = NULL, type = c("os", "pfs"))

Arguments

Value

A ggplot2::ggplot object.

Examples

db <- mp_example_db(n_patients = 50, seed = 1)
mp_plot_survival(db, type = "os")
mp_plot_survival(db, group_by = "diagnosis", type = "os")

Description

Displays a timeline of events for a single patient: sample collections, report dates, and clinical measurements.

Usage

mp_plot_timeline(db, patient_id)

Arguments

Value

A ggplot2::ggplot object.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
pid <- db$patients$patient_id[1]
mp_plot_timeline(db, pid)

Description

Histogram or density plot of variant allele frequencies (VAF), optionally filtered by gene.

Usage

mp_plot_vaf_distribution(db, gene = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_plot_vaf_distribution(db)
mp_plot_vaf_distribution(db, gene = "TP53")

Description

Creates a tile plot showing variant classifications across samples and genes.

Usage

mp_plot_variant_landscape(db, genes = NULL, top_n = 20)

Arguments

Value

A ggplot2::ggplot object.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_plot_variant_landscape(db, top_n = 10)

Description

Uses tidy evaluation to filter the patients table.

Usage

mp_query_patients(db, ...)

Arguments

Value

A tibble of matching patients.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_query_patients(db, diagnosis == "Melanoma")
mp_query_patients(db, age > 60, sex == "F")

Description

Uses tidy evaluation to filter the samples table.

Usage

mp_query_samples(db, ...)

Arguments

Value

A tibble of matching samples.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_query_samples(db, sample_type == "FFPE")

Description

Filter the variants table by gene, classification, VAF range, or variant type.

Usage

mp_query_variants(
  db,
  genes = NULL,
  classification = NULL,
  min_vaf = NULL,
  max_vaf = NULL,
  variant_type = NULL
)

Arguments

Value

A tibble of matching variants.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_query_variants(db, genes = c("TP53", "KRAS"))
mp_query_variants(db, classification = "Pathogenic", min_vaf = 0.1)

Description

Detect the file type from its extension and/or content, then dispatch to the appropriate parser.

Usage

mp_read_auto(path, source_name = NULL)

Arguments

Details

Extension mapping:

• .vcf, .vcf.gz: mp_read_vcf

• .fastq, .fq, .fastq.gz, .fq.gz: mp_read_fastq

• .bam: mp_read_bam

• .xml: mp_read_xml_report

• .pdf: mp_read_pdf_report

• .xlsx, .xls, .csv: tries survival/clinical format detection

Value

A molpath_parsed object produced by the appropriate parser.

Examples

f <- system.file("extdata", "example.vcf", package = "molpathR")
if (nzchar(f)) {
  result <- mp_read_auto(f)
  print(result)
}

Description

Parse a BAM (Binary Alignment Map) file into a tidy tibble.

Usage

mp_read_bam(path, regions = NULL)

Arguments

Details

Uses Rsamtools::scanBam() when installed. Otherwise it calls samtools view; if neither is available an informative error is raised. Backend decoding errors are reported rather than triggering another reader.

Value

A molpath_parsed object whose data slot is a tibble with columns qname, flag, rname, pos, mapq, cigar, seq, and qual.

Examples

bam_file <- system.file("extdata", "example.bam", package = "molpathR")
if (nzchar(bam_file)) {
  result <- mp_read_bam(bam_file)
  print(result)
}

Description

Parse a FASTQ file into a tidy tibble of sequencing reads.

Usage

mp_read_fastq(path, n = NULL)

Arguments

Details

Uses ShortRead when installed, streaming the first requested records rather than sampling. Otherwise a strict 4-line text parser is used. Invalid or incomplete records raise an error; backend parse errors are not hidden.

Value

A molpath_parsed object whose data slot is a tibble with columns read_id, sequence, quality, and seq_length.

Examples

fq_file <- system.file("extdata", "example.fastq", package = "molpathR")
if (nzchar(fq_file)) {
  result <- mp_read_fastq(fq_file, n = 100)
  print(result)
}

Description

Parse a clinical data export (CSV format) from a clinical information system such as Nexus.

Usage

mp_read_nexus_clinical(path_or_connection)

Arguments

Value

A molpath_parsed object whose data slot is a tibble with columns patient_id, parameter, value, unit, date, and source.

Examples

clin_file <- system.file("extdata", "nexus_clinical.csv",
                         package = "molpathR")
if (nzchar(clin_file)) {
  result <- mp_read_nexus_clinical(clin_file)
  print(result)
}

Description

Parse an export from a pathology information system (e.g. Nexus) in either CSV or XML format.

Usage

mp_read_nexus_pathology(path_or_connection)

Arguments

Value

A molpath_parsed object whose data slot is a tibble with columns patient_id, name, dob, sex, sample_id, sample_type, diagnosis, and report_date.

Examples

nexus_file <- system.file("extdata", "nexus_pathology.csv",
                          package = "molpathR")
if (nzchar(nexus_file)) {
  result <- mp_read_nexus_pathology(nexus_file)
  print(result)
}

Description

Extract structured information from a pathology PDF report using pdftools::pdf_text() and regex-based section parsing. Complete extracted pages and text are retained in metadata even when section heuristics match only part of the report. Database report summaries use that complete text. This does not perform OCR or validate extraction accuracy against the PDF.

Usage

mp_read_pdf_report(path, template = "generic")

Arguments

Value

A molpath_parsed object whose data slot is a tibble with columns section and content extracted from the report (Patient, Sample, Findings, Interpretation, Recommendations).

Examples

pdf_file <- system.file("extdata", "report.pdf", package = "molpathR")
if (nzchar(pdf_file)) {
  result <- mp_read_pdf_report(pdf_file)
  print(result)
}

Description

Read a survival data file in Excel or CSV format and standardise the column names to a canonical schema.

Usage

mp_read_survival(path)

Arguments

Value

A molpath_parsed object whose data slot is a tibble with columns patient_id, os_months, os_status, pfs_months, and pfs_status.

Examples

surv_file <- system.file("extdata", "survival.csv", package = "molpathR")
if (nzchar(surv_file)) {
  result <- mp_read_survival(surv_file)
  print(result)
}

Description

Parse a Variant Call Format (VCF 4.x) file and return a tidy tibble of variant calls.

Usage

mp_read_vcf(path)

Arguments

Details

A validated text parser preserves original ID, INFO, FORMAT and sample fields for single- and multi-sample VCFs, including gzip input. Installing VariantAnnotation does not change the returned representation. Header lines and declared sample names are retained in the result metadata.

Value

A molpath_parsed object whose data slot is a tibble with columns chrom, pos, id, ref, alt, qual, filter, info, and any sample-level columns present in the file, plus format when declared. Sample names conflicting with these fixed output names are rejected.

Examples

vcf_file <- system.file("extdata", "example.vcf", package = "molpathR")
if (nzchar(vcf_file)) {
  result <- mp_read_vcf(vcf_file)
  print(result)
}

Description

Parse a structured XML variant interpretation report (e.g. from Molecular Health or similar providers) into a tidy tibble.

Usage

mp_read_xml_report(path, provider = "molecular_health")

Arguments

Value

A molpath_parsed object whose data slot is a tibble with one row per variant and columns for patient info, sample info, gene, variant description, classification, evidence level, therapeutic implications and an explicit VAF proportion when supplied. VAF must be between 0 and 1, inclusive; percentages or other units are not inferred.

Examples

xml_file <- system.file("extdata", "report.xml", package = "molpathR")
if (nzchar(xml_file)) {
  result <- mp_read_xml_report(xml_file, provider = "molecular_health")
  print(result)
}

Description

Starts an interactive Shiny application for exploring molecular pathology data. If a molpath_db object is provided, the app launches pre-loaded with that database. Otherwise, the user can upload data through the app interface.

Usage

mp_run_app(db = NULL, ...)

Arguments

Details

CSV/TSV downloads require a working zip executable (or R_ZIPCMD). Excel downloads additionally require the optional writexl package. Uploaded files are staged and validated as one batch before changing session data.

Value

This function does not return a value; it launches a Shiny app.

Examples

## Not run: 
# Launch with example data
db <- mp_example_db()
mp_run_app(db)

# Launch empty — upload data in browser
mp_run_app()

## End(Not run)

Description

Validates the database and saves it as a compressed RDS file. Serialization and read-back verification occur in a sibling temporary file before replacement. If replacement fails, the previous destination is restored or an explicit recovery path is reported. Use one writer per destination; this is not a multi-process database transaction. The file path is returned invisibly for use in pipelines.

Usage

mp_save_db(db, path)

Arguments

Value

The file path, returned invisibly.

Examples

db <- mp_example_db(n_patients = 5, seed = 1)
tmp <- tempfile(fileext = ".rds")
mp_save_db(db, tmp)
unlink(tmp)

Description

Searches all text fields across all tables for the given term (case-insensitive).

Usage

mp_search(db, term)

Arguments

Value

A named list of tibbles, one per table, containing rows that match the search term. Empty tibbles are omitted.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_search(db, "TP53")

Description

Computes summary statistics across all layers of the database.

Usage

mp_summary(db)

Arguments

Value

An S3 object of class molpath_summary (a named list) containing n_patients, n_samples, n_variants, n_reports, n_clinical, diagnosis_distribution, variant_gene_counts, classification_distribution, sample_type_distribution, date_range, and completeness.

Examples

db <- mp_example_db(n_patients = 20, seed = 1)
mp_summary(db)

Description

Checks that all foreign key relationships in the database are satisfied (e.g., every sample references an existing patient) and reports on data completeness across tables.

Usage

mp_validate_db(db)

Arguments

Details

The following referential integrity checks are performed:

• All patient_id values in the samples table exist in patients.

• All sample_id values in the variants table exist in samples.

• All sample_id values in the reports table exist in samples.

• All patient_id values in the clinical table exist in patients.

• All patient_id values in the survival table exist in patients.

When called interactively, results are printed using cli formatting.

Value

Invisibly, a list with three elements:

valid

Logical. TRUE if no referential integrity issues were found.

issues

Character vector of issue descriptions (empty if valid).

completeness

Named numeric vector with percentages of patients having data in each table (e.g., pct_with_variants, pct_with_survival).

Examples

db <- mp_example_db(n_patients = 10, seed = 1)
validation <- mp_validate_db(db)
validation$valid

Description

Constructs a molpath_db object, which is a list of linked tibbles representing the core data model for molecular pathology workflows.

Usage

new_molpath_db(
  patients = tibble::tibble(patient_id = character(), age = integer(), sex = character(),
    diagnosis = character()),
  samples = tibble::tibble(sample_id = character(), patient_id = character(), sample_type
    = character(), date = as.Date(character()), source_file = character()),
  variants = tibble::tibble(sample_id = character(), gene = character(), variant =
    character(), classification = character(), vaf = double()),
  reports = tibble::tibble(sample_id = character(), report_type = character(),
    report_date = as.Date(character()), summary_text = character(), source_file =
    character()),
  clinical = tibble::tibble(patient_id = character(), parameter = character(), value =
    character(), date = as.Date(character()), source = character()),
  survival = tibble::tibble(patient_id = character(), os_months = double(), os_status =
    integer(), pfs_months = double(), pfs_status = integer()),
  metadata = list(creation_date = Sys.time(), source_files = character(), parser_versions
    = list())
)

Arguments

Value

An S3 object of class molpath_db.

Examples

db <- new_molpath_db()
db

Description

Constructs a molpath_parsed object representing the result of parsing a single data source. This serves as an intermediate representation before data is integrated into a molpath_db.

Usage

new_molpath_parsed(
  data = tibble::tibble(),
  source_type = character(1L),
  source_file = character(1L),
  parse_date = Sys.time(),
  metadata = list()
)

Arguments

Value

An S3 object of class molpath_parsed.

Examples

parsed <- new_molpath_parsed(
  data = tibble::tibble(gene = "BRAF", variant = "V600E"),
  source_type = "vcf",
  source_file = "sample1.vcf"
)
parsed

Description

Displays a human-readable summary of a molpath_db, including table dimensions, date ranges, and data completeness.

Usage

## S3 method for class 'molpath_db'
print(x, ...)

Arguments

Value

The molpath_db object (invisibly).

Description

Displays a compact summary of a parsed data source, including source metadata and a preview of the data.

Usage

## S3 method for class 'molpath_parsed'
print(x, ...)

Arguments

Value

The molpath_parsed object (invisibly).

Description

Prints a detailed summary of a molpath_db, including per-table completeness, unique counts for key columns, and metadata.

Usage

## S3 method for class 'molpath_db'
summary(object, ...)

Arguments

Value

The molpath_db object (invisibly).

Description

Prints a detailed summary of a parsed data source, including column types, missing value counts, and a preview of distinct values.

Usage

## S3 method for class 'molpath_parsed'
summary(object, ...)

Arguments

Value

The molpath_parsed object (invisibly).

Description

Checks that all required tables are present, that each is a tibble, and that mandatory columns, types, value ranges and primary identifiers are valid. Incomplete cross-table links are reported as warnings; use mp_validate_db() for a structured link report. Missing parent evidence is not fabricated.

Usage

validate_molpath_db(x)

Arguments

Value

The original molpath_db object (invisibly). Structural or value corruption raises an error. Incomplete links warn and remain unchanged.

Examples

db <- new_molpath_db()
validate_molpath_db(db)