smx.zones.extraction
====================

.. py:module:: smx.zones.extraction

.. autoapi-nested-parse::

   Extract spectral zones from a DataFrame based on numeric column boundaries.



Functions
---------

.. autoapisummary::

   smx.zones.extraction.extract_spectral_zones


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

.. py:function:: extract_spectral_zones(Xcal: pandas.DataFrame, cuts: List[Union[Tuple, dict]]) -> Dict[str, pandas.DataFrame]

   Extract spectral zones from a DataFrame based on specified cuts.

   Parameters
   ----------
   Xcal : pd.DataFrame
       DataFrame with spectral data.  Columns must be numeric (or convertible
       to numeric) values representing wavelengths / energies.
   cuts : list of tuples/lists or dicts
       Each item defines a spectral zone to extract.

       * ``(start, end)`` — zone boundaries; name defaults to ``"start-end"``
       * ``(name, start, end)`` — named zone
       * ``(name, start, end, group)`` — named zone assigned to a group
       * ``{'name': str, 'start': float, 'end': float}`` — dict form
       * ``{'name': str, 'start': float, 'end': float, 'group': str}`` — dict
         form with grouping

       When multiple cuts share the same ``group`` value their column subsets
       are concatenated into a single zone keyed by the group name.  Cuts
       *without* a group are extracted individually under their own name, as
       before.

   Returns
   -------
   dict[str, pd.DataFrame]
       Dictionary where keys are zone names (or group names) and values are
       DataFrames with the extracted spectral data (same row index as *Xcal*).

   Examples
   --------
   >>> zones = extract_spectral_zones(X, [('Ca ka', 3.6, 3.7), ('Fe ka', 6.3, 6.5)])
   >>> zones['Ca ka'].shape
   (n_samples, n_cols_in_Ca_ka_zone)

   Group background regions into a single zone:

   >>> cuts = [
   ...     ('background 1', 1.0, 101.0, 'background'),
   ...     ('Feature 1',  101.0, 193.3),
   ...     ('background 2', 193.3, 255.4, 'background'),
   ...     ('Feature 2',  255.4, 341.6),
   ... ]
   >>> zones = extract_spectral_zones(X, cuts)
   >>> 'background' in zones   # True — merged from background 1 & 2
   True
   >>> 'background 1' in zones  # False — individual cuts absorbed into group
   False