rename hot start resuming from similar posterior to warm start

docs/index.rst

@@ -27,6 +27,7 @@ Welcome to UltraNest's documentation!
    example-line.ipynb
    example-outliers.ipynb
    example-sine-bayesian-workflow.ipynb
+   example-warmstart.ipynb
 
 .. include:: ../README.rst
 

tests/test_hotstart.py

@@ -4,7 +4,7 @@
 from numpy import log10
 from ultranest import ReactiveNestedSampler
 from ultranest.utils import vectorize
-from ultranest.integrator import resume_from_hot_file
+from ultranest.integrator import warmstart_from_similar_file
 from ultranest.hotstart import reuse_samples, get_extended_auxiliary_problem
 from ultranest.hotstart import compute_quantile_intervals, get_auxiliary_contbox_parameterization, compute_quantile_intervals_refined
 import os
@@ -110,7 +110,7 @@ def test_contbox_hotstart():
             header='weight logl mean scatter',
             fmt='%f'
         )
-        aux_param_names, aux_loglike, aux_transform, vectorized = resume_from_hot_file(
+        aux_param_names, aux_loglike, aux_transform, vectorized = warmstart_from_similar_file(
             tmpfilename,
             parameters,
             extended_log_likelihood,
@@ -122,7 +122,7 @@ def test_contbox_hotstart():
         assert p.shape == (len(aux_param_names)+1,)
         L = float(aux_loglike(p))
         print(L)
-        aux_param_names, aux_vloglike, aux_vtransform, vectorized = resume_from_hot_file(
+        aux_param_names, aux_vloglike, aux_vtransform, vectorized = warmstart_from_similar_file(
             tmpfilename,
             parameters,
             vectorize(extended_log_likelihood),

tests/test_run.py

@@ -6,7 +6,7 @@
 import json
 import pandas
 from ultranest import NestedSampler, ReactiveNestedSampler, read_file
-from ultranest.integrator import resume_from_hot_file
+from ultranest.integrator import warmstart_from_similar_file
 import ultranest.mlfriends
 from numpy.testing import assert_allclose
 
@@ -493,7 +493,7 @@ def transform(x):
         print('%15s : %.3f +- %.3f' % (name, col.mean(), col.std()))
 
 
-def test_run_hotstart_gauss_SLOW():
+def test_run_warmstart_gauss_SLOW():
     center = None
     stdev = 0.001
 
@@ -523,7 +523,7 @@ def transform(x):
                     loglike, transform=transform,
                     log_dir=folder, resume=resume, vectorized=True)
             else:
-                aux_param_names, aux_loglike, aux_transform, vectorized = resume_from_hot_file(
+                aux_param_names, aux_loglike, aux_transform, vectorized = warmstart_from_similar_file(
                     os.path.join(folder, 'chains', 'weighted_post_untransformed.txt'),
                     paramnames, loglike=loglike, transform=transform, vectorized=True,
                 )

ultranest/hotstart.py

@@ -338,14 +338,6 @@ def get_auxiliary_contbox_parameterization(
     likelihood and prior transform that is identical but
     requires fewer nested sampling iterations.
 
-    This is achieved by deforming the prior space, and undoing that
-    transformation by correction weights in the likelihood.
-
-    The auxiliary distribution used for transformation/weighting is
-    factorized. Each axis considers the ECDF of the auxiliary samples,
-    and segments it into five quantile segments. Within each segment,
-    the parameter edges in u-space are linearly interpolated.
-
     Usage::
 
         aux_loglikelihood, aux_transform = get_auxiliary_contbox_parameterization(
@@ -354,6 +346,20 @@ def get_auxiliary_contbox_parameterization(
         aux_results = aux_sampler.run()
         posterior_samples = aux_results['samples'][:,-1]
 
+    This is achieved by deforming the prior space, and undoing that
+    transformation by correction weights in the likelihood.
+    A additional parameter, "aux_logweight", is added at the end,
+    which contains the correction weight. You can ignore it.
+
+    The auxiliary distribution used for transformation/weighting is
+    factorized. Each axis considers the ECDF of the auxiliary samples,
+    and segments it into quantile segments. Within each segment,
+    the parameter edges in u-space are linearly interpolated.
+    To see the interpolation quantiles for each axis, use::
+    
+        steps = 10**-(1.0 * np.arange(1, 8, 2))
+        ulos, uhis, uinterpspace = compute_quantile_intervals_refined(steps, upoints, uweights)
+
     Parameters
     ------------
     loglike: function

ultranest/integrator.py

@@ -27,7 +27,7 @@
 from .hotstart import get_auxiliary_contbox_parameterization
 
 
-__all__ = ['ReactiveNestedSampler', 'NestedSampler', 'read_file']
+__all__ = ['ReactiveNestedSampler', 'NestedSampler', 'read_file', 'warmstart_from_similar_file']
 
 
 def _get_cumsum_range(pi, dp):
@@ -915,7 +915,7 @@ def plot(self):
             plt.close()
 
 
-def resume_from_hot_file(
+def warmstart_from_similar_file(
     usample_filename,
     param_names,
     loglike,
@@ -924,6 +924,46 @@ def resume_from_hot_file(
     derived_param_names=[],
     min_num_samples=50
 ):
+    """Warmstart from a previous run.
+
+    
+
+    Parameters
+    ------------
+    usample_filename: str
+        'directory/chains/weighted_post_untransformed.txt'
+        contains posteriors in u-space (untransformed) of a previous run.
+        Columns are weight, logl, param1, param2, ...
+    min_num_samples: int
+        minimum number of samples in the usample_filename file required.
+        Too few samples will give a poor approximation.
+
+    The remaining parameters have the same meaning as in :class:ReactiveNestedSampler.
+
+    Returns:
+    ---------
+    aux_param_names: list
+        new parameter list
+    aux_loglikelihood: function
+        new loglikelihood function
+    aux_transform: function
+        new prior transform function
+    vectorized: bool
+        whether the new functions are vectorized
+
+    Usage::
+
+        aux_paramnames, aux_log_likelihood, aux_prior_transform, vectorized = warmstart_from_similar_file(
+            'model1/chains/weighted_post_untransformed.txt', parameters, log_likelihood_with_background, prior_transform)
+
+        aux_sampler = ReactiveNestedSampler(aux_paramnames, aux_log_likelihood, transform=aux_prior_transform,vectorized=vectorized)
+        aux_sampler.run()
+        posterior_samples = aux_results['samples'][:,-1]
+
+    See :py:func:`ultranest.hotstart.get_auxiliary_contbox_parameterization`
+    for more information.
+
+    """
     # load samples
     try:
         with open(usample_filename) as f: