easyscience 2.4.0__tar.gz → 2.5.1__tar.gz

{easyscience-2.4.0 → easyscience-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easyscience
-Version: 2.4.0
+Version: 2.5.1
 Summary: Core building blocks for EasyScience
 Project-URL: Documentation, https://easyscience.github.io/core
 Project-URL: Release Notes, https://github.com/easyscience/core/releases
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.11
 Requires-Dist: asteval
-Requires-Dist: bumps
+Requires-Dist: bumps>=1.0.4
 Requires-Dist: dfo-ls
 Requires-Dist: lmfit
 Requires-Dist: numpy

{easyscience-2.4.0 → easyscience-2.5.1}/docs/docs/tutorials/fitting-bayesian.ipynb

@@ -7,7 +7,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%matplotlib widget"
+    "%matplotlib inline"
    ]
   },
   {
@@ -28,7 +28,7 @@
     "\n",
     "where $\\theta$ are the model parameters, $d$ is the observed data, $p(d \\mid \\theta)$ is the likelihood, and $p(\\theta)$ is the prior. In `easyscience`, the `min`/`max` bounds of a `Parameter` are interpreted as a **uniform prior**, and a Gaussian likelihood is constructed from the data and supplied weights.\n",
     "\n",
-    "`easyscience` exposes a Bayesian Markov-chain Monte Carlo (MCMC) sampler through the `Fitter.mcmc_sample` method.  Under the hood this uses BUMPS' DREAM sampler, so the underlying minimizer must be switched to BUMPS.\n",
+    "`easyscience` exposes a Bayesian Markov-chain Monte Carlo (MCMC) sampler through the `Sampler` class.  Under the hood this uses BUMPS' DREAM sampler, so the underlying minimizer must be switched to BUMPS.\n",
     "\n",
     "```{note}\n",
     "This tutorial focuses on Bayesian analysis with a simple QENS model for illustration. For dedicated QENS fitting with more sophisticated models, consider using [`EasyDynamics`](https://github.com/easyscience/easydynamics).\n",
@@ -45,7 +45,7 @@
     "\n",
     "The trade-off is computational cost: MCMC requires thousands of model evaluations, whereas an MLE fit may converge in dozens. For the simple 4-parameter model used here the difference is negligible, but for expensive models it is worth starting with MLE and only switching to MCMC when you need the richer output.\n",
     "\n",
-    "In this tutorial we re-use the QENS dataset and the Lorentzian-with-resolution model from the [Fitting QENS](fitting-qens.ipynb) tutorial, but instead of returning a single best-fit value with a symmetric error bar we will draw thousands of samples from the posterior.\n"
+    "In this tutorial we re-use the QENS dataset and the Lorentzian-with-resolution model from the [Fitting QENS](fitting-qens.ipynb) tutorial, but instead of returning a single best-fit value with a symmetric error bar we will draw thousands of samples from the posterior."
    ]
   },
   {
@@ -215,9 +215,20 @@
    "id": "11",
    "metadata": {},
    "source": [
-    "## Maximum-likelihood fit (for reference)\n",
+    "## Maximum-likelihood fit (optional, but recommended)\n",
     "\n",
-    "Before running MCMC, perform a quick maximum-likelihood fit. The result will give us a good starting point and lets us compare the central tendency of the posterior with the classical best-fit values.\n"
+    "Perform a quick maximum-likelihood fit. This is **not** a prerequisite for sampling: `Sampler`\n",
+    "needs a *configured* `Fitter`, not a *fitted* one, and you can sample straight from the initial\n",
+    "parameter values.\n",
+    "\n",
+    "It is worth doing anyway, for two reasons:\n",
+    "\n",
+    "1. It lets us compare the central tendency of the posterior against the classical best-fit values.\n",
+    "2. It gives the chain a much better starting point. DREAM seeds its entire starting population\n",
+    "   inside a tiny ball around whatever the parameter values happen to be at the time (BUMPS' default\n",
+    "   `init='eps'`), so sampling from fitted values begins in the right region of parameter space and\n",
+    "   needs less burn-in to reach the typical set. Starting from a poor initial guess is not wrong, but\n",
+    "   expect to burn for longer."
    ]
   },
   {
@@ -250,20 +261,20 @@
     "\n",
     "We now draw samples from the posterior distribution $p(\\theta \\mid d)$ using the BUMPS DREAM (DiffeRential Evolution Adaptive Metropolis) algorithm. DREAM is an ensemble MCMC method that runs multiple chains in parallel and automatically tunes the proposal distribution.\n",
     "\n",
-    "DREAM only works with the BUMPS minimizer. We reuse the ``mle_fitter`` created above, switch it to BUMPS, and call `Fitter.mcmc_sample`, which returns a dictionary with the following keys:\n",
+    "DREAM only works with the BUMPS minimizer. We reuse the ``mle_fitter`` created above — any configured `Fitter` would do, and it does not have to have been fitted — switch it to BUMPS, and create a `Sampler` instance bound to the fitter and data. Calling `sampler.sample()` returns a `SamplingResults` object with the following attributes:\n",
     "\n",
-    "- `draws`: a `(n_samples, n_parameters)` array of posterior samples: each **row** is one complete draw from the joint posterior (one value for every parameter simultaneously), and each **column** holds all sampled values for a single parameter;\n",
+    "- `draws`: a `(n_samples, n_parameters)` array of posterior samples: each **row** is one complete draw from the joint posterior (one value for every parameter simultaneously), and each **column** holds all sampled values for a single parameter. Note this is a *trimmed* view of the chain rather than the raw buffer, so `n_samples` is smaller than `samples / thin` — see the note under [Extend the chain](#extend-the-chain-and-check-convergence);\n",
     "- `param_names`: the unique names of the parameters, in the same column order as `draws`;\n",
-    "- `internal_bumps_object`: the underlying BUMPS `MCMCDraw` object, useful for advanced diagnostics;\n",
+    "- `state`: the underlying BUMPS `MCMCDraw` object, useful for advanced diagnostics;\n",
     "- `logp`: the log-posterior of each retained sample.\n",
     "\n",
     "The key sampling parameters are:\n",
     "\n",
-    "- `samples` (4000): the total number of posterior draws to generate across all chains;\n",
-    "- `burn` (500): the number of initial *burn-in* iterations to discard — the sampler needs time to find the typical set of the posterior, and early samples are not representative;\n",
-    "- `thin` (2): the *thinning* interval — only every second sample is kept, which reduces autocorrelation between consecutive draws;\n",
+    "- `samples` (10000): the number of raw samples to draw across all chains, *before* thinning. This is a guaranteed minimum rather than an exact count: DREAM advances in blocks of 10 generations (one generation = one draw per chain) and stops at the first block boundary at or past `samples`;\n",
+    "- `burn` (500): the number of initial *burn-in* generations to discard — the sampler needs time to find the typical set of the posterior, and early samples are not representative. Note this counts generations, not raw samples, so `burn=500` discards `500 × n_chains` raw samples;\n",
+    "- `thin` (2): the *thinning* interval — only every second generation is kept, which reduces autocorrelation between consecutive draws;\n",
     "\n",
-    "First, we switch to the BUMPS minimizer:\n"
+    "First, we switch to the BUMPS minimizer:"
    ]
   },
   {
@@ -285,17 +296,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "result = mle_fitter.mcmc_sample(\n",
-    "    x=omega,\n",
-    "    y=intensity_obs,\n",
-    "    weights=1 / intensity_error,\n",
-    "    samples=10000,\n",
-    "    burn=500,\n",
-    "    thin=2,\n",
-    ")\n",
+    "from easyscience.fitting import Sampler\n",
     "\n",
-    "print(f'Drew {result[\"draws\"].shape[0]} samples for {result[\"draws\"].shape[1]} parameters.')\n",
-    "print('parameters:', result['param_names'])"
+    "sampler = Sampler(mle_fitter, omega, intensity_obs, weights=1 / intensity_error)\n",
+    "results = sampler.sample(samples=10000, burn=500, thin=2)\n",
+    "\n",
+    "print(f'Drew {results.draws.shape[0]} samples for {results.draws.shape[1]} parameters.')\n",
+    "print('parameters:', results.param_names)"
    ]
   },
   {
@@ -320,12 +327,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "draws = result['draws']\n",
-    "logp = result['logp']\n",
-    "if callable(logp):\n",
-    "    _, logp = logp()\n",
-    "    logp = logp.flatten()\n",
-    "name_to_col = {name: idx for idx, name in enumerate(result['param_names'])}\n",
+    "draws = results.draws\n",
+    "logp = results.logp\n",
+    "name_to_col = {name: idx for idx, name in enumerate(results.param_names)}\n",
     "\n",
     "\n",
     "def column_for(parameter):\n",
@@ -367,7 +371,7 @@
     "The MLE finds the single point that maximises the likelihood, while the Bayesian median is the central value of the *posterior* — which also accounts for the prior $p(\\theta)$. If a parameter's posterior is skewed (asymmetric), the median and the mode (which approximates the MLE) will not coincide. The table below shows both so you can spot any such differences.\n",
     "\n",
     "\n",
-    "Note that the columns of `result['draws']` are ordered by `result['param_names']` (which use the parameters' `unique_name`), so it is worth building a small helper to look up a column by friendly name.\n"
+    "Note that the columns of `results.draws` are ordered by `results.param_names` (which use the parameters' `unique_name`), so it is worth building a small helper to look up a column by friendly name."
    ]
   },
   {
@@ -492,11 +496,206 @@
     "ax.legend()\n",
     "plt.show()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "03339658",
+   "metadata": {},
+   "source": [
+    "## Extend the chain and check convergence\n",
+    "\n",
+    "The original run asked for ``samples=10000`` with ``thin=2``. Here we **extend the\n",
+    "chain by 5000 more raw samples** using ``sampler.extend()`` — DREAM continues from\n",
+    "the previous in-memory state instead of starting from scratch.\n",
+    "\n",
+    "``sampler.extend(additional_samples=5000)`` does the ring-buffer arithmetic for you\n",
+    "automatically: it reads the number of stored generations from the saved state and\n",
+    "sizes the new buffer to ``old_generations + additional_samples``, so no existing\n",
+    "draws are dropped from the buffer.\n",
+    "\n",
+    "```{note}\n",
+    "`results.draws` grows by less than `additional_samples / thin`, for two unrelated\n",
+    "reasons.\n",
+    "\n",
+    "First, BUMPS post-processes the chain before returning it: with the default\n",
+    "`trim=True` it re-runs a burn-point detector over the whole extended chain and\n",
+    "returns only the part after the detected burn point, minus any chains flagged as\n",
+    "outliers. The detector runs anew on every `sample()` and `extend()` call, so the\n",
+    "retained count is not deterministic and can even shrink. This is unrelated to\n",
+    "`burn=500`: `extend()` resumes with `burn=0`.\n",
+    "\n",
+    "Second, `samples` is a minimum, not an exact count. DREAM advances in blocks of\n",
+    "10 generations (one generation = one draw per chain - this model has 4 parameters\n",
+    "and the default population scale of 10, hence 40 chains) and only checks its\n",
+    "stopping condition between blocks, so the chain grows by `additional_samples`\n",
+    "rounded up to a multiple of `10 × n_chains` raw draws. Here that is\n",
+    "5000 -> 13 blocks of 400 -> 5200 raw draws, i.e. 2600 retained rows at `thin=2`.\n",
+    "\n",
+    "The full chain is always available via\n",
+    "`results.state.draw(portion=1.0, outliers=True)`; pass\n",
+    "`sampler_kwargs={'trim': False}` to disable the trimming altogether.\n",
+    "```\n",
+    "\n",
+    "After the extension we compare the posterior summaries and check convergence with\n",
+    "Gelman-Rubin R-hat."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "293b140b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Extend the existing chain by 5000 more raw samples.\n",
+    "# extend() handles the ring-buffer arithmetic automatically.\n",
+    "extended_results = sampler.extend(additional_samples=5000, thin=2)\n",
+    "\n",
+    "\n",
+    "def n_full_chain(res):\n",
+    "    \"\"\"Rows in the whole chain, before BUMPS' automatic trimming.\"\"\"\n",
+    "    return res.state.draw(portion=1.0, outliers=True).points.shape[0]\n",
+    "\n",
+    "\n",
+    "print(f'{\"chain\":<10s} {\"trimmed\":>9s} {\"full\":>9s}')\n",
+    "print('-' * 30)\n",
+    "print(f'{\"original\":<10s} {results.draws.shape[0]:9d} {n_full_chain(results):9d}')\n",
+    "print(\n",
+    "    f'{\"extended\":<10s} {extended_results.draws.shape[0]:9d} {n_full_chain(extended_results):9d}'\n",
+    ")\n",
+    "\n",
+    "grew_by = n_full_chain(extended_results) - n_full_chain(results)\n",
+    "print(f'\\nThe full chain grew by {grew_by} draws: the {5000 // 2} we asked for')\n",
+    "print('(additional_samples / thin), rounded up to whole DREAM blocks of 10 generations.')\n",
+    "print('The \"trimmed\" column is what results.draws exposes: a view, not the chain.')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9ec4302c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Build helpers to look up parameter columns.\n",
+    "name_to_col_ext = {name: idx for idx, name in enumerate(extended_results.param_names)}\n",
+    "name_to_col_orig = {name: idx for idx, name in enumerate(results.param_names)}\n",
+    "\n",
+    "\n",
+    "def col_orig(par):\n",
+    "    return results.draws[:, name_to_col_orig[par.unique_name]]\n",
+    "\n",
+    "\n",
+    "def col_ext(par):\n",
+    "    return extended_results.draws[:, name_to_col_ext[par.unique_name]]\n",
+    "\n",
+    "\n",
+    "# Side-by-side posterior summary: the original chain vs the full extended set.\n",
+    "lbl_orig = f'original ({results.draws.shape[0]})'\n",
+    "lbl_ext = f'extended ({extended_results.draws.shape[0]})'\n",
+    "print(f'{\"param\":<10s} {\"metric\":>8s} {lbl_orig:>18s} {lbl_ext:>18s}  diff')\n",
+    "print('-' * 70)\n",
+    "for label, par in (('area', area), ('gamma', gamma), ('omega_0', omega_0), ('sigma', sigma)):\n",
+    "    c_first = col_orig(par)\n",
+    "    c_full = col_ext(par)\n",
+    "    for metric, fn in [\n",
+    "        ('mean', np.mean),\n",
+    "        ('std', np.std),\n",
+    "        ('q2.5%', lambda c: np.percentile(c, 2.5)),\n",
+    "        ('q50%', lambda c: np.percentile(c, 50)),\n",
+    "        ('q97.5%', lambda c: np.percentile(c, 97.5)),\n",
+    "    ]:\n",
+    "        vf = fn(c_first)\n",
+    "        vx = fn(c_full)\n",
+    "        diff = vx - vf\n",
+    "        print(f'{label:<10s} {metric:>8s} {vf:18.4g} {vx:18.4g} {diff:+.2e}')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b0f30be6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Visual comparison: overlay the original chain with the extended set.\n",
+    "fig, axes = plt.subplots(1, 4, figsize=(14, 3))\n",
+    "for ax, label, par in zip(\n",
+    "    axes, ('area', 'gamma', 'omega_0', 'sigma'), (area, gamma, omega_0, sigma)\n",
+    "):\n",
+    "    c_first = col_orig(par)\n",
+    "    c_full = col_ext(par)\n",
+    "    ax.hist(\n",
+    "        c_first, bins=40, density=True, alpha=0.5, color='C0', label=f'original ({len(c_first)})'\n",
+    "    )\n",
+    "    ax.hist(\n",
+    "        c_full, bins=40, density=True, alpha=0.5, color='C3', label=f'extended ({len(c_full)})'\n",
+    "    )\n",
+    "    ax.set_title(label)\n",
+    "    ax.set_yticks([])\n",
+    "axes[0].legend(fontsize=9)\n",
+    "fig.suptitle('Marginal posterior: original chain vs extended chain')\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "50b7213a",
+   "metadata": {},
+   "source": [
+    "### What is Gelman-Rubin R-hat?\n",
+    "\n",
+    "DREAM runs many chains in parallel, each started from a different point. The\n",
+    "Gelman-Rubin statistic $\\hat{R}$ compares two variance estimates: $W$, the average\n",
+    "variance *within* each chain, and $B$, the variance of the per-chain *means*.\n",
+    "\n",
+    "$$\n",
+    "\\hat{R} \\approx \\sqrt{\\frac{W + B}{W}}\n",
+    "$$\n",
+    "\n",
+    "If all chains sample the same distribution, each chain mean estimates the same\n",
+    "posterior mean with standard error $\\sqrt{W/n}$ (for $n$ draws per chain), so\n",
+    "$B \\approx W/n$ — negligible next to $W$ — and $\\hat{R} \\to 1$ as the chains grow.\n",
+    "If the chains are still drifting toward the posterior, or have settled in different\n",
+    "regions of it, their means genuinely disagree, $B$ stays comparable to $W$ or\n",
+    "larger, and $\\hat{R}$ sits visibly above 1. (The exact statistic — Gelman & Rubin\n",
+    "1992, which is what ``state.gelman()`` computes — adds finite-sample corrections\n",
+    "to this; the rule-of-thumb thresholds below are unchanged.)\n",
+    "\n",
+    "The usual rule of thumb is $\\hat{R} < 1.05$ for **every** parameter; above $\\approx 1.1$\n",
+    "the chain should be run for longer. Note that $\\hat{R} \\approx 1$ is *necessary but not\n",
+    "sufficient* for convergence: chains can agree with each other and still have all\n",
+    "missed the same region of the posterior, so read it alongside the trace plots.\n",
+    "\n",
+    "Extending a chain should improve convergence, so we print $\\hat{R}$ for the original and\n",
+    "the extended chain side by side."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3449e0a7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Convergence diagnostic: Gelman-Rubin R-hat before and after the extension.\n",
+    "# extend() leaves the original chain state untouched, so both can be compared.\n",
+    "rhat_short = results.state.gelman()\n",
+    "rhat_extended = extended_results.state.gelman()\n",
+    "\n",
+    "print('Gelman-Rubin R-hat — values < 1.05 indicate convergence:')\n",
+    "print(f'{\"parameter\":<22s} {\"short\":>10s} {\"extended\":>10s}')\n",
+    "print('-' * 46)\n",
+    "for name, r_short, r_ext in zip(extended_results.param_names, rhat_short, rhat_extended):\n",
+    "    status = '✓' if r_ext < 1.05 else '?' if r_ext < 1.1 else '✗'\n",
+    "    print(f'{name:<22s} {r_short:10.4f} {r_ext:10.4f}  {status}')"
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "p312",
+   "display_name": "era",
    "language": "python",
    "name": "python3"
   },
@@ -510,7 +709,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.11"
+   "version": "3.12.12"
   }
  },
  "nbformat": 4,