Package 'CGExplorer'

Title: Chemo-Genomic Screening Data Preprocessor and Visualizer
Description: An R package providing S4 data structures, analysis methods, and a Shiny application for preprocessing, quality control, and chemo-genomic interaction scoring of 384-well plate screening datasets generated by Tecan plate readers. Plate data is managed via a persistent local registry (PlateRegistry S4 object) that accumulates across sessions and survives package upgrades.
Authors: Qingzhou Zhang [aut, cre]
Maintainer: Qingzhou Zhang <[email protected]>
License: MIT + file LICENSE
Version: 0.3.2
Built: 2026-10-09 17:27:15 UTC
Source: https://github.com/zqzneptune/CGExplorer

Help Index

Add batch to registry

Description

Add batch to registry

Usage

add_batch(registry, batch, ...)

## S4 method for signature 'PlateRegistry'
add_batch(registry, batch, ...)

Arguments

registry

PlateRegistry object
batch

Batch object
...

additional arguments

Methods (by class)

  • add_batch(PlateRegistry): Add Batch object to PlateRegistry

Add layout to registry

Description

Add layout to registry

Usage

add_layout(registry, layout_name, layout_data, ...)

## S4 method for signature 'PlateRegistry'
add_layout(registry, layout_name, layout_data, ...)

Arguments

registry

PlateRegistry object
layout_name

character name of layout
layout_data

data.frame of layout
...

additional arguments

Methods (by class)

  • add_layout(PlateRegistry): Add layout to PlateRegistry

Add plate to registry

Description

Add plate to registry

Usage

add_plate(registry, plate, ...)

## S4 method for signature 'PlateRegistry'
add_plate(registry, plate, ...)

Arguments

registry

PlateRegistry object
plate

Plate object
...

additional arguments

Methods (by class)

  • add_plate(PlateRegistry): Add Plate object to PlateRegistry

S4 Class representing a Scoring Batch

Description

S4 Class representing a Scoring Batch

Slots

uuid

character.

name

character. User-assigned name.

plate_uuids

character. Ordered Plate UUIDs included in this batch.

scores

list. Scoring results per strategy/metric.

scoring_params

list. Params used in last score_batch().

created_at

POSIXct.

S4 Generics for CGExplorer

Description

S4 Generics for CGExplorer

Compute relative biofilm

Description

Compute relative biofilm

Usage

compute_relative_biofilm(growth_m, biofilm_m)

Arguments

growth_m

data.frame growth metrics
biofilm_m

data.frame biofilm metrics

Value

data.frame joined and scored

Detect staining addition from a kinetic read

Description

Computes per-well OD delta between consecutive cycles. If the median plate-wide delta exceeds the threshold, flags that cycle as the start of the staining assay.

Usage

detect_staining_jump(df, threshold = 0.3)

Arguments

df

data.frame with Plate, Row, Column, DateTime, Time_Hours, OD_Raw
threshold

numeric, OD jump threshold (default 0.3)

Value

A list with 'has_staining', 'jump_cycle', 'jump_time', 'staining_hr'

Export per-strain growth curves for a batch to a multi-page PDF

Description

Writes one page per strain (WT/control strains first, then mutants alphabetically). Each page has one facet per plate in the batch and one line per well, coloured by well ID.

Usage

export_batch_growth_curves_pdf(
  registry,
  batch_name,
  file,
  mode = c("raw", "corrected"),
  strains = NULL,
  progress = NULL
)

Arguments

registry

PlateRegistry
batch_name

character. Name of a batch in registry@batches.
file

character. Output PDF path.
mode

"raw" (raw OD values from the growth assay, as read) or "corrected" (OD_Raw minus the plate blank median at each timepoint, with no floor or clipping). Values are never normalized or rescaled; all wells, including blanks, are plotted in both modes. Staining reads are excluded.
strains

optional character vector restricting which strains are drawn.
progress

optional function(i, n, strain) called after each page.

Value

Invisibly, the number of pages written.

Extract biofilm metrics

Description

Extract biofilm metrics

Usage

extract_biofilm_metrics(df)

Arguments

df

data.frame corrected

Value

data.frame of biofilm metrics

Extract growth metrics

Description

Extract growth metrics

Usage

extract_growth_metrics(df, growth_threshold = 0.02)

Arguments

df

data.frame corrected
growth_threshold

numeric, threshold for valid growth

Value

data.frame of metrics

Get layout from registry

Description

Get layout from registry

Usage

get_layout(registry, layout_name, ...)

## S4 method for signature 'PlateRegistry'
get_layout(registry, layout_name, ...)

Arguments

registry

PlateRegistry object
layout_name

character name of layout
...

additional arguments

Methods (by class)

  • get_layout(PlateRegistry): Get layout from PlateRegistry

Load a PlateRegistry from RDS

Description

Load a PlateRegistry from RDS

Usage

load_registry(path)

Arguments

path

character. Path to the RDS file or directory containing cgexplorer_registry.rds.

Value

A PlateRegistry-class object loaded from disk.

Merge plates in registry

Description

Merge plates in registry

Usage

merge_plates(registry, uuids, ...)

## S4 method for signature 'PlateRegistry'
merge_plates(registry, uuids, ...)

Arguments

registry

PlateRegistry object
uuids

character vector of plate UUIDs
...

additional arguments

Methods (by class)

  • merge_plates(PlateRegistry): Merge multiple plates in PlateRegistry

Constructor for Batch

Description

Constructor for Batch

Usage

new_batch(name, plate_uuids)

Arguments

name

character. Name of the batch.
plate_uuids

character vector. UUIDs of plates included in this batch.

Value

A Batch-class object.

Constructor for Plate

Description

Constructor for Plate

Usage

new_plate(slot_id, growth_data, layout, timezone = "America/Halifax")

Arguments

slot_id

character. Unique identifier for the plate slot (e.g. "S1L1").
growth_data

data.frame. Raw growth assay readings.
layout

data.frame. Well layout definition.
timezone

character. Timezone string, defaults to "America/Halifax".

Value

A Plate-class object.

Constructor for PlateRegistry

Description

Constructor for PlateRegistry

Usage

new_registry(project_name = "Untitled Project", project_dir = getwd())

Arguments

project_name

character. Project display name.
project_dir

character. Path to project directory storing registry.

Value

A PlateRegistry-class object.

Parse 96 or 384 well Plate Layout

Description

Parse 96 or 384 well Plate Layout

Usage

parse_plate_layout(filepath)

Arguments

filepath

character.

Value

A list containing format info and the parsed data.frame.

Parse Tecan Plate Reader output (.txt)

Description

Parse Tecan Plate Reader output (.txt)

Usage

parse_tecan_txt(filepath)

Arguments

filepath

character.

Value

A data.frame with Plate, DateTime, Row, Column, OD

S4 Class representing a Chemo-Genomic Plate

Description

S4 Class representing a Chemo-Genomic Plate

Slots

uuid

character. Internal UUID.

slot_id

character. E.g. "S1L1".

label

character. User-facing name.

treatment

character. E.g. "NoDrug", "Drug1".

replicate

integer. Biological replicate number.

media

character. Growth media label.

layout

data.frame. Well map.

assays

list. Named list of assay data.frames (growth, final, staining).

staining_hr

numeric. Hours post t0 when staining was performed (NA if unknown).

staining_confirmed

logical. TRUE after user confirms staining detection.

t0

POSIXct. Earliest DateTime in assays$growth.

t_end

POSIXct. Latest DateTime across all non-NULL assays.

timezone

character. Timezone, fixed to "America/Halifax".

metrics

list. Populated by compute_metrics().

qc_flags

list. QC results.

provenance

list. Audit trail records.

is_merged

logical. TRUE if created from merge_plates().

S4 Class representing the Project Plate Registry

Description

S4 Class representing the Project Plate Registry

Slots

plates

list. Named list: UUID -> Plate S4 object.

batches

list. Named list: batch_name -> Batch S4 object.

layouts

list. Named layout registry.

project_name

character. User-assigned project name.

project_dir

character. Absolute path to directory holding registry.rds.

schema_version

character. Package version at save time.

created_at

POSIXct.

modified_at

POSIXct.

Plot Multi-Strain Growth Curves

Description

Plot Multi-Strain Growth Curves

Usage

plot_multi_strain_growth_curves(
  df,
  selected_genes = NULL,
  use_raw_od = FALSE,
  color_by = "strain"
)

Arguments

df

data.frame containing Time_Hours, OD_Corrected, OD_Raw, Gene, Type, Rep_Suffix, Row, Column
selected_genes

character vector of selected genes/strains
use_raw_od

logical. TRUE for OD_Raw, FALSE for OD_Corrected
color_by

character. "strain", "replicate", or "type"

Value

plotly object

Plot Plate QC Layout

Description

Plot Plate QC Layout

Usage

plot_plate_qc_layout(
  plate,
  metric = "Growth_Endpoint_OD",
  colorscale = "plasma",
  cmin = NULL,
  cmax = NULL
)

Arguments

plate

Plate object
metric

character. Column name in metrics to plot.
colorscale

character. Color scheme key.
cmin

numeric. Minimum value for color scale.
cmax

numeric. Maximum value for color scale.

Value

plotly object

Plot Replicate Growth Curves

Description

Plot Replicate Growth Curves

Usage

plot_replicate_growth_curves(replicate_data, stain_hr = 26)

Arguments

replicate_data

data.frame containing Time_Hours, OD_Raw or OD_Corrected, Row, Column, Gene, Rep_Suffix
stain_hr

numeric staining hour threshold

Value

plotly object

Remove batch from registry

Description

Remove batch from registry

Usage

remove_batch(registry, batch_name, ...)

## S4 method for signature 'PlateRegistry'
remove_batch(registry, batch_name, ...)

Arguments

registry

PlateRegistry object
batch_name

character batch name
...

additional arguments

Methods (by class)

  • remove_batch(PlateRegistry): Remove Batch object from PlateRegistry

Remove layout from registry

Description

Remove layout from registry

Usage

remove_layout(registry, layout_name, ...)

## S4 method for signature 'PlateRegistry'
remove_layout(registry, layout_name, ...)

Arguments

registry

PlateRegistry object
layout_name

character name of layout
...

additional arguments

Methods (by class)

  • remove_layout(PlateRegistry): Remove layout from PlateRegistry

Remove plate from registry

Description

Remove plate from registry

Usage

remove_plate(registry, uuid, ...)

## S4 method for signature 'PlateRegistry'
remove_plate(registry, uuid, ...)

Arguments

registry

PlateRegistry object
uuid

character plate UUID
...

additional arguments

Methods (by class)

  • remove_plate(PlateRegistry): Remove Plate object from PlateRegistry

Run the Shiny Application

Description

Run the Shiny Application

Usage

run_cgexplorer_app(...)

Arguments

...

arguments to pass to golem_opts.

Save registry to disk

Description

Save registry to disk

Usage

save_registry(registry, ...)

## S4 method for signature 'PlateRegistry'
save_registry(registry, ...)

Arguments

registry

PlateRegistry object
...

additional arguments

Methods (by class)

  • save_registry(PlateRegistry): Save PlateRegistry to RDS file

Standardized Scoring Engine

Description

Standardized Scoring Engine

Usage

score_batch_dataset(
  pheno_df,
  strategy_type = c("NoDrug_Plates", "NoDrug_Wells"),
  metrics,
  control_drug = "NoDrug"
)

Arguments

pheno_df

data.frame containing aggregated phenotypic metrics across a batch
strategy_type

character, either "NoDrug_Plates" or "NoDrug_Wells"
metrics

character vector of target metrics
control_drug

character, name of control treatment

Value

data.frame of scores

Subtract blanks at the plate level

Description

Subtract blanks at the plate level

Usage

subtract_plate_blanks(df, blank_threshold = 0.05)

Arguments

df

data.frame with Row, Column, Time_Hours, OD_Raw, Type, Is_Stained
blank_threshold

numeric, threshold for bad blanks

Value

list with corrected 'data' and 'removed_blanks'

Update plate in registry

Description

Update plate in registry

Usage

update_plate(registry, plate, ...)

## S4 method for signature 'PlateRegistry'
update_plate(registry, plate, ...)

Arguments

registry

PlateRegistry object
plate

Plate object
...

additional arguments

Methods (by class)

  • update_plate(PlateRegistry): Update Plate object in PlateRegistry

Validate plate eligibility and layout uniformity for a batch

Description

Validate plate eligibility and layout uniformity for a batch

Usage

validate_batch_plates(registry, uuids)

Arguments

registry

PlateRegistry
uuids

character vector of plate UUIDs

Value

TRUE if valid, otherwise throws an error