Extending SrMise

The Tutorial gives an overview of how to use SrMise with the existing peak and baseline functions. These inherit from classes providing generic peak and baseline functionality, and from which additional peaks and baselines can be implemented. The process for adding new peaks and baselines is summarized below, but see the source code for additional details.

If you implement a peak or baseline likely to be of broad interest to the PDF community, please consider submitting a pull request to the GitHub SrMise repository.

Organization of Functions

The BaseFunction class in diffpy.srmise.basefunction implements the functionality common to all SrMise baseline and peak functions, which are separately implemented in the diffpy.srmise.baselines and diffpy.srmise.peaks subpackages. Specific baseline and peak functions inherit from the BaselineFunction and PeakFunction classes in those subpackges, as shown below.

  • class BaseFunction
    • class BaselineFunction
      • class FromSequence
      • class NanoSpherical
      • class Polynomial

      • etc.

    • class PeakFunction
      • class Gaussian
      • class GaussianOverR

      • etc.

Adding Baselines

To add a baseline, create a new module which defines a class inheriting from diffpy.srmise.baselines.base.BaselineFunction. The class data and methods which need to be implemented are summarized in the source code.

class BaselineFunction(BaseFunction):
    """Base class for functions which represent some data's baseline term.

    Class members
    -------------
    parameterdict: dict
        The dictionary mapping string keys to their index in the
        sequence of parameters.  These keys apply only to
        the default "internal" format.
    parformats: array-like
        The sequence of strings defining what formats are recognized
        by a baseline function.
    default_formats: dict
        The dictionary which maps the strings "default_input" and
        "default_output" to strings also appearing in parformats.
        "default_input"-> format used internally within the class
        "default_output"-> Default format to use when converting
        parameters for outside use.

    Class methods (implemented by inheriting classes)
    -------------------------------------------------
    estimate_parameters() (optional)
    _jacobianraw() (optional, but strongly recommended)
    _transform_derivativesraw() (optional, supports propagation of uncertainty for different paramaterizations)
    _transform_parametersraw()
    _valueraw()

    Class methods
    -------------
    actualize()

    Inherited methods
    -----------------
    jacobian()
    value()
    transform_derivatives()
    transform_parameters()
    """

The class methods should follow these specifications. See existing baselines for examples.

estimate_parameters(r, y)

Return a Numpy array of parameters estimated from the data.

Parameters:

  • r (Sequence) – Grid on which the data are defined.

  • y (Sequence) – The data.

Returns:

Estimated parameters

Return type:

numpy.ndarray

Raises:

NotImplementedError if estimation has not been implemented.

Raises:

SrMiseEstimationError if estimation fails.

_jacobian_raw(pars, r, free)

Return Jacobian for parameters evaluated over r.

Parameters:

  • pars (Sequence(float)) – The parameters of the baseline.

  • r (int, float, or Sequence(int or float)) – Scalar or grid on which to calculate the Jacobian.

  • free (Sequence(boolean)) – Boolean values indicating if corresponding parameter is free (True) or fixed (False).

Returns:

List of Jacobian values (or None if parameter is not free) for each parameter evaluated at r.

Return type:

list(numpy.ndarray(float) or float or None)

_transform_derivativesraw(pars, in_format, out_format)

Return the gradient matrix of pars represented in format ‘out_format’.

Parameters:

  • pars (Sequence(float)) – The parameters of the baseline.

  • in_format (str) – The format of pars.

  • out_format (str) – The desired format of pars.

Returns:

The gradient matrix for the transformation.

Return type:

numpy.ndarray

_transform_parametersraw(pars, in_format, out_format)

Return parameters transformed into format ‘out_format’.

Parameters:

  • pars (Sequence(float)) – The parameters of the baseline.

  • in_format (str) – The format of pars.

  • out_format (str) – The desired format of pars.

Returns:

The transformed parameters.

Return type:

numpy.ndarray

_valueraw(pars, r)

Return value of baseline with given parameters at r.

Parameters:

  • pars (Sequence(float)) – The parameters of the baseline.

  • r (int, float, or Sequence(int or float)) – Scalar or grid on which to calculate the baseline.

Returns:

The value of the baseline.

Return type:

float or numpy.ndarray(float).

Adding Peaks

To add a new peak function, create a new module which defines a class inheriting from diffpy.srmise.peaks.base.PeakFunction. Implementing a peak function is nearly identical to implementing a baseline function, with the following differences:

  1. The estimate_parameters method is required.

  2. The “position” key must be defined in the parameterdict class member.

  3. Peak functions must implement the additional method scale_at.

scale_at(pars, r, scale)

Return peak parameters such that the value at r is scaled by scale while the position of the peak’s maxima remains unchanged.

Parameters:

  • pars (Sequence(float)) – The parameters of the peak.

  • r (int or float) – Position where the peak will be rescaled.

  • scale (float) – A scale factor > 0.

Returns:

The adjusted peak parameters.

Return type:

numpy.ndarray(float).