Data Structures
===============

The data structure for spectroscopic data is :class:`Orange.data.Table`.
Conversion to and from other data models is provided by
:class:`ewoksxas.converters.orange.Converter`.

Terminology
-----------

+-------------------+----------------+----------------+----------------+----------------+-----------------------------------------------+
| Domain            | Row            | Feature Column | Target Column  | Meta Column    | Description                                   |
+===================+================+================+================+================+===============================================+
| Tabular data      | row            | column         | column         | column         | A row is one record; a column is one field.   |
+-------------------+----------------+----------------+----------------+----------------+-----------------------------------------------+
| Machine learning  | sample         | feature        | target         | metadata       | A sample is described by features and may     |
|                   |                |                |                |                | have targets and metadata.                    |
+-------------------+----------------+----------------+----------------+----------------+-----------------------------------------------+
| Statistics        | observation    | variable       | response       | covariate      | An observation contains measured variables    |
|                   |                |                |                |                | and associated information.                   |
+-------------------+----------------+----------------+----------------+----------------+-----------------------------------------------+
| Measurement       | measurement    | variable       | result         | metadata       | A measurement contains measured quantities    |
|                   |                |                |                |                | and contextual information.                   |
+-------------------+----------------+----------------+----------------+----------------+-----------------------------------------------+
| Orange            | instance       | feature        | target         | meta           | An instance is one table row; columns have    |
|                   |                |                |                |                | feature, target, or meta roles.               |
+-------------------+----------------+----------------+----------------+----------------+-----------------------------------------------+
| Spectroscopy      | spectrum       | channel        | property       | metadata       | A spectrum contains intensities sampled along |
|                   |                |                |                |                | a spectral coordinate (e.g. photon energy).   |
+-------------------+----------------+----------------+----------------+----------------+-----------------------------------------------+

Orange Table Structure
----------------------

Each column has one of three roles:

- **feature**: measured values used as input data.
- **target**: values to predict or analyze.
- **meta**: additional information not used as input or target.

Example:

+-------------+-------------+-------------+-------------+-------------+-----------+
| Filename    | Scan number | Sample      | 7110 eV     | 7111 eV     | Quality   |
+=============+=============+=============+=============+=============+===========+
| meta        | meta        | meta        | feature     | feature     | target    |
+-------------+-------------+-------------+-------------+-------------+-----------+
| fe_foil.h5  | 1.1         | Fe foil     | 0.842       | 0.861       | good      |
+-------------+-------------+-------------+-------------+-------------+-----------+
| fe_foil.h5  | 2.1         | Fe foil     | 0.735       | 0.754       | good      |
+-------------+-------------+-------------+-------------+-------------+-----------+
| sample.h5   | 3.1         | Catalyst A  | 0.612       | 0.645       | poor      |
+-------------+-------------+-------------+-------------+-------------+-----------+

Features
~~~~~~~~

Features contain the measured spectral signal. In XAS, feature names
represent photon energy coordinates (typically in eV), and feature values
represent the measured response at each energy.

Example:

- Feature names: ``[7100, 7101, 7102]`` eV
- Feature values: measured absorption signal at these energies

Targets
~~~~~~~

Targets are variables to predict or analyze. They are optional and mainly
used in machine learning workflows.

Examples:

- ``Quality``: sample quality score
- ``Class``: material category (``glass``, ``metal``, ``plastic``)
- ``Concentration``: estimated chemical concentration

Targets are represented by:

- :class:`Orange.data.ContinuousVariable` for numeric values
  (e.g. concentration = 2.5 mg/L)
- :class:`Orange.data.DiscreteVariable` for categories
  (e.g. class = ``leaf`` or ``root``)

Metadata (metas)
~~~~~~~~~~~~~~~~

Metadata describes each spectrum but is not used as input features or
prediction targets.

Examples:

- sample location
- motor position
- acquisition timestamp
- experiment identifier

Metadata can be numeric, categorical, or text.