pyextal.jaxGeo.oversub
======================

.. py:module:: pyextal.jaxGeo.oversub

.. autoapi-nested-parse::

   Reflections whose integration background was over-subtracted.

   Weak reflections next to a bright one can have their integration background
   overestimated -- the annulus reaches into the neighbour's tail -- and
   ``ApertureSum`` then clips the result at zero. On SrTiO3 [001] data (-100) and
   (100), beside the direct beam, were 65-75 % zeros, and the rest sat well below
   the simulation. ``oversub`` models that instead of fitting against it: those
   channels are compared as ``max(sim - c - k * I(000), 0)``, where ``I(000)`` is
   the measured direct-beam intensity at the same pixel, and their data are clipped
   at zero to match (`jaxEngine.postProcess.apply_oversubtraction`). Where the data
   is zero and the model is at or below zero the residual vanishes, so a clipped
   pixel only says "at most zero", which is what it measured.

   ``c`` and ``k`` (one pair per reflection) are held at zero until
   ``oversub_start``, then fitted directly to the current simulation
   (:func:`enable_oversub`) and released to Adam. There is deliberately no
   per-reflection scale: it would absorb the structure-factor information those
   rocking curves carry. The stored variance is left as it is, so these channels
   still weigh what the integration's error propagation says they do.



Functions
---------

.. autoapisummary::

   pyextal.jaxGeo.oversub.crop
   pyextal.jaxGeo.oversub.oversub_config
   pyextal.jaxGeo.oversub.fit_oversub
   pyextal.jaxGeo.oversub.enable_oversub


Module Contents
---------------

.. py:function:: crop(arr, config)

   Crops (ny, nx, ...) data to the pixels `simulate` returns.

   With the Voigt probe on, `simulate` convolves in 'valid' mode and drops
   ``kernel_radius`` pixels on every side.


.. py:function:: oversub_config(config, g_include, wanted, leak=True)

   Switches the over-subtraction model on for some reflections, held at zero.

   :param config: The configuration.
   :type config: OptConfig
   :param g_include: (n_beams, 3) labels of the experimental beam axis.
   :type g_include: array-like
   :param wanted: ``(h, k, l)`` triples to model.
   :type wanted: sequence
   :param leak: Include the term proportional to the measured (000).
   :type leak: bool

   :returns: OptConfig

   :raises SetupError: If a reflection (or (000), with ``leak``) is not measured.


.. py:function:: fit_oversub(sim, exp, var, indices, leak_index, names)

   Fits the over-subtraction of each channel to a simulation, bounded >= 0.

   Bounded least squares of ``max(sim - c - k * I_leak, 0)`` against the data,
   with the loss's variance weights. The slope on ``sim`` is held at 1: a free
   per-channel scale would absorb the structure-factor information these
   channels carry.

   :param sim: (ny, nx, n_beams) simulation after scale and background.
   :type sim: np.ndarray
   :param exp: (ny, nx, n_beams) measured intensities, same pixels.
   :type exp: np.ndarray
   :param var: (ny, nx, n_beams) variances.
   :type var: np.ndarray
   :param indices: Channels to fit.
   :type indices: tuple
   :param leak_index: Leak source channel, or -1 for a constant offset only.
   :type leak_index: int
   :param names: Labels for the log.
   :type names: list

   :returns: ``(offsets, leaks)`` as arrays, one entry per channel.
   :rtype: tuple


.. py:function:: enable_oversub(params, metadata, config, data, sim, names)

   Starts the over-subtraction model from a fit to the current simulation.

   Adam moves a normalised parameter by about ``lr x range`` per step, so it
   cannot travel from zero to an offset of ~1e5 counts in a few hundred steps.
   Instead :func:`fit_oversub` fits the offset and leak of each channel
   directly, and Adam then refines them with the rest.

   :param params: Current normalised parameters.
   :type params: dict
   :param metadata: Current metadata; its oversub bounds are replaced.
   :type metadata: dict
   :param config: With ``oversub_indices`` set.
   :type config: OptConfig
   :param data: Holds ``experimental_data`` and ``variance``.
   :type data: dict
   :param sim: The current simulation (`simulate_safely`).
   :type sim: np.ndarray
   :param names: Labels of the channels, for the log.
   :type names: list

   :returns: ``(params, config)`` -- parameters holding the fitted values, and
             the config with ``oversub_optimize`` switched on.
   :rtype: tuple