Package {qviewparsR}

Title:	Read .Q-View Multiplex ELISA Project Files
Version:	1.0.0
Description:	Pure-R parser for the binary '.Q-View' project file format used in chemiluminescent multiplex ELISA plate imaging and quantification. Reads the embedded H2 database container and CSV report, and returns project metadata, the analyte panel with units and detection limits, sample well-group assignments, per-well pixel-intensity replicates, summary statistics, optional back-calculated concentrations, and a plate layout, all as tidy tibbles. No Java runtime or H2 database driver is required.
License:	MIT + file LICENSE
URL:	https://github.com/CTTIR/qviewparsR, https://cttir.github.io/qviewparsR/
BugReports:	https://github.com/CTTIR/qviewparsR/issues
Depends:	R (≥ 4.1.0)
Imports:	cli, dplyr, lifecycle, openxlsx2, readr, rlang, stats, tibble, tidyr, tools, utils
Suggests:	bslib, chromote, DT, ggplot2, knitr, patchwork, rmarkdown, shiny, shinytest2, testthat (≥ 3.0.0), withr
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
Config/roxygen2/version:	8.0.0
Config/Needs/website:	CTTIR/themakR
NeedsCompilation:	no
Packaged:	2026-07-16 11:49:44 UTC; rh
Author:	R. Heller [aut, cre, cph], M. Mannes [aut, cph]
Maintainer:	R. Heller <raban.heller@uni-ulm.de>
Repository:	CRAN
Date/Publication:	2026-07-23 13:50:08 UTC

qviewparsR: Read .Q-View Multiplex ELISA Project Files

Description

Pure-R parser for .Q-View binary project files used in chemiluminescent multiplex ELISA plate imaging and quantification. Extracts pixel intensities, analyte mappings, sample assignments, plate layout, optional curve-fit parameters, and the embedded CSV report from the H2 database container format. Returns tidy tibbles ready for downstream statistical analysis.

Main functions

• Reader: read_qview() – parse a .Q-View file.

• Helpers: strip_qview_prefix() reverse the Q-View internal naming convention; well_label() map (row, column) to plate notation.

• Optional: read_qview_template() parse a Q-View well-assignment template CSV.

• Methods: is_qview(), print.qview(), plot.qview(), as_tibble.qview().

• Shiny: qview_app() interactive upload / preview / download.

Author(s)

Maintainer: R. Heller raban.heller@uni-ulm.de (ORCID) [copyright holder]

Authors:

• R. Heller raban.heller@uni-ulm.de (ORCID) [copyright holder]

• M. Mannes (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/CTTIR/qviewparsR

• https://cttir.github.io/qviewparsR/

• Report bugs at https://github.com/CTTIR/qviewparsR/issues

Coerce a Q-View object to a tibble

Description

Returns the long-format pixel_intensities table — the primary tabular data carried by a qview object. To access other slots (well groups, analyte panel, summary statistics) use ⁠qv$<slot>⁠ directly.

Usage

## S3 method for class 'qview'
as_tibble(x, ...)

Arguments

Value

A tibble::tibble() of replicate pixel-intensity readings.

See Also

Other qview-methods: is_qview(), plot.qview(), print.qview(), print.qview_summary(), summary.qview()

Examples

path <- system.file("extdata", "example.Q-View", package = "qviewparsR")
qv <- read_qview(path, verbose = FALSE)
tibble::as_tibble(qv)

Test whether an object is a qview

Description

Usage

is_qview(x)

Arguments

Value

Logical scalar.

See Also

Other qview-methods: as_tibble.qview(), plot.qview(), print.qview(), print.qview_summary(), summary.qview()

Examples

path <- system.file("extdata", "example.Q-View", package = "qviewparsR")
is_qview(read_qview(path, verbose = FALSE))
is_qview(list())

Plot a Q-View object

Description

Quick-look plots for a parsed qview object.

Usage

## S3 method for class 'qview'
plot(x, type = c("plate_map", "intensity_heatmap", "replicate_scatter"), ...)

Arguments

Details

• "plate_map" – heat-coloured plate map, one cell per well, fill by well type (standard / negative / sample / control).

• "intensity_heatmap" – per-analyte facet, fill by replicate-1 pixel intensity per well.

• "replicate_scatter" – replicate 1 vs replicate 2 pixel intensity per analyte.

Requires the ggplot2 package (Suggested).

Value

A ggplot object.

See Also

Other qview-methods: as_tibble.qview(), is_qview(), print.qview(), print.qview_summary(), summary.qview()

Examples

path <- system.file("extdata", "example.Q-View", package = "qviewparsR")
qv <- read_qview(path, verbose = FALSE)
plot(qv, type = "plate_map")
plot(qv, type = "replicate_scatter")

Print a Q-View object

Description

Compact summary of a parsed qview object: project / plate identifiers, analyte panel, well-group counts by type, and whether the embedded report carries quantitative concentrations or only qualitative pixel intensities.

Usage

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

Arguments

Value

x, invisibly.

See Also

Other qview-methods: as_tibble.qview(), is_qview(), plot.qview(), print.qview_summary(), summary.qview()

Examples

qv <- read_qview(system.file("extdata", "example.Q-View",
                             package = "qviewparsR"), verbose = FALSE)
print(qv)

Print a qview_summary object

Description

Usage

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

Arguments

Value

x, invisibly.

See Also

Other qview-methods: as_tibble.qview(), is_qview(), plot.qview(), print.qview(), summary.qview()

Examples

path <- system.file("extdata", "example.Q-View", package = "qviewparsR")
qv <- read_qview(path, verbose = FALSE)
summary(qv)

Launch the qviewparsR Q-View Shiny app

Description

Usage

qview_app(max_upload_mb = 512, ...)

Arguments

Details

Interactive front-end for read_qview(). Uploads a .Q-View file (and optionally an accompanying well-assignment template CSV), displays the parsed metadata, analytes, well groups, and replicate tables, and lets the user download the parsed result as xlsx, rds, or a zip of per-table CSV files.

Requires the shiny, bslib, and DT packages (listed under Suggests).

Value

Invoked for its side effect of running the app.

Examples

if (interactive()) {
  qview_app()
}

Read a .Q-View project file

Description

Usage

read_qview(
  path,
  strip_prefix = FALSE,
  verbose = TRUE,
  call = rlang::caller_env()
)

Arguments

Details

Parses a .Q-View binary container (a chemiluminescent multiplex ELISA project file holding an embedded H2 database plus binary LOB segments) and extracts the assay data: project metadata, analyte panel with units, well-group sample assignments, per-well replicate pixel intensities, summary statistics, and (when present) the embedded CSV report.

The file format is reverse-engineered from public binary inspection: it begins with a plain-text manifest, followed by three concatenated H2 database segments. The fully-formatted report Q-View renders for the user is stored as a CLOB inside the main H2 segment. This parser scans the binary for that CLOB, reassembles it across H2 page boundaries (2048-byte pages), and parses it as CSV.

Parsing is done in pure R: no Java runtime, no H2 database driver, no system dependencies beyond a working R installation.

Value

A list with class "qview" containing:

metadata

Named list: project, plate, image, imager, product, user, report_created, qview_version, template, container_version, file_path, parsed_at.

manifest

Tibble with one row per declared file entry (name, size_bytes, parent).

segments

Tibble of H2 segment byte ranges (segment, start, end, size).

analytes

Tibble: spot_number, analyte, unit, plus lod, lloq, uloq, assay_control_low, assay_control_high when reported.

well_groups

Tibble: well_group, sample_id, is_standard, is_negative, is_sample, is_control, well_type.

pixel_intensities

Long-format tibble of replicate readings: well_group, sample_id, well, replicate, analyte, unit, pixel_intensity, dilution.

summary_statistics

Long-format tibble of per-group averages, std-dev, and CV statistics: well_group, sample_id, statistic, analyte, value, unit.

concentrations

Long-format concentration tibble or NULL if the regression model is "Qualitative".

curve_fit

Tibble with analyte, regression_model, or NULL if not reported.

report_csv

Character vector of the raw CSV report lines, or NULL if no report was generated.

plate_layout

Tibble with one row per well: well, plate_row, plate_col, well_group, sample_id, well_type, dilution.

See Also

strip_qview_prefix(), read_qview_template(), print.qview(), plot.qview().

Other qview-reader: read_qview_report(), read_qview_template()

Examples

# A small synthetic .Q-View ships with the package:
path <- system.file("extdata", "example.Q-View", package = "qviewparsR")
qv <- read_qview(path)
qv
qv$analytes
head(qv$pixel_intensities)

if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot(qv, type = "plate_map")
}

Read a Q-View report export (CSV or XLSX)

Description

Usage

read_qview_report(
  path,
  strip_prefix = FALSE,
  verbose = TRUE,
  call = rlang::caller_env()
)

Arguments

Details

Parses one of the flat report files Q-View exports next to the native .Q-View container – the ..._auto_report or ..._auto_all-parameters_report export, as either .csv or .xlsx – and returns the same qview object read_qview() builds from the binary container. Use it when only the exports were kept and the original .Q-View project file is unavailable.

The export shares its report layout with the CLOB embedded in the binary container, so the two readers agree on concentrations and pixel intensities. Two behaviours differ from read_qview(), both to preserve information the study workflows rely on:

• The plain "Reduced Concentration" point estimate (one row per sample, the value the exports headline) is captured with statistic == "reduced". read_qview() currently keeps only the per-replicate / summary concentration rows.

• Out-of-range cells are preserved, not dropped: a "< 52.50" cell yields concentration = 52.50 with flag = "<", a "> 7700" cell flag = ">", and an "Incalculable ..." cell concentration = NA with flag = "incalculable". In-range cells carry flag = NA.

Value

A list with class "qview", structured as the read_qview() return value, with these deviations. Container-only slots (manifest, segments) are zero-row tibbles; metadata$container_version is NA. The concentrations tibble carries one extra column, flag (NA / "<" / ">" / "incalculable"), relative to read_qview(). report_csv echoes the full export in file order (metadata preamble, blank spacer rows, the analyte header, then the data rows), whereas read_qview()'s report_csv holds only the unique report data lines.

See Also

read_qview(), read_qview_template().

Other qview-reader: read_qview(), read_qview_template()

Examples

path <- system.file("extdata", "example-report.csv",
                    package = "qviewparsR")
if (nzchar(path)) {
  qv <- read_qview_report(path)
  qv$concentrations
}

Read a Q-View well-assignment template CSV

Description

Usage

read_qview_template(path, verbose = TRUE, call = rlang::caller_env())

Arguments

Details

Parses the plate-template CSV that Q-View imports for sample assignment. The file uses a multi-section layout: an NxM cell in the top-left declares the plate dimensions, followed by sections labelled ⁠Group Name⁠, ⁠Group Type⁠, and ⁠Dilution Factor⁠. Each section is one row per plate row and one column per plate column.

All template data is also embedded inside the .Q-View file itself (and is recovered by read_qview()); this function exists for setting up new plates or cross-validating Q-View imports against the original template.

Value

A tibble::tibble() with one row per well and columns well (character, e.g. "A1"), plate_row (character, "A"..), plate_col (integer), sample_id (character), group_type (character), dilution (numeric).

See Also

Other qview-reader: read_qview(), read_qview_report()

Examples

path <- system.file("extdata", "example-template.csv",
                    package = "qviewparsR")
layout <- read_qview_template(path)
head(layout)

Reverse the Q-View internal naming convention

Description

Usage

strip_qview_prefix(x)

Arguments

Details

On import, the producing software prefixes well-assignment template names with single-letter codes:

• "Cal 1" ... "Cal N" -> "ICal 1" ... "ICal N" (Internal calibrator)

• "Low" -> "GLow"

• "High" -> "HHigh"

• "FD..." and any all-digit ID -> "N..." (sample prefix)

strip_qview_prefix() reverses this transformation so that downstream code sees the identifiers exactly as they appear in the original template CSV. Strings that do not match a known prefix pattern are returned unchanged.

Value

Character vector of the same length as x, with prefixes stripped. NAs and unrecognised values pass through unchanged.

See Also

Other qview-helper: well_label()

Examples

strip_qview_prefix(c("ICal 1", "GLow", "HHigh",
                     "NFD24277364", "N1211498458", "Plate 1"))

Summary statistics for a Q-View object

Description

Per-analyte mean, standard deviation, and coefficient of variation (sd / mean) of pixel intensities, by well-group type. Calibrator / standard wells are reported separately so calibration variability is easy to inspect.

Usage

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

Arguments

Value

A tibble::tibble() with one row per well_type x analyte combination, columns: well_type, analyte, unit, n, mean, sd, cv, min, max.

See Also

Other qview-methods: as_tibble.qview(), is_qview(), plot.qview(), print.qview(), print.qview_summary()

Examples

path <- system.file("extdata", "example.Q-View", package = "qviewparsR")
qv <- read_qview(path, verbose = FALSE)
summary(qv)

Convert plate row / column to a well label

Description

Usage

well_label(row, col, zero_based = FALSE)

Arguments

Details

Converts 0-based or 1-based row and column indices to the standard "A1" ... "H12" plate notation. Vectorised.

Value

Character vector of well labels (e.g. "A1", "H12"), recycled to the longer of row / col.

See Also

Other qview-helper: strip_qview_prefix()

Examples

well_label(0, 0, zero_based = TRUE)   # "A1"
well_label(7, 11, zero_based = TRUE)  # "H12"
well_label("C", 5)                    # "C5"

Write a Q-View object to disk

Description

Usage

write_qview_xlsx(
  qv,
  path,
  template = NULL,
  overwrite = FALSE,
  call = rlang::caller_env()
)

write_qview_csv(qv, path, template = NULL, call = rlang::caller_env())

write_qview_rds(qv, path, overwrite = FALSE, call = rlang::caller_env())

qview_to_xlsx(
  qv,
  path,
  template = NULL,
  overwrite = FALSE,
  call = rlang::caller_env()
)

qview_to_csv_dir(qv, dir, template = NULL, call = rlang::caller_env())

Arguments

Details

Three writers, one for each common destination. All return the input qv invisibly so they compose with the pipe.

• write_qview_xlsx() – one sheet per parsed table.

• write_qview_csv() – one CSV per parsed table inside a directory.

• write_qview_rds() – a single .rds containing the full qview object (lossless, the only round-trippable format).

Value

qv, invisibly, to support pipelines.

Examples

path <- system.file("extdata", "example.Q-View", package = "qviewparsR")
qv <- read_qview(path, verbose = FALSE)

out <- tempfile()
dir.create(out)
qv |>
  write_qview_rds(file.path(out, "plate.rds")) |>
  write_qview_csv(file.path(out, "plate_csv"))
list.files(out, recursive = TRUE)