NEWS

---

epiPortrait 0.99.3

• Docker/docs polish and manuscript-readiness pass performed on top of 0.99.2; no public API change. Aligned documentation wording with analyze_differential_domains() (limma-on-continuous-intensity caveat, NA != zero-signal semantics) and synced regenerated man pages.

epiPortrait 0.99.2

• Removed inst/CITATION until a manuscript with a DOI is available (README carries the inline citation instead).
• codecov.yml: patch coverage gate set to informational so a continuation line (e.g. a string literal) that maps poorly to coverage feedback does not fail commits; README badge switched to the token-free codecov.svg.
• Windows notes and error messages clarified.

epiPortrait 0.99.1

• Made elbow calling orientation-aware so inverse/left-loaded ranked curves produce no_call instead of an implausibly large Super set.
• Propagated both NA and the explicit Uncertain class through combined and per-sample transitions.
• Fixed two-group limma analysis for grouping factors with unused levels.
• Added genome/seqlevel compatibility checks for signal extraction and cross-mark integration; epigenomic cross-mark overlaps are now explicitly strand-agnostic.
• Modernized the package citation and strengthened caller input validation.

Changes in version 0.99.0 (2026-08-10)

Cross-mark integration and per-sample transitions (2026-08-26)

• New integrate_cross_mark(se_a, se_b, ...): overlays the per-sample super-domain calls of object B onto the (possibly DIFFERENT) domain universe of object A. Each object A domain is classified from the object B calls of the object B domains that overlap it (any_super or majority aggregation, optional min_overlap_bp). Enables the two-axis design (e.g. enhancer-mark Intensity on the promoter mark's domains, or boundary-rescue of promoter-proximal enhancers). Adds <mark_b>_Call__<tp> + <mark_b>_NOverlaps__<tp> rowData columns, a long-format table in metadata(se_a)$cross_mark_integration, and provenance in metadata(se_a)$cross_mark_provenance.
• New transition_matrix_per_sample(se, feature/call_fmt, timepoints, ref): pairwise transitions between per-SAMPLE call columns (mode per_sample, one sample per time point), which compare_superdomains()/compare_superdomain_classes() do not support (they need per-GROUP columns). Adds <prefix>_SampleTransition__<ref>_vs_<target> rowData columns with compare_superdomain_classes()-consistent labels (Persistent_ / to / Uncertain) and per-pair counts tables in metadata(se)$transitions. With ref = NULL all ordered time-point pairs are computed.

BEDPE contact-score aggregation in annotate_epi_domains() (2026-08-26)

• New bedpe_score_col argument: an optional BEDPE column (integer index

  = 7 or column name) holding a per-record contact STRENGTH, e.g. the FitHiChIP TMM-normalized contact frequency. Motivated by real datasets (GSE251898) where the published TMM BEDPE loop SET is identical across conditions and only the score varies — count-based contact integration alone is invariant there by construction.

• When supplied: metadata(se)$domain_gene_links$contact_score carries the per-evidence-row score; the dedup pair table and the annotation summary gain bedpe_contact_score (summed over UNIQUE supporting records; domain level = sum over all contacted records); rowData(se)$bedpe_contact_score mirrors the domain-level value. bedpe_provenance$score_column records what was used.
• Semantics: no BEDPE evidence -> 0; evidence without usable scores (or runs without bedpe_score_col) -> NA, so "no 3D evidence" and "unscored 3D evidence" remain distinguishable.
• get_domain_genes() gains a bedpe_contact_score column and a new rank_by = c("tier", "bedpe_score") argument: "bedpe_score" prioritizes candidate genes primarily by descending 3D contact strength (dominant-loop-style target assignment), with the evidence tier and expression as tie-breakers.
• Default behaviour (bedpe_score_col = NULL) is unchanged apart from the two new NA-valued columns.

Statistical hardening of analyze_differential_domains() (2026-08-23)

• analyze_differential_domains() now fits the limma mean-variance trend by default (trend = TRUE): integrated intensity exhibits a strong mean-variance dependence across domains, and without the trend low-signal domains were over-called as significant. The trend is disabled automatically with a warning when fewer than 20 domains pass min_signal filtering.
• New robust = FALSE argument exposes limma's robust empirical-Bayes moderation for outlier-resistant inference.
• Both settings are recorded in metadata(se)$differential_domains provenance; invalid values are rejected.
• Documented the scale-dependence of the log(x + 1) pseudo-count offset (CPM vs RPGC vs spike-in units) and its interaction with min_signal.
• eBayes(trend = TRUE) changes P-values slightly relative to previous releases; re-run differential analyses after upgrading.
• Bug fix: a two-element character contrast (coefficient-name pair, documented as coef1 - coef2) was silently ignored and the uncontrasted fit was returned. It is now converted to numeric contrast weights, with a clear error when a name does not match a design coefficient. Supplying design without any contrast is now also rejected instead of silently returning an uncontrasted fit.
• Bug fix: a user-supplied formula design (e.g. ~ Condition or ~ 0 + Condition) crashed inside limma with an obscure internal error, because the formula object was passed to lmFit() unconverted. Formulas are now materialized with model.matrix() on colData before fitting, so custom paired/batched designs are actually usable.

Expert review fixes (2026-08-14)

• normalize_portrait(): the completion message no longer uses a sprintf() format string without a placeholder (this produced a runtime warning "argument out of range" and truncated the message to "Normalization complete! Intensity adjusted; SignalDispersion "). The "(bp-scale spatial descriptor) is left unchanged" note is now emitted correctly.
• plot_hockey_stick(): when the object was called with mode = "per_group" and group is omitted, the error now states that the calls are per-group and lists the available condition groups, instead of the misleading "Run call_super_domains first" message.
• annotate_epi_domains(): the strand-aware signed nearest-TSS distance is now fully vectorized (one match() over the gene model instead of a per-domain O(genes) subsetting loop); output is unchanged.
• build_portrait_matrix(): the batch import path accumulates Intensity into a double (numeric()) vector instead of integer() (values were never truncated because R promotes on assignment, but the type was misleading for continuous CPM/RPGC signal).
• plot_peak_track(): replaced scale_fill_brewer("Set1") (capped at 9 groups) with the package's own condition palette, consistent with the rest of the visualization suite.
• call_super_domains(): documented the intentional asymmetry of min_valid_replicates under support_rule = "fraction" (a low threshold, e.g. 0.5 with n=2, resolves to 1 and can call a "Super + no_call" pair Super because the user explicitly chose how much support suffices).
• Added regression tests: fractional Intensity preservation through build_portrait_matrix() (double precision, cache and non-cache paths identical) and the per-group hockey-stick error message.

Documentation repositioning (2026-08-11)

• Package identity repositioned from "super-domain caller" to "replicate-aware epigenomic domain profiling": DESCRIPTION title and README/vignette narrative now describe the framework as quantitative phenotyping of shared epigenomic domains (Intensity x native peak breadth + within-domain signal architecture), with super-domain calling as one analytical module. ROSE is presented as an optional H3K27ac benchmark; the tangent inflection is documented as a geometric variant, not a bit-exact ROSE reproduction.

Breadth top-fraction & stability calling (2026-08-11)

• call_super_domains(feature = "Breadth") now supports quantile_cutoff as an explicit top-fraction opt-in, symmetric with Intensity: the cutoff is the quantile_cutoff quantile of each replicate's genome-wide eligible native PeakWidth distribution (top 100*(1-quantile_cutoff)% widest peaks are Broad; e.g. 0.95 = top 5%). It never auto-falls-back to, or from, the data-driven elbow/tangent inflection, so no-call semantics of the default path are unchanged. quantile_cutoff and min_replicate_support are now validated.
• n_bootstrap is supported for Breadth (symmetric with Intensity): a per-replicate within-set cutoff stability interval and success rate are stored in get_call_provenance(se, "Breadth")$replicates[[s]]. As with Intensity, this is a resampling-stability diagnostic whose information content shrinks with the size of the ranked set; the dominant uncertainty for Breadth (upstream native-peak set composition) is assessed separately via the peak-set perturbation check in validation/02.

Freeze pre-check fixes (deep review 2026-08-10)

• Z-score normalization REMOVED from normalize_portrait(): it is a row-wise display/clustering transform that destroys the cross-domain magnitude ranking required by Super calling and must never overwrite the canonical Intensity assay. plot_portrait_pca() and plotting layers already apply their own scaling for display. normalize_portrait() description now states that SignalDispersion is preserved in native bp units.
• plot_domain_landscape() now accepts and respects group_var (was hard-coded to "Condition"), matching call_super_domains() / get_replicate_calls() / combine_superdomain_calls() for custom group variables.
• filter_promoter_peaks() now enforces domain/TxDb seqlevel compatibility (zero shared -> error, partial -> warning) and validates upstream/downstream parameters, consistent with annotate_epi_domains().
• filter_blacklist() now fails loudly on zero shared seqlevels (chr1-vs-1 mismatch) instead of silently removing 0 peaks, and warns on partial overlap.
• validate_epiportrait_object() now verifies the replicate_call_matrix contract (rows = domains, rownames = domain IDs, columns a subset of samples).
• stitch_epi_peaks(): min.gapwidth = stitch_distance + 1 so a gap exactly equal to the documented "maximum distance" is merged (off-by-one fix).
• get_replicate_calls(group = NULL) preserves the original sample order instead of the alphabetical group order used during column binding.
• Removed package-root Rplots.pdf; added ^Rplots[.]pdf$ to .Rbuildignore.
• Updated stale comments (annotation resolver, NEWS font wording).

Nature-style publication theming (nature-figure skill)

• All plots now use a Nature-style publication theme: no background grid lines, thin black axis lines, platform-safe sans-serif, compact base sizes, and frameless legends. Affected: .epi_theme_publication() (hockey-stick, PCA, landscape, transition, replicate support, class composition, feature profile), plot_peak_track() and plot_portrait_correlation() (both switched from theme_minimal to the grid-free classic theme).
• Export via save_epiportrait_figure() produces editable-text SVG / PDF (vector fonts, no outlined paths).

Intensity replicate-calling transparency (design 2026-08-10)

• New get_replicate_calls(): exposes the per-domain x per-replicate super-domain call matrix underlying the group-level replicate-support call (matrix or long format). For mode = "per_group" it reads the stored provenance (replicate_call_matrix is now saved per group); for mode = "per_sample" it reconstructs from the Call_ rowData columns.
• call_super_domains(mode = "per_group") now stores the full domain x replicate call matrix in metadata(se)$superdomain_calls[[feature]]$groups[[g]]$ replicate_call_matrix, making 2/3-style support fully auditable.
• Documentation clarified (mode descriptions): per_group calls EACH replicate independently on its own ranked feature distribution, then aggregates replicate calls by the support rule; group-mean ranks are stored for visualization only and never determine the group call.
• Fixed min_valid_replicates documentation: NULL (default) resolves to the support-rule-required number (majority: floor(n/2)+1; all: n; fraction: ceiling(fraction*n)), not "default 1".

Species/genome & annotation audit fixes (deep audit 2026-08-10)

• P0-1: filter_blacklist() no longer depends on the TxDb/OrgDb resolver. Blacklist resolution is independent: built-in hg38/hg19/mm10/mm9 blacklists load directly from inst/extdata, so mm9 works and blacklist filtering never requires a TxDb Suggests package. Custom BEDs via blacklist_path.
• P0-2: domain-TxDb seqlevel compatibility is now ENFORCED in annotate_epi_domains(): zero shared seqlevels -> error (with domain-only seqlevels reported); partial overlap -> warning. A genome-build / chr-vs-1 naming mismatch is never silently reinterpreted as intergenic domains. Compatibility details (shared, domain_without_txdb, txdb_only) are stored in annotation_provenance.
• P1-1: min_expression is now genuinely NULL by default. expressed_first on TPM/CPM uses a documented convenience threshold of 1; on VST/rlog/ normalized_counts it requires an explicit user threshold. high_expression_first needs no threshold and leaves expression_status NA.
• P1-2: wide RNA expression matrices with ANY unmatched sample column now error (previously silently dropped); a subset of ChIP samples is allowed.
• P1-3: wide RNA validates unique non-empty rownames and numeric values.
• P1-4: candidate_priority is re-ranked to a contiguous 1..N ordinal after unique_genes collapse (no gaps from dropped rows).
• P1-5: added a real evidence-vs-expression test (BEDPE-supported low-expression gene outranks nearest-only high-expression gene).
• P1-6: BEDPE provenance/comment wording unified: records are not modified or re-scored; bedpe_record_id links derived evidence back to the source.
• P1-7: gene_symbol is NA when no symbol mapping is available (never a gene_id masquerading as a symbol).
• P1-8: a user-provided gene_id_keytype whose mapping fails now warns (not silent); gene_id_keytype is recorded in annotation_provenance.
• P1-9: BEDPE seqlevel_style inferred from the anchors (UCSC or custom/unknown), not hard-coded.
• P1-10: promoter_upstream / promoter_downstream validated (finite, >= 0).
• P1-11: get_domain_genes() validates domains length/NA, group existence, and requires group + expression data for expression_priority != "none".
• P1-12/13: documentation clarifies the gene-level representative TSS and the difference between filter_promoter_peaks() (transcript-level promoters) and annotate_epi_domains() (gene-level promoter window).
• P1-14: export_epiportrait_results() writes annotation/domain_gene_links.tsv and annotation/provenance.txt when domain annotation is present.
• Added 11 audit tests (mm9 blacklist, blacklist/TxDb independence, zero/partial seqlevels, wide unmatched samples, rownames/numeric validation, VST threshold, invalid group, unique rerank, evidence-vs-expression, annotation export).

Annotation correctness fixes (deep review 2026-08-10)

• P0-1: .gene_model_from_txdb() no longer reduce()s TxDb genes. One TxDb gene is now always one gene-level feature; overlapping genes are never merged into a pseudo-gene ("geneA,geneB").
• P0-2: nearest_tss_distance_bp is now the strand-aware SHORTEST interval-to-TSS distance: 0 when the TSS lies inside the domain (previously the midpoint offset could give several kb for an overlapping TSS).
• P0-3: nearest-TSS hits are backfilled by queryHits() so domains on contigs absent from the TxDb stay NA instead of misaligning.
• P0-4: primary_genomic_context simplified to Promoter-associated / Gene-body-associated / Intergenic, consistent with the count columns (no more over-produced "Mixed" or unbounded "Downstream").
• P0-5: long-format RNA aggregation now uses stats::aggregate (correct gene x replicate collapse; tapply length mismatch fixed).
• P0-6: wide RNA matrix columns are matched to epiPortrait samples BY NAME, not by position; independent RNA sample IDs require the long-format input.
• P0-7: candidate_priority is now a true integer rank (order() permutation was being assigned directly).
• P0-8: BEDPE evidence score uses pmax() so the strongest 3D evidence is never overwritten by a weaker relation on the same domain-gene pair.
• P1-1: gene symbols are resolved once over ALL linked gene ids and backfilled into every relation row (previously only nearest_tss got symbols).
• P1-2: gene_id_keytype parameter; custom TxDbs require an explicit keytype instead of hard-coded ENTREZID.
• P1-3: unique_genes = TRUE now retains the BEST-SUPPORTED domain-gene association per gene (sorted by priority first).
• P1-4: bedpe_support_count counts UNIQUE BEDPE records (a record matching via both directions is no longer double counted).
• P1-5: BEDPE seqlevels are actually checked against the domains (zero shared -> error; partial -> warning).
• P1-6: BEDPE input validation (non-empty chrom, numeric coordinates, start>=0, end>start).
• P1-7: BEDPE provenance notes that records are not modified/re-scored and that bedpe_record_id links derived evidence back to the source (accurate promise).
• P1-8: BEDPE promoter-contact linking is range-vectorized (one findOverlaps per direction + join by record id), scaling to 10^4-10^6 interactions.
• P1-9: expression provenance records the RNA sample IDs (not the ChIP ones).
• P1-10: RNA gene-ID match QC (n_matched / match_fraction in provenance; stop on zero matches, warning on <50%).
• P1-11: min_expression = NULL default semantics; expressed_first on non-TPM/CPM types requires an explicit user threshold.
• P1-13: ChIPseeker removed from README/vignette install commands and vignette section title (DESCRIPTION no longer imports it).
• Genome resolver: custom TxDb seqstyle inferred from seqlevels (no longer hard-coded "UCSC"); filter_blacklist() now uses the shared resolver.
• Added 17 edge-case tests (overlapping genes, TSS-inside-domain distance=0, contig mismatch, RNA long/wide alignment, candidate rank, BEDPE validation).

Domain-aware annotation & candidate-gene prioritization (integrated design

2026-08-10)

• New annotate_epi_domains(): genome-flexible, domain-aware annotation of the final shared domains (not individual peaks). Adds 7 compact rowData columns: primary_genomic_context, nearest_tss_gene_id, nearest_tss_gene_symbol, nearest_tss_distance_bp (strand-aware), promoter_overlap_gene_count, gene_body_overlap_gene_count, fully_contained_gene_count. Stores a long-format domain-gene link table in metadata(se)$domain_gene_links.
• New get_domain_genes(): transparent candidate-gene extraction / ordinal prioritization from the stored evidence (evidence first, expression as a secondary tie-breaker; no black-box composite score).
• New internal .resolve_genome_resources() / .check_seqlevel_compatibility(): unified genome resource contract (hg38/hg19/mm10 built-in TxDb/OrgDb, mm9 blacklist-only, custom TxDb/OrgDb/blacklist) shared by annotate_epi_domains(), filter_promoter_peaks() and filter_blacklist().
• BEDPE 3D evidence: optional bedpe_promoter_contact (symmetric / bidirectional domain-anchor to gene-promoter contact). BEDPE is read-only: no calling, filtering, merging, or FDR re-scoring; bedpe_record_id links derived evidence back to the source; per-record bedpe_record_id; provenance in metadata(se)$bedpe_provenance.
• RNA-seq expression integration: user-declared expression_type (TPM/CPM/VST/ rlog), per-condition median aggregation over replicates, and expression-aware prioritization (none / expressed_first / high_expression_first). Expression alone never creates a domain-gene link (evidence required first).
• Removed annotate_epi_peaks(): it was a thin ChIPseeker::annotatePeak() wrapper and epiPortrait's analysis object is the shared domain, not the individual peak. Peak-level annotation remains available via ChIPseeker.
• Provenance: metadata(se)$annotation_provenance, $bedpe_provenance, $expression_provenance.
• Added 23 tests (genome resolution, linear annotation, BEDPE contacts, RNA-seq integration, candidate prioritization).

Changes in version 0.99.0 (2026-08-09)

Pre-submission release for Bioconductor. Metric redesign (v1.0 design docs, 2026-08-09): the taxonomy is simplified to the two-axis architecture Intensity x Breadth, and Breadth-Super is moved to a peak-level, consensus-free calling paradigm.

Heterochromatin / broad-repressive mark compatibility (plan 2026-08-10)

• get_mark_preset() now returns mark_class ("active" / "broad_repressive"), taxonomy_style ("super_domain" / "repressive_remodeling") and class_labels (display aliases). H3K27me3 / H3K9me3 default to stitch_distance = 0: their domains are already spatially clustered by the upstream broad-domain caller (SICER / epic2 / RECOGNICER / MACS2_broad), so epiPortrait no longer applies an extra 5 kb stitching by default (users can pass stitch_distance = 5000 explicitly).
• Display-only terminology: with mark = "H3K27me3" (or H3K9me3), plot_domain_ landscape(), plot_class_transition() and plot_domain_class_composition() render Intensity-Extreme / Extended-Domain / Dual-Extreme. The internal canonical classes (Intensity-Super / Breadth-Super / Dual-Super) are never changed, so the API and transition engine stay mark-independent.
• New compute_width_transition(): continuous domain-width expansion/contraction descriptor (WidthDelta_bp, log2WidthRatio, WidthDirection) between two condition groups, computed from per-domain median native width. This is a continuous effect descriptor, not a significance test (no new p-value framework at n=2/n=3).
• build_portrait_matrix() records domain-source / caller provenance in metadata(se)$domain_provenance when the sample sheet carries optional domain_source / domain_caller / caller_version / caller_mode columns.
• Added tests: mark presets, display alias mapping, mark-aware plots, compute_width_transition semantics, domain provenance.

Correctness fixes from the deep review (2026-08-09)

• Performance: .native_peak_geometry() is now fully vectorized. The previous per-domain R loop (one intersect/reduce per domain) took ~100 s for 3,000 domains and ~17 min for 26,000 domains, making build_portrait_matrix() unusable at mammalian scale. The rewrite clips all peaks to their domains in one pintersect() call and reduces only multi-peak domains (single-peak domains need no reduce), giving an ~10,000x speedup with identical output. Verified on real GBM10 H3K4me3 (26,483 domains): 98.7 s -> 0.01 s for the geometry step; full build_portrait_matrix() incl. a 450 MB BigWig runs in ~6 s.
• Breadth-Super: a replicate whose native PeakWidth elbow is NOT reliable (no_call) now contributes NO evidence (its domains become Uncertain) instead of being coerced to "all Typical". Previously no_call was encoded as an all-FALSE logical vector, silently downgrading super support.
• Breadth-Super mapping: Unmapped / Ambiguous peaks now never produce Typical evidence. Only uniquely-mapped peaks contribute evidence (broad wins over typical inside a domain). Previously any-overlap domains could be labelled Typical even when their only peak was below the overlap threshold or ambiguous.
• build_portrait_matrix(): has_peaks is now always a per-sample logical vector. Previously, when no peak_path column existed, has_peaks was a scalar FALSE and has_peaks[i] for i>1 evaluated to NA, breaking BigWig-only multi-sample mode. has_peaks is also correctly re-subset after fail_action = "drop".
• normalize_portrait(): SignalDispersion (a spatial descriptor in bp) is no longer rescaled by library-size factors, quantile or z-score transforms. Only Intensity is normalized; SignalDispersion stays in bp and is scale-invariant by construction.
• compare_superdomains(): fixed an inverted condition that forced support_rule = "majority" for reference/pooled transitions even when the stored call used "all" or "fraction".
• call_super_domains(feature = "Breadth"): quantile_cutoff is supported as an explicit top-fraction opt-in on the genome-wide native PeakWidth distribution (see "Breadth top-fraction calling" above); n_bootstrap is supported per replicate (within-set cutoff stability, symmetric with Intensity); and min_peak_overlap_fraction is validated to lie in [0, 1].
• Breadth peak-to-domain mapping provenance now records OverlapBp, PeakOverlapFraction, DomainOverlapFraction, the row index AND the actual Domain_ID (epiDomain_xxxxxx).
• plot_hockey_stick(feature = "Breadth"): new peak-level branch that plots the replicate-specific native PeakWidth rank curve from metadata(se)$breadth_peak_calls; the replicate is passed via group.
• validate_epiportrait_object() now requires Intensity and SignalDispersion (native geometry assays remain optional).
• Added unit tests for Breadth no-call propagation, below-threshold Unmapped, ambiguous ties, unique broad/typical mapping, broad-over-typical precedence, and overlap-fraction provenance; consensus A/B robustness benchmark in validation/02_breadth_super_validation.R (Jaccard / PeakBroadCall concordance).

Breaking changes (v1.0 metric simplification)

• Assays: RobustHeight and EffectiveWidth (alias Spreading / Central80Width) are REMOVED from build_portrait_matrix(). Core assays are now Intensity, SignalDispersion, and (when peak files are provided) NativeMaxPeakWidth, NativeOccupiedWidth, NativePeakCount. The static interval length stays in rowData(se)$IntervalWidth.
• signal_contract metadata no longer carries width_baseline_quantile (the central-80% span was removed); SignalSpan80 / .central80_width() are gone.
• call_super_domains(): feature = "Breadth" routes to a NEW peak-level Breadth-Super pipeline (see below). RobustHeight / EffectiveWidth / Spreading are no longer valid features; use Intensity, SignalDispersion or Breadth.
• combine_superdomain_calls(): combines Intensity x Breadth and produces Intensity-Super / Breadth-Super / Dual-Super / Typical / Uncertain (Width-Super is renamed Breadth-Super).
• get_mark_preset(): broad marks (H3K4me3 / H3K27me3 / H3K9me3) now default to primary_feature = "Breadth".

New: peak-level Breadth-Super calling

• Breadth-Super is called at the NATIVE PEAK level, before and independently of consensus construction: each replicate's genome-wide eligible native PeakWidth distribution is ranked and cut by an elbow/inflection (method / min_quality / tie_policy), producing PeakBroadCall per peak.
• Broad peaks are mapped to the shared domain universe by UNIQUE assignment (maximum overlap + min_peak_overlap_fraction, default 0.5); a peak cannot double-count into neighbouring domains (MappingStatus = Unique / Ambiguous / Unmapped).
• Replicate-aware aggregation (support_rule / min_replicate_support / min_valid_replicates) yields group-level / global Breadth-Super.
• Sample-specific native peak files are OPTIONAL: provide peak_path in the sample_sheet to build_portrait_matrix(). Imported peaks are stored in metadata(se)$native_peaks; peak-level calls and mapping provenance are stored in metadata(se)$breadth_peak_calls / breadth_peak_mapping.
• New params on call_super_domains(): min_peak_overlap_fraction, valid_chroms.

New: SignalDispersion

• Signal-weighted genomic SD within each domain. Secondary within-domain signal architecture descriptor; scale-invariant, spatially sensitive, and requires no background baseline. Replaces the removed EffectiveWidth as the continuous-profile descriptor, but does NOT define Breadth-Super.

Visualization

• plot_domain_landscape(): y-axis defaults to NativeMaxPeakWidth (falls back to NativeOccupiedWidth / SignalDispersion).
• plot_peak_track(): show_effective_width replaced by show_native_occupancy (NativeOccupiedWidth band).
• plot_peak_portrait(): features default to Intensity, SignalDispersion, NativeMaxPeakWidth.
• Example data (example_se) regenerated with the 5-assay structure and native peaks; validation scripts updated (01_signal_dispersion_validation.R, 02_breadth_super_validation.R).

Changes in version 0.99.0 (2026-08-08)

Pre-submission release for Bioconductor. Complete refocus of the package from the legacy "4D Shape Shift / MANOVA" framework to a BigWig-first super-domain profiling framework.

Algorithm & science

• P0-1: negative_policy is now applied once via .sanitize_signal() BEFORE any feature is computed; clip_zero actually clips negatives (Intensity, RobustHeight, EffectiveWidth, custom features all share the sanitized vector). NA positions are treated as 0 to preserve the genomic coordinate axis. The negative fraction is now computed over signal positions (not domain count) and stored in colData(se)$NegativeFraction.
• P0-2: bootstrap resampling preserves the user-selected log scale. The effective transform is resolved once; log_transform=FALSE stays FALSE inside the bootstrap (previously it silently re-resolved to TRUE for Intensity). metadata records log_transform_requested and log_transform_used.
• P0-3: replicate support uses a configurable rule (support_rule = "majority" | "all" | "fraction") with a min_valid_replicates requirement. no-call replicates are never counted as Super and never inflate support (previously Super + no_call gave 100% support). n=2 majority now requires 2/2.
• P0-4: compare_superdomains() gained cutoff_scope = "relative" (default) | "reference" | "pooled". Relative transitions are reported as Relative_Prominence_Up/Down and must not be interpreted as absolute Gain/Loss; only reference/pooled common-cutoff modes report Gain/Loss.
• P0-5: Spreading (EffectiveWidth) is sensitive to low-level distributed background; added width_baseline_quantile to build_portrait_matrix() to subtract a per-profile baseline before computing the span. Simulation shows a 100 bp peak in a 1000 bp domain spans ~81 bp for background 0-2 with q10 correction vs 81-700 bp without (validation/01_signal_width_validation.R).
• Added min_quality argument to call_super_domains() (previously implicit).
• Removed legacy MANOVA and Shape Shift modules: test_global_shape_shift(), test_shape_shift(), test_differential_feature(), classify_shape_shift(), detect_conformational_outliers(), simulate_power(), plot_power_curve(), and their dependent visualization/export/report functions.
• Removed the Skewness assay from build_portrait_matrix() (was signal-value skewness, not genomic spatial directionality). Portrait now produces Intensity, RobustHeight, and Spreading.
• Added Spreading (per-sample effective signal span = central 80% signal-mass span) as a core assay, aliased as EffectiveWidth / Central80Width.
• Moved the static genomic interval length out of the assays into rowData(se)$IntervalWidth (alias "Width").
• Height is now RobustHeight (95th percentile of the signal profile), robust to single-bin spikes.
• Added find_hockey_inflection() with two inflection heuristics:
  • "elbow" (default): maximum perpendicular distance on [0,1]-normalized coordinates; dimensionless and scale-invariant.
  • "tangent": tangent-optimization cutoff ported from the ROSE algorithm (Whyte et al., 2013, Cell 153:307-319).
• Added log_transform argument to call_super_domains(): NULL (auto), TRUE, or FALSE (rank on raw scale for ROSE-style comparison).
• Added combine_superdomain_calls() for the Intensity-Super / Width-Super / Dual-Super / Typical / Uncertain taxonomy. Default width feature is now EffectiveWidth (dynamic breadth), not static interval length.
• call_super_domains() now stores full call provenance in metadata(se)$superdomain_calls (cutoff, cutoff_CI, quality, status, ...).
• Consensus mode is condition-aware: replicate support is stratified by group. per_group mode is replicate-aware (per-replicate calls + group support) rather than a single group-mean ranking.
• normalize_portrait() now defaults to method = "None"; TotalSignal and Quantile emit warnings that they may remove genuine global biological shifts.
• build_portrait_matrix() gained negative_policy ("error" | "clip_zero" | "allow") and fail_action ("stop" | "drop") arguments.
• Added check_signal_compatibility() for pre-analysis BigWig QC.
• build_portrait_matrix() now imports BigWig coverage in region batches (memory-bounded for mammalian-scale domains).
• Cache keys include full path + size + mtime to avoid collisions and stale reads.
• Rewrote vignette and README around the super-domain workflow.
• Updated example_se dataset (Spreading assay, RobustHeight, IntervalWidth).

Bioconductor packaging

• Version bumped to 0.99.0 for first submission.
• Removed LazyData; removed unused Suggests; added TxDb and rmarkdown Suggests; unified maintainer metadata via Authors@R.
• R CMD check passes with 0 errors / 0 warnings / 0 notes (including --run-donttest).

Changes in version 0.1.0 (2026-05-12)

Initial Release

• Added build_portrait_matrix() core engine for 4D geometric feature extraction (Width, Intensity, Height, Skewness) from BigWig coverage with BiocParallel support, HDF5 on-disk storage option, and per-BigWig caching.
• Added get_consensus_peaks() and stitch_epi_peaks() for consensus peak calling and macro-domain stitching.
• Added call_super_domains() for ROSE-style single-dimension super-element / broad-domain / steep-peak identification.
• Added normalize_portrait() with TotalSignal, Quantile, and TMM methods. (A row-wise Z-score method was prototyped but removed before release: it is a display/clustering transform that would destroy the cross-domain magnitude ranking used by Super calling.)
• Added visualization suite: plot_peak_portrait(), plot_peak_track(), plot_hockey_stick(), plot_portrait_pca(), plot_portrait_correlation().
• Added annotate_epi_peaks() for ChIPseeker-based gene mapping with lazy TxDb loading for hg38, hg19, and mm10.
• Added filter_promoter_peaks() for promoter-proximal peak exclusion.