dfbayes 0.1.0__tar.gz

dfbayes-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# Upstream R sources are read-only inputs, not part of the port
+upstream/
+
+# R / fixture scratch
+.Rlib/
+Rplots.pdf
+tests/fixtures/*.tmp

dfbayes-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

dfbayes-0.1.0/AUTHORS

@@ -0,0 +1,16 @@
+Upstream DFBA
+=============
+
+Daniel H. Barch <daniel.barch@tufts.edu>
+Richard A. Chechile <richard.chechile@tufts.edu>
+Tufts University
+
+CRAN package DFBA 0.1.0, published 2023-12-13:
+https://CRAN.R-project.org/package=DFBA
+
+Python port
+===========
+
+dfbayes contributors
+
+See NOTICE for provenance and licence details.

dfbayes-0.1.0/COVERAGE.md

@@ -0,0 +1,220 @@
+# Coverage map — R source branch to test
+
+Fixture case names refer to `tests/fixtures/fixtures.json`; stochastic case
+names refer to `tests/fixtures/stochastic.json`. The deterministic suite runs
+every fixture in `tests/test_deterministic.py`; the stochastic suite is
+`tests/test_stochastic.py`; Phase 2 model/power behaviour is in
+`tests/test_simulation.py`.
+
+`upstream/` is read-only. Expected values are produced by running R DFBA 0.1.0,
+never by hand.
+
+## `dfba_binomial` (`dfba_binomial.R`)
+
+| R branch | Tests |
+| --- | --- |
+| default uniform prior | `binomial_default`, `binomial_zero_zero` |
+| non-default prior (`a0`, `b0`) | `binomial_prior_2_3`, `binomial_jeffreys_99` |
+| `prob_interval` 0.5 / 0.99 / 0.999 | `binomial_half_interval`, `binomial_jeffreys_99`, `binomial_interval_999` |
+| all successes / all failures | `binomial_all_success`, `binomial_all_fail` |
+| large counts | `binomial_large` |
+| negative / non-integer counts | `binomial_err_n1_neg`, `binomial_err_n2_neg`, `binomial_err_n1_nonint`, `binomial_err_n2_nonint` |
+| non-positive / infinite / NA prior | `binomial_err_a0_zero`, `binomial_err_b0_zero`, `binomial_err_a0_inf`, `binomial_err_b0_inf`, `binomial_err_a0_na`, `binomial_err_b0_na` |
+| NA counts | `binomial_err_n1_na`, `binomial_err_n2_na` |
+| `prob_interval` at 0 / 1 / NA | `binomial_err_pi_zero`, `binomial_err_pi_one`, `binomial_err_pi_na` |
+
+## `dfba_beta_descriptive` (`dfba_beta_descriptive.R`)
+
+| R branch | Tests |
+| --- | --- |
+| regular mode/HDI | `bd_38_55`, `bd_38_55_90`, `bd_38_55_99`, `bd_large` |
+| mode undefined (`a==1 & b==1`, or both ≤ 1) | `bd_1_1`, `bd_2_2`, `bd_1_2` |
+| mode defined with one shape ≤ 1 | `bd_half_2`, `bd_2_half` |
+| `prob_interval` 0.5 | `bd_interval_half` |
+| non-positive / infinite / NA shape | `bd_err_a_zero`, `bd_err_b_zero`, `bd_err_a_inf`, `bd_err_b_inf`, `bd_err_a_na`, `bd_err_b_na` |
+| `prob_interval` < 0 / > 1 / NA | `bd_err_pi_neg`, `bd_err_pi_gt1`, `bd_err_pi_na` |
+
+## `dfba_beta_bayes_factor` (`dfba_beta_bayes_factor.R`)
+
+| R branch | Tests |
+| --- | --- |
+| interval H0 | `bf_interval`, `bf_interval_narrow`, `bf_interval_jeffreys`, `bf_interval_full` |
+| point H0 | `bf_point`, `bf_point_jeffreys`, `bf_point_zero`, `bf_point_one` |
+| point density 0 → `BF10=NaN` / `BF01=Inf` | `bf_point_zero`, `bf_point_one` |
+| interval H0 = (0,1) → `BF10=NaN` / `BF01=Inf` | `bf_interval_full` |
+| bad method | `bf_err_method` |
+| point H0 length / out of range | `bf_err_point_len2`, `bf_err_point_gt1`, `bf_err_point_neg` |
+| interval H0 length / range / order | `bf_err_interval_len1`, `bf_err_interval_gt1`, `bf_err_interval_order` |
+| prior validation and posterior below prior | `bf_err_a0_zero`, `bf_err_a_post_lt_a0`, `bf_err_b_post_lt_b0`, `bf_err_a_post_na` |
+
+## `dfba_sign_test` (`dfba_sign_test.R`)
+
+| R branch | Tests |
+| --- | --- |
+| positive/negative sign counts | `sign_default`, `sign_jeffreys_99` |
+| zero differences removed | `sign_with_zeros`, `sign_three_pairs` |
+| pairwise NA removal | `sign_with_na`, `sign_nan` |
+| `prob_interval=0` | `sign_pi_zero` |
+| BF always uses the uniform prior (upstream bug) | `sign_jeffreys_99` |
+| length mismatch / too few / all trivial | `sign_err_length`, `sign_err_too_few`, `sign_err_all_zero` |
+| NA prior / invalid interval | `sign_err_a0_na`, `sign_err_b0_na`, `sign_err_pi_neg`, `sign_err_pi_gt1`, `sign_err_pi_na` |
+
+## `dfba_median_test` (`dfba_median_test.R`)
+
+| R branch | Tests |
+| --- | --- |
+| E > C and C > E counts | `med_example`, `med_jeffreys` |
+| ties | `med_ties`, `med_all_equal` |
+| independent NA removal | `med_na` |
+| one/both vectors empty | `med_one_empty`, `med_both_empty` |
+| invalid prior | `med_err_a0_na`, `med_err_b0_na`, `med_err_a0_zero`, `med_err_b0_inf` |
+
+## `dfba_gamma` (`dfba_gamma.R`)
+
+| R branch | Tests |
+| --- | --- |
+| matrix/table input | `gamma_example`, `gamma_table`, `gamma_2x2` |
+| zero cells | `gamma_zeros` |
+| 1×1, 1×N, N×1 | `gamma_1x1`, `gamma_1xN`, `gamma_Nx1` |
+| NA cell → `invalid 'times' argument` | `gamma_na` |
+| non-matrix input | `gamma_not_matrix` |
+| invalid prior / interval | `gamma_err_a0_na`, `gamma_err_b0_zero`, `gamma_err_pi_99` |
+
+## `dfba_mcnemar` (`dfba_mcnemar.R`)
+
+| R branch | Tests |
+| --- | --- |
+| `n_01 > n_10`, `n_10 > n_01` | `mc_default`, `mc_all_01`, `mc_all_10` |
+| both zero | `mc_zero_zero` |
+| large counts and cancellation | `mc_large` |
+| Jeffreys prior / 99% interval | `mc_jeffreys_99` |
+| negative / non-integer / NA counts | `mc_err_neg`, `mc_err_nonint`, `mc_err_na` |
+| invalid prior / interval | `mc_err_a0_na`, `mc_err_pi_zero`, `mc_err_pi_one`, `mc_err_pi_na` |
+
+## `dfba_bivariate_concordance` (`dfba_bivariate_concordance.R`)
+
+| R branch | Tests |
+| --- | --- |
+| `nc`, `nd`, `tau` from concordant/discordant pairs | `bc_example`, `bc_jeffreys`, `bc_pi_99` |
+| tied pairs removed from `nc`/`nd` | `bc_ties_doc` |
+| all equal / empty / single pair / two pairs | `bc_all_equal`, `bc_empty`, `bc_single_pair`, `bc_two_pairs` |
+| pairwise NA row removal warning | `bc_na_rows` |
+| NA `prob_interval` propagates | `bc_pi_na` |
+| `fitting_parameters` 0 / 2 / 3 / NA | `bc_star_0`, `bc_star_2`, `bc_star_3`, `bc_star_na` |
+| invalid prior / unequal lengths | `bc_err_a0_na`, `bc_err_b0_zero`, `bc_err_length` |
+
+The star class has R's duplicated `prob_interval` slot; see `DECISION.md`.
+
+## `dfba_mann_whitney` (`dfba_mann_whitney.R`)
+
+| R branch | Tests |
+| --- | --- |
+| `method=NULL`, `nH >= 20` → large | `mw_large_example`, `test_method_none_selects_at_the_nH_20_boundary[20-20-large]` |
+| `method=NULL`, `nH < 20` → small | `test_method_none_selects_at_the_nH_20_boundary[19-21-small]`; forced small `mw_small_branch_*` |
+| explicit `method="large"` | `mw_large_forced_small_data`, `mw_large_forced_19` |
+| explicit `method="small"` | `mw_small_branch_a`, `mw_small_branch_b` (stochastic) |
+| large branch `xs >= .5` | `mw_large_example`, `mw_large_jeffreys`, `mw_large_99` |
+| large branch `xs < .5` (swap a/b) | `mw_large_reversed` |
+| `nH` exactly at the 20 boundary | `mw_large_nH_boundary` |
+| independent NA cell removal + messages | `mw_large_na` |
+| all values equal → `missing value where TRUE/FALSE needed` | `mw_large_all_equal` |
+| small branch A (`length(E)*length(C) > Ntot`) | `mw_small_branch_a` (stochastic, frozen `fomega`) |
+| small branch B (`length(E)*length(C) <= Ntot`) | `mw_small_branch_b` (stochastic, frozen `fomega`) |
+| `samples < 10000` message → warning | `mw_large_low_samples` |
+| invalid prior / interval / method | `mw_err_a0_na`, `mw_err_b0_zero`, `mw_err_pi_neg`, `mw_err_pi_gt1`, `mw_err_pi_na`, `mw_err_method` |
+| empty E / C | `mw_err_empty_e`, `mw_err_empty_c` |
+| analytic null at `omega=0.5` (branch A and B) | `test_mw_fomega_matches_null_branch_a/b` |
+| sampler determinism | `test_mw_sampler_is_deterministic` |
+| public wrapper shape/range | `test_mw_small_public_wrapper` |
+
+## `dfba_wilcoxon` (`dfba_wilcoxon.R`)
+
+| R branch | Tests |
+| --- | --- |
+| `method=NULL`, `n > 24` → large | `wil_large_example` |
+| explicit `method="large"` | `wil_large_forced_small` |
+| explicit `method="small"` | `wil_small` (stochastic, frozen `fphi`) |
+| ties get average ranks | `wil_large_ties` |
+| zero/trivial differences removed | `wil_large_zero_diffs` |
+| pairwise NA removal | `wil_large_na` |
+| Jeffreys prior / 99% interval | `wil_large_jeffreys`, `wil_large_99` |
+| `samples < 10000` message → warning | `wil_large_low_samples` |
+| length mismatch / too few / all trivial | `wil_err_length`, `wil_err_too_few`, `wil_err_all_equal` |
+| invalid prior / interval / method | `wil_err_a0_na`, `wil_err_b0_zero`, `wil_err_pi_neg`, `wil_err_pi_gt1`, `wil_err_pi_na`, `wil_err_method` |
+| analytic null at `phi=0.5` (Poisson binomial) | `test_wilcoxon_fphi_matches_poisson_binomial_null` |
+| sampler determinism | `test_wilcoxon_sampler_is_deterministic` |
+| average tie ranks used by `tpos`/`tneg` | `test_average_ranks_matches_scipy_including_ties` |
+| public wrapper shape/range | `test_wilcoxon_small_public_wrapper` |
+
+## `dfba_beta_contrast` (`dfba_beta_contrast.R`)
+
+| R branch | Tests |
+| --- | --- |
+| two conditions, `delta`/`delta0` frozen | `beta_contrast_2` (stochastic) |
+| four conditions / orthogonal contrast | `beta_contrast_4` (stochastic) |
+| `prH1==1 | priorprH1==0` shortcut | `_finish_beta_contrast` unit path; public smoke |
+| `samples < 10000` / NA samples | `bcon_err_samples_low`, `bcon_err_samples_na` |
+| vector length mismatch | `bcon_err_length` |
+| non-integer / NA / negative counts | `bcon_err_n1_nonint`, `bcon_err_n1_na`, `bcon_err_n2_neg` |
+| invalid prior | `bcon_err_a0_zero`, `bcon_err_a0_inf`, `bcon_err_a0_na`, `bcon_err_b0_na` |
+| positive/negative contrast sums | `bcon_err_contrast_pos`, `bcon_err_contrast_neg` |
+| NA contrast / invalid interval | `bcon_err_contrast_na`, `bcon_err_pi_neg`, `bcon_err_pi_na` |
+| `a0_vec`/`b0_vec` length-1 broadcast (documented divergence) | public wrapper + `DECISION.md` |
+| sampler determinism | `test_beta_contrast_sampler_is_deterministic` |
+| public wrapper shape/range | `test_beta_contrast_public_wrapper` |
+
+## `dfba_sim_data` (`dfba_sim_data.R`)
+
+| R branch | Tests |
+| --- | --- |
+| negative delta | `sim_err_delta_neg` |
+| `n < 20` / non-integer | `sim_err_n_lt20`, `sim_err_n_nonint` |
+| invalid model / design | `sim_err_model`, `sim_err_design` |
+| negative block effect | `sim_err_block_neg` |
+| invalid prior | `sim_err_a0_zero` |
+| model shape validation | `sim_err_shape_normal`, `sim_err_shape_pareto` |
+| independent summary (t + Mann-Whitney) against frozen R E/C | `sim_frozen_independent` |
+| paired summary (t + Wilcoxon) against frozen R E/C | `sim_frozen_paired` |
+| nine model parameterisations | `test_model_means`, `test_cauchy_scale_and_location`, `test_pareto_support_and_median` |
+| paired block effect cancels in differences | `test_sim_data_paired_block_effect_cancels_in_differences` |
+| independent block effects change both conditions | `test_sim_data_independent_block_effect_changes_values` |
+| `block_max=0` does not consume RNG state (R's `runif(n,0,0)` behaviour) | `test_zero_block_max_does_not_advance_the_generator` |
+| pinned-seed reproducibility | `test_sim_data_is_reproducible_with_a_seed` |
+| output shape, design, ranges | `test_sim_data_returns_both_conditions` |
+
+## `dfba_power_curve` (`dfba_power_curve.R`)
+
+| R branch | Tests |
+| --- | --- |
+| negative `delta_step` | `power_err_delta_step_neg` |
+| `n < 20` | `power_err_n_lt20` |
+| invalid model / design / effect criterion / prior / block | `power_err_model`, `power_err_design`, `power_err_effect_crit`, `power_err_a0_zero`, `power_err_block_neg` |
+| 21-point delta grid and 21 power rows | `test_power_curve_structure_and_reproducibility` |
+| `n` rounded like R | `test_power_curve_rounds_n_like_r` |
+| `samples` errors for NA/NaN/Inf/negative | `test_samples_rejected_where_r_also_errors` |
+| `samples` rounding to zero (deliberate divergence) | `test_samples_rounding_to_zero_are_rejected_divergence` |
+| `samples` rounded like R | `test_samples_are_rounded_like_r` |
+| pinned-seed reproducibility | `test_power_curve_structure_and_reproducibility` |
+| summary fast path equals full analysis | `test_summary_fast_path_matches_full_analysis` |
+| power loop shares the draw path with `dfba_sim_data` | `test_power_loop_uses_the_public_draw_path` |
+| output table and pandas export | `test_output_table_is_pandas_friendly`, `test_power_result_helpers_and_batch_dataframe` |
+| plotting | `test_power_curve_plot` |
+
+## `dfba_bayes_vs_t_power` (`dfba_bayes_vs_t_power.R`)
+
+| R branch | Tests |
+| --- | --- |
+| negative delta | `bvt_err_delta_neg` |
+| `n_min < 20` / non-integer | `bvt_err_n_min_lt20`, `bvt_err_n_min_nonint` |
+| invalid prior / model / design / effect criterion | `bvt_err_a0_zero`, `bvt_err_model`, `bvt_err_design`, `bvt_err_effect_crit` |
+| 11 sample sizes from `n_min` to `n_min+50` | `test_bayes_vs_t_power_structure_and_reproducibility`, `test_bayes_vs_t_power_sample_size_grid_respects_n_min` |
+| `samples` validation (shared `_check_nsims`) | `test_samples_rejected_where_r_also_errors`, `test_samples_rounding_to_zero_are_rejected_divergence`, `test_samples_are_rounded_like_r` |
+| pinned-seed reproducibility | `test_bayes_vs_t_power_structure_and_reproducibility` |
+| plotting | `test_bayes_vs_t_power_plot` |
+
+## `methods-*.R`
+
+| R source | Coverage |
+| --- | --- |
+| `show` methods | `summary()`/`str()` field order in `tests/test_results.py` |
+| `plot` methods | Python-native `result.plot()` dispatch in `tests/test_plotting.py`; not byte-compatible with R base graphics |

dfbayes-0.1.0/DECISION.md

@@ -0,0 +1,298 @@
+# Decision record — `dfbayes`
+
+## Upstream pin
+
+- Package: **DFBA**
+- Version: **0.1.0**
+- CRAN publication: 2023-12-13
+- Tarball: `upstream/DFBA_0.1.0.tar.gz` (vendored read-only)
+- Installed from source with `R CMD INSTALL`; R 4.6.1 at `/usr/bin/R`.
+- Upstream licence: **GPL-2** (no `LICENSE` file). This port is
+  **GPL-2.0-only**.
+
+`testthat` is not installed in the fixture environment; the fixture generator
+uses base R plus `jsonlite` and does not require `testthat`. The upstream
+`tests/testthat/` suite was read as a behavioural oracle, but our fixtures come
+from calling the installed R functions directly.
+
+## Distribution and import name
+
+`dfba` on PyPI is an unrelated dynamic-flux-balance package. This port is
+distributed and imported as **`dfbayes`**. `dfbayes` returned 404 on PyPI when
+checked on 2026-10-31.
+
+## Target language: pure Python + numpy
+
+Confirmed. No Rust, no PyO3, no compiled extension. The reasons are:
+
+1. Upstream has no compiled code at all (`NeedsCompilation: no`), so there is
+   no kernel to translate and no performance gap to close.
+2. The compute that does exist is Monte Carlo, which vectorises. Rust would buy
+   a constant factor at best, not an order of magnitude.
+3. The API returns 18 S4 list-subclass result objects with 15–20 fields each.
+   An FFI boundary would marshal a 20-field struct per call for functions whose
+   actual compute is microseconds. Net negative.
+4. Pure Python ships as a single `py3-none-any` wheel. `mixtime`'s
+   `DECISION.md` documents the maturin/abi3/universal2 cost we would otherwise
+   repeat.
+
+Note: "no quadrature/optimisation" is true but is *not* the reason Python wins.
+The heavy paths are Monte Carlo:
+
+- `dfba_mann_whitney(method="small")`: 200-point omega grid × `samples`
+  replications, each drawing `rexp(n_E)` and `rexp(n_C)` and doing an
+  `n_E × n_C` comparison loop.
+- `dfba_wilcoxon(method="small")`: same structure.
+- `dfba_beta_contrast`: `samples` × K individual `rbeta(1, ...)` draws.
+- `dfba_power_curve` / `dfba_bayes_vs_t_power`: 21 × `nsims` full simulations.
+
+The R original makes roughly 12 million R-level `rexp()` calls in the
+Mann-Whitney small path. The port draws the whole replication batch at once and
+uses broadcasting for the comparison matrix; it does not transliterate the
+loops line-for-line.
+
+## NA policy
+
+R distinguishes logical `NA` (structural) from `NA_real_` (propagated), and
+`is.na()` is TRUE for both `NA` and `NaN`.
+
+- **Inputs:** `None` and `NaN` are both treated as missing, matching `is.na()`.
+  Scalar validation mirrors R's `if (...)` branches and raises `ValueError`.
+- **Outputs:** all output NA is **`None`**. Genuine `0/0` remains
+  `float("nan")`. This preserves the NA-vs-NaN distinction that affects
+  arithmetic, but collapses R's logical-vs-double NA distinction; Python has no
+  typed NA. `dfbayes.is_na()` treats `None` and `NaN` as missing.
+- **Deletion semantics are per function** (see `AGENTS.md`):
+  pairwise/listwise drop for `dfba_sign_test`, `dfba_wilcoxon`, and
+  `dfba_bivariate_concordance`; independent per-vector drop for
+  `dfba_median_test` and `dfba_mann_whitney`.
+- `dfba_bivariate_concordance(prob_interval=NA)` is not validated by R; the
+  interval fields become NA. The port returns `None` there.
+- `dfba_gamma` with an NA cell raises, because R's `rep(..., times=NA)`
+  raises `invalid 'times' argument`. The port mirrors that error.
+
+## RNG policy: (a) freeze the narrowest intermediate
+
+R's `rexp()` uses inversion from `unif_rand()`; `rbeta()` uses a different
+algorithm again. Bit-exact reproduction is a multi-day subproject and buys
+nothing: R's own small-sample output already varies with `samples`, so
+cross-language `set.seed()` reproducibility is not a property users rely on.
+
+Policy:
+
+- `dfba_mann_whitney(method="small")` → freeze `fomega` (length-200 counts).
+- `dfba_wilcoxon(method="small")` → freeze `fphi` (length-200 counts).
+- `dfba_beta_contrast` → freeze `delta` and `delta0`.
+- `dfba_power_curve` / `dfba_bayes_vs_t_power` → the simulation loop is
+  implemented directly; its aggregation is checked structurally (21 or 11
+  grid points, proportions in [0,1], exact grid spacing), and the per-dataset
+  summary is replayed against a frozen R E/C pair. Numeric power values are
+  not fixture-pinned because they depend on the RNG.
+- `dfba_sim_data` → each of the nine models is checked against its analytic
+  mean/median or support under a pinned numpy seed. The t-test and large-sample
+  posterior are replayed exactly against R for a frozen E/C pair.
+- The sampling wrappers use numpy. They are **not** claimed to match R, and the
+  package does not ship or depend on an R RNG emulator.
+  Two tests per stochastic function: (1) analytic-vs-Monte-Carlo empirical
+  probability within ~5 standard errors at the null value (`omega=0.5` uses the
+  exact Mann-Whitney U distribution; `phi=0.5` uses the Poisson binomial);
+  (2) same seed → identical output, different seed → different output.
+- `dfba_beta_contrast` uses R's `quantile()` default type 7;
+  `numpy.percentile` matches it.
+
+Pinned seeds are recorded with each fixture case in
+`tests/fixtures/stochastic.json`:
+
+| case | seed | frozen intermediate |
+| --- | ---: | --- |
+| `beta_contrast_2` | 20261030 | `delta`, `delta0` (10000 each) |
+| `beta_contrast_4` | 20261031 | `delta`, `delta0` (10000 each) |
+| `mw_small_branch_a` | 20261032 | `fomega` (200 bins) |
+| `mw_small_branch_b` | 20261033 | `fomega` (200 bins) |
+| `wil_small` | 20261034 | `fphi` (200 bins) |
+
+The two Mann-Whitney cases sit on opposite sides of R's branch test
+`length(E)*length(C) > UE + UC`:
+
+- branch A: `E = C = c(1,1,2,2)` → 16 comparisons, `Ntot = 8`;
+- branch B: `E = c(2,4,6)`, `C = c(1,3,5,7,9)` → 15 comparisons,
+  `Ntot = 15`.
+
+Branch A counts only the first `Ntot` row-major comparisons; branch B counts
+all of them. Both are preserved and replay-tested against the frozen `fomega`.
+
+## Phase 2 simulation models
+
+`dfba_sim_data` draws with numpy's `Generator`; R's `set.seed()` state is not
+reproduced. Each model uses R's parameterisation:
+
+| model | C draw | E draw |
+| --- | --- | --- |
+| `normal` | `N(0, shape1)` | `N(delta, shape2)` |
+| `weibull` | `Weibull(shape1, 1)` | `delta + Weibull(shape2, 1)` |
+| `cauchy` | `Cauchy(0, shape1)` | `Cauchy(delta, shape2)` |
+| `lognormal` | `LogNormal(0, shape1)` | `LogNormal(delta, shape2)` |
+| `chisquare` | `chi2(shape1)` | `delta + chi2(shape2)` |
+| `logistic` | `Logistic(0, shape1)` | `Logistic(delta, shape2)` |
+| `exponential` | `Exp(rate = shape1)` | `delta + Exp(rate = shape2)` |
+| `gumbel` | inverse transform on `U in [1e-5, 1-1e-5]` | same, offset by `delta` |
+| `pareto` | inverse transform, `xm=1`, `alpha=1.16*shape1` | inverse transform, `xm=1+delta`, `alpha=1.16*shape2` |
+
+The block effect is `U(0, block_max)`. Paired designs add the same block to
+both conditions; independent designs add separate blocks. The one-tailed
+p-value uses Student's t with `2n-2` degrees of freedom (independent) or `n-1`
+(paired). The Bayesian probability is the `prH1` from the large-sample
+Mann-Whitney or Wilcoxon branch, matching R.
+
+`dfba_power_curve` evaluates 21 deltas from 0 to `20*delta_step`;
+`dfba_bayes_vs_t_power` evaluates 11 sample sizes from `n_min` to `n_min+50` in
+steps of five. Both accept an optional numpy `Generator` via `rng`, which is a
+Python extension.
+
+## Tolerances
+
+`pbeta`/`qbeta` are TOMS 708 in R and Boost in scipy. Agreement is expected
+around 1e-12, not bit-identical. Tolerances are derived from the fixtures by
+measuring the observed relative/absolute difference, then rounded up to a
+documented bound. They are never loosened to make a test pass; a larger
+difference is a port bug or a documented divergence.
+
+The suite default is `rtol=1e-11, atol=1e-12`. Observed maxima outside the
+Mann-Whitney large branch are below `3e-12` relative, driven by the final
+`pbeta`/`qbeta` calls. Two exceptions are documented and handled explicitly in
+`tests/_support.py`:
+
+- `mw_large*` `BF10`: `rtol=1e-9`. R's large-branch polynomial is evaluated by
+  subtracting O(1e3) terms to leave an O(1e-2) result, and `BF10` is then a
+  ratio of two beta tails. The observed maximum relative difference is
+  `2.40e-11`, so `1e-9` is a conservative bound, not a license to drift.
+- `mc_large` `BF10interval`/`postH1`: the relative difference is `7.4e-8`
+  because the value itself is `2.99e-9`, formed by cancellation. The absolute
+  difference is about `2.2e-16`, well inside the shared `atol=1e-12`; no
+  field-specific `rtol` is needed.
+
+R's `^` on doubles is repeated multiplication, not libm `pow`; the port uses
+`r_pow()` where R's one-ulp behaviour is observable (`mann_whitney` polynomial
+and `beta` variance).
+
+## Documented divergences and deliberate choices
+
+These are intentional and covered by tests; none changes a deterministic
+numeric result.
+
+1. **Progress output.** R's small-sample functions emit `\r...% complete` via
+   `message()` unless `hide_progress=TRUE`. The port emits no progress output by
+   default and has no `\r` rewriting. This is display-only.
+2. **R `message()` → Python `UserWarning`.** Sample-size advice and the
+   NA-cell notes become `UserWarning`s, preserving the text. `dfba_beta_contrast`
+   raises `ValueError` for `samples < 10000` exactly as R stops; NA `samples`
+   raises `missing value where TRUE/FALSE needed`.
+3. **`a0_vec`/`b0_vec` recycling in `dfba_beta_contrast`.** R silently recycles
+   mismatched lengths through vector arithmetic. The port broadcasts length 1
+   and rejects other mismatched lengths with `ValueError` rather than silently
+   recycling.
+4. **Star concordance duplicate field.** R's `dfba_bivariate_concordance_out`
+   with `fitting_parameters` has two `prob_interval` slots. The dataclass has
+   one field; `R_FIELDS` records the duplicate so `summary()` can reproduce R's
+   field order.
+5. **Logical NA.** `dfba_beta_descriptive` returns logical `NA` for an
+   undefined mode/HDI. Python has no typed NA, so these are `None`; see the NA
+   policy above.
+6. **`dfba_sign_test` Bayes factor prior.** Upstream computes the BF with the
+   default uniform prior even when the caller sets `a0`/`b0`. The port
+   reproduces that bug; the posterior interval still uses the caller's prior.
+7. **`dfba_gamma` matrix expansion.** R expands a table/matrix row-major
+   (`x` = row, `y` = column) and uses `int(count)` per cell. Python accepts a
+   2-D array and indexes it explicitly; column-major storage is not assumed.
+8. **`plot()` and text `show()`.** The 15 R `plot()` S4 methods are not
+   ported. In their place the package offers an optional, Python-native
+   matplotlib layer (`result.plot()`) that returns an `Axes`; it is a
+   usability extension, not a reproduction of R's base-graphics output.
+   `summary()` reproduces field names/order, not R's exact `sprintf` layout.
+9. **Result helpers.** `to_dict()`, `to_json()`, `to_dataframe()`, `bf10`,
+   `credible_interval`, `posterior_mean`, `posterior_median`,
+   `probability_h1`, `interpret()`, `_repr_html_()`, and
+   `results_to_dataframe()` are additions, not R API. `to_json()` maps
+   non-finite values to `null` because JSON has no NaN or infinity.
+   `to_dataframe()` omits array slots unless `include_arrays=True`.
+10. **Phase 2 progress and RNG.** `hide_progress` is accepted but no `\r...%`
+    progress output is emitted, matching the Phase 1 policy. The simulation
+    functions accept an optional numpy `Generator` (`rng=`) for reproducibility;
+    R only offers `set.seed()`. Sampling is not bit-compatible with R.
+11. **`dfba_power_curve` result shape.** The R documentation mentions a
+    `delta_vec` slot, but the R implementation does not add one to the returned
+    list; the values live in `outputdf$delta_value`. The port follows the
+    implementation. `PowerCurveOut.delta_vec` is a Python convenience property,
+    not an R slot.
+12. **Phase 2 `samples` validation.** R computes `nsims <- round(samples)` and
+    then `rep(NA, nsims)` without validating. R 4.6.1 behaves as follows for
+    both `dfba_power_curve` and `dfba_bayes_vs_t_power`:
+
+    | `samples` input | R behaviour |
+    | --- | --- |
+    | `NA`, `NaN`, `Inf`, `-Inf` | error: `invalid 'times' argument` |
+    | `-0.6`, `-1`, any value rounding negative | error: `invalid 'times' argument` |
+    | `-0.5`, `-0.4`, `0`, `0.4`, `0.5` (rounds to 0) | returns `nsims = 0` with `NaN`/`Inf` power from a pathological `1:0` loop |
+    | `0.6` and above | accepted; uses R's banker's rounding (`0.6 -> 1`, `1.5 -> 2`, `2.5 -> 2`) |
+
+    The port matches the first two rows. It deliberately rejects the
+    rounds-to-zero row with `samples must be a positive integer` instead of
+    returning undefined `NaN`/`Inf` power. This is an intentional behaviour
+    change for inputs R "accepts", documented here rather than reproduced.
+    Fractions that round to at least one follow R. `None` is the port's NA
+    convention and raises the same `invalid 'times' argument` as `NA`.
+13. **Power-loop summary fast path.** `dfba_power_curve` and
+    `dfba_bayes_vs_t_power` only consume `pvalue` and `prH1` from each
+    simulated data set. R still calls the full analysis, which computes the
+    posterior median, equal-tailed interval and HDI for every replication. The
+    port factors the closed-form posterior parameters into helpers and exposes
+    `_wilcoxon_prh1` / `_mann_whitney_prh1`, which skip that unused interval
+    work. The public analysis functions keep their full output. A differential
+    test (`test_summary_fast_path_matches_full_analysis`) pins the fast path to
+    the public functions. Measured on the development machine at
+    `samples=1000`, `dfba_power_curve` fell from 86.6 s to 5.5 s (paired) and
+    76.2 s to 3.5 s (independent); `dfba_bayes_vs_t_power` fell from 41.9 s to
+    3.0 s and 32.6 s to 2.1 s. No fixture or tolerance was changed.
+14. **Zero-width block effect does not consume RNG state.** R's
+    `runif(n, 0, 0)` returns zeros without advancing `.Random.seed`; numpy's
+    `Generator.uniform(0, 0, n)` does advance. `dfba_sim_data` now skips the
+    block draw when `block_max == 0` (the default), so a caller-supplied
+    `Generator` moves in lockstep with what R's stream would do. The returned
+    values are unchanged because the skipped block was identically zero. This
+    is stream-position fidelity only; the port still does not claim
+    bit-compatible draws. Test: `test_zero_block_max_does_not_advance_the_generator`.
+15. **Student-t tail without the `rv_continuous` dispatch.** `_summarise`
+    computes the one-tailed p-value with `scipy.special.stdtr(df, -t)`, which
+    is exactly what `scipy.stats.t.sf(t, df)` calls internally, but without the
+    frozen-distribution argument handling. The result is bit-identical
+    (`t.sf` and `stdtr` agree exactly at every tested `t`/`df`, including
+    `±Inf` and `NaN`). At `samples=500`, `dfba_power_curve` fell from 2.43 s to
+    1.86 s (paired) and 1.54 s to 0.94 s (independent), process CPU, best of
+    three; the test suite and all fixtures are unchanged.
+16. **Average ranks without `scipy.stats.rankdata`.** The Wilcoxon signed-rank
+    statistic needs R's `rank(..., ties.method = "average")`. `_average_ranks`
+    implements it with `argsort` plus a vectorised tie collapse and a no-tie
+    fast path. It is bit-identical to `scipy.stats.rankdata(method="average")`
+    on 2,000 randomised arrays, including heavy integer ties, repeated values
+    and empty/singleton inputs. At `samples=500`, the paired power curve fell
+    from 1.86 s to 0.83 s; the independent path is unchanged. A snapshot of 120
+    large and 120 small Wilcoxon calls (with tied data), 18 power curves and 4
+    `dfba_bayes_vs_t_power` calls is byte-identical before and after.
+17. **Power loops share the draw path without re-validating.** The power
+    functions validate their constant arguments once, then call the private
+    `_simulate` helper for every replication instead of `dfba_sim_data`. It
+    performs the same draw, block effect and summary but skips repeated
+    argument checks and result-object allocation. `dfba_sim_data` delegates to
+    the same helper, so there is still a single implementation. At
+    `samples=500`, the paired power curve fell from 0.83 s to 0.60 s and the
+    independent one from 0.84 s to 0.64 s. The 240-call Wilcoxon/power/Bayes-vs-t
+    snapshot in item 16 is byte-identical. Test:
+    `test_power_loop_uses_the_public_draw_path` pins the shared path and RNG
+    stream position.
+
+## Out of scope
+
+- The 15 R `plot()` S4 methods. The Python-native plotting layer above replaces
+  them for Python users but does not reproduce R's base-graphics output.
+- `summary()`/`show()` byte-for-byte text formatting. Field names and order are
+  matched; the R `sprintf`/`cat` layout is not reproduced exactly.