Read in the PEDESTAL values from a *fitopt.fits file

    Parameters
    ----------
    filename : str
        Name of output file to check. This should be a *fitopt.fits file.

    refpix : tup
        4-element tuple listing the number of outer rows and columns that
        are reference pixels

    Returns
    -------
    pedestal : numpy.ndarray
        3D array of pedestal values (signal extrapolated to time=0)


Read in the PEDESTAL values from a *fitopt.fits file

    Parameters
    ----------
    filename : str
        Name of uncalibrated file. This should be a *uncal.fits file.

    refpix : tup
        4-element tuple listing the number of outer rows and columns that
        are reference pixels

    Returns
    -------
    group2 : numpy.ndarray
        3D array of group 2


Read in the science extension from a group of slope images

    Parameters
    ----------
    filenames : list
        List of fits files containing slope values

    Returns
    -------
    instrument : str
        Name of instrument associated with the data

    slope_data : numpy.ndarray
        3D array containing slope values for science pixels only.
        Reference pixels have been stripped off.

    starting_indexes : list
        List of numbers corresponding to the index numbers within slope_data
        where each file's data begins. For example, if slope_data is an array
        of size (10, 2048, 2048), and starting_indexes = [0, 5, 7, 10] then
        we can pull apart slope_data into its constituent exposures using
        slope_data[starting_indexes[0]: starting_indexes[1]], etc.

    left_cols : int
        Number of columns of reference pixels on the left side of the array

    right_cols : int
        Number of columns of reference pixels on the right side of the array

    bottom_rows : int
        Number of rows of reference pixels on the bottom of the array

    top_rows : int
        Number of rows of reference pixels on the top of the array


Read in the science extension from a group of slope images

    Parameters
    ----------
    filenames : list
        List of fits files containing slope values

    refpix : tup
        4-element tuple listing the number of outer rows and columns that
        are reference pixels

    Returns
    -------
    slope : numpy.ndarray
        2D or 3D array of slope values (signal extrapolated to time=0)
        Reference pixels have been stripped off.


Read in the science extension from a group of slope images

    Parameters
    ----------
    filenames : list
        List of fits files containing slope values

    Returns
    -------
    slope_data : numpy.ndarray
        3D array containing slope values for science pixels only.
        Reference pixels have been stripped off.

    left_cols : int
        Number of columns of reference pixels on the left side of the array

    right_cols : int
        Number of columns of reference pixels on the right side of the array

    bottom_rows : int
        Number of rows of reference pixels on the bottom of the array

    top_rows : int
        Number of rows of reference pixels on the top of the array


Generate a list of pixels that are saturated in all groups

    Parameters
    ----------
    pedestal_array : numpy.ndarray
        2D array of pedestal values (signal extrapolated to time=0)

    first_group_sat: numpy.ndarray
        2D array of the first group DQ containing either 0 = not saturated or 2 = saturated.

    Returns
    -------
    full_saturation : numpy.ndarray
        Boolean array describing which pixels are saturated in all reads


 Plot an Image

    Parameters
    ----------
    image : numpy.ndarray
         2D image to plot

    image_max :  float
         maximum of image to use for scaling the image

    titleplot : string
         title of the plot

    fileout : string
         output file of the plot

    Returns
    -------
      prints the plot to disk


 Plot a histogram of stats and over the upper limit cut off

    Parameters
    ----------
    data_array : numpy.ndarray
         2D data to make a histogram from
    sigma_threshold :  float
         used to plotting sigma clip line on plot
    nbins : integer
         number of bins in creating histogram
    titleplot : string
         title of the plot
    fileout : string
         output file of the plot

    Returns
    -------
      prints the plot to disk


Call the dark current algorithm. The only requirement is that the output
        reference file is saved as self.args.outputreffilename

        mkrefs.py will supply the input files in self.inputimages['output_name'].
        This will be a list containing the filenames to use as input. The
        file types (e.g. dark, flat) associated with each filename are
        contained in self.inputimages['imtype']. From this, you can specify
        the appropriate file names in the call to your module.


Return boolean indicating whether ``pathname`` has the specified
    owner, permission, and group scheme.

    Parameters
    ----------
    pathname : str
        Directory or file to be inspected
    owner : str
        String representation of the owner
    mode : int
        Integer representation of the permission mode, compatible
        with ``os.stat`` output
    group : str
        String representation of the group
    verbose : bool
        Boolean indicating whether verbose output is requested

    Returns
    -------
    boolean : bool


if file exists, remove it


 execute the given command cmd as a shell command.

    cmdlog and errorlog can be a filename or a file handle.

    clobbercmdlog=True and cmdlog_access_mode only apply if cmdlog is
    a filename. log_access_mode can be all allowed access_mode values
    for subprocess.Popen.  if clobbercmdlog=True, the cmdlog file is
    deleted before logging begins, even if cmdlog_access_mode='a'.

    if cmdlog!=None: As default, cmdlog_save_as_chunk_flag=True, which
    means that the output of the cmd is save in cmdlog *after* the
    command is finished. If there is an error, it could be that then
    the output is not saved in the cmdlog, thus for debugging, the
    user can set cmdlog_save_as_chunk_flag=False, and then each
    individual output line is immediately saved into cmdlog

    The output of the command is shown on screen in real-time if
    verbose>1.

    The errorlog captures the stderr output. By default, old errors
    are not deleted (i.e. errorlog_access_mode='a'). If there is an
    error, this routine returns 1

    if return_output=True, then the stdout and stderr are returned as
    lists: (returncode,stdout_lines,stderr_lines). Otherwise, only
    retruncode is returned


Loop through all string parameters and substitute environment variables


 check if all the parameters in the newparams already
        exist. Throw a Runtime Error if requireParamExists=True and
        parameter does not exist. Then add them


Transform a 4D array containing cosmic ray hit locations
    (1 for CR hit, 0 for no hit), into a 3D (integration, y, x)
    map that lists for each pixel the group number of the first
    CR hit. If that pixel has no CR hits in the integration, then
    it will have a value of NaN.

    Parameters
    ----------
    dq_map : numpy.ndarray
        4D array of CR hit locations

    Returns
    -------
    index_map : numpy.ndarray
        3D array of group numbers of the first CR hit in each pixel


Create a map of reference pixel locations in a given file.
    Reference pixels have a value of 1. Other pixels have a value
    of zero.

    Parameters
    ----------
    filename : str
        Name of FITS file containing the data quality information

    Returns
    -------
    refmap : numpy.ndarray
        2D array containing a map of reference pixels. 1 indicates a
        reference pixel, while 0 indicates a science pixel


Read in ``filename``, which is assumed to be a 4D ramp, extract
    the DQ bits associated with JUMPS, and return a map containing only
    those bits.


Translate an array that lists the number of good groups per
    integration with good signal into an array that shows the number
    of good signal values per group (i.e. look across integrations)

    Parameters
    ----------
    number_of_good : numpy.ndarray
        3D array (integration, y, x) of the number of good groups per
        integration.

    ngroup : int
        The total number of groups in an integration

    Returns
    -------
    good_per_group : numpy.ndarray
        3D array (group, y, x) giving the number of good signal values
        within each group

    bad_per_group : numpy.ndarray
        3D array (group, y, x) giving the number of bad signal values
        within each group


Make sure that the pedigree entry is one of the valid options

    Parameters
    ----------
    value : str
        Pedigree value


Make sure that the use_after entry is the correct format

    Parameters
    ----------
    value : str
        Use after value


Configure the log file with a standard logging format.

    Parameters
    ----------
    module : str
        The name of the module being logged.

    path : str
        Where to write the log if user-supplied path; default to working dir.

    log_file_level : str
        Minimum message level to route to the output log file.
        Allowed values: "debug", "info", "warning", "ciritical"

    log_screen_level : str
        Minimum message level to route to the screen.
        Allowed values: "debug", "info", "warning", "ciritical"

    Returns
    -------
    log_file : str
        Name and path of the output log file


Decorator to log useful system information.

    This function can be used as a decorator to log user environment
    and system information. Future packages we want to track can be
    added or removed as necessary.

    Parameters
    ----------
    func : func
        The function to decorate.

    Returns
    -------
    wrapped : func
        The wrapped function.


Read in the science extension from a group of slope images

    Parameters
    ----------
    filename : list
        Name of FITS file containing the data

    integ_number : int
        Integration number of the exposure to be read in. If None, all
        integrations are read in

    min_group : int
        Minimum group number to be read in.

    max_group : int
        Maximum group number to be read in. If None then all groups from
        ``min_group`` to the end are read in.

    extension : str
        Extension name within the FITS file to be read in

    Returns
    -------
    data : numpy.ndarray
        Array of data


Create a dictionary of pipeline steps with boolean entries
    given a list of steps to be set to True

    Parameters
    ----------
    steplist : str
        Comma separated list of pipeline steps to set to True

    Returns
    -------
    step_dict : dict
        Dictionary with requested steps set to True


Create instance of calibPrep and prepare for later tests


    Checks if all values in provided input argument `values` with `name` meet
    all criteria given in `args`. If no criteria are given, it is checked if
    all values are finite.
    Returns `values` (0 or 1 in case of bool) if *True* and raises a
    :class:`~ValueError` or :class:`~TypeError` if *False*.

    Parameters
    ----------
    values : array_like of {int, float, str, bool}
        The values to be checked against all given criteria in `args`.
    name : str
        The name of the input argument, which is used in the error message if
        a criterion is not met.
    args : tuple of {'bool', 'float', 'int', 'neg', 'nneg', 'normal', 'npos', \
        'nzero', 'pos', 'str'}
        Sequence of strings determining the criteria that `values` must meet.
        If `args` is empty, it is checked if `values` are finite.

    Returns
    -------
    return_values : array_like of {int, float, str}
        If `args` contained 'bool', returns 0 or 1. Else, returns `values`.

    Notes
    -----
    If `values` is array_like, every element is replaced by its checked values
    (0s or 1s in case of bools, or ints converted to floats in case of floats).
    Because of this, a copy will be made of `values`. If this is not possible,
    `values` is adjusted in place.


    Opens a logging file called `filename` in the current working directory,
    opened with `mode` and starts the logger.

    Optional
    --------
    filename : str or None. Default: None
        String containing the name of the log-file that is opened.
        If *None*, a new log-file will be created.


    Determines the active parameters to be used for every individual data
    point in the provided emulator iteration `emul_i`. Uses backwards
    stepwise elimination to determine the set of active parameters.

    Parameters
    ----------
    %(emul_i)s

    Generates
    ---------
    active_par : 1D :obj:`~numpy.ndarray` object
        Array containing the indices of all the parameters that are active
        in the emulator iteration `emul_i`.
    active_par_data : List of 1D :obj:`~numpy.ndarray` objects
        List containing the indices of all the parameters that are active
        in the emulator iteration `emul_i` for every individual data point.


    Reads in the pipeline parameters from the provided HDF5-file and saves
    them in the current :obj:`~Pipeline` instance.


    Opens the HDF5-file `filename` according to some set of default
    parameters and returns the opened HDF5-object.

    Parameters
    ----------
    mode : {'r', 'r+', 'w', 'w-'/'x', 'a'}
        String indicating how the HDF5-file needs to be opened.

    Optional
    --------
    filename : str. Default: None
        The name/path of the HDF5-file that needs to be opened in
        `working_dir`. Default is to open the HDF5-file that was provided
        during class initialization.
    **kwargs : dict. Default: {'driver': None, 'libver': 'earliest'}
        Other keyword arguments that need to be given to the
        :func:`~h5py.File` function.

    Returns
    -------
    file : :obj:`~h5py._hl.files.File` object
        Opened HDF5-file object.


    Closes the opened HDF5-file object `file`. This method exists only
    for logging purposes.

    Parameters
    ----------
    file : :obj:`~h5py._hl.files.File` object
        Opened HDF5-file object requiring closing.


    bool: Whether or not all MPI ranks are in worker mode, in which all
    worker ranks are listening for calls from the controller rank. If
    *True*, all workers are continuously listening for calls made with
    :meth:`~_make_call` until set to *False*.
    By default, this is *False*.

    Setting this value to *True* allows for easier use of *PRISM* in
    combination with serial/OpenMP codes (like MCMC methods).


    Checks if the provided `emul_version` is compatible with the current
    version of *PRISM*.
    Raises a :class:`~RequestError` if *False* and indicates which version of
    *PRISM* still supports the provided `emul_version`.


    Checks if all values in provided input argument `values` with `name` meet
    all criteria given in `args`. If no criteria are given, it is checked if
    all values are finite.
    Returns `values` (0 or 1 in case of bool) if *True* and raises a
    :class:`~ValueError` or :class:`~TypeError` if *False*.

    Parameters
    ----------
    values : array_like of {bool; complex; float; int; str}
        The values to be checked against all given criteria in `args`. It must
        be possible to convert `values` to a :obj:`~numpy.ndarray` object.
    name : str
        The name of the input argument, which is used in the error message if
        a criterion is not met.
    args : positional arguments in {'bool'; 'complex'; 'float'; 'int'; 'neg'; \
                                    'nneg'; 'normal'; 'npos'; 'nzero'; 'pos'; \
                                    'str'}
        Sequence of strings determining the criteria that `values` must meet.
        If `args` is empty, it is checked if `values` are finite.

    Returns
    -------
    return_values : array_like of {complex; float; int; str}
        If `args` contained 'bool', returns 0s or 1s. Else, returns `values`.

    Notes
    -----
    If `values` contains integers, but `args` contains 'float', `return_values`
    will be cast as float.


    Moves the base :class:`~PRISM_Logger` from the current working directory to
    the given `working_dir`, and then restarts it again.

    Parameters
    ----------
    working_dir : str
        String containing the directory the log-file needs to be moved to.


Returns ``np.array(obj, *args, copy=False, **kwargs)``.


        Analyzes the emulator iteration `emul_i` and constructs a series of
        projection figures detailing the behavior of the model parameters
        corresponding to the given `proj_par`.
        The input and output depend on the number of model parameters
        :attr:`~prism.modellink.ModelLink.n_par`.

        All optional keyword arguments (except `force`) control various aspects
        of drawing the projection figures and do not affect the projection data
        that is saved to HDF5. This is instead influenced by the
        :attr:`~proj_res` and :attr:`~proj_depth` properties.

        Parameters
        ----------
        %(emul_i)s
        %(proj_par)s

        Keyword arguments
        -----------------
        proj_type : {'2D'; '3D'; '2D+3D'}. Default: '2D' (2D), '2D+3D' (nD)
            String indicating which projection type to create for all supplied
            active parameters.
            If :attr:`~prism.modellink.ModelLink.n_par` == 2, this is always
            '2D' (and cannot be modified).
        figure : bool. Default: True
            Whether or not to create the projection figures. If *True*, the
            figures are calculated, drawn and saved. If *False*, the figures
            are calculated and their data is returned in a dict.
        align : {'row'/'horizontal'; 'col'/'column'/'vertical'}. Default: 'col'
            If `figure` is *True*, string indicating how to position the two
            subplots.
            If 'row'/'horizontal', the subplots are positioned on a single row.
            If 'col'/'column'/'vertical', the subplots are positioned on a
            single column.
        show_cuts : bool. Default: False
            If `figure` is *True* and `proj_type` is not '3D', whether to show
            all implausibility cut-offs in the 2D projections (*True*) or only
            the first cut-off (*False*).
        smooth : bool. Default: False
            Controls what to do if a grid point contains no plausible samples,
            but does contain a minimum implausibility value below the first
            non-wildcard cut-off.
            If *False*, these values are kept, which can show up as
            artifact-like features in the projection figure.
            If *True*, these values are set to the first cut-off, removing them
            from the projection figure. Doing this may also remove interesting
            features. This does not affect the projection data saved to HDF5.
            Smoothed figures have an '_s' string appended to their filenames.
        use_par_space : bool. Default: False
            Controls whether to use the model parameter space (*True*) or the
            parameter space in which emulator iteration `emul_i` is defined
            (*False*) as the axes limits in the projection figure.
            If this is *True* and a parameter estimate is outside of the axes
            limit, a parameter estimate arrow is used instead of a line.
        full_impl_rng : bool. Default: False
            Controls whether to use zero (*True*) or the lowest plotted value
            (*False*) as the lower bound for the minimum implausibility plot.
            Set this to *True* for the same plotting behavior as in versions
            earlier than v1.2.4.

            .. versionadded:: 1.2.4
        force : bool. Default: False
            Controls what to do if a projection hypercube has been calculated
            at the emulator iteration `emul_i` before.
            If *False*, it will use the previously acquired projection data to
            create the projection figure.
            If *True*, it will recalculate all the data required to create the
            projection figure. Note that this will also delete all associated
            projection figures.
        fig_kwargs : dict. Default: {'dpi': 100}
            Dict of keyword arguments to be used when creating the subplots
            figure. It takes all optional arguments that can be provided to the
            :func:`~matplotlib.pyplot.figure` function.
        impl_kwargs_2D : dict. Default: {}
            Dict of keyword arguments to be used for making the minimum
            implausibility (top/left) plot in the 2D projection figures. It
            takes all optional arguments that can be provided to the
            :func:`~matplotlib.pyplot.plot` function.
        impl_kwargs_3D : dict. Default: {'cmap': 'cmr.rainforest_r'}
            Dict of keyword arguments to be used for making the minimum
            implausibility (top/left) plot in the 3D projection figures. It
            takes all optional arguments that can be provided to the
            :func:`~matplotlib.pyplot.hexbin` function.
        los_kwargs_2D : dict. Default: {}
            Dict of keyword arguments to be used for making the line-of-sight
            (bottom/right) plot in the 2D projection figures. It takes all
            optional arguments that can be provided to the
            :func:`~matplotlib.pyplot.plot` function.
        los_kwargs_3D : dict. Default: {'cmap': 'cmr.freeze'}
            Dict of keyword arguments to be used for making the line-of-sight
            (bottom/right) plot in the 3D projection figures. It takes all
            optional arguments that can be provided to the
            :func:`~matplotlib.pyplot.hexbin` function.
        line_kwargs_est : dict. Default: {'linestyle': '--', 'color': 'grey'}
            Dict of keyword arguments to be used for drawing the parameter
            estimate lines in both plots. It takes all optional arguments that
            can be provided to the :func:`~matplotlib.pyplot.plot` function.
        arrow_kwargs_est : dict. Default: {'color': 'grey', \
            'fh_arrowlength': 0.015, 'fh_arrowwidth': 0.025, 'ft_arrowlength':\
            1.5, 'ft_arrowwidth': 0.003, 'rel_xpos': 0.5, 'rel_ypos': 0.5}
            Dict of keyword arguments to be used for drawing the parameter
            estimate arrows in both plots. It takes a special set of arguments
            that are described in the `Notes`_.
        line_kwargs_cut : dict. Default: {'color': 'r'}
            Dict of keyword arguments to be used for drawing the implausibility
            cut-off line(s) in the top/left plot in the 2D projection figures.
            It takes all optional arguments that can be provided to the
            :func:`~matplotlib.pyplot.plot` function.

        Returns (if `figure` is *False*)
        --------------------------------
        fig_data : dict of dicts
            Dict containing the data for every requested projection figure,
            split up into the 'impl_min' and 'impl_los' dicts. For 2D
            projections, every dict contains a list with the x and y values.
            For 3D projections, it contains the x, y and z values.
            Note that due to the figures being interpolations, the y/z values
            can be below zero or the line-of-sight values being above unity.

        Generates (if `figure` is *True*)
        ---------------------------------
        A series of projection figures detailing the behavior of the model.
        The lay-out and output of the projection figures depend on the type of
        figure:

            2D projection figure: The output will feature a figure with two
            subplots for every active model parameter (``n_par``). Every figure
            gives details about the behavior of the corresponding model
            parameter, by showing the minimum implausibility value (top/left)
            and the line-of-sight depth (bottom/right) obtained at the
            specified parameter value, independent of the values of the other
            parameters.

            3D projection figure (only if
            :attr:`~prism.modellink.ModelLink.n_par` > 2): The output
            will feature a figure with two subplots for every combination of
            two active model parameters that can be made
            (``n_par*(n_par-1)/2``). Every figure gives details about the
            behavior of the corresponding model parameters, as well as their
            dependency on each other. This is done by showing the minimum
            implausibility (top/left) and the line-of-sight depth
            (bottom/right) obtained at the specified parameter values,
            independent of the values of the remaining model parameters.

        Notes
        -----
        All colormaps defined in the :mod:`~cmasher` package are loaded
        automatically when *PRISM* is imported and can be used.

        Some `kwargs` dicts have a subset of arguments that are reserved for
        this function (like `x`/`y` for `impl_kwargs_2D` and co.). These
        arguments are ignored when provided.

        The `arrow_kwargs_est` argument takes all optional arguments that
        :func:`~matplotlib.pyplot.arrow` takes, plus a few special arguments
        that are described below:

            fh_arrowlength : float. Default: 0.015
                The fraction of the appropriate axis limit used as the length
                of the arrow head.
            fh_arrowwidth : float. Default: 0.03
                The fraction of the appropriate axis limit used as the width
                of the arrow head.
            ft_arrowlength : float. Default: 1.5
                The relative length of the arrow tail compared to its head.
            ft_arrowwidth : float. Default: 0.002
                The fraction of the appropriate axis limit used as the width
                of the arrow tail.
            rel_xpos : float. Default: 0.5
                The relative x-position of the arrow. Only used if the arrow is
                drawn vertically and has no anchor in 3D projections.
            rel_ypos : float. Default: 0.5
                The relative y-position of the arrow. Only used if the arrow is
                drawn horizontally and has no anchor in 3D projections.


        int: %(proj_depth)s
        Note that when making 2D projections of nD models, the used depth will
        be this number multiplied by :attr:`~proj_res`.


        Draws parameter estimate arrow and lines in the given `ax`, for the
        provided estimates `par_est1` and `par_est2`.
        Whether an arrow and/or a line is drawn, and what their layout and
        position is, depends on the given estimate values.

        Parameters
        ----------
        par_est1, par_est2 : float or None
            The parameter estimates for which an arrow or line must be drawn.
            If the estimate is within the axes limits, a line is drawn.
            If the estimate is outside of the axes limits, an arrow is drawn in
            the direction of `(par_est1, par_est2)`.
            If *None*, a default value is used for the respective argument.
        ax : :obj:`~matplotlib.axes.Axes` object
            The Axes object in which the arrow and lines must be drawn.

        Note
        ----
        Because the arrow is drawn using relative DPI-coordinates, the axes
        limits and positions of `ax` must be final before calling this
        function.


        Returns the projection data belonging to the provided hypercube
        `hcube`.

        Parameters
        ----------
        %(hcube)s

        Returns
        -------
        proj_data : dict
            Dict containing all the data associated with the specified `hcube`.


        Reads in and transforms the projection parameter space hypercube that
        is stored in the provided `hcube_group`.

        Parameters
        ----------
        hcube_group : :obj:`~h5py.Group` object
            The HDF5-group from which the projection parameter space hypercube
            needs to be read in.

        Returns
        -------
        proj_space : 2D :obj:`~numpy.ndarray` object
            The read-in hypercube boundaries.


        Determines which projection hypercubes have been requested by the user.
        Also checks if these projection hypercubes have been calculated before,
        and depending on the value of :attr:`~force`, either skips them or
        recreates them.

        Parameters
        ----------
        %(emul_i)s
        %(proj_par)s

        Generates
        ---------
        hcubes : list of lists
            List containing the parameter indices of the requested projection
            hypercubes.
        create_hcubes : list of lists
            List containing the parameter indices of the requested projection
            hypercubes that need to be created first.


        Determines the name of a provided projection hypercube `hcube` and
        returns it.

        Parameters
        ----------
        %(hcube)s

        Returns
        -------
        hcube_name : str
            The name of this projection hypercube.


        Determines the absolute path of a projection figure corresponding to a
        provided projection hypercube `hcube` and returns it.

        Parameters
        ----------
        hcube : 1D array_like of int of length {2, 3} or str
            Array containing the internal integer identifiers of the main model
            parameters that require a projection hypercube.
            If str, the name of `hcube` instead
            (:meth:`~_Projection__get_hcube_name`).

        Returns
        -------
        fig_path : str
            The absolute path to the requested projection figure.
        fig_path_s : str
            The absolute path to the smoothed version.


        Generates a dict containing default values for all input arguments.

        Returns
        -------
        kwargs_dict : dict
            Dict containing all default input argument values.


        Returns the indices of all parameters that are in the grid points of
        the given projection hypercube `hcube`.

        Parameters
        ----------
        %(hcube)s

        Returns
        -------
        grid_idx : list of int
            Indices of all grid point parameters.


        Generates a projection hypercube `hcube` containing emulator evaluation
        samples The output of this function depends on the requested projection
        type.

        Parameters
        ----------
        %(hcube)s

        Returns
        -------
        proj_hcube : 3D :obj:`~numpy.ndarray` object
            3D projection hypercube of emulator evaluation samples.
            For 3D projections, the grid uses matrix indexing (second parameter
            varies the fastest).


        Analyzes an emulator projection hypercube `hcube`.

        Parameters
        ----------
        %(hcube)s

        Returns
        -------
        %(proj_data)s


        Processes the input arguments given to the :meth:`~project` method.

        Parameters
        ----------
        %(emul_i)s
        kwargs : keyword arguments
            Keyword arguments that were provided to :meth:`~project`.

        Generates
        ---------
        All default and provided arguments are saved to their respective
        properties.


        Prepares the pipeline for the creation of the requested projections.

        Parameters
        ----------
        %(emul_i)s
        %(proj_par)s
        kwargs : keyword arguments
            Keyword arguments that were provided to :meth:`~project`.


        Returns the boundaries of the hypercube that encloses the parameter
        space in which the projection space of the provided emulator iteration
        `emul_i` is defined.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        proj_space : 2D :obj:`~numpy.ndarray` object
            The requested hypercube boundaries.


        Saves a given data dict ``{keyword: data}`` at the emulator iteration
        this class was initialized for, to the HDF5-file.

        %(save_data)s


        :obj:`~mpi4pyd.MPI.Intracomm`: The MPI intra-communicator that is used
        in this :obj:`~Pipeline` instance. By default, this is
        :obj:`MPI.COMM_WORLD`.


        int: The rank of this MPI process in :attr:`~comm`. If no MPI is used,
        this is always 0.


        int: The number of MPI processes in :attr:`~comm`. If no MPI is used,
        this is always 1.


        bool: Whether or not this MPI process is a controller rank. If no MPI
        is used, this is always *True*.


        bool: Whether or not this MPI process is a worker rank. If no MPI is
        used, this is always *False*.


        :obj:`~prism._pipeline.WorkerMode`: Special context manager within
        which all code is executed in worker mode. In worker mode, all worker
        ranks are continuously listening for calls from the controller rank
        made with :meth:`~_make_call` or :meth:`~_make_call_workers`.

        Note that all code within the context manager is executed by all ranks,
        with the worker ranks executing it after the controller rank exits.
        It is therefore advised to use an if-statement inside to make sure only
        the controller rank executes the code.

        Using this context manager allows for easier use of *PRISM* in
        combination with serial/OpenMP codes (like MCMC methods). It also makes
        it easier to write long complex code that is mostly executed on the
        controller rank (but the worker ranks sometimes need to execute
        something).

        All worker modes are independent of each other and can be created in a
        nested fashion.


        bool: Whether or not to save all logging messages. If *False*, all
        logging messages of level :attr:`~logging.INFO` and below are ignored.
        It also enables/disables the progress bar when making projections.


str: Absolute path to the root directory.


str: Absolute path to the working directory.


str: Absolute path to the loaded master HDF5-file.


        dict: Dictionary containing all *PRISM* parameters that were provided
        during :class:`~Pipeline` initialization.


        :class:`~h5py.File`: Custom :class:`~h5py.File` class that has added
        logging and automatically uses :attr:`~hdf5_file` as the HDF5-file to
        open.


        :obj:`~prism.modellink.ModelLink`: The
        :obj:`~prism.modellink.ModelLink` instance provided during
        :class:`~Pipeline` initialization.


        :obj:`~prism.emulator.Emulator`: The :obj:`~prism.emulator.Emulator`
        instance created during :class:`~Pipeline` initialization.


        dict of code object: Collection of pre-compiled built-in code snippets
        that are used in the :meth:`~_evaluate_sam_set` method.


        str, float or None: Value indicating which criterion to use in the
        :func:`~e13tools.sampling.lhd` function.


        bool: Whether or not to do an active parameters analysis during the
        construction of the emulator systems.


        bool: Whether or not previously active parameters always stay active if
        possible.


        list of str: The potentially active parameters. Only parameters from
        this list can become active during the active parameters analysis.
        If :attr:`~do_active_anal` is *False*, all parameters in this list will
        be active.


        int: Number of evaluation samples that will be used to construct the
        first iteration of the emulator systems.


        int: Base number of emulator evaluations used to analyze the emulator
        systems. This number is scaled up by the number of model parameters to
        generate the true number of emulator evaluations (:attr:`~n_eval_sam`).


        list of float: The non-wildcard univariate implausibility cut-off
        values for an emulator iteration. Setting it with the reduced
        implausibility cut-off list will change the values of :attr:`~cut_idx`
        and this property at the last emulator iteration.


        int: The index of the first non-wildcard in a list of implausibility
        values. This is equivalent to the number of wildcards leading the
        cut-off values in :attr:`~impl_cut`.


        int: The number of evaluation samples used to analyze an emulator
        iteration of the emulator systems. The number of plausible evaluation
        samples is stored in :attr:`~n_impl_sam`.
        It is zero if the specified iteration has not been analyzed yet.


        int: Number of model evaluation samples that passed the implausibility
        checks during the analysis of an emulator iteration.
        It is zero if the specified iteration has not been analyzed yet or has
        no plausible samples.


        list of dict: The model evaluation samples that will be added to the
        next emulator iteration.


        Evaluates the model for provided evaluation sample set `sam_set` at
        given data points `data_idx`.

        This method automatically distributes the samples according to the
        various flags set in the :class:`~prism.modellink.ModelLink` subclass.

        Parameters
        ----------
        %(emul_i)s
        sam_set : 1D or 2D array_like
            Parameter/sample set to evaluate in the model.
        data_idx : list of tuples
            The list of data identifiers for which the model is requested to
            return the corresponding data values.

        Returns
        -------
        sam_set : 2D :obj:`~numpy.ndarray` object of shape ``(n_sam, n_par)``
            Array containing the sample set used to evaluate the model.
        mod_set : 2D :obj:`~numpy.ndarray` object of shape ``(n_sam, n_data)``
            Array containing the data values corresponding to the requested
            data points.


        Reads in all parameters in the provided `prism_par` and saves them as
        a dict in the current :obj:`~Pipeline` instance.


        This function calculates the total number of emulator evaluation
        samples at a given emulator iteration `emul_i` from
        :attr:`~base_eval_sam`.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        n_eval_sam : int
            Total number of emulator evaluation samples.


        Obtains the path for the root directory, working directory and
        parameters file for *PRISM*.

        Parameters
        ----------
        %(paths)s

        Generates
        ---------
        The absolute paths to the root directory, working directory, emulator
        master HDF5-file and *PRISM* parameters file.


        Generates mock data and loads it into the
        :obj:`~prism.modellink.ModelLink` object that was provided
        during class initialization.
        This function overwrites the
        :class:`~prism.modellink.ModelLink` properties holding the
        parameter estimates, data values and data errors.

        Parameters
        ----------
        mock_par : 1D array_like or None
            If 1D array_like, use the provided parameter estimates to create
            the mock data. If *None*, a random parameter set will be generated
            as parameter estimates.

        Generates
        ---------
        Overwrites the corresponding :class:`~prism.modellink.ModelLink` class
        properties with the generated values.


        Loads in all the important pipeline data into memory for the controller
        rank.
        If it is detected that the last emulator iteration has not been
        analyzed yet, the implausibility analysis parameters are taken from the
        *PRISM* parameters dict and temporarily stored in memory.

        Generates
        ---------
        All relevant pipeline data up to the last emulator iteration is loaded
        into memory.


        Saves a given data dict ``{keyword: data}`` at the last emulator
        iteration to the HDF5-file and as an data attribute to the current
        :obj:`~Pipeline` instance.

        %(save_data)s


        Saves a given statistics dict ``{keyword: [value, unit]}`` at
        emulator iteration `emul_i` to the HDF5-file. The provided values are
        always saved as strings.

        Parameters
        ----------
        %(emul_i)s

        Dict variables
        --------------
        keyword : str
            String containing the name/keyword of the statistic that is being
            saved.
        value : int, float or str
            The value of the statistic.
        unit : str
            The unit of the statistic.


        Obtains the model realization data for given emulator iteration
        `emul_i` by evaluating the provided `sam_set` in the model and
        distributing model outputs to the correct emulator systems.

        Parameters
        ----------
        %(emul_i)s
        sam_set : 2D :obj:`~numpy.ndarray` object
            Array containing the model evaluation samples.
        %(ext_sam)s
        %(ext_mod)s

        Generates
        ---------
        sam_set : 2D :obj:`~numpy.ndarray` object
            Array containing the model evaluation samples for emulator
            iteration `emul_i`.
        mod_set : 2D :obj:`~numpy.ndarray` object
            Array containing the model outputs of all specified model
            evaluation samples for emulator iteration `emul_i`.


        Generates an emulator evaluation sample set to be used for analyzing an
        emulator iteration. Currently uses the :func:`~e13tools.sampling.lhd`
        function.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        eval_sam_set : 2D :obj:`~numpy.ndarray` object
            Array containing the evaluation samples.


        Returns the fraction of parameter space that passed the implausibility
        checks during the analysis of the provided emulator iteration `emul_i`.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        f_impl : float
            The fraction of parameter space that is still plausible.


        Returns the boundaries of the hypercube that encloses the parameter
        space in which the plausible space of the provided emulator iteration
        `emul_i` is defined.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        impl_space : 2D :obj:`~numpy.ndarray` object
            The requested hypercube boundaries.

        Note
        ----
        The parameter space over which plausible space is defined is always
        equal to the emulator space of the next iteration. This means that
        reanalyzing an iteration can change the result of this function.


        Performs an implausibility cut-off check on the provided implausibility
        values `uni_impl_vals` at emulator iteration `emul_i`.

        Parameters
        ----------
        %(emul_i)s
        uni_impl_vals : 2D array_like
            Array containing all univariate implausibility values corresponding
            to all parameter sets for all data points.

        Returns
        -------
        impl_check_vals : 1D :obj:`~numpy.ndarray` object
            Array containing whether the check was successful for that sample.
        impl_cut_vals : 1D :obj:`~numpy.ndarray` object
            Array containing the implausibility value at the first real
            implausibility cut-off for every sample.


        Calculates the univariate implausibility values at a given emulator
        iteration `emul_i` for specified expectation and variance values
        `adj_exp_val` and `adj_var_val`, corresponding to given `par_set`.

        Parameters
        ----------
        %(emul_i)s
        par_set : 1D :obj:`~numpy.ndarray` object
            Model parameter value set to calculate the univariate
            implausibility values for. Only used to pass to the
            :meth:`~prism.modellink.ModelLink.get_md_var` method.
        adj_exp_val, adj_var_val : 1D array_like
            The adjusted expectation and variance values to calculate the
            univariate implausibility for.

        Returns
        -------
        uni_impl_val : 1D :obj:`~numpy.ndarray` object
            Univariate implausibility value for all requested emulator systems.


        Retrieves the model discrepancy variances, which includes all variances
        that are created by the model provided by the
        :obj:`~prism.modellink.ModelLink` instance. This method tries
        to call the :meth:`~prism.modellink.ModelLink.get_md_var`
        method, and assumes a default model discrepancy variance of ``1/6th``
        the data value if it cannot be called. If the data value space is not
        linear, then this default value is calculated such to reflect that.

        Parameters
        ----------
        %(emul_i)s
        par_set : 1D :obj:`~numpy.ndarray` object
            Model parameter value set to calculate the model discrepancy
            variances for.

        Returns
        -------
        var_md : 2D :obj:`~numpy.ndarray` object
            Variance of the model discrepancy.


        Sets the :attr:`~impl_cut` and :attr:`~cut_idx` properties for
        implausibility evaluations using :attr:`~prism.Pipeline.prism_dict` and
        the provided `impl_cut`.

        Parameters
        ----------
        impl_cut : list of float or None
            Incomplete, shortened impl_cut-offs list to be used during the
            analysis of this emulator iteration. If *None*, use
            :attr:`~prism.Pipeline.prism_dict` instead.

        Generates
        ---------
        %(impl_cut)s


        Processes an externally provided model realization set `ext_real_set`,
        containing the used sample set and the corresponding data value set, to
        be used for the provided `emul_i`.

        Parameters
        ----------
        %(emul_i)s
        %(ext_set)s

        Returns
        -------
        %(ext_sam)s
        %(ext_mod)s


        Compiles all pre-defined built-in code snippets to code objects and
        saves them to :attr:`~code_objects`. These code objects are used for
        performing standard operations in the :meth:`~_evaluate_sam_set`
        method.


        Evaluates a provided set of emulator evaluation samples `sam_set` at a
        given emulator iteration `emul_i`.
        The provided tuple of code snippets `exec_code` are executed using
        Python's :func:`~exec` function at specific points during the analysis.

        Parameters
        ----------
        %(emul_i)s
        sam_set : 2D :obj:`~numpy.ndarray` object
            Array containing model parameter value sets to be evaluated in all
            emulator systems in emulator iteration `emul_i`.
        exec_code : {'analyze', 'evaluate', 'hybrid', 'project'} or tuple
            Tuple of five code snippets ``(pre_code, eval_code, anal_code,
            post_code, exit_code)`` to be executed at specific points during
            the analysis.
            If string, use one of the built-in tuples in :attr:`~code_objects`
            instead.

        Other parameters
        ----------------
        pre_code : str or code object
            Code snippet to be executed before the evaluation of `sam_set`
            starts.
        eval_code : str or code object
            Code snippet to be executed after the evaluation of each sample in
            `sam_set`.
        anal_code : str or code object
            Code snippet to be executed after the analysis of each sample in
            `sam_set`. This code snippet is only executed by the controller.
        post_code : str or code object
            Code snippet to be executed after the evaluation of `sam_set` ends.
        exit_code : str or code object
            Code snippet to be executed before returning the results of the
            evaluation of `sam_set`. This code snippet is only executed by the
            controller.

        Returns
        -------
        results : object
            The object that is assigned to a local variable called `results`,
            which is defaulted to *None* if no code snippet sets it.
            Preferably, the execution of `post_code` and/or `exit_code`
            sets this variable. All MPI ranks return it.

        Notes
        -----
        If any of the code snippets is provided as a string, it will be
        compiled into a code object before starting the evaluation.


        Analyzes the emulator at the last emulator iteration for a large number
        of emulator evaluation samples. All samples that survive the
        implausibility checks set by the provided `impl_cut`, are used in the
        construction of the next emulator iteration.

        Optional
        --------
        impl_cut : list of float or None. Default: None
            Incomplete, shortened implausibility cut-offs list to be used
            during the analysis of this emulator iteration.
            If *None*, the currently set implausibility cut-off values
            (:attr:`~impl_cut`) will be used.

        Generates
        ---------
        impl_sam : 2D :obj:`~numpy.ndarray` object
            Array containing all emulator evaluation samples that survived the
            implausibility checks.


        Constructs the emulator at the specified emulator iteration `emul_i`,
        and performs an implausibility analysis on the emulator iteration right
        afterward if requested (:meth:`~analyze`).

        Optional
        --------
        %(emul_i)s
        analyze : bool. Default: True
            Bool indicating whether or not to perform an analysis after the
            specified emulator iteration has been successfully constructed,
            which is required for making projections (:meth:`~project`) and
            constructing the next iteration.
        %(ext_set)s
        force : bool. Default: False
            Controls what to do if the specified emulator iteration `emul_i`
            already (partly) exists.
            If *False*, finish construction of the specified iteration or skip
            it if already finished.
            If *True*, reconstruct the specified iteration entirely.

        Generates
        ---------
        A new HDF5-group with the emulator iteration as its name, in the loaded
        emulator master file, containing emulator data required for this
        emulator iteration.

        Notes
        -----
        Using an emulator iteration that has been (partly) constructed before,
        will finish construction or skip it if already finished when `force` is
        *False*; or it will delete that and all following iterations, and
        reconstruct the specified iteration when `force` is *True*. Using
        `emul_i` = 1 and `force` is *True* is equivalent to reconstructing the
        entire emulator.

        If no implausibility analysis is requested, then the implausibility
        parameters are taken from the *PRISM* parameters dict and temporarily
        stored in memory in order to enable the usage of the :meth:`~evaluate`
        method.


        Prints the details/properties of the currently loaded :obj:`~Pipeline`
        instance at given emulator iteration `emul_i`. See ``Props`` for
        detailed descriptions of all printed properties.

        Optional
        --------
        %(emul_i)s

        Props
        -----
        Working directory
            The relative path to the working directory of the emulator starting
            at the current working directory.
        Emulator type
            The type of this emulator, corresponding to the
            :attr:`~prism.emulator.Emulator.emul_type` of the provided
            `emul_type` during :class:`~Pipeline` initialization.
            If no emulator type was provided during initialization, this is
            'default'.
        ModelLink subclass
            Name of the :class:`~prism.modellink.ModelLink` subclass
            used to construct this emulator.
        Emulation method
            Indicates the combination of regression and Gaussian emulation
            methods that have been used for this emulator.
        Mock data used?
            Whether or not mock data has been used to construct this emulator.
            If so, the printed estimates for all model parameters are the
            parameter values used to create the mock data.

        ----

        Emulator iteration
            The iteration of the emulator this details overview is about. By
            default, this is the last (partly) constructed iteration.
        Construction completed?
            Whether or not the construction of this emulator iteration is
            completed. If not, the missing components for each emulator system
            are listed and the remaining information of this iteration is not
            printed.
        Plausible regions?
            Whether or not plausible regions have been found during the
            analysis of this emulator iteration. If no analysis has been done
            yet, "N/A" will be printed.
        Projections available?
            Whether or not projections have been created for this emulator
            iteration. If projections are available and analysis has been done,
            but with different implausibility cut-offs, a "desynced" note is
            added. Also prints number of available projections versus maximum
            number of projections in parentheses.

        ----

        # of model evaluation samples
            The total number of model evaluation samples used to construct all
            emulator iterations up to this iteration, with the number for every
            individual iteration in parentheses.
        # of plausible/analyzed samples
            The number of emulator evaluation samples that passed the
            implausibility check out of the total number of analyzed samples in
            this emulator iteration.
            This is the number of model evaluation samples that was/will be
            used for the construction of the next emulator iteration.
            If no analysis has been done, the numbers show up as "-".
        %% of parameter space remaining
            The percentage of the total number of analyzed samples that passed
            the implausibility check in this emulator iteration.
            If no analysis has been done, the number shows up as "-".
        # of active/total parameters
            The number of model parameters that was considered active during
            the construction of this emulator iteration, compared to the total
            number of model parameters defined in the used
            :class:`~prism.modellink.ModelLink` subclass.
        # of emulated data points
            The number of data points that have been emulated in this
            emulator iteration.
        # of emulator systems
            The total number of emulator systems that are required in this
            emulator. The number of active emulator systems is equal to the
            number of data points.

        ----

        Parameter space
            Lists the name, lower and upper value boundaries and estimate (if
            provided) of all model parameters defined in the used
            :class:`~prism.modellink.ModelLink` subclass. An asterisk is
            printed in front of the parameter name if this model parameter was
            considered active during the construction of this emulator
            iteration. A question mark is used instead if the construction of
            this emulator iteration is not finished.


        Evaluates the given model parameter sample set `sam_set` up to given
        emulator iteration `emul_i`.
        The output of this function depends on the number of dimensions in
        `sam_set`. The output is always provided on the controller rank.

        Parameters
        ----------
        sam_set : 1D or 2D array_like or dict
            Array containing model parameter value sets to be evaluated in the
            emulator up to emulator iteration `emul_i`.

        Optional
        --------
        %(emul_i)s

        Returns (if 2D `sam_set`)
        -------------------------
        impl_check : list of bool
            List of bool indicating whether or not the given samples passed the
            implausibility check at the given emulator iteration `emul_i`.
        emul_i_stop : list of int
            List containing the last emulator iterations at which the given
            samples are still within the plausible region of the emulator.
        adj_exp_val : 2D :obj:`~numpy.ndarray` object
            Array containing the adjusted expectation values for all given
            samples.
        adj_var_val : 2D :obj:`~numpy.ndarray` object
            Array containing the adjusted variance values for all given
            samples.
        uni_impl_val : 2D :obj:`~numpy.ndarray` object
            Array containing the univariate implausibility values for all given
            samples.

        Prints (if 1D `sam_set`)
        ------------------------
        emul_i_stop : int
            Last emulator iteration at which the given sample is still within
            the plausible region of the emulator.
        adj_exp_val : 1D :obj:`~numpy.ndarray` object
            The adjusted expectation values for the given sample.
        adj_var_val : 1D :obj:`~numpy.ndarray` object
            The adjusted variance values for the given sample.
        sigma_val : 1D :obj:`~numpy.ndarray` object
            The corresponding sigma value for the given sample.
        uni_impl_val : 1D :obj:`~numpy.ndarray` object
            The univariate implausibility values for the given sample.

        Notes
        -----
        If given emulator iteration `emul_i` has been analyzed before, the
        implausibility parameters of the last analysis are used. If not, then
        the values are used that were read in when the emulator was loaded or
        that have been set by the user.


        All worker ranks in the :attr:`~prism.Pipeline.comm` communicator start
        listening for calls from the corresponding controller rank and will
        attempt to execute the received message. Listening for calls continues
        until this context manager exits (:meth:`~__exit__` is called).

        This method is automatically initialized and finalized when using the
        :attr:`~prism.Pipeline.worker_mode` context manager.


        Processes a call that was made with the :meth:`~make_call` or
        :meth:`~make_call_workers` method.

        This function should solely be called through either of these methods
        and never directly.

        Parameters
        ----------
        %(pipeline)s
        exec_fn : str or callable
            If string, a callable attribute of this :obj:`~prism.Pipeline`
            instance or a callable object that should be executed if not.
        args : tuple
            Positional arguments that need to be provided to `exec_fn`.
        kwargs : dict
            Keyword arguments that need to be provided to `exec_fn`.

        Returns
        -------
        out : object
            The object returned by executing `exec_fn`.

        Note
        ----
        If any entry in `args` or `kwargs` is a string written as 'pipe.XXX',
        it is assumed that 'XXX' refers to a :class:`~prism.Pipeline`
        attribute of the MPI rank receiving the call. It will be replaced with
        the corresponding attribute before `exec_fn` is called.


        Processes a provided `string` that was provided as an argument value to
        :meth:`~_process_call`.

        Parameters
        ----------
        %(pipeline)s
        string : str
            String value that must be processed.

        Returns
        -------
        out : str or object
            If `string` starts with 'pipe.', the corresponding
            :class:`~prism.Pipeline` attribute will be returned. Else, `string`
            is returned.


        str: The type of emulator that is currently loaded. This determines the
        way in which the :obj:`~prism.Pipeline` instance will treat this
        :obj:`~Emulator` instance.


        bool: Whether or not a previously constructed emulator is currently
        loaded.


        str: The version of *PRISM* that was used to construct the emulator
        that is currently loaded.


        int: The last emulator iteration that is fully constructed for all
        emulator systems on this MPI rank.


        list of str: The emulator system components that are still required to
        complete the construction of an emulator iteration on this MPI rank.
        The controller rank additionally lists the required components that are
        emulator iteration specific ('mod_real_set' and 'active_par').


        int: Number of model evaluation samples that have been/will be used to
        construct an emulator iteration.


int: Number of emulator systems assigned to this MPI rank.


        int: Total number of emulator systems assigned to all MPI ranks
        combined. Only available on the controller rank.


        str: The emulation method to use for constructing the emulator.
        Possible are 'gaussian', 'regression' and 'full'.


        bool: Whether or not mock data has been used for the construction of
        this emulator instead of actual data. If *True*, changes made to the
        data in the provided :obj:`~prism.modellink.ModelLink` object
        are ignored.


        bool: Whether or not to take into account the regression covariance
        when calculating the covariance of the emulator, in addition to the
        Gaussian covariance.
        If :attr:`~method` == 'gaussian', this bool is not required.
        If :attr:`~method` == 'regression', this bool is always set to *True*.


        int: Polynomial order that is considered for the regression process.
        If :attr:`~method` == 'gaussian' and
        :attr:`~prism.Pipeline.do_active_anal` is *False*, this number is not
        required.


        int: Number of (k-fold) cross-validations that are used for determining
        the quality of the regression process. It is set to zero if
        cross-validations are not used.
        If :attr:`~method` == 'gaussian' and
        :attr:`~prism.Pipeline.do_active_anal` is *False*, this number is not
        required.


        list of int: The indices of the emulator systems on this MPI rank that
        are active.


        list of int: The indices of the emulator systems that are assigned to
        this MPI rank.


        list of lists: List of the indices of the emulator systems that are
        assigned to every MPI rank. Only available on the controller rank.


        list of lists: List of the data identifiers that were assigned to the
        emulator systems listed in :attr:`~emul_s_to_core`. Only available on
        the controller rank.


        list of str: The model parameter names that are considered active.
        Only available on the controller rank.


        dict of lists: The model parameter names that are considered active for
        every emulator system on this MPI rank.


        dict of float: The residual variance of every emulator system on this
        MPI rank.
        Obtained from regression process and replaces the Gaussian sigma.
        Empty if :attr:`~method` == 'gaussian'.


        dict of dict: Overview of all polynomial terms with non-zero
        coefficients in the regression function for every emulator system on
        this MPI rank.
        Empty if :attr:`~method` == 'gaussian'.

        This is basically a human-readable representation of :attr:`~poly_coef`
        plus :attr:`~poly_powers`. Given its formatting, it is not advised to
        use this for any operations.


        list of :obj:`~numpy.ndarray`: The non-zero coefficients of the
        polynomial terms in the regression function for every emulator system
        on this MPI rank.
        Empty if :attr:`~method` == 'gaussian'.


        list of :obj:`~numpy.ndarray`: The covariances of all coefficients in
        :attr:`~poly_coef` for every emulator system on this MPI rank.
        Empty if :attr:`~method` == 'gaussian' or :attr:`~use_regr_cov` is
        *False*.


        list of :obj:`~numpy.ndarray`: The powers of all polynomial terms with
        non-zero coefficients in the regression function for every emulator
        system on this MPI rank.
        Empty if :attr:`~method` == 'gaussian'.


        list of :obj:`~numpy.ndarray`: The indices of all polynomial terms with
        non-zero coefficients in the regression function for every emulator
        system on this MPI rank.
        Empty if :attr:`~method` == 'gaussian'.


        list of dict: The model evaluation samples that have been/will be used
        to construct the specified emulator iteration.


        dict of :obj:`~numpy.ndarray`: The boundaries of the hypercube that
        encloses the parameter space in which the specified emulator iteration
        is defined. This is always equal to the plausible space of the previous
        iteration.


        dict of :obj:`~numpy.ndarray`: The model outputs corresponding to the
        samples in :attr:`~sam_set` for every emulator system on this MPI rank.


        dict of :obj:`~numpy.ndarray`: The inverses of the covariance matrices
        for every emulator system on this MPI rank.


        dict of :obj:`~numpy.ndarray`: The second expectation adjustment
        dot-term values of all model evaluation samples for every emulator
        system on this MPI rank.


        float: Value of the Gaussian sigma.
        If :attr:`~method` != 'gaussian', this value is not required, since it
        is obtained from the regression process instead.


        dict of float: The Gaussian correlation lengths for all model
        parameters, which is defined as the maximum distance between two values
        of a specific model parameter within which the Gaussian contribution to
        the correlation between the values is still significant.


        float: The residual variance inflation factor. The prior variance of
        all known samples is inflated by this factor multiplied with
        :attr:`~rsdl_var` (regression) or :attr:`~sigma` (Gaussian).
        If this value is zero, no variance inflation is performed.


        dict of float: The active contribution of the residual variance of
        every emulator system on this MPI rank.
        Obtained from either :attr:`~rsdl_var` (regression) or :attr:`~sigma`
        (Gaussian).


        dict of float: The passive contribution of the residual variance of
        every emulator system on this MPI rank. If :attr:`~f_infl` is not zero,
        this also includes the inflated residual variance value.
        Obtained from either :attr:`~rsdl_var` (regression) or :attr:`~sigma`
        (Gaussian).


        Checks if the provided emulator iteration `emul_i` can be requested or
        replaces it if *None* was provided.
        This method requires all MPI ranks to call it simultaneously.

        Parameters
        ----------
        %(emul_i)s

        Optional
        --------
        cur_iter : bool
            Bool determining whether the current (*True*) or the next (*False*)
            emulator iteration is requested.

        Returns
        -------
        emul_i : int
            The requested emulator iteration that passed the check.


        Checks if the version of this emulator is compatible with the provided
        `req_version`.
        If not, raises a :class:`~FutureWarning`, indicating that the given
        `dep_version` will no longer support this emulator.

        Parameters
        ----------
        req_version : str
            The version in which an incompatible change was introduced.
        dep_version : str
            The version in which the backward compatibility for this change
            will be removed.


        Returns the boundaries of the hypercube that encloses the parameter
        space in which the provided emulator iteration `emul_i` is defined.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        emul_space : 2D :obj:`~numpy.ndarray` object
            The requested hypercube boundaries. If `emul_i` == 1, this is equal
            to the defined model parameter space.

        Note
        ----
        The parameter space over which an emulator iteration is defined is
        always equal to the plausible space of the previous iteration.


        Creates a new master HDF5-file that holds all the information of a new
        emulator and writes all important emulator details to it.
        Afterwards, resets all loaded emulator data and prepares the HDF5-file
        and emulator for the construction of the first emulator iteration.

        Generates
        ---------
        A new master HDF5-file 'prism.hdf5' contained in the working directory
        specified in the :obj:`~prism.Pipeline` instance, holding all
        information required to construct the first iteration of the emulator.


        Opens all emulator HDF5-files and removes the provided emulator
        iteration `emul_i` and subsequent iterations from them. Also removes
        any related projection figures that have default names.
        If `emul_i` == 1, all emulator HDF5-files are removed instead.

        Parameters
        ----------
        %(emul_i)s


        Reads in and combines the parts of the data point identifier that is
        assigned to the provided `emul_s_group`.

        Parameters
        ----------
        emul_s_group : :obj:`~h5py.Group` object
            The HDF5-group from which the data point identifier needs to be
            read in.

        Returns
        -------
        data_idx : tuple of {int, float, str}
            The combined data point identifier.


        Splits a given `data_idx` up into individual parts and saves it as an
        attribute to the provided `emul_s_group`.

        Parameters
        ----------
        emul_s_group : :obj:`~h5py.Group` object
            The HDF5-group to which the data point identifier needs to be
            saved.
        data_idx : tuple of {int, float, str}
            The data point identifier to be saved.


        Obtains the data point identifiers `data_idx` that are assigned to each
        MPI rank for the provided emulator iteration `emul_i` and returns them
        as a single list.
        The number of data points assigned to each MPI rank is also returned.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        n_data_rank : list of int
            The number of data points each MPI rank has assigned to it for
            given `emul_i`. These values can be used to split `data_idx_flat`
            up again into MPI rank-specific data point identifiers.
        data_idx_flat : list of tuples
            The data point identifiers that are assigned to an MPI rank for
            given `emul_i`.


        Determines the emulator system each data point in the provided emulator
        iteration `emul_i` should be assigned to, in order to make sure that
        recurring data points have the same emulator system index as in the
        previous emulator iteration. If multiple options are possible, data
        points are assigned such to spread them as much as possible.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        data_to_emul_s : list of int
            The index of the emulator system that each data point should be
            assigned to.
        n_emul_s : int
            The total number of active and passive emulator systems there will
            be in the provided emulator iteration.

        Examples
        --------
        If the number of data points is less than the previous iteration:

            >>> emul_i = 2
            >>> self._data_idx[emul_i-1]
            ['A', 'B', 'C', 'D', 'E']
            >>> self._modellink._data_idx
            ['B', 'F', 'G', 'E']
            >>> self._assign_data_idx(emul_i)
            ([1, 3, 2, 4], 5)

        If the number of data points is more than the previous iteration:

            >>> emul_i = 2
            >>> self._data_idx[emul_i-1]
            ['A', 'B', 'C', 'D', 'E']
            >>> self._modellink._data_idx
            ['B', 'F', 'G', 'E', 'A', 'C']
            >>> self._assign_data_idx(emul_i)
            ([1, 5, 3, 4, 0, 2], 6)

        If there is no previous iteration:

            >>> emul_i = 1
            >>> self._data_idx[emul_i-1]
            []
            >>> self._modellink._data_idx
            ['B', 'F', 'G', 'E', 'A', 'C']
            >>> self._assign_data_idx(emul_i)
            ([5, 4, 3, 2, 1, 0], 6)


        Determines which emulator systems (files) should be assigned to which
        MPI rank in order to balance the number of active emulator systems on
        every rank for every iteration up to the provided emulator iteration
        `emul_i`. If multiple choices can achieve this, the emulator systems
        are automatically spread out such that the total number of active
        emulator systems on a single rank is also balanced as much as possible.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        emul_s_to_core : list of lists
            A list containing the emulator systems that have been assigned to
            the corresponding MPI rank by the controller.

        Notes
        -----
        Currently, this function only uses high-level MPI. Additional speed can
        be obtained by also implementing low-level MPI, which will potentially
        be done in the future.


        Prepares the emulator for the construction of a new iteration `emul_i`.
        Checks if this iteration can be prepared or if it has been prepared
        before, and acts accordingly.

        Parameters
        ----------
        %(emul_i)s

        Returns
        -------
        reload : bool
            Bool indicating whether or not the controller rank of the
            :obj:`~prism.Pipeline` instance needs to reload its data.

        Generates
        ---------
        A new group in the master HDF5-file with the emulator iteration as its
        name, containing subgroups corresponding to all emulator systems that
        will be used in this iteration.

        Notes
        -----
        Preparing an iteration that has been prepared before, causes that and
        all subsequent iterations of the emulator to be deleted.
        A check is carried out to see if it was necessary to reprepare the
        requested iteration and a warning is given if this check fails.


        Constructs the emulator iteration corresponding to the provided
        `emul_i`, by performing the given emulation method and pre-calculating
        the prior expectation and variance values of the used model evaluation
        samples.

        Parameters
        ----------
        %(emul_i)s

        Generates
        ---------
        All data sets that are required to evaluate the emulator at the
        constructed iteration.


        Determines the active parameters to be used for every emulator system
        listed in `emul_s_seq` in the provided emulator iteration `emul_i`.
        Uses backwards stepwise elimination to determine the set of active
        parameters. The polynomial order that is used in the stepwise
        elimination depends on :attr:`~poly_order`.

        Parameters
        ----------
        %(emul_i)s
        %(emul_s_seq)s

        Generates (for every emulator system)
        -------------------------------------
        active_par_data : 1D :obj:`~numpy.ndarray` object
            Array containing the indices of all the parameters that are active
            in the emulator iteration `emul_i`.


        Performs a forward stepwise linear regression for all requested
        emulator systems `emul_s_seq` in the provided emulator iteration
        `emul_i`. Calculates what the expectation values of all polynomial
        coefficients are. The polynomial order that is used in the regression
        depends on :attr:`~poly_order`.

        Parameters
        ----------
        %(emul_i)s
        %(emul_s_seq)s

        Generates (for every emulator system)
        -------------------------------------
        rsdl_var : float
            Residual variance of the regression function.
        regr_score : float
            Fit-score of the regression function.
        poly_coef : 1D :obj:`~numpy.ndarray` object
            Array containing the expectation values of the non-zero polynomial
            coefficients.
        poly_powers : 2D :obj:`~numpy.ndarray` object
            Array containing the powers of the non-zero polynomial terms in the
            regression function.
        poly_idx : 1D :obj:`~numpy.ndarray` object
            Array containing the indices of the non-zero polynomial terms in
            the regression function.
        poly_coef_cov : 1D :obj:`~numpy.ndarray` object (if \
            :attr:`~use_regr_cov` is *True*)
            Array containing the covariance values of the non-zero polynomial
            coefficients.


        Calculates the prior expectation value for requested emulator systems
        `emul_s_seq` at a given emulator iteration `emul_i` for specified
        parameter set `par_set`. This expectation depends on :attr:`~method`.

        Parameters
        ----------
        %(emul_i)s
        %(emul_s_seq)s
        par_set : 1D :obj:`~numpy.ndarray` object or None
            If *None*, calculate the prior expectation values of sam_set.
            If not *None*, calculate the prior expectation value for the given
            model parameter value set.

        Returns
        -------
        prior_exp : 1D or 2D :obj:`~numpy.ndarray` object
            Prior expectation values for either sam_set or `par_set` for
            requested emulator systems.


        Pre-calculates the second expectation adjustment dot-term for requested
        emulator systems `emul_s_seq` at a given emulator iteration `emul_i`
        for all model evaluation samples and saves it for later use.

        Parameters
        ----------
        %(emul_i)s
        %(emul_s_seq)s

        Generates
        ---------
        exp_dot_term : 2D :obj:`~numpy.ndarray` object
            2D array containing the pre-calculated values for the second
            adjustment dot-term of the adjusted expectation for requested
            emulator systems.


        Calculates the full emulator covariances for requested emulator systems
        `emul_s_seq` at emulator iteration `emul_i` for given parameter sets
        `par_set1` and `par_set2`. The contributions to these covariances
        depend on :attr:`~method`.

        %(full_cov)s


        Calculates the covariances of the regression function for requested
        emulator systems `emul_s_seq` at emulator iteration `emul_i` for given
        parameter sets `par_set1` and `par_set2`.

        %(regr_cov)s


        Calculates the (inverse) matrix of covariances between known model
        evaluation samples for requested emulator systems `emul_s_seq` at
        emulator iteration `emul_i`.

        Parameters
        ----------
        %(emul_i)s
        %(emul_s_seq)s

        Generates
        ---------
        cov_mat : 3D :obj:`~numpy.ndarray` object
            Matrix containing the covariances between all known model
            evaluation samples for requested emulator systems.
        cov_mat_inv : 3D :obj:`~numpy.ndarray` object
            Inverse of covariance matrix for requested emulator systems.


        Calculates the inverse of a given `matrix`.
        Right now only uses the :func:`~numpy.linalg.pinv` function.

        Parameters
        ----------
        matrix : 2D array_like
            Matrix to be inverted.

        Returns
        -------
        matrix_inv : 2D :obj:`~numpy.ndarray` object
            Inverse of the given `matrix`.


        Checks if the provided working directory contains a constructed
        emulator and loads in the emulator data accordingly.

        Parameters
        ----------
        modellink_obj : :obj:`~prism.modellink.ModelLink` object
            Instance of the :class:`~prism.modellink.ModelLink` class that
            links the emulated model to this :obj:`~prism.Pipeline` object.


        Sets the :obj:`~prism.modellink.ModelLink` object that will
        be used for constructing this emulator. If a constructed emulator is
        present, checks if provided `modellink_obj` argument matches the
        :class:`~prism.modellink.ModelLink` subclass used to
        construct it.

        Parameters
        ----------
        modellink_obj : :obj:`~prism.modellink.ModelLink` object
            Instance of the :class:`~prism.modellink.ModelLink` class
            that links the emulated model to this
            :obj:`~prism.Pipeline` object.
            The provided :obj:`~prism.modellink.ModelLink` object
            must match the one used to construct the loaded emulator.
        modellink_loaded : str or None
            If str, the name of the
            :class:`~prism.modellink.ModelLink` subclass that was
            used to construct the loaded emulator.
            If *None*, no emulator is loaded.


        Loads in all the important emulator data up to emulator iteration
        `emul_i` into memory.

        Parameters
        ----------
        %(emul_i)s

        Generates
        ---------
        All relevant emulator data up to emulator iteration `emul_i` is loaded
        into memory.


        Saves a given data dict ``{keyword: data}`` at the given emulator
        iteration `emul_i` and local emulator system `lemul_s` to the HDF5-file
        and as an data attribute to the current :obj:`~Emulator` instance.

        %(save_data)s


        Sets the provided `sam_set` as the iteration data at the given emulator
        iteration `emul_i`.

        Parameters
        ----------
        %(emul_i)s
        sam_set : 2D :obj:`~numpy.ndarray` object
            Array containing the model evaluation samples for emulator
            iteration `emul_i`.


        Reads in the emulator parameters from the provided working directory
        and saves them in the current :obj:`~Emulator` instance.


        Loads previously used mock data into the
        :class:`~prism.modellink.ModelLink` object, overwriting the
        parameter estimates, data values, data errors, data spaces and data
        identifiers with their mock equivalents.

        Generates
        ---------
        Overwrites the corresponding
        :class:`~prism.modellink.ModelLink` class properties with the
        previously used values (taken from the first emulator iteration).


        Returns the string representation of a polynomial term given by the
        provided `active_par` and `poly_power`.

        Parameters
        ----------
        active_par : list of int
            List containing the indices of the parameters whose polynomial
            powers are given in `poly_power`.
        poly_power : list of int
            List with the powers of the requested polynomial term.

        Returns
        -------
        poly_term : str
            String representation of the requested polynomial term.


        Splits up the calculated residual variances for requested emulator
        systems `emul_s_seq` at emulator iteration `emul_i` into active and
        passive contributions.

        Parameters
        ----------
        %(emul_i)s
        %(emul_s_seq)s

        Generates
        ---------
        act_rsdl_var : list of float
            List containing the active portions of the residual variances.
        pas_rsdl_var : list of float
            List containing the passive portions of the residual variances.
            If :attr:`~f_infl` is not zero, this also includes the inflated
            residual variance values.


        Calculates the natural logarithm of the posterior probability of
        `par_set` using the provided function `lnpost_fn`, in addition to
        constraining it first with the emulator defined in the `pipeline_obj`.

        This function needs to be called by all MPI ranks unless called within
        the :attr:`~prism.Pipeline.worker_mode` context manager.

        Parameters
        ----------
        par_set : 1D array_like or dict
            Sample to calculate the posterior probability for. This sample is
            first analyzed in `pipeline_obj` and only given to `lnpost_fn` if
            it is plausible. If `par_dict` is *True*, this is a dict.
        args : positional arguments
            Positional arguments that need to be passed to `lnpost_fn`.
        kwargs : keyword arguments
            Keyword arguments that need to be passed to `lnpost_fn`.

        Returns
        -------
        lnp : float
            The natural logarithm of the posterior probability of `par_set`, as
            determined by `lnpost_fn` if `par_set` is plausible. If
            `impl_prior` is *True*, `lnp` is calculated as `lnprior` +
            `lnpost_fn()`, with `lnprior` the natural logarithm of the first
            implausibility cut-off value of `par_set` scaled with its maximum.


    Generates `req_n_walkers` unique starting positions for MCMC walkers using
    Metropolis-Hastings sampling and the provided `pipeline_obj` and
    `p0_walkers`.

    This function needs to be called by all MPI ranks.

    Parameters
    ----------
    pipeline_obj : :obj:`~prism.Pipeline` object
        The instance of the :class:`~prism.Pipeline` class that needs to be
        used for determining the validity of a proposed sampling step.
    p0_walkers : 2D :obj:`~numpy.ndarray` object
        Sample set of starting positions for the MCMC chains.
    req_n_walkers : int
        The minimum required number of unique MCMC walker positions that must
        be returned.

    Returns
    -------
    n_walkers : int
        Number of unique MCMC walker positions that are returned.
    walkers : 2D :obj:`~numpy.ndarray` object
        Array containing all unique MCMC walker positions.

    Note
    ----
    Executing this function will temporarily disable all regular logging in the
    provided :obj:`~prism.Pipeline` object. If logging was enabled before this
    function was executed, it will be enabled again afterward.


int: Number of Gaussians used in this :obj:`~GaussianLink` instance.


        str: Name associated with an instance of this :class:`~ModelLink`
        subclass.
        By default, it is set to the name of this :class:`~ModelLink` subclass.
        Can be manually manipulated to allow for more user control.


        bool: Whether :meth:`~call_model` can/should be supplied with a single
        evaluation sample. At least one of :attr:`~single_call` and
        :attr:`~multi_call` must be *True*.
        By default, single model calls are requested (True).


        bool: Whether :meth:`~call_model` can/should be supplied with a set of
        evaluation samples. At least one of :attr:`~single_call` and
        :attr:`~multi_call` must be *True*.
        By default, single model calls are requested (False).


        str: String indicating whether :meth:`call_model` should be supplied
        with a single evaluation sample ('single') or a set of samples
        ('multi'), or can be supplied with both ('hybrid').
        By default, single model calls are requested ('single').


        bool: Whether :meth:`~call_model` can/should be called by all MPI ranks
        simultaneously instead of by the controller.
        By default, only the controller rank calls the model (False).


int: Number of model parameters.


list of str: List with model parameter names.


        dict of :obj:`~numpy.ndarray`: The lower and upper values of the model
        parameters.


        dict of {float, None}: The user-defined estimated values of the model
        parameters. Contains *None* in places where estimates were not
        provided.


        dict of list: The dict of model parameters as used by this
        :obj:`~ModelLink` instance.

        This dict can be used as the `model_parameters` argument when
        initializing this :class:`~ModelLink` subclass.


int: Number of provided data points.


dict of float: The values of provided data points.


        dict of float: The upper and lower :math:`1\\sigma`-confidence levels
        of provided data points.


        dict of str: The types of value space ({'lin', 'log', 'ln'}) of
        provided data points.


list of tuples: The user-defined data point identifiers.


        dict of list: The dict of model data points as used by this
        :obj:`~ModelLink` instance.

        This dict can be used as the `model_data` argument when initializing
        this :class:`~ModelLink` subclass.


        Converts provided `sam_set` from unit space ([0, 1]) to parameter space
        ([lower_bnd, upper_bnd]).


        Converts provided `sam_set` from parameter space ([lower_bnd,
        upper_bnd]) to unit space ([0, 1]).


        Converts a provided sequence `par_seq` of model parameter names and
        indices to a list of indices, removes duplicates and checks if every
        provided name/index is valid.

        Parameters
        ----------
        par_seq : 1D array_like of {int, str}
            A sequence of integers and strings determining which model
            parameters need to be used for a certain operation.
        name : str
            A string stating the name of the variable the result of this method
            will be stored in. Used for error messages.

        Returns
        -------
        par_seq_conv : list of int
            The provided sequence `par_seq` converted to a sorted list of
            model parameter indices.


        Returns the boundaries of the hypercube that encloses the parameter
        space in which the provided `sam_set` is defined.

        The main use for this function is to determine what part of model
        parameter space was likely sampled from in order to obtain the provided
        `sam_set`. Because of this, extra spacing is added to the boundaries to
        reduce the effect of the used sampling method.

        Parameters
        ----------
        sam_set : 1D or 2D array_like or dict
            Parameter/sample set for which an enclosing hypercube is requested.

        Returns
        -------
        sam_space : 2D :obj:`~numpy.ndarray` object
            The requested hypercube boundaries.


        Checks validity of provided set of model outputs `mod_set` in this
        :obj:`~ModelLink` instance.

        Parameters
        ----------
        mod_set : 1D or 2D array_like or dict
            Model output (set) to validate in this :obj:`~ModelLink` instance.
        name : str
            The name of the model output (set), which is used in the error
            message if the validation fails.

        Returns
        -------
        mod_set : 1D or 2D :obj:`~numpy.ndarray` object
            The provided `mod_set` if the validation was successful. If
            `mod_set` was a dict, it will be converted to a
            :obj:`~numpy.ndarray` object (sorted on :attr:`~data_idx`).


        Checks validity of provided set of model parameter samples `sam_set` in
        this :obj:`~ModelLink` instance.

        Parameters
        ----------
        sam_set : 1D or 2D array_like or dict
            Parameter/sample set to validate in this :obj:`~ModelLink`
            instance.
        name : str
            The name of the parameter/sample set, which is used in the error
            message if the validation fails.

        Returns
        -------
        sam_set : 1D or 2D :obj:`~numpy.ndarray` object
            The provided `sam_set` if the validation was successful. If
            `sam_set` was a dict, it will be converted to a
            :obj:`~numpy.ndarray` object.


        Converts a provided set of model parameter samples `sam_set` to a dict
        for use in this :obj:`~ModelLink` instance.

        This dict can be used as the `par_set` argument in the
        :meth:`~call_model` and :meth:`~get_md_var` methods.

        Parameters
        ----------
        sam_set : 1D or 2D array_like
            Parameter/sample set to convert for this :obj:`~ModelLink`
            instance.

        Returns
        -------
        sam_dict : dict of list
            Dict of parameter samples.


        Checks validity of provided set of model discrepancy variances `md_var`
        in this :obj:`~ModelLink` instance.

        Parameters
        ----------
        md_var : 1D or 2D array_like or dict
            Model discrepancy variance set to validate in this
            :obj:`~ModelLink` instance.
        name : str
            The name of the model discrepancy set, which is used in the error
            message if the validation fails.

        Returns
        -------
        md_var : 2D :obj:`~numpy.ndarray` object
            The (converted) provided `md_var` if the validation was successful.
            If `md_var` was a dict, it will be converted to a
            :obj:`~numpy.ndarray` object.


        Returns the absolute path to a backup file made by this
        :obj:`~ModelLink` instance, using the provided `emul_i` and `suffix`.

        This method is used by the :meth:`~_make_backup` and
        :meth:`~_read_backup` methods, and should not be called directly.

        Parameters
        ----------
        emul_i : int
            The emulator iteration for which a backup filepath is needed.
        suffix : str or None
            If str, determine path to associated backup file using provided
            `suffix`. If `suffix` is empty, obtain last created backup file.
            If *None*, create a new path to a backup file.

        Returns
        -------
        filepath : str
            Absolute path to requested backup file.


        WARNING: This is an advanced utility method and probably will not work
        unless used properly. Use with caution!

        Creates an HDF5-file backup of the provided `args` and `kwargs` when
        called by the :meth:`~call_model` method or any of its inner functions.
        Additionally, the backup will contain the `emul_i`, `par_set` and
        `data_idx` values that were passed to the :meth:`~call_model` method.
        It also contains the version of *PRISM* that made the backup.
        The backup can be restored using the :meth:`~_read_backup` method.

        If it is detected that this method is used incorrectly, a
        :class:`~prism._internal.RequestWarning` is raised (and the method
        returns) rather than a :class:`~prism._internal.RequestError`, in order
        to not disrupt the call to :meth:`~call_model`.

        Parameters
        ----------
        args : positional arguments
            All positional arguments that must be stored in the backup file.
        kwargs : keyword arguments
            All keyword arguments that must be stored in the backup file.

        Notes
        -----
        The name of the created backup file contains the value of `emul_i`,
        :attr:`~name` and a random string to avoid replacing an already
        existing backup file.

        The saved `emul_i`, `par_set` and `data_idx` are the values these
        variables have locally in the :meth:`~call_model` method at the point
        this method is called. Because of this, making any changes to them may
        cause problems and is therefore heavily discouraged. If changes are
        necessary, it is advised to copy them to a different variable first.


        Reads in a backup HDF5-file created by the :meth:`~_make_backup`
        method, using the provided `emul_i` and the value of :attr:`~name`.

        Parameters
        ----------
        emul_i : int
            The emulator iteration that was provided to the :meth:`~call_model`
            method when the backup was made.

        Optional
        --------
        suffix : str or None. Default: None
            The suffix of the backup file (everything between parentheses) that
            needs to be read. If *None* or empty, the last created backup will
            be read.

        Returns
        -------
        filename : str
            The absolute path to the backup file that has been read.
        data : dict with keys `('emul_i', 'prism_version', 'par_set',` \
            `'data_idx', 'args', 'kwargs')`
            A dict containing the data that was provided to the
            :meth:`~_make_backup` method.


        dict: The default model parameters to use for every instance of this
        :class:`~ModelLink` subclass.


        Generates the model parameter properties from the default model
        parameters and the additional input argument `add_model_parameters`.

        Parameters
        ----------
        add_model_parameters : array_like, dict, str or None
            Anything that can be converted to a dict that provides non-default
            model parameters information or *None* if only default information
            is used from :meth:`~ModelLink.get_default_model_parameters`.

        Generates
        ---------
        n_par : int
            Number of model parameters.
        par_name : list
            List with model parameter names.
        par_rng : :obj:`~numpy.ndarray` object
            Array containing the lower and upper values of the model
            parameters.
        par_est : list
            List containing user-defined estimated values of the model
            parameters.
            Contains *None* in places where estimates were not provided.


        dict: The default model data to use for every instance of this
        :class:`~ModelLink` subclass.


        Generates the model data properties from the default model data and the
        additional input argument `add_model_data`.

        Parameters
        ---------
        add_model_data : array_like, dict, str or None
            Anything that can be converted to a dict that provides non-default
            model data information or *None* if only default data is used from
            :meth:`~ModelLink.get_default_model_data`.

        Generates
        ---------
        n_data : int
            Number of provided data points.
        data_val : list
            List with values of provided data points.
        data_err : list of lists
            List with upper and lower :math:`1\\sigma`-confidence levels of
            provided data points.
        data_spc : list
            List with types of value space ({'lin', 'log', 'ln'}) of provided
            data points.
        data_idx : list of tuples
            List with user-defined data point identifiers.