Changes in version 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.
