mc3 3.3.0__py3-none-any.whl

mc3/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2015-2026 Patricio Cubillos and contributors.
+# mc3 is open-source software under the MIT license (see LICENSE).
+
+from .sampler_driver import *
+from .fit_driver import *
+from . import plots
+from . import utils
+from . import stats
+from .version import __version__
+
+
+__all__ = (
+    sampler_driver.__all__
+  + fit_driver.__all__
+  + ['plots', 'utils', 'stats']
+)
+
+
+# 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)

mc3/__main__.py

@@ -0,0 +1,240 @@
+# Copyright (c) 2015-2026 Patricio Cubillos and contributors.
+# mc3 is open-source software under the MIT license (see LICENSE).
+
+import sys
+import os
+import warnings
+import argparse
+import configparser
+
+import matplotlib
+import matplotlib.pyplot as plt
+
+import mc3
+import mc3.utils as mu
+
+
+def main():
+    """
+    Multi-Core Markov-chain Monte Carlo (mc3) wrapper for the command line
+
+    Notes
+    -----
+    To display the full list of arguments, run from the prompt:
+    mc3 -h
+
+    Command-line arguments overwrite the config-file arguments if the
+    argument is defined twice.
+    """
+    parser = parse()
+
+    # Parse command-line args (right now, just interested in the config file):
+    args, unknown = parser.parse_known_args()
+
+    # Parse configuration file to a dictionary:
+    if args.cfile is not None and not os.path.isfile(args.cfile):
+        print(f"Configuration file: '{args.cfile}' not found.")
+        sys.exit(0)
+    if args.cfile:
+        config = configparser.ConfigParser()
+        config.read([args.cfile])
+        defaults = dict(config.items("MCMC"))
+    else:
+        defaults = {}
+    # Set defaults from the configuration-file values:
+    parser.set_defaults(**defaults)
+    # Overwrite defaults with the command-line arguments:
+    args, unknown = parser.parse_known_args()
+    delattr(args, 'cfile')
+    # Call MCMC driver:
+    mc3.sample(**vars(args))
+
+
+def parse():
+    """mc3 command-line argument parser"""
+    # Parse the config file from the command line:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    # Configuration-file option:
+    parser.add_argument(
+        "-c", "--cfile", help="Configuration file.", metavar="FILE")
+    parser.add_argument(
+        "-v", "--version", action="version",
+        help="Display mc3's version.",
+        version=f'mc3 version {mc3.__version__}.')
+    # MCMC Options:
+    group = parser.add_argument_group("MCMC General Options")
+    group.add_argument(
+        "--nsamples", dest="nsamples", action="store", type=eval, default=None,
+        help="Number of MCMC samples.")
+    group.add_argument(
+        "--nchains", dest="nchains", action="store", type=int, default=7,
+        help="Number of chains [default: %(default)s]")
+    group.add_argument(
+        "--ncpu", dest="ncpu", action="store", type=int, default=None,
+        help="Number of CPUs for the chains [default: nchains+1]")
+    group.add_argument(
+        "--sampler", dest="sampler", action="store", type=str, default=None,
+        help="Sampler algorithm, select from: ['mrw', 'demc', 'snooker'].")
+    group.add_argument(
+        "--wlike", dest="wlike", action="store", type=eval, default=False,
+        help="Calculate the likelihood in a wavelet base "
+             "[default: %(default)s]")
+    group.add_argument(
+        "--leastsq", dest="leastsq", action="store", type=eval, default=None,
+        help="If not None, perform a least-squares optimiztion before the "
+             "MCMC run.  Select from: 'lm': Levenberg-Marquardt (most "
+             "efficient, but does not obey bounds); 'trf': Trust Region "
+             "Reflective [default: %(default)s].")
+    group.add_argument(
+        "--chisqscale", dest="chisqscale", action="store",
+        type=eval, default=False,
+        help="Scale the data uncertainties such that the reduced "
+             "chi-squared = 1. [default: %(default)s]")
+    group.add_argument(
+        "--grtest", dest="grtest", action="store", type=eval, default=False,
+        help="Run Gelman-Rubin test [default: %(default)s]")
+    group.add_argument(
+        "--grbreak", dest="grbreak", action="store", type=float, default=0.0,
+        help="Gelman-Rubin convergence threshold to stop the MCMC.  I'd "
+             "suggest grbreak ~ 1.001 -- 1.005.  Do not break if "
+             "grbreak=0.0 (default).")
+    group.add_argument(
+        "--grnmin", dest="grnmin", action="store", type=eval, default=0.5,
+        help="Minimum number of valid samples required for grbreak.  If grnmin "
+             "is integer, require at least grnmin samples to break out of the "
+             "MCMC. If grnmin is a float (in the range 0.0--1.0), require at "
+             "least grnmin * maximum number of samples to break out of the "
+             "MCMC [default: %(default)s]")
+    group.add_argument(
+        "--burnin", dest="burnin", action="store", type=eval, default=0,
+        help="Number of burn-in iterations (per chain) [default: %(default)s]")
+    group.add_argument(
+        "--thinning", dest="thinning", action="store", type=int,  default=1,
+        help="Chains thinning factor (use every thinning-th iteration) for GR "
+             "test and plots [default: %(default)s]")
+    group.add_argument(
+        "--fgamma", dest="fgamma", action="store", type=float, default=1.0,
+        help="Scaling factor for DEMC's gamma [default: %(default)s]")
+    group.add_argument(
+        "--fepsilon", dest="fepsilon", action="store", type=float, default=0.0,
+        help="Scaling factor for DEMC's support distribution "
+             "[default: %(default)s]")
+    group.add_argument(
+        "--hsize", dest="hsize", action="store", type=int, default=10,
+        help="Number of initial samples per chain [default: %(default)s]")
+    group.add_argument(
+        "--kickoff", dest="kickoff", action="store", type=str, default="normal",
+        help="Chain's starter mode, select between: ['normal', 'uniform']. "
+             "[default: %(default)s]")
+    group.add_argument(
+        "--plots", dest="plots", action="store", type=eval, default=False,
+        help="If True, generate output figures. [default: %(default)s]")
+    group.add_argument(
+        "--theme", dest="theme", action="store", type=str, default='blue',
+        help="Color theme for plots, can be any color format recognized "
+        "by matplotlib. [default: %(default)s]")
+    group.add_argument(
+        "--statistics", dest="statistics", action="store", type=str,
+        default='med_central',
+        help="Which statistics to adopt for the plots, select between: "
+        "'med_central' (default, median and central quantile statistics), "
+        "'max_like' (mode and HPD statistics), or 'global_max_like' "
+        "(best-fit and HPD statistics).")
+    group.add_argument(
+        "--ioff", dest="ioff", action="store", type=eval, default=False,
+        help="If True, set plt.ioff(), i.e., do not display figures on screen "
+             "[default: %(default)s]")
+    group.add_argument(
+        "--showbp", dest="showbp", action="store", type=eval, default=True,
+        help="If True, show best-fitting values in histogram and pairwise "
+             "plots [default: %(default)s]")
+    group.add_argument(
+        "--savefile", dest="savefile", action="store", type=str, default=None,
+        help="Output npz filename to store the parameter posterior "
+             "distributions [default: %(default)s]")
+    group.add_argument(
+        "-r", "--resume", dest="resume", action="store_true", default=False,
+        help="If set, resume a previous run (load output).")
+    group.add_argument(
+        "--rms", dest="rms", action="store", type=eval, default=False,
+        help="If True, calculate RMS-vs-binsize of data--bestmodel residuals "
+             "[default: %(default)s]")
+    group.add_argument(
+        "--log", dest="log", action="store", type=str,  default=None,
+        help="Output log filename.")
+    group.add_argument(
+        "--pnames", dest="pnames", action="store", type=mu.parray, default=None,
+        help="List of parameter names for screen output (and figures if "
+             "texnames is not defined).  If pnames is not defined, default "
+             "to texnames.")
+    group.add_argument(
+        "--texnames", dest="texnames", action="store", type=mu.parray,
+        default=None,
+        help="List of parameter names for figures (may use latex syntax). "
+             "[default: None]")
+    # Fitting-parameter Options:
+    group = parser.add_argument_group("Fitting-function Options")
+    group.add_argument(
+        "--func", dest="func", action="store", type=mu.parray, default=None,
+        help="List of strings with the function name, module "
+             "name, and path-to-module [required]")
+    group.add_argument(
+        "--params", dest="params", action="store", type=mu.parray, default=None,
+        help="Filename or list of initial-guess model-fitting "
+             "parameter [required]")
+    group.add_argument(
+        "--pmin", dest="pmin", action="store", type=mu.parray, default=None,
+        help="Filename or list of parameter lower boundaries "
+             "[default: -inf for each parameter]")
+    group.add_argument(
+        "--pmax", dest="pmax", action="store", type=mu.parray, default=None,
+        help="Filename or list of parameter upper boundaries "
+             "[default: +inf for each parameter]")
+    group.add_argument(
+        "--pstep", dest="pstep", action="store", type=mu.parray, default=None,
+        help="Parameter stepping [required].  Additionally, parameters with "
+             "pstep=0 are fixed, parameters with negative pstep are "
+             "shared (see documentation).")
+    group.add_argument(
+        "--indparams", dest="indparams", action="store",
+        type=mu.parray, default=[],
+        help="Filename or list with independent parameters for func "
+             "[default: None]")
+    group.add_argument(
+        "--indparams_dict", dest="indparams_dict", action="store",
+        type=dict, default={},
+        help="Dictionary with independent keyword parameters for func "
+             "[default: {}]")
+    # Data Options:
+    group = parser.add_argument_group("Data Options")
+    group.add_argument(
+        "--data", dest="data", action="store", type=mu.parray, default=None,
+        help="Filename or array of the data being fitted [required]")
+    group.add_argument(
+        "--uncert", dest="uncert", action="store", type=mu.parray, default=None,
+        help="Filemane or array with the data uncertainties [required]")
+    group.add_argument(
+        "--prior", dest="prior", action="store", type=mu.parray, default=None,
+        help="Filename or array with parameter prior estimates "
+             "[default: %(default)s]")
+    group.add_argument(
+        "--priorlow", dest="priorlow", action="store", type=mu.parray,
+        default=None,
+        help="Filename or array with prior lower uncertainties "
+             "[default: %(default)s]")
+    group.add_argument(
+        "--priorup", dest="priorup", action="store", type=mu.parray,
+        default=None,
+        help="Filename or array with prior upper uncertainties "
+             "[default: %(default)s]")
+    return parser
+
+
+if __name__ == "__main__":
+    matplotlib.use('Agg')
+    plt.ioff()
+    warnings.simplefilter("ignore", RuntimeWarning)
+    main()

mc3/chain.py

@@ -0,0 +1,340 @@
+# Copyright (c) 2015-2026 Patricio Cubillos and contributors.
+# mc3 is open-source software under the MIT license (see LICENSE).
+
+import sys
+import warnings
+import random
+import multiprocessing as mp
+
+import numpy as np
+
+from . import stats as ms
+
+
+# Ingnore RuntimeWarnings:
+warnings.simplefilter("ignore", RuntimeWarning)
+
+
+class Chain(mp.get_context('fork').Process):
+  """
+  Background process.  This guy evaluates the model and calculates chisq.
+  """
+  def __init__(self, func, args, kwargs, pipe, data, uncert,
+      params, freepars, pstep, pmin, pmax,
+      sampler, wlike, prior, priorlow, priorup, thinning,
+      fgamma, fepsilon, Z, zsize, log_post, zchain, M0,
+      numaccept, outbounds, ncpp,
+      chainsize, bestp, best_log_post, ID, ncpu, **kwds):
+      """
+      Chain class initializer.
+
+      Parameters
+      ----------
+      func: Callable
+          Model fitting function.
+      args: List
+          Additional arguments for func (besides the fitting parameters).
+      kwargs: Dict
+          Additional keyword arguments for func (if needed).
+      pipe: multiprocessing.Pipe object
+          Pipe to communicate with mcmc.
+      data: 1D shared-ctypes float ndarray
+          Dependent data fitted by func.
+      uncert: 1D Shared ctypes float ndarray
+          Uncertainty of data.
+      params: 1D float array
+          Array of model parameters (including fixed and shared).
+      freepars: 2D shared-ctypes float ndarray
+          Current state of fitting parameters (X, as in Braak & Vrugt 2008).
+      pstep: 1D float ndarray
+          Proposal jump scale.
+      pmin: 1D float ndarray
+          Lower boundaries of the posteriors.
+      pmax: 1D float ndarray
+          Upper boundaries of the posteriors.
+      sampler: String
+          Flag to indicate wich MCMC algorithm to use [mrw, demc, snooker].
+      wlike: Boolean
+          Flag to use a wavelet-based likelihood function (True) or not (False).
+      prior: 1D float ndarray
+          Parameter prior.
+      priorlow: 1D float ndarray
+          Prior lower uncertainties.
+      priorup: 1D float ndarray
+          Prior uppper uncertainties.
+      thinning: Integer
+          Thinning factor of the chains.
+      fgamma: Float
+          Proposals jump scale factor for DEMC's gamma.
+          The code computes: gamma = fgamma * 2.38 / sqrt(2*Nfree)
+      fepsilon: Float
+          Jump scale factor for DEMC's support distribution.
+          The code computes: e = fepsilon * Normal(0, pstep)
+      Z: 2D shared-ctype float ndarray
+          MCMC parameters history (Z, as in Braak & Vrugt 2008).
+      zsize: Shared ctypes integer
+          Current number of samples in the Z array.
+      log_post: Float multiprocessing.Array
+          log(posterior) values for the samples in Z.
+      zchain: multiprocessing.Array integer
+          Chain ID for the given state in the Z array.
+      M0: Integer
+          Initial number of samples in the Z array.
+      numaccept: multiprocessing.Value integer
+          Number of accepted MCMC proposals
+      outbounds:  1D shared multiprocessing integer Array
+          Number of out-of-bound proposals per free parameter.
+      ncpp: Integer
+          Number of chains for this process.
+      chainsize: multiprocessing.Array integer
+          The current length of this chain.
+      bestp: Shared ctypes float array
+          The array with the current best-fitting parameter.
+      best_log_post: Float multiprocessing.Value
+          The log(posterior) value for bestp.
+      ID: Integer
+          Identification serial number for this chain.
+      ncpu: Integer
+          The number of processes running chains.
+      """
+      # Multiprocessing setup:
+      mp.Process.__init__(self, **kwds)
+      self.daemon = True
+      self.ID = ID
+      self.ncpp = ncpp
+      self.ncpu = ncpu
+      # MCMC setup:
+      self.sampler = sampler
+      self.thinning = thinning
+      self.fgamma   = fgamma
+      self.fepsilon = fepsilon
+      self.Z        = Z
+      self.zsize    = zsize
+      self.log_post = log_post
+      self.zchain   = zchain
+      self.chainsize = chainsize
+      self.M0        = M0
+      self.numaccept = numaccept
+      self.outbounds = outbounds
+      # Best values:
+      self.bestp = bestp
+      self.best_log_post = best_log_post
+      # Modeling function:
+      self.func = func
+      self.args = args
+      self.kwargs = kwargs
+      # Model, fitting, and shared parameters:
+      self.params = params
+      self.freepars = freepars
+      self.pstep = pstep
+      self.pmin = pmin
+      self.pmax = pmax
+      # Input/output Pipe:
+      self.pipe = pipe
+      # Data:
+      self.data = data
+      self.uncert = uncert
+      # Chisq function:
+      self.wlike = wlike
+
+      # Index of parameters:
+      self.ishare = np.where(self.pstep < 0)[0]
+      self.ifree = np.where(self.pstep > 0)[0]
+
+      # Keep only the priors that count:
+      self.prior = prior
+      self.priorlow = priorlow
+      self.priorup = priorup
+
+      # Size of variables:
+      self.nfree = np.sum(self.pstep > 0)   # Number of free parameters
+      self.nchains = np.shape(self.freepars)[0]
+      self.Zlen = np.shape(Z)[0]
+
+      # Length of mrw/demc chains:
+      self.chainlen = int((self.Zlen) / self.nchains)
+
+
+  def run(self):
+      """
+      Process the requests queue until terminated.
+      """
+      # Indices in Z-array to start this chains:
+      IDs = np.arange(self.ID, self.nchains, self.ncpu)
+      self.index = self.M0 + IDs
+      for j in range(self.ncpp):
+          if np.any(self.zchain==self.ID):  # (i.e., resume=True)
+              # Set ID to the last iteration for this chain:
+              IDs[j] = self.index[j] = np.where(self.zchain==IDs[j])[0][-1]
+          self.freepars[self.ID + j*self.ncpu] = np.copy(self.Z[IDs[j]])
+      chisq = -2*self.log_post[IDs]
+
+      nextp = np.copy(self.params)  # Array for proposed sample
+      nextchisq = 0.0               # Chi-square of nextp
+      njump = 0                     # Number of jumps since last Z-update
+      gamma = self.fgamma * 2.38 / np.sqrt(2*self.nfree)
+
+      # The numpy random system must have its seed reinitialized in
+      # each sub-processes to avoid identical 'random' steps.
+      # random.randomint is process- and thread-safe.
+      np.random.seed(random.randint(0, 100000))
+
+      # Run until completing the Z array:
+      while True:
+          njump += 1
+          normal = np.random.normal(0, self.pstep[self.ifree], self.nfree)
+
+          if self.sampler == "demc":
+              b = self.pipe.recv()  # Synchronization flag
+
+          for j in range(self.ncpp):
+              ID = self.ID + j*self.ncpu
+              mrfactor = 1.0
+
+              # Algorithm-specific proposals jumps:
+              if self.sampler == "snooker":
+                  # Sampling without replacement (0 <= iR1 != iR2 < zsize):
+                  iR1 = np.random.randint(0, self.zsize.value)
+                  iR2 = np.random.randint(1, self.zsize.value)
+                  if iR2 == iR1:
+                      iR2 = 0
+                  sjump = np.random.uniform() < 0.1
+                  if sjump:  # Snooker update:
+                      iz = np.random.randint(self.zsize.value)
+                      z  = self.Z[iz]  # Not to confuse with Z!
+                      if np.all(z == self.freepars[ID]):  # Do not project:
+                          jump = np.random.uniform(1.2, 2.2) \
+                                     * (self.Z[iR2]-self.Z[iR1])
+                      else:
+                          dz = self.freepars[ID] - z
+                          zp1 = np.dot(self.Z[iR1], dz)
+                          zp2 = np.dot(self.Z[iR2], dz)
+                          jump = np.random.uniform(1.2, 2.2) * (zp1-zp2) \
+                                     * dz/np.dot(dz,dz)
+                  else: # Z update:
+                      jump = \
+                          gamma*(self.Z[iR1] - self.Z[iR2]) \
+                          + self.fepsilon*normal
+
+              elif self.sampler == "mrw":
+                  jump = normal
+              elif self.sampler == "demc":
+                  # Select r1, r2 such that: r1 != r2 != ID:
+                  r1 = np.random.randint(1, self.nchains)
+                  if r1 == ID:
+                      r1 = 0
+                  # Pick r2 without replacement:
+                  r2 = (r1 + np.random.randint(2, self.nchains))%self.nchains
+                  if r2 == ID:
+                      r2 = (r1 + 1) % self.nchains
+                  jump = \
+                      gamma*(self.freepars[r1] - self.freepars[r2]) \
+                      + self.fepsilon*normal
+
+              # Propose next point:
+              nextp[self.ifree] = np.copy(self.freepars[ID]) + jump
+
+              # Check boundaries:
+              outpars = np.asarray(
+                  ((nextp < self.pmin) | (nextp > self.pmax))[self.ifree])
+              # If any parameter lied out of bounds, skip model evaluation:
+              if np.any(outpars):
+                  with self.outbounds.get_lock():
+                      self.outbounds[:] += outpars
+              else:
+                  # Update shared parameters:
+                  for s in self.ishare:
+                      nextp[s] = nextp[-int(self.pstep[s])-1]
+                  # Evaluate model:
+                  nextchisq = self.eval_model(nextp, ret="chisq")
+                  # Additional factor in Metropolis ratio for Snooker jump:
+                  if self.sampler == "snooker" and sjump:
+                      # squared norm of current and next:
+                      cnorm = np.dot(self.freepars[ID]-z, self.freepars[ID]-z)
+                      nnorm = np.dot(nextp[self.ifree]-z, nextp[self.ifree]-z)
+                      mrfactor = (nnorm/cnorm)**(0.5*(self.nfree-1))
+                  # Evaluate the Metropolis ratio:
+                  metro = (
+                     np.exp(0.5*(chisq[j]-nextchisq)) * mrfactor
+                     > np.random.uniform()
+                  )
+                  if metro:
+                      # Update freepars[ID]:
+                      self.freepars[ID] = np.copy(nextp[self.ifree])
+                      chisq[j] = nextchisq
+                      with self.numaccept.get_lock():
+                          self.numaccept.value += 1
+                      # Check lowest chi-square:
+                      with self.best_log_post.get_lock():
+                          if chisq[j] < -2*self.best_log_post.value:
+                              self.bestp[self.ifree] = self.freepars[ID]
+                              for s in self.ishare:
+                                  k = -int(self.pstep[s]) - 1
+                                  self.bestp[s] = self.bestp[k]
+                              self.best_log_post.value = -0.5*chisq[j]
+              # Update Z if necessary:
+              if njump == self.thinning:
+                  with self.zsize.get_lock():
+                      # Stop when we fill Z:
+                      if self.zsize.value == self.Zlen:
+                          return
+                      if self.sampler == "snooker":
+                          self.index[j] = self.zsize.value
+                      self.zsize.value += 1
+                  # Update values:
+                  self.zchain[self.index[j]] = ID
+                  self.Z[self.index[j]] = np.copy(self.freepars[ID])
+                  self.log_post[self.index[j]] = -0.5*chisq[j]
+                  self.index[j] += self.nchains
+                  self.chainsize[ID] += 1
+
+          if njump == self.thinning:
+              njump = 0  # Reset njump
+
+          if self.sampler == "demc":
+              self.pipe.send(chisq[j])
+          # Stop when the chain is complete:
+          if self.sampler in ["mrw", "demc"] \
+              and self.chainsize[0]==self.chainlen:
+              return
+
+
+  def eval_model(self, params, ret="model"):
+      """
+      Evaluate the model for the requested set of parameters.
+
+      Parameters
+      ----------
+      params: 1D float ndarray
+         The set of model fitting parameters.
+      ret: String
+         Flag to indicate what to return.  Valid options:
+         - 'model'  Return the evaluated model.
+         - 'chisq'  Return chi-square.
+         - 'both'   Return a list with the model and chisq.
+      """
+      if self.wlike:
+          model = self.func(params[0:-3], *self.args, **self.kwargs)
+      else:
+          model = self.func(params, *self.args, **self.kwargs)
+
+      # Reject proposed iteration if any model value is infinite:
+      if np.any(model == np.inf):
+          chisq = np.inf
+      else:
+          # Calculate chisq:
+          if self.wlike:
+              chisq = ms.dwt_chisq(
+                  model, self.data, params,
+                  self.prior, self.priorlow, self.priorup)
+          else:
+              chisq = ms.chisq(
+                  model, self.data, self.uncert, params,
+                  self.prior, self.priorlow, self.priorup)
+
+      if ret == "both":
+          return [model, chisq]
+      elif ret == "chisq":
+          return chisq
+      else:  # ret == "model"
+          return model