mc3 3.3.0__py3-none-any.whl

mc3/fit_driver.py

@@ -0,0 +1,270 @@
+# Copyright (c) 2015-2026 Patricio Cubillos and contributors.
+# mc3 is open-source software under the MIT license (see LICENSE).
+
+__all__ = [
+    'fit',
+]
+
+import numpy as np
+import scipy.optimize as so
+
+from . import stats as ms
+from . import utils as mu
+
+
+def fit(
+        data, uncert, func, params, indparams=[], indparams_dict={},
+        pstep=None, pmin=None, pmax=None,
+        prior=None, priorlow=None, priorup=None, leastsq='lm',
+    ):
+    r"""
+    Find the best-fitting params values to the dataset by performing a
+    Maximum-A-Posteriori optimization.
+
+    This is achieved by minimizing the negative log posterior, with:
+    log_post = log(posterior)
+             = log(likelihood) + log(prior)
+             = -0.5*chi-squared + log_prior
+             = sum_i -0.5*((data[i] - model[i])/uncert[i])**2 + log_prior
+
+    where log_prior is defined as:
+        log_prior = sum -0.5*((params - prior)/prior_uncert)**2
+    for each parameter with a Gaussian prior; parameters with
+    uniform priors do not contribute to log_prior.
+
+    Constant terms have been neglected since they don't affect the
+    optimization.
+
+    Parameters
+    ----------
+    data: 1D ndarray
+        Data fitted by func.
+    uncert: 1D ndarray
+        1-sigma uncertainties of data.
+    func: callable
+        The fitting function to model the data. It must be callable as:
+        model = func(params, *indparams, **indparams_dict)
+    params: 1D ndarray
+        The model parameters.
+    indparams: tuple
+        Additional arguments required by func (if required).
+    indparams_dict: dict
+        Additional keyword arguments required by func (if required).
+    pstep: 1D ndarray
+        Parameters fitting behavior.
+        If pstep is positive, the parameter is free for fitting.
+        If pstep is zero, keep the parameter value fixed.
+        If pstep is a negative integer, copy the value from
+            params[np.abs(pstep)+1].
+    pmin: 1D ndarray
+        Model parameters' lower boundaries.  Default -np.inf.
+        Only for leastsq='trf', since 'lm' does not handle bounds.
+    pmax: 1D ndarray
+        Model parameters' upper boundaries.  Default +np.inf.
+        Only for leastsq='trf', since 'lm' does not handle bounds.
+    prior: 1D ndarray
+        Parameters priors.  The type of prior is determined by priorlow
+        and priorup:
+            Gaussian: if both priorlow>0 and priorup>0
+            Uniform:  else
+    priorlow: 1D ndarray
+        Parameters' lower 1-sigma Gaussian prior.
+    priorup: 1D ndarray
+        Paraneters' upper 1-sigma Gaussian prior.
+    leastsq: String
+        Optimization algorithm:
+        If 'lm': use the Levenberg-Marquardt algorithm
+        If 'trf': use the Trust Region Reflective algorithm
+
+    Returns
+    -------
+    mc3_output: Dict
+        A dictionary containing the fit outputs, including:
+        - best_log_post: optimal log of the posterior (as defined above).
+        - best_chisq: chi-square for the found best_log_post.
+        - best_model: model evaluated at bestp.
+        - bestp: Model parameters for the optimal best_log_post.
+        - optimizer_res: the output from the scipy optimizer.
+
+    Examples
+    --------
+    >>> import mc3
+    >>> import numpy as np
+
+    >>> def quad(p, x):
+    >>>     '''Quadratic polynomial: y(x) = p0 + p1*x + p2*x^2'''
+    >>>     return p[0] + p[1]*x + p[2]*x**2.0
+
+    >>> # Preamble, create a noisy synthetic dataset:
+    >>> np.random.seed(10)
+    >>> x = np.linspace(0, 10, 100)
+    >>> p_true = [4.5, -2.4, 0.5]
+    >>> y = quad(p_true, x)
+    >>> uncert = np.sqrt(np.abs(y))
+    >>> data = y + np.random.normal(0, uncert)
+
+    >>> # Initial guess for fitting parameters:
+    >>> params = np.array([ 3.0, -2.0,  0.1])
+
+    >>> # Fit data:
+    >>> output = mc3.fit(data, uncert, quad, params, indparams=[x])
+    >>> print(output['bestp'], output['best_chisq'], -2*output['best_log_post'], sep='\n')
+    [ 4.57471072 -2.28357843  0.48341911]
+    92.79923183159411
+    92.79923183159411
+
+    >>> # Fit with priors (Gaussian, uniform, uniform):
+    >>> prior    = np.array([4.0, 0.0, 0.0])
+    >>> priorlow = np.array([0.1, 0.0, 0.0])
+    >>> priorup  = np.array([0.1, 0.0, 0.0])
+    >>> output = mc3.fit(data, uncert, quad, params, indparams=[x],
+            prior=prior, priorlow=priorlow, priorup=priorup)
+    >>> print(output['bestp'], output['best_chisq'], -2*output['best_log_post'], sep='\n')
+    [ 4.01743461 -2.00989433  0.45686521]
+    93.77082119449915
+    93.80121777303248
+    """
+    with mu.Log() as log:
+        if leastsq not in [None, 'lm', 'trf']:
+            log.error(
+                f"Invalid 'leastsq' input ({leastsq}). Must select "
+                "from ['lm', 'trf']"
+            )
+
+    # Total number of model parameters:
+    npars = len(params)
+    # Default pstep:
+    if pstep is None:
+        pstep = np.ones(npars, np.double)
+    # Default boundaries (all parameter space):
+    if pmin is None:
+        pmin = np.tile(-np.inf, npars)
+    if pmax is None:
+        pmax = np.tile(np.inf,  npars)
+    # Default priors, must set all or no one:
+    if prior is None or priorlow is None or priorup is None:
+        prior = priorup = priorlow = np.zeros(npars)
+
+    # Cast to ndarrays:
+    params   = np.asarray(params)
+    pstep    = np.asarray(pstep)
+    pmin     = np.asarray(pmin)
+    pmax     = np.asarray(pmax)
+    prior    = np.asarray(prior)
+    priorlow = np.asarray(priorlow)
+    priorup  = np.asarray(priorup)
+
+    # Get indices:
+    ifree  = np.where(pstep > 0)[0]
+    ishare = np.where(pstep < 0)[0]
+
+    fitparams = params[ifree]
+
+    args = (
+        params, func, data, uncert, indparams, indparams_dict,
+        pstep, prior, priorlow, priorup, ifree, ishare,
+    )
+    # Levenberg-Marquardt optimization:
+    if leastsq == 'lm':
+        lsfit = so.leastsq(
+            residuals, fitparams, args=args,
+            ftol=3e-16, xtol=3e-16, gtol=3e-16,
+            full_output=True,
+        )
+        output, cov_x, infodict, mesg, err = lsfit
+        params[ifree] = lsfit[0]
+        resid = lsfit[2]["fvec"]
+
+    # Bounded optimization:
+    elif leastsq == 'trf':
+        lsfit = so.least_squares(
+            residuals, fitparams,
+            bounds=(pmin[ifree], pmax[ifree]), args=args,
+            ftol=3e-16, xtol=3e-16, gtol=3e-16,
+            method='trf',
+        )
+        params[ifree] = lsfit["x"]
+        resid = lsfit["fun"]
+
+    # Update shared parameters:
+    for s in ishare:
+        params[s] = params[-int(pstep[s])-1]
+
+    # Compute best-fit model:
+    best_model = func(params, *indparams, **indparams_dict)
+    # Calculate chi-squared for best-fitting values:
+    best_log_post = -0.5*np.sum(resid**2.0)
+    log_prior = ms.log_prior(params[ifree], prior, priorlow, priorup, pstep)
+    best_chisq = -2*(best_log_post - log_prior)
+
+    return {
+        'bestp':params,
+        'best_log_post':best_log_post,
+        'best_chisq':best_chisq,
+        'best_model':best_model,
+        'optimizer_res':lsfit,
+    }
+
+
+def residuals(
+        fitparams, params, func, data, uncert, indparams, indparams_dict,
+        pstep, prior, priorlow, priorup, ifree, ishare,
+    ):
+    """
+    Calculate the weighted residuals between data and a model, accounting
+    also for parameter priors.
+
+    Parameters
+    ----------
+    fitparams: 1D ndarray
+        The model free parameters.
+    params: 1D ndarray
+        The model parameters (including fixed and shared parameters).
+    func: Callable
+        The fitting function to model the data, called as:
+        model = func(params, *indparams, **indparams_dict)
+    data: 1D ndarray
+        Dependent data fitted by func.
+    uncert: 1D ndarray
+        1-sigma uncertainty of data.
+    indparams: tuple
+        Additional arguments required by func (if required).
+    indparams_dict: dict
+        Additional keyword arguments required by func (if required).
+    pstep: 1D ndarray
+        Parameters' jump scale (same size as params).
+        If the pstep is positive, the parameter is free for fitting.
+        If the pstep is 0, keep the parameter value fixed.
+        If the pstep is a negative integer, copy (share) the parameter value
+        from params[np.abs(pstep)+1], which can be free or fixed.
+    prior: 1D ndarray
+        Model parameters' (Gaussian) prior values (same size as params).
+        Considered only when priolow != 0.  priorlow and priorup are the
+        lower and upper 1-sigma width of the Gaussian prior, respectively.
+    priorlow: 1D ndarray
+        Parameters' lower 1-sigma Gaussian prior (same size as params).
+    priorup: 1D ndarray
+        Paraneters' upper 1-sigma Gaussian prior (same size as params).
+    ifree: 1D bool ndarray
+        Indices of the free parameters in params.
+    ishare: 1D bool ndarray
+        Indices of the shared parameters in params.
+
+    Returns
+    -------
+    Array of weighted data-model and prior-params residuals.
+    """
+    # Update params with fitparams:
+    params[ifree] = fitparams
+
+    # Update shared parameters:
+    for s in ishare:
+        params[s] = params[-int(pstep[s])-1]
+
+    # Compute model:
+    model = func(params, *indparams, **indparams_dict)
+    # Calculate residuals:
+    residuals = ms.residuals(
+        model, data, uncert, params, prior, priorlow, priorup,
+    )
+    return residuals

mc3/mcmc_driver.py

@@ -0,0 +1,378 @@
+# Copyright (c) 2015-2026 Patricio Cubillos and contributors.
+# mc3 is open-source software under the MIT license (see LICENSE).
+
+__all__ = [
+    'mcmc',
+]
+
+import time
+import ctypes
+import multiprocessing as mpr
+
+import numpy as np
+
+from . import chain as ch
+from . import stats as ms
+
+
+def mcmc(
+        data, uncert, func, params, indparams, indparams_dict,
+        pmin, pmax, pstep,
+        prior, priorlow, priorup,
+        nchains, ncpu, nsamples, sampler,
+        wlike, fit_output, grtest, grbreak, grnmin, burnin, thinning,
+        fgamma, fepsilon, hsize, kickoff, savefile, resume, log,
+        pnames, texnames,
+    ):
+    """
+    Mid-level routine called by mc3.sample() to execute Markov-chain Monte
+    Carlo run.
+
+    Parameters
+    ----------
+    data: 1D float ndarray
+        Data to be fit by func.
+    uncert: 1D float ndarray
+        Uncertainties of data.
+    func: Callable or string-iterable
+        The callable function that models data as:
+        model = func(params, *indparams, **indparams_dict)
+    params: 1D float ndarray
+        Set of initial fitting parameters for func.
+    indparams: tuple
+        Additional arguments required by func.
+    indparams_dict: dict
+        Additional keyword arguments required by func (if required).
+    pmin: 1D ndarray
+        Lower boundaries for the posterior exploration.
+    pmax: 1D ndarray
+        Upper boundaries for the posterior exploration.
+    pstep: 1D ndarray
+        Parameter stepping.
+    prior: 1D ndarray
+        Parameter prior distribution means.
+    priorlow: 1D ndarray
+        Lower prior uncertainty values.
+    priorup: 1D ndarray
+        Upper prior uncertainty values.
+    nchains: Scalar
+        Number of simultaneous chains to run.
+    ncpu: Integer
+        Number of processors for the MCMC chains.
+    nsamples: Scalar
+        Total number of samples.
+    sampler: String
+        MCMC sampling algorithm select from [mrw, demc, snooker]
+    wlike: Bool
+        If True, calculate the likelihood in a wavelet-base.
+    grtest: Boolean
+        Run Gelman & Rubin test.
+    grbreak: Float
+        Gelman-Rubin convergence threshold to stop the MCMC.
+    grnmin: Float
+        Minimum number of samples required for grbreak to stop the MCMC.
+    burnin: Integer
+        Number of burned-in (discarded) iterations.
+    thinning: Integer
+        Thinning factor of the chains (use every thinning-th iteration).
+    fgamma: Float
+        Proposals jump scale factor for DEMC's gamma.
+    fepsilon: Float
+        Jump scale factor for DEMC's support distribution.
+    hsize: Integer
+        Number of initial samples per chain.
+    kickoff: String
+        How to start the chains:
+        'normal' for normal distribution around initial guess, or
+        'uniform' for uniform distribution withing the given boundaries.
+    savefile: String
+        If not None, filename to store allparams and other MCMC results.
+    resume: Boolean
+        If True resume a previous run.
+    log: mc3.utils.Log instance
+        Logging object.
+
+    Returns
+    -------
+    output: Dict
+        A Dictionary containing the MCMC posterior distribution and related
+        stats, including:
+        - posterior: thinned posterior distribution of shape [nsamples, nfree].
+        - zchain: chain indices for each sample in Z.
+        - zmask: indices that turn Z into the desired posterior (remove burn-in)
+        - chisq: chi^2 value for each sample in Z.
+        - log_posterior: log(posterior) for the samples in Z.
+        - burnin: number of burned-in samples per chain.
+        - bestp: model parameters for the optimal log(posterior) sample.
+        - best_model: model evaluated at bestp.
+        - best_chisq: chi^2 for the optimal log(posterior) in the sample.
+        - best_log_post: optimal log(posterior) in posterior.
+        - acceptance_rate: sample's acceptance rate.
+
+    Examples
+    --------
+    >>> # See https://mc3.readthedocs.io/en/latest/mcmc_tutorial.html
+    """
+    nfree  = int(np.sum(pstep > 0))
+    ifree  = np.where(pstep > 0)[0]
+    ishare = np.where(pstep < 0)[0]
+
+    if resume:
+        oldrun = np.load(savefile)
+        zold = oldrun["posterior"]
+        zchain_old = oldrun["zchain"]
+        # Size of posterior (prior to this MCMC sample):
+        pre_zsize = M0 = np.shape(zold)[0]
+    else:
+        pre_zsize = M0 = hsize*nchains
+
+    # Number of Z samples per chain:
+    nzchain = int(np.ceil(nsamples/nchains/thinning))
+    # Number of iterations per chain:
+    niter = nzchain * thinning
+    # Total number of Z samples (initial + chains):
+    zlen = pre_zsize + nzchain*nchains
+
+    burnin = int(burnin)
+    if not resume and niter < burnin:
+        log.error(
+            f"The number of burned-in samples ({burnin}) is greater than "
+            f"the number of iterations per chain ({niter})"
+        )
+
+    # Initialize shared-memory variables:
+    sm_freepars = mpr.Array(ctypes.c_double, nchains*nfree)
+    freepars = np.ctypeslib.as_array(sm_freepars.get_obj())
+    freepars = freepars.reshape((nchains, nfree))
+
+    best_log_post = mpr.Value(ctypes.c_double, np.inf)
+    sm_bestp = mpr.Array(ctypes.c_double, np.copy(params))
+    bestp = np.ctypeslib.as_array(sm_bestp.get_obj())
+    # There seems to be a strange behavior with np.ctypeslib.as_array()
+    # when the argument is a single-element array. In this case, the
+    # returned value is a two-dimensional array, instead of 1D. The
+    # following line fixes(?) that behavior:
+    if np.ndim(bestp) > 1:
+        bestp = bestp.flatten()
+
+    numaccept = mpr.Value(ctypes.c_int, 0)
+    outbounds = mpr.Array(ctypes.c_int, nfree)
+
+    # Z array with the chains history:
+    sm_Z = mpr.Array(ctypes.c_double, zlen*nfree)
+    Z = np.ctypeslib.as_array(sm_Z.get_obj())
+    Z = Z.reshape((zlen, nfree))
+
+    # Chi-square value of Z:
+    sm_log_post = mpr.Array(ctypes.c_double, zlen)
+    log_post = np.ctypeslib.as_array(sm_log_post.get_obj())
+    # Chain index for given state in the Z array:
+    sm_zchain = mpr.Array(ctypes.c_int, -np.ones(zlen, int))
+    zchain = np.ctypeslib.as_array(sm_zchain.get_obj())
+    # Current number of samples in the Z array:
+    zsize = mpr.Value(ctypes.c_int, M0)
+    # Burned samples in the Z array per chain:
+    zburn = int(burnin/thinning)
+
+    # Include values from previous run:
+    if resume:
+        Z[0:pre_zsize,:] = zold
+        zchain[0:pre_zsize] = oldrun["zchain"]
+        log_post[0:pre_zsize] = oldrun["log_post"]
+        # Redefine zsize:
+        zsize.value = pre_zsize
+        numaccept.value = int(oldrun["acceptance_rate"] / 100. * pre_zsize)
+
+    # Set GR N-min as number of thinned samples:
+    if grnmin >= 1:
+        grnmin = int(grnmin/thinning)
+    elif grnmin > 0:
+        grnmin = int(grnmin*nchains*(nzchain-zburn))
+    elif grnmin < 0:
+        log.error(
+            "Invalid 'grnmin' argument (minimum number of samples to "
+            "stop the MCMC under GR convergence), must either be grnmin > 1"
+            "to set the minimum number of samples, or 0 < grnmin < 1"
+            "to set the fraction of samples required to evaluate.")
+    # Add these to compare grnmin to zsize (which also include them):
+    grnmin += int(M0 + zburn*nchains)
+
+    # Current length of each chain:
+    sm_chainsize = mpr.Array(ctypes.c_int, np.tile(hsize, nchains))
+    chainsize = np.ctypeslib.as_array(sm_chainsize.get_obj())
+
+    # Number of chains per processor:
+    ncpp = np.tile(int(nchains/ncpu), ncpu)
+    ncpp[0:nchains % ncpu] += 1
+
+    # Launch Chains:
+    mp_context = mpr.get_context('fork')
+    pipes  = []
+    chains = []
+    for i in range(ncpu):
+        p = mp_context.Pipe()
+        pipes.append(p[0])
+        chains.append(
+            ch.Chain(func, indparams, indparams_dict, p[1], data, uncert,
+            params, freepars, pstep, pmin, pmax,
+            sampler, wlike, prior, priorlow, priorup, thinning,
+            fgamma, fepsilon, Z, zsize, log_post, zchain, M0,
+            numaccept, outbounds, ncpp[i],
+            chainsize, bestp, best_log_post, i, ncpu))
+
+    if resume:
+        bestp[:] = oldrun['bestp']
+        best_log_post.value = oldrun['best_log_post']
+        for c in range(nchains):
+            chainsize[c] = np.sum(zchain_old==c)
+    else:
+        def random_pick(kickoff):
+            x0 = np.copy(params[ifree])
+            sigma = np.copy(pstep[ifree])
+            x_min = np.copy(pmin[ifree])
+            x_max = np.copy(pmax[ifree])
+            while True:
+                if kickoff == 'normal':
+                    yield np.random.normal(x0, sigma)
+                elif kickoff == 'uniform':
+                    yield np.random.uniform(x_min, x_max)
+
+        # Evaluate models for initial sample of Z:
+        values = np.asarray(params)
+        i = 0
+        j = 0
+        nmax_trials = 100 * M0
+        for trial in random_pick(kickoff):
+            if i == M0 or j == nmax_trials:
+                break
+
+            values[ifree] = trial
+            if np.any(values > pmax) or np.any(values < pmin):
+                j += 1
+                continue
+            # Update shared parameters:
+            for s in ishare:
+                values[s] = values[-int(pstep[s])-1]
+            chi_square = -0.5*chains[0].eval_model(values, ret='chisq')
+            if not np.isfinite(chi_square):
+                j += 1
+                continue
+            Z[i] = values[ifree]
+            log_post[i] = chi_square
+            i += 1
+
+        if i < M0-1:
+            log.error(
+                'Cannot populate an initial sample set of parameters, try '
+                'updating the parameters initial guess to avoid sampling '
+                'beyond the parameter boundaries or where the model returns '
+                'non-finite values.'
+            )
+
+        # Best-fitting values (so far):
+        izbest = np.argmax(log_post[0:M0])
+        best_log_post.value = log_post[izbest]
+        bestp[ifree] = np.copy(Z[izbest])
+        if fit_output is not None:
+            bestp[:] = np.copy(fit_output['bestp'])
+            best_log_post.value = fit_output['best_log_post']
+
+    # The output dict:
+    output = {
+        'pnames': pnames,
+        'texnames': texnames,
+        'pstep': pstep,
+        'ifree': ifree,
+        'burnin': zburn,
+    }
+
+    # ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+    # Start loop:
+    print("Yippee Ki Yay Monte Carlo!")
+    log.msg(f"Start MCMC chains  ({time.ctime()})")
+    for chain in chains:
+        chain.start()
+    bit = bool(1)  # Dummy variable to send through pipe for DEMC
+    # Intermediate steps to run GR test and print progress report:
+    intsteps = (nzchain*nchains) / 10
+    report = intsteps
+
+    while True:
+        # Proposal jump:
+        if sampler == "demc":
+            # Send and receive bit for DEMC synchronization:
+            for pipe in pipes:
+                pipe.send(bit)
+            for pipe in pipes:
+                _ = pipe.recv()
+
+        # Print intermediate info:
+        if (zsize.value-pre_zsize >= report) or (zsize.value == zlen):
+            report += intsteps
+            log.progressbar((zsize.value+1.0-pre_zsize)/(nzchain*nchains))
+
+            out_of_bounds = np.asarray(outbounds[:])
+            chisq = -2*best_log_post.value
+            log.msg(
+                f"Out-of-bound Trials:\n{out_of_bounds}\n"
+                f"Best Parameters: (chisq={chisq:.4f})\n{bestp[ifree]}",
+                width=80)
+
+            # Save intermediate state:
+            if savefile is not None:
+                ms.update_output(output, chains[0], hsize)
+                np.savez(savefile, **output)
+
+            # Gelman-Rubin statistics:
+            if grtest and np.all(chainsize > (zburn+hsize)):
+                psrf = ms.gelman_rubin(Z, zchain, zburn)
+                log.msg(
+                    f"Gelman-Rubin statistics for free parameters:\n{psrf}",
+                    width=80,
+                )
+                if np.all(psrf < 1.01):
+                    log.msg("All parameters converged to within 1% of unity.")
+                converged = (
+                    grbreak > 0.0 and
+                    np.all(psrf < grbreak) and
+                    zsize.value > grnmin
+                )
+                if converged:
+                    with zsize.get_lock():
+                        zsize.value = zlen
+                    log.msg(
+                        "\nAll parameters satisfy the GR convergence "
+                        f"threshold of {grbreak:g}, stopping the MCMC.")
+                    break
+            if zsize.value == zlen:
+                break
+
+    # Make sure chains finish and release all locks
+    for chain in chains:
+        chain.join()
+        
+    for chain in chains:  # Make sure to terminate the subprocesses
+        chain.terminate()
+
+    # Evaluate model for best fitting parameters:
+    posterior = ms.update_output(output, chains[0], hsize)
+
+    # Print out Summary:
+    Z = output['posterior']
+    nsample = len(Z)*thinning
+    nzsample = len(posterior)
+    fmt = len(str(nsample))
+    chain_iter = nsample // nchains
+    accept_rate = output['acceptance_rate']
+
+    log.msg('\nMCMC Summary:\n-------------')
+    log.msg(
+        f"Number of evaluated samples:        {nsample:{fmt}d}\n"
+        f"Number of parallel chains:          {nchains:{fmt}d}\n"
+        f"Average iterations per chain:       {chain_iter:{fmt}d}\n"
+        f"Burned-in iterations per chain:     {burnin:{fmt}d}\n"
+        f"Thinning factor:                    {thinning:{fmt}d}\n"
+        f"MCMC sample size (thinned, burned): {nzsample:{fmt}d}\n"
+        f"Acceptance rate:   {accept_rate:.2f}%\n", indent=2)
+
+    return output

mc3/plots/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2015-2026 Patricio Cubillos and contributors.
+# mc3 is open-source software under the MIT license (see LICENSE).
+
+from .plot_functions import *
+from .posterior import *
+from .colors import *
+
+__all__ = (
+    plot_functions.__all__
+    + posterior.__all__
+    + colors.__all__
+)
+
+# Clean up top-level namespace--delete everything that isn't in __all__
+# or is a magic attribute, and that isn't a submodule of this package
+for varname in dir():
+    if not ((varname.startswith('__') and varname.endswith('__')) or
+            varname in __all__):
+        del locals()[varname]
+del(varname)