# diffHTS

<!-- badges: start -->
<!-- badges: end -->

**diffHTS** provides reusable methods for **large-scale**, **two-condition**
high-throughput drug screening (HTS). It compares drug sensitivity between any
two experimental conditions — for example irradiated versus non-irradiated
cells, cancer versus normal cell lines, or treated versus untreated samples —
across many plates and experiments, in a documented and tested toolkit.

## Installation

Install from a local source checkout:

```r
# install.packages("remotes")
remotes::install_local("diffHTS")

# or, from the built source tarball
install.packages("diffHTS_0.1.0.tar.gz", repos = NULL, type = "source")
```

Dose-response fitting is implemented in base R, so no external fitting package
is needed. Some visualisation and I/O features use packages that are only
*suggested*: the Bioconductor packages `ComplexHeatmap` and `circlize`
(heatmaps), `ggrepel` (labelled scatter plots), `readxl` (Excel import) and
`rmarkdown` (HTML reports).

## Standard pipeline

**diffHTS** organises a complete HTS analysis into seven modules that take raw
plate readouts all the way to an annotated, ranked hit list. It supports both
single-concentration **primary** screens and gradient **secondary**
(dose-response) confirmation screens. Each module pairs business functions with
matching visualisation functions.

| Module | Business functions | Visualisation |
|--------|--------------------|---------------|
| **1. Import & pre-QC** | `read_plate_layout()`, `apply_plate_layout()`, `read_hts_plate()`, `summarize_plate_setup()`, `baseline_subtract()`, `detect_outlier_wells()`, `calc_z_prime()`, `calc_robust_z_prime()`, `calc_z_factor()`, `calc_ssmd()`, `calc_sb_ratio()`, `calc_sn_ratio()`, `calc_cv()`, `calc_plate_qc()`, `calc_well_zscore()`, `filter_valid_plates()` | `plot_plate_heatmap_raw()`, `plot_plate_qc()` |
| **2. Normalisation** | `norm_by_control()`, `merge_plate_data()` | `plot_plate_heatmap_inhibition()`, `plot_inhibition_hist()` |
| **3. Replicate consistency** | `calc_replicate_cv()`, `calc_replicate_correlation()`, `filter_bad_replicate()` | `plot_replicate_scatter()`, `plot_cv_distribution()` |
| **4. Primary hit selection** | `select_primary_hit()`, `select_sigma_hits()`, `summarize_primary_hit()`, `summarize_sigma_hits()` | `plot_primary_inhibition_rank()`, `plot_hit_bar_count()`, `plot_sigma_hits()` |
| **5. Dose-response & AUC** | `import_dose_response()`, `fit_4pl_curve()`, `extract_drc_params()`, `calc_drc_auc()`, `filter_low_quality_curve()` | `plot_single_drc()`, `plot_batch_drc_overlay()`, `plot_ic50_auc_cor()` |
| **6. AUC matrix & clustering** | `build_auc_matrix()`, `cluster_auc_matrix()`, `extract_cluster_hit()` | `plot_auc_heatmap()`, `plot_cluster_tree()` |
| **7. Ranking, annotation & report** | `rank_hit_compound()`, `annotate_hit_info()`, `export_hit_table()`, `generate_hts_report()` | `plot_hit_stratify_bar()`, `plot_primary_secondary_cor()` |

**Utilities**: `plate_layout()` / `plate_layout_384()` / `plate_layout_1536()`,
`convert_conc_log10()`, `check_control_label()`, `clean_compound_id()`.

The original two-condition (differential) analysis remains available:
`four_pl()`, `compute_auc()`, `fit_dose_response()`, `compute_delta_auc()`,
`select_hits_cutoff()`, `select_hits_sigma()`, `calculate_qc_metrics()`,
`plot_dose_response_curves()`, `plot_delta_auc_heatmap()`,
`plot_condition_scatter()` and the QC plots.

## Quick start

```r
library(diffHTS)

## --- Primary screen: raw signals -> hits ---------------------------------
## Author a plate map (which wells are NC / PC / blank / compound) yourself,
## then stamp it onto the instrument readings:
layout <- read_plate_layout(
  system.file("extdata", "plate_layout_example.csv", package = "diffHTS"),
  plate_id = "P01")
# raw <- apply_plate_layout(signal_export, layout)  # merge roles onto readings

raw  <- read_hts_plate(hts_primary_raw) # three 96-well plates in one object
summarize_plate_setup(raw)             # per-plate layout: controls & compounds
raw  <- baseline_subtract(raw)
qc   <- calc_plate_qc(raw)             # full QC panel: Z'/robust-Z'/SSMD/S:B/S:N/CV%
plot_plate_qc(qc, metric = "ssmd")     # one plot fn, choose any metric
good <- filter_valid_plates(raw)       # drop failed plates (P03)
norm <- norm_by_control(good)          # % inhibition vs NC/PC
hits <- select_primary_hit(norm, threshold = 50)
summarize_primary_hit(hits)

## --- Secondary screen: dose-response -> ranked hits ----------------------
dr   <- import_dose_response(hts_dose_response,
                             response_col = "viability",
                             group_cols   = "cell_line")
drc  <- calc_drc_auc(fit_4pl_curve(dr, group_cols = "cell_line"))
params <- merge(extract_drc_params(drc), drc$meta[, c("curve_id", "auc")])

ranked <- rank_hit_compound(params)                 # Strong/Moderate/Weak
annotate_hit_info(ranked, hts_compound_meta)        # add target/MoA
plot_single_drc(drc, drc$meta$curve_id[1])          # one fitted curve
plot_auc_heatmap(build_auc_matrix(drc$meta, zscore = "row"))
```

## Example data

- `hts_primary_raw` — simulated 96-well primary screen with raw signals
  (plates P01/P02 good, P03 failed).
- `hts_dose_response` — simulated gradient dose-response screen (10 compounds,
  3 cell lines, 2 replicates).
- `hts_compound_meta` — simulated compound annotation table.
- `screen_doseresponse` — a small simulated two-condition dose-response screen.
- `screen_delta_auc` — a small simulated differential-AUC table.
- `screen_plate_qc`, `screen_plate_layout` — QC / plate-layout demo data.

All are fully simulated (see `data-raw/make_datasets.R`) and do not correspond
to any real compound or cell line.

## Vignette

See `vignette("diffHTS")` for an end-to-end walkthrough.

## License

GPL-3
