nessai.samplers.importancesampler ================================= .. py:module:: nessai.samplers.importancesampler .. autoapi-nested-parse:: Importance nested sampler. .. !! processed by numpydoc !! Classes ------- .. autoapisummary:: nessai.samplers.importancesampler.OrderedSamples nessai.samplers.importancesampler.ImportanceNestedSampler Module Contents --------------- .. py:class:: OrderedSamples(strict_threshold: bool = False, replace_all: bool = False, save_log_q: bool = False) Samples ordered by log-likelihood. :Parameters: **strict_threshold** If true, when adding new samples, only those above the current log-likelihood threshold will be added to the live points. **replace_all** If true, all samples will be remove when calling :code:`remove_samples` **save_log_q** If true, :code:`log_q` will be saved when the instance is pickled. This makes resuming faster but increases the disk usage. If false, the values will not be saved and must be recomputed. .. !! processed by numpydoc !! .. py:property:: live_points :type: numpy.ndarray The current set of live points .. !! processed by numpydoc !! .. py:property:: nested_samples :type: numpy.ndarray The current set of discarded points .. !! processed by numpydoc !! .. py:method:: update_log_likelihood_threshold(threshold: float) -> None Update the log-likelihood threshold. Only relevant if using :code:`strict_threshold=True`. :Parameters: **threshold** : float New log-likelihood threshold .. !! processed by numpydoc !! .. py:method:: sort_samples(samples: numpy.ndarray, *args) -> numpy.ndarray Correctly sort new live points. :Parameters: **x** Array to sort **args** Any extra iterables to sort in the same way as x. .. !! processed by numpydoc !! .. py:method:: add_samples(samples: numpy.ndarray, log_q: numpy.ndarray) -> None Add samples the existing samples .. !! processed by numpydoc !! .. py:method:: add_to_nested_samples(indices: numpy.ndarray) -> None Move a set of samples from the live points to the nested samples .. !! processed by numpydoc !! .. py:method:: remove_samples() -> int Remove samples all samples below the current log-likelihood threshold. :Returns: **n** : int The number of samples removed .. !! processed by numpydoc !! .. py:method:: update_evidence() -> None Update the evidence estimate given the current samples .. !! processed by numpydoc !! .. py:method:: finalise() -> None Finalise the samples by consuming all of the live points .. !! processed by numpydoc !! .. py:method:: compute_importance(importance_ratio: float = 0.5) Compute the importance :Parameters: **importance_factor** Relative importance of the posterior versus the evidence. 1 is only the posterior and 0 is only the evidence. :Returns: dict Dictionary containing the total, posterior and evidence importance as a function of iteration. .. !! processed by numpydoc !! .. py:method:: compute_evidence_ratio(threshold: Optional[float] = None) -> float Compute the evidence ratio given the current log-likelihood threshold. :Parameters: **threshold** Log-likelihood threshold to use instead of the current value. .. !! processed by numpydoc !! .. py:class:: ImportanceNestedSampler(model: nessai.model.Model, nlive: int = 5000, n_initial: Optional[int] = None, output: Optional[str] = None, seed: Optional[int] = None, rng: Optional[numpy.random.Generator] = None, checkpointing: bool = True, checkpoint_interval: int = 600, checkpoint_on_iteration: bool = False, checkpoint_callback: Optional[Callable] = None, save_existing_checkpoint: bool = False, save_log_q: bool = False, logging_interval: int = None, log_on_iteration: bool = True, resume_file: Optional[str] = None, plot: bool = True, plotting_frequency: int = 5, min_iteration: Optional[int] = None, max_iteration: Optional[int] = None, min_samples: int = 500, min_remove: int = 1, max_samples: Optional[int] = None, stopping_criterion: str = 'ratio', tolerance: float = 0.0, n_update: Optional[int] = None, plot_pool: bool = False, plot_level_cdf: bool = False, plot_trace: bool = True, plot_likelihood_levels: bool = True, plot_training_data: bool = False, plot_extra_state: bool = False, trace_plot_kwargs: Optional[dict] = None, replace_all: bool = False, threshold_method: Literal['entropy', 'quantile'] = 'entropy', threshold_kwargs: Optional[dict] = None, n_pool: Optional[int] = None, pool: Optional[Any] = None, check_criteria: Literal['any', 'all'] = 'any', weighted_kl: bool = False, draw_constant: bool = True, train_final_flow: bool = False, bootstrap: bool = False, close_pool: bool = False, strict_threshold: bool = False, draw_iid_live: bool = True, **kwargs: Any) Bases: :py:obj:`nessai.samplers.base.BaseNestedSampler` :Parameters: **model** User-defined model. **nlive** Number of live points. **tolerance** Tolerance for determining when to stop the sampler. **stopping_criterion** Choice of stopping criterion to use. **check_criteria** If using multiple stopping criteria determines whether any or all criteria must be met. **threshold_method** Method for determining new likelihood threshold. **threshold_kwargs** Keyword arguments for function that determines the likelihood threshold. **draw_constant** If specified the sampler will always add a constant number of samples from each proposal whilst removing a variable amount. If False, the the number will depend on the level method chosen. Note that this will override the choice of live points. The number of points draw is set by the live points. **min_samples** Minimum number of samples that are used for training the next normalising flow. **min_remove** Minimum number of samples that can be removed when creating the next level. If less than one, the sampler will stop if the level method determines no samples should be removed. **max_samples** The maximum number of samples at any given iteration. If not specified, then there is no limit to the number of samples. **plot_likelihood_levels** Enable or disable plotting the likelihood levels. **trace_plot_kwargs** Keyword arguments for the trace plot. **strict_threshold** : bool If true, when drawing new samples, only those with likelihoods above the current threshold will be added to the live points. If false, all new samples are added to the live points. **save_log_q** : bool Boolean that determines if the log_q array is saved when checkpointing. If False, this can help reduce the disk usage. .. !! processed by numpydoc !! .. py:property:: posterior_effective_sample_size :type: float The effective sample size of the posterior distribution. Returns the value for the posterior samples from the resampling step if they are available, otherwise falls back to the samples from the initial sampling. .. !! processed by numpydoc !! .. py:property:: samples_entropy :type: float Differential entropy of all of the samples (nested + live). .. rubric:: Notes Compute the Monte Carlo approximation of .. math:: -\int W(x) \log W(x) dx where :math:`W(x) = \pi(x)/Q(x)`. .. !! processed by numpydoc !! .. py:property:: current_proposal_entropy :type: float Differential entropy of the current proposal .. !! processed by numpydoc !! .. py:property:: live_points_unit :type: numpy.ndarray The current set of live points .. !! processed by numpydoc !! .. py:property:: nested_samples_unit :type: numpy.ndarray The current set of discarded points .. !! processed by numpydoc !! .. py:property:: reached_tolerance :type: bool Indicates if tolerance has been reached. Checks if any or all of the criteria have been met, this depends on the value of :code:`check_criteria`. .. !! processed by numpydoc !! .. py:property:: stopping_criteria :type: List[str] The stopping criteria used by the sampler .. !! processed by numpydoc !! .. py:method:: add_fields() :staticmethod: Add extra fields logW, logQ, logU .. !! processed by numpydoc !! .. py:method:: configure_stopping_criterion(stopping_criterion: Union[str, List[str]], tolerance: Union[float, List[float]], check_criteria: Literal['any', 'all']) -> None Configure the stopping criterion .. !! processed by numpydoc !! .. py:method:: get_proposal(subdir: str = 'levels', **kwargs) Configure the proposal. .. !! processed by numpydoc !! .. py:method:: update_output(output: str) -> None Update the output directory and resume file. :Parameters: **output: str** Path to the output directory .. !! processed by numpydoc !! .. py:method:: configure_iterations(min_iteration: Optional[int] = None, max_iteration: Optional[int] = None) -> None Configure the minimum and maximum iterations. Note: will override any existing values when called. .. !! processed by numpydoc !! .. py:method:: check_configuration() -> bool Check sampler configuration is valid. Returns true if all checks pass. .. !! processed by numpydoc !! .. py:method:: populate_live_points() -> None Draw the initial live points from the prior. The live points are automatically sorted and assigned the iteration number -1. .. !! processed by numpydoc !! .. py:method:: initialise() -> None Initialise the nested sampler. Draws live points, initialises the proposal. .. !! processed by numpydoc !! .. py:method:: initialise_history() -> None Initialise the dictionary to store history .. !! processed by numpydoc !! .. py:method:: update_history() -> None Update the history dictionary .. !! processed by numpydoc !! .. py:method:: determine_threshold_quantile(samples: numpy.ndarray, q: float = 0.8, include_likelihood: bool = False) -> int Determine where the next likelihood threshold should be located. Computes the q'th quantile based on log-likelihood and log-weights. :Parameters: **samples** : np.ndarray An array of samples **q** : float Quantile to use. Defaults to 0.8 **include_likelihood** : bool If True, the likelihood is included in the weights. :Returns: int The number of live points to discard. .. !! processed by numpydoc !! .. py:method:: determine_threshold_entropy(samples: numpy.ndarray, q: float = 0.5, include_likelihood: bool = False, use_log_weights: bool = True) -> int Determine where the next likelihood threshold should be located using the entropy method. :Parameters: **q** Fraction by which to shrink the current level. **include_likelihood** Boolean to indicate whether the likelihood is included in the weights for each samples. **use_log_weights** Boolean to determine if the CDF is computed using the weights or log-weights. .. !! processed by numpydoc !! .. py:method:: plot_level_cdf(log_likelihood_values: numpy.ndarray, cdf: numpy.ndarray, threshold: float, q: float, filename: Optional[str] = None) -> Union[matplotlib.figure.Figure, None] Plot the CDF of the log-likelihood :Parameters: **log_likelihood_values** : np.ndarray The log-likelihood values for the CDF **cdf** : np.ndarray The CDF to plot **filename** : Optional[str] Filename for saving the figure. If not specified the figure will be returned instead. :Returns: matplotlib.figure.Figure Level CDF figure. Only returned when the filename is not specified. .. !! processed by numpydoc !! .. py:method:: determine_log_likelihood_threshold(samples: numpy.ndarray, method: Literal['entropy', 'quantile'] = 'entropy', **kwargs) -> int Determine the next likelihood threshold :Parameters: **samples** : numpy.ndarray An array of samples **method** : Literal["entropy", "quantile"] The method to use **kwargs** Keyword arguments passed to the function for the chosen method. :Returns: float The log-likelihood threshold .. !! processed by numpydoc !! .. py:method:: add_new_proposal() Add a new proposal to the meta proposal .. !! processed by numpydoc !! .. py:method:: draw_n_samples(n: int, **kwargs) Draw n samples from the current proposal Includes computing the log-likelihood of the samples :Parameters: **n** : int Number of samples to draw **kwargs** Keyword arguments passed to the :code:`draw` method of the proposal class. .. !! processed by numpydoc !! .. py:method:: compute_leakage(samples: numpy.ndarray, weights: bool = True) -> float Compute the leakage for a number of samples. :Parameters: **samples** : numpy.ndarray Array of samples. **weights** : bool If True, the weight of each sample is accounted for in the calculation. :Returns: float The leakage as a fraction of the total number of samples (or effective sample size if weights is True). .. !! processed by numpydoc !! .. py:method:: add_and_update_points(n: int) Add new points to the current set of live points. :Parameters: **n** : int The number of points to add. .. !! processed by numpydoc !! .. py:method:: remove_samples() -> int Remove samples from the current set of live points. .. !! processed by numpydoc !! .. py:method:: adjust_final_samples(n_batches=5) Adjust the final samples .. !! processed by numpydoc !! .. py:method:: finalise() -> None Finalise the sampling process. .. !! processed by numpydoc !! .. py:method:: add_level_post_sampling(samples: numpy.ndarray, n: int) -> None Add a level to the nested sampler after initial sampling has completed. .. !! processed by numpydoc !! .. py:method:: compute_stopping_criterion() -> List[float] Compute the stopping criterion. The method used will depend on how the sampler was configured. .. !! processed by numpydoc !! .. py:method:: checkpoint(periodic: bool = False, force: bool = False) Checkpoint the sampler. .. !! processed by numpydoc !! .. py:method:: log_state() Log the state of the sampler .. !! processed by numpydoc !! .. py:method:: update_proposal_weights() Update the proposal weights based on the current sample counts. Uses the values from :code:`sample_counts`. See also: code:`update_sample_counts`. .. !! processed by numpydoc !! .. py:method:: update_sample_counts() -> None Update the sample counts for each proposal based on the current samples. Uses the samples from :code:`samples_unit` See also: :code:`update_proposal_weights`. .. !! processed by numpydoc !! .. py:method:: add_new_proposal_weight(iteration: int, n_new: int) -> None Set the weights for a new proposal. Samples cannot have been drawn from the proposal already. .. !! processed by numpydoc !! .. py:method:: nested_sampling_loop() Main nested sampling loop. .. !! processed by numpydoc !! .. py:method:: draw_posterior_samples(sampling_method: str = 'rejection_sampling', n: Optional[int] = None, use_final_samples: bool = True) -> numpy.ndarray Draw posterior samples from the current nested samples. .. !! processed by numpydoc !! .. py:method:: kl_divergence(samples: numpy.ndarray) -> float :staticmethod: Compute the KL divergence between the meta-proposal and posterior. Uses all samples drawn from the meta-proposal .. !! processed by numpydoc !! .. py:method:: draw_more_nested_samples(n: int) -> numpy.ndarray Draw more nested samples from g .. !! processed by numpydoc !! .. py:method:: draw_final_samples(n_post: Optional[int] = None, n_draw: Optional[int] = None, max_its: int = 1000, max_batch_size: int = 20000, max_samples_ratio: Optional[float] = 1.0, use_counts: bool = False, optimise_weights: bool = False, optimise_kwargs: Optional[dict] = None, optimisation_method: Literal['evidence', 'kl'] = 'kl') Draw final unbiased samples until a desired ESS is reached. The number of samples drawn is based on the efficiency of the existing nested samples up to a maximum size determined by :code:`max_batch_size` or on the value of :code:`n_draw. The number is increased by 1% to account for samples being rejected. Returns nested samples, NOT posterior samples. Restarts the multiprocessing pool for evaluations the likelihood. :Parameters: **n_post** Target effective sample size for the posterior distribution. May not be reached if max_its is reached first. If not specified then the number of samples drawn will match the nested samples. **n_draw** Number of samples to draw from the meta proposal. Should only be specified if not specifying :code:`n_post`. **max_its** Maximum number of iterations before stopping. **max_batch_size** Maximum number of samples to draw in a single batch. **max_samples_ratio** Maximum number of samples in terms of the number of samples drawn during sampling. For example if :code:`max_samples=1`, up to half the initial number of samples will be drawn. If None, no limit is set. **optimise_weights** If True, the weights for each proposal are optimised before redrawing the samples. **optimise_kwargs** Keyword arguments passed to the optimiser function. **use_counts** Use the exact counts for each proposal rather than the weights. Not recommended. Ignored if :code:`optimise_weights` is True. :Returns: log_evidence The log evidence for the new samples samples Structured array with the new nested samples. .. !! processed by numpydoc !! .. py:method:: train_final_flow() Train a final flow using all of the nested samples .. !! processed by numpydoc !! .. py:method:: plot_state(filename: Optional[str] = None) -> Optional[matplotlib.figure.Figure] Produce plots with the current state of the nested sampling run. Plots are saved to the output directory specified at initialisation. :Parameters: **filename** If specified the figure will be saved, otherwise the figure is returned. .. !! processed by numpydoc !! .. py:method:: plot_extra_state(filename: Optional[str] = None) -> Union[matplotlib.figure.Figure, None] Produce a state plot that contains extra tracked statistics. :Parameters: **filename** : Optional[str] Filename name for the plot when saved. If specified the figure will be saved, otherwise the figure is returned. :Returns: Union[matplotlib.figure.Figure, None] Returns the figure if a filename name is not given. .. !! processed by numpydoc !! .. py:method:: plot_trace(enable_colours: bool = True, filename: Optional[str] = None) -> Union[matplotlib.figure.Figure, None] Produce a trace-like plot of the nested samples. :Parameters: **enable_colours** : bool If True, the iteration will be plotted on the colour axis. If False, the points will be plotted with a single colour. **filename** : Optional[str] Filename for saving the figure. If not specified the figure will be returned instead. :Returns: matplotlib.figure.Figure Trace plot figure. Only returned when the filename is not specified. .. !! processed by numpydoc !! .. py:method:: plot_likelihood_levels(filename: Optional[str] = None, cmap: str = 'viridis', max_bins: int = 50) -> Optional[matplotlib.figure.Figure] Plot the distribution of the likelihood at each level. :Parameters: **filename** Name of the file for saving the figure. If not specified, then the figure is returned. **cmap** Name of colourmap to use. Must be a valid colourmap in matplotlib. **max_bins** The maximum number of bins allowed. .. !! processed by numpydoc !! .. py:method:: produce_plots(override: bool = False) -> None Produce all of the relevant plots. Checks if plotting is enabled. :Parameters: **force** : bool Override the plotting setting and force the plots to be produced. .. !! processed by numpydoc !! .. py:method:: get_result_dictionary() Get a dictionary contain the main results from the sampler. .. !! processed by numpydoc !! .. py:method:: resume_from_pickled_sampler(sampler, model, flow_config=None, weights_path=None, **kwargs) :classmethod: Resume from a pickled sampler. :Parameters: **sampler** : Any Pickled sampler. **model** : :obj:`nessai.model.Model` User-defined model **flow_config** : Optional[dict] Dictionary for configuring the flow **weights_path** : Optional[dict] Path to the weights files that will override the value stored in the proposal. **kwargs** Keyword arguments passed to the parent class's method. :Returns: Instance of ImportanceNestedSampler .. .. !! processed by numpydoc !!