API

The following details the objects used in this package.

Experiment

class dmdd.Experiment(name, element, Qmin, Qmax, exposure, efficiency_fn, tex_name=None, energy_resolution=True)

An object representing a dark-matter direct-detection experiment.

This object packages all the information that defines a single “experiment”. For statistical analysis, a list of these objects is passed to initialize an instance of a MultinestRun object, or to initialize an instance of a Simulation object. It can also be used on its own to explore the capabilities of an experiment with given characteristics. Experiments set up here can either have perfect energy resolution in a given analysis window, or no resolution (controlled by the parameter energy_resolution, default being True).

Parameters:

• name (str) – Name of experiment.
• element (str) – Detector target element. Only single-element targets currently supported.
• Qmin,Qmax – Nuclear-recoil energy range of experiment [in keV].
• exposure – Total exposure of experiment [kg-years].
• efficiency_fn (function) – Efficiency as a function of nuclear recoil energy.
• tex_name (str) – Optional; provide this if you want a specific tex name on plots.
• energy_resolution (bool) – If True, then the energy of recoil events will be taken into account in likelihood analyses using this experiment; otherwise, not (e.g., for bubble-chamber experiments).

NminusNbg(sigma_val, sigma_name='sigma_si', fnfp_name='fnfp_si', fnfp_val=None, mass=50.0, Nbackground=4, v_esc=540.0, v_lag=220.0, v_rms=220.0, rho_x=0.3)

Expected number of events minus background

Parameters:

• sigma_val – Scattering cross-section for interaction with proton [cm^2]
• sigma_name – Which sigma this corresponds to (i.e., which argument of rate_UV.R())
• fnfp_name (str) – Which fnfp to use.
• fnfp_val – Value of fnfp (optional).
• mass – Dark-matter particle mass in GeV.
• Nbackground – Number of background events expected.
• v_esc,v_lag,v_rms,rho_x – Passed to rate_UV.R().

VminusVesc(mx, v_esc=540.0, v_lag=220.0)

This function returns the value of the minimum velocity needed to produce recoil of energy Qmin, minus escape velocity in Galactic frame.

See Eq 2.3 in (Gluscevic & Peter, 2014).

Zero of this function gives minimal dark-matter particle mass mx that can be detected with this Experiment. This is usually called by Experiment.find_min_mass().

Parameters:

• mx – WIMP mass [GeV]
• v_esc – escape velocity in Galactic frame [km/sec]
• v_lag – rotational velocity of the Milky Way [km/sec]

Returns:

Vmin - Vesc

find_min_mass(v_esc=540.0, v_lag=220.0, mx_guess=1.0)

This finds the minimum dark-matter particle mass detectable with this experiment, by finding a zero of VminusVesc.

Parameters:mx_guess – guess-value [GeV].

Other parameters documented in Experiment.VminusVesc().

sigma_exclusion(sigma_name, fnfp_name='fnfp_si', fnfp_val=None, mass_max=5000, Nbackground=4, mx_guess=1.0, sigma_guess=10000000000.0, v_esc=540.0, v_lag=220.0, v_rms=220.0, rho_x=0.3, mass_spacing='log', nmass_points=100, make_plot=False, ymax=None)

Makes exclusion curve for a chosen sigma parameter.

Calculates Experiment.sigma_limit() for a grid of masses, and interpolates.

Parameters:

• sigma_name (str) – Name of cross-section to exclude.
• mass_spacing – ‘log’ (logarithmic) or ‘lin’ (linear) spacing for mass grid.
• nmass_points – Number of points to calculate for mass grid.
• make_plot – Whether to make the plot. If False, then function will return arrays of mass, sigma.
• ymax – Set the y maximum of plot axis.

For other parameters, see Experiment.sigma_limit()

sigma_limit(sigma_name='sigma_si', fnfp_name='fnfp_si', fnfp_val=None, mass=50.0, Nbackground=4, sigma_guess=10000000000.0, mx_guess=1.0, v_esc=540.0, v_lag=220.0, v_rms=220.0, rho_x=0.3)

Returns value of sigma at which expected number of dark-matter induced recoil events is equal to the number of expected background events, N = Nbg, in order to get a rough projected exclusion for this experiment.

Parameters:

• sigma_guess – Initial guess for solver.
• mx_guess – Initial guess for dark-matter particle mass in order to find the minimum mass detectable from experiment (Experiment.find_min_mass()).

For other arguments, see Experiment.NminusNbg()

Model

class dmdd.Model(name, param_names, dRdQ_fn, loglike_fn, default_rate_parameters, tex_names=None, fixed_params=None, modelname_tex=None)

A generic class describing a dark-matter scattering model.

This object facilitates handling of a “hypothesis” that describes the scattering interaction at hand (to be used either to simulate recoil spectra, or to fit them). There is an option to give any parameter a fixed value, which will not be varied if the model is used to fit data.

Subclassed by UV_Model.

Parameters:

• name (str) – Name of the model, matching the operator(s) name. It cannot have spaces.
• param_names (list) – Names of the parameters.
• dRdQ_fn (function) – Appropriate rate function.
• loglike_fn (function) – Function that returns the log-likelihood of an array of event energies, given experimental and astrophysical parameters. Must take Q, eff_fn, **kwargs as arguments.
• default_rate_parameters (dict) – Default parameters to be passed to rate function.
• tex_names (dict) – Dictionary of LaTeX names of parameters.
• fixed_params (dict) – Parameters of model that are not intended to be fit for.

class dmdd.UV_Model(name, param_names, **kwargs)

Subclass of Model implementing UV-complete scattering models. Rate function and log-likelihood function are taken from the rate_UV module.

Simulation

class dmdd.Simulation(name, experiment, model, parvals, path='/home/docs/.dmdd/simulations_uv/', force_sim=False, asimov=False, nbins_asimov=20, plot_nbins=20, plot_theory=True, silent=False)

A simulation of dark-matter direct-detection data under a given experiment and scattering model.

This object handles a single simulated data set (nuclear recoil energy spectrum). It is generaly initialized and used by the MultinestRun object, but can be used stand-alone.

Simulation data will only be generated if a simulation with the right parameters and name does not already exist, or if force_sim=True is provided upon Simulation initialization; if the data exist, it will just be read in. (Data is a list of nuclear recoil energies of “observed” events.) Initializing Simulation with given parameters for the first time will produce 3 files, located by default at $DMDD_PATH/simulations (or ./simulations if $DMDD_PATH not defined):

• .dat file with a list of nuclear-recoil energies (keV), drawn from a

Poisson distribution with an expected number of events given by the underlying scattering model.

• .pkl file with all relevant initialization parameters for record
• .pdf plot of the simulated recoil-energy spectrum with simulated

data points (with Poisson error bars) on top of the underlying model

Parameters:

• name (str) – Identifier for simulation (e.g. ‘sim1’)
• experiment (Experiment) – Experiment for simulation.
• model (Model) – Model under which to simulate data.
• parvals (dict) – Values of model parameters. Must contain the same parameters as model.
• path (str) – The path under which to store the simulations.
• force_sim (bool) – If True, then redo the simulations no matter what. If False, then the simulations will be redone if and only if the given simulation parameters don’t match what has already been simulated for this simulation name.
• asimov – Do asimov simulations. Not currently implemented.
• nbins_asimov – Number of asimov bins.
• plot_nbins – Number of bins to bin data in for rate plot.
• plot_theory – Whether to plot the “true” theoretical rate curve along with the simulated data.
• silent – If True, then print messages will be suppressed.

plot_data(plot_nbins=20, plot_theory=True, save_plot=True, make_plot=True, return_plot_items=False)

Plot simuated data.

Parameters:

• plot_nbins – Number of bins for plotting.
• plot_theory – Whether to overplot the theory rate curve on top of the data points.
• save_plot – Whether to save plot under self.plotfile.
• make_plot – Whether to make the plot. No reason really to ever be false unless you only want the “plot items” returned if return_plot_items=True is passed.
• return_plot_items – If True, then function will return lots of things.

simulate_data()

Do Poisson simulation of data according to scattering model’s dR/dQ.

MultinestRun

class dmdd.MultinestRun(sim_name, experiments, sim_model, param_values, fit_model, prior_ranges, prior='logflat', sim_root='/home/docs/.dmdd/simulations_uv/', chains_root='/home/docs/.dmdd/chains_uv/', force_sim=False, asimov=False, nbins_asimov=20, n_live_points=2000, evidence_tolerance=0.1, sampling_efficiency=0.3, resume=False, basename='1-', silent=False, empty_run=False)

This object controls a single simulated data set and its MultiNest analysis.

This is a “master” class of dmdd that makes use of all other objects. It takes in experimental parameters, particle-physics parameters, and astrophysical parameters, and then generates a simulation (if it doesn’t already exist), and prepares to perform MultiNest analysis of simulated data. It has methods to do a MultiNest run (MultinestRun.fit()) and to visualize outputs (visualize()). Model used for simulation does not have to be the same as the Model used for fitting. Simulated spectra from multiple experiments will be analyzed jointly if MultiNest run is initialized with a list of appropriate Experiment objects.

The likelihod function is an argument of the fitting model (Model object); for UV models it is set to dmdd.rate_UV.loglikelihood(), and for models that would correspond to rate_genNR, dmdd.rate_genNR.loglikelihood() should be used. Both likelihood functions include the Poisson factor, and (if energy_resolution=True of the Experiment at hand) the factors that evaluate probability of each individual event (i.e. each recoil-energy measurement), given the fitting scattering model.

MultiNest-related files produced by this object will go to a directory, under $DMDD_MAIN_PATH, with the name defined by the parameters passed. This directory name will be accessible via self.chainspath after the object is initialized.

Parameters:

• sim_name (str) – The name of the simulation (e.g. ‘sim1’)
• experiments (list) – A list of Experiment objects, or a single such object.
• sim_model (Model) – The true underlying model for the simulations (name cannot have spaces).
• param_values (dict) – The values of the parameters for sim_model.
• fit_model (Model) – The model for MultiNest to fit to the data. Does not have to be the same as sim_model, but can be. Its name cannot have spaces.
• prior_ranges (dict) – Dictionary of prior ranges for parameters of fit_model. e.g. {‘mass’:(1,1000), ‘sigma_si’:(0.1,1e4), etc....}
• prior (str) – either ‘logflat’ or ‘flat’
• sim_root (str) – The path under which to store the simulations.
• chains_root (str) – The path under which to store the Multinest chains.
• force_sim (bool) – If True, then redo the simulations no matter what. If False, then the simulations will be redone if and only if the given simulation parameters don’t match what has already been simulated for this sim_name.
• asimov – Do asimov simulations. Not currently implemented.
• nbins_asimov – Number of asimov bins.
• n_live_points,evidence_tolerance,sampling_efficiency,resume,basename – Parameters to pass to MultiNest, defined in the PyMultiNest documentation.
• silent – If True, then print messages will be suppressed.
• empty_run – if True, then simulations are not initialized.

fit(force_run=False)

Runs MultiNest; parameters set by object initialization.

Parameters:force_run – If True, then fit will re-run; by default, it will not, unless the simulation data has changed, or chains don’t exist.

flat_prior(cube, ndim, nparams)

Flat prior, passed to MultiNest.

Converts unit cube into correct parameter values based on flat prior within range defined by self.prior_ranges.

get_evidence()

Returns evidence from stats file produced by MultiNest.

global_bestfit()

Returns maximum a posteriori values for parameters.

logflat_prior(cube, ndim, nparams)

Logflat prior, passed to MultiNest.

Converts unit cube into correct parameter values based on log-flat prior within range defined by self.prior_ranges.

loglikelihood_total(cube, ndim, nparams)

Log-likelihood function used by MultiNest.

Parameters:ndim, nparams (cube,) – Params required by MulitNest.

return_chains_loglike()

Returns MultiNest chains and equal-weighted posteriors.

visualize(**kwargs)

Makes plots of data for each experiment with theoretical and best-fit models.

Also makes 2-d posteriors for each fitted parameter vs. every other. These plots get saved to self.chainspath.

Parameters:**kwargs –

Keyword arguments passed to dmdd.dmdd_plot.plot_2d_posterior().