NEWS

---

HiCPotts 1.3.1 (2026-09-06)

• Parameter documentation and diagnostic messages describe individual criteria and thresholds. The fitted model and diagnostic calculations are unchanged.
• The function reference now runs a small worked analysis during vignette builds and includes session information. Argument descriptions are formatted for readability in both source and rendered documentation.
• No model changes: the three-component likelihood, Potts formulation, posterior target and official classification rule are unchanged.
• Faster computation: cached native likelihood evaluations, direct checkerboard allocation updates, shared ABC calibration and optional parallel execution of independent chains.
• Regression proposals now retain the tuned QR-whitened random-walk kernel through burn-in and report ordinary beta acceptance separately from label swaps, preventing a rejected replacement proposal from freezing a chain.
• Robust empirical-Bayes fitting now uses a short multi-chain pilot to build one shared frozen prior for all production chains, so split-R-hat compares chains with the same posterior target.
• diagnose_hicpotts_fit() no longer returns an overall verdict. The allocation_reliable, parameter_reliable, gamma_reliable, reliable and reliability_by_domain fields are removed: one flag collapsed twelve independent criteria into a single word, so a marginal result on any one gate read as a blanket failure. reliability_flags, holding one row per gate with its threshold, is the reported result.
• summarise_hicpotts_parameters() now judges the estimates it is about to report instead of requiring every gate to pass. require_reliable = TRUE rejects a summary only when a precondition leaves the estimates ill-defined -- chains on different posterior targets, an unmoved regression block, unaligned components, mixed coefficient scales or ill-conditioned covariates -- or when a reported parameter falls short of the requested effective sample size or exceeds the R-hat tolerance. Gamma near a boundary, low occupancy and fewer chains than recommended no longer block the table; they remain visible in reliability_flags. The returned table gains a resolved column marking which rows met the criteria.
• diagnose_hicpotts_fit() now reports classification_entropy for every fit. It previously stayed NA unless prob_result was supplied; the sampler's own pooled latent-state frequencies are used when it is not.
• Poisson and NB fits are no longer rejected by the effective sample size and split R-hat gates. theta was monitored even for families without zero inflation, where it is carried at its starting value and never updated, so its non-finite ESS and R-hat failed both gates however well the chains had converged. theta is now monitored only for ZIP and ZINB, as size already was.
• get_data() reads .cool and .h5 contact matrices substantially faster. Bin coordinates are now attached by index, and pixels are restricted to the requested chromosome before the join, instead of merging the whole pixel table twice. The returned data frame is unchanged.
• process_data() gains a mirror argument. Hi-C contact maps are symmetric, so a half matrix holding one triangle can be completed by reflection rather than zero padding, which would invent roughly as many observations as were supplied. The block-size error now also recognises a triangular row count and names the lattice dimension implied by the distinct bins, instead of only reporting a failed modulus.
• combine_hicpotts_blocks() now creates a reusable block-aware fit. Each submatrix keeps the chains selected by its own mode screen; downstream classification, parameter summaries, diagnostics and posterior-predictive checks run per block without pooling unrelated MCMC draws. Cell-level output gains block and global indices. A single fit passes through unchanged.
• summarise_hicpotts_parameters() can now produce an optional descriptive posterior summary across independently fitted blocks. Regression and dispersion draws use posterior expected component occupancy weights, while gamma and theta use analysed-cell weights. Empirical credible intervals, between-block heterogeneity, contributing blocks and exclusions are reported; the result is explicitly distinguished from a joint shared-parameter fit.
• Code improvements: clearer organisation, stricter input validation and reproducible cross-platform random number streams.
• plot_upper_prob_lower_count() now retains the intended reversed genomic y-axis without replacing it with a second scale.
• plot_upper_prob_lower_count() gains a symmetric_matrix argument. Symmetric full matrices are checked for equal mirrored counts, triangular inputs are reflected, and ordered matrices can be plotted without combining directions.
• Shared-prior progress output now distinguishes the short pilot length from the user-requested production iterations.
• Likelihood-informed initialisation now skips a numerically unstable candidate partition, and starting allocations are prepared before parallel dispatch so serial and Windows PSOCK runs use the same deterministic initialisation path.
• New exported functions: classify_hicpotts(), summarise_hicpotts_parameters(), allocation_diagnostics(), posterior_predictive_hicpotts() and diagnose_hicpotts_fit().
• Simplified interface: fitting is consolidated in run_chain_betas(); low-level sampler, validation and simulation helpers are now internal.
• run_chain_betas() now exposes the controls users need for chain initialisation, progress reporting, MCSE stopping, ABC workload, gamma-update frequency, gamma-prior sensitivity and robust diagnostic thresholds. The component-defining priors and low-level reversible-move settings remain internal, and all fitting defaults are unchanged.
• The gamma starting value is now named gamma_start. The previous gamma_prior argument remains as a deprecated compatibility alias. The actual Beta prior is controlled separately by gamma_prior_shape.
• abc_potts_sweeps, abc_sim_reps and gamma_update_interval expose the main ABC computation controls. The default sweep count grows with N^2, so the ABC step scales as N^4; users can deliberately trade auxiliary-simulation effort for speed without changing the package defaults.
• The sampler no longer warns per chain about low component occupancy. The counts are still returned on the allocation field and are checked by the occupancy gate in diagnose_hicpotts_fit().
• The default minimum-component occupancy threshold is now zero. Empty components are permitted by the reliability gate, while their observed and posterior-expected occupancy counts remain available in diagnostics.
• Fitted objects now carry provenance, chain settings, stage timings and reliability metadata.
• Documentation updates: runnable examples for all exported functions, a new vignette section on checking a fit before reporting parameters, and a full description of every reliability gate on diagnose_hicpotts_fit(). Internal functions that appear in an exported signature or in help-page prose are now explained where users meet them, including the canonical component definition used as a default by classify_hicpotts() and compute_HMRFHiC_probabilities(), and how covariate_diagnostics is obtained.
• Roxygen markdown is enabled, so inline code in the help pages now renders as code rather than showing literal backticks.