.. _superdataset:

SuperDataset
============

.. container:: lang-en

   Builds the superdataset used to train and evaluate predictive models: for
   each *feasible* event (with a value of the target variable) of each spot it
   computes all the described features and the class to predict at the given
   horizon. Native port of ``gen_datasets.R`` (steps 1–3 and 5: configuration,
   events join, superdataset construction and class type). Missing-value
   imputation (step 4, disabled by default in R) is left to Orange's
   **Impute** widget.

   **Inputs**: **Events** (table with ``SPOT_ID``, ``TIME`` and the variables;
   the output of **Events Fusion** — without ``SPOT_ID`` it is a single spot)
   and **Features Description** (output of **Features Description** or an
   ``attributes-spec`` read with **File**).

   **Outputs**

   - **SuperDataset**: one row per feasible event; ``SPOT_ID``, ``IDX`` and
     ``TIME`` as meta attributes (optional), the generated features, the
     previous horizons ``OUT_k+1..OUT_k+h-1`` and the class ``CLASS``
     (= ``OUT_k+h``) as target. With ``delta-reg`` the target is
     ``CLASS_DELTA`` and ``CLASS`` becomes a meta attribute.
   - **Events**: the events used, with ``IDX`` and ``FEASIBLE``.
   - **Features Description**: the rows actually used.

   **Model configuration (the former ``<Model>.cfg``)**

   - *Target variable* and *Horizon*: the class is the value of the target at
     the ``h``-th future event with output, if it is closer than
     ``AheadTolerance × h`` units.
   - *Class type*: ``reg`` or the discretisations ``classif3``,
     ``classif3S``, ``classif3crom``, ``classif4``, ``classif5``,
     ``delta-reg``, ``delta-classif`` or custom cut points.
   - *Include previous horizons*: ``removePreviousHorizons = FALSE``.
   - *Frequency*: unit of windows and tolerances (days, hours or years).
   - *Cycle type*: defines ``FE``, ``FCE`` and ``PREVCYCLE``.
   - *Events per horizon* and *Tolerance*.
   - *Missing-value thresholds*: a feature (except ``LAST`` and rows with
     Param7 = 1) is missing when the missing proportion of the variable in the
     scope exceeds ``missingAttrCalcThreshold`` or the largest relative
     consecutive gap exceeds ``missingConsecAttrCalcThreshold``.

   The build runs in the background when **Build superdataset** is pressed
   (with a progress bar and cancellation); the log shows the processed spots,
   warnings and the resulting size.

   **Differences with the R code**: no files are read or written; the
   project-specific feature types (``SIF``, ``ASIF``, ...) of ``definitions.R``
   are ignored with a warning; behaviour follows the current R version (v6,
   October 2024): empty constrained count = 0, ``SD`` of a single value = 0,
   winter from 21 Dec to 20 Mar and previous autumn from 21 Sep to 20 Dec.

.. container:: lang-es

   Construye el superdataset para entrenar y evaluar modelos predictivos: para
   cada evento *factible* (con valor de la variable objetivo) de cada spot
   calcula todos los atributos descritos y la clase a predecir en el horizonte
   indicado. Port nativo de ``gen_datasets.R`` (pasos 1 a 3 y 5:
   configuración, unión de eventos, construcción del superdataset y cambio del
   tipo de clase). La imputación de valores ausentes (paso 4, desactivada por
   defecto en R) se deja al widget **Impute** de Orange.

   **Entradas**: **Events** (tabla con ``SPOT_ID``, ``TIME`` y las variables;
   salida de **Events Fusion** — sin ``SPOT_ID`` se trata como un único spot)
   y **Features Description** (salida de **Features Description** o un
   ``attributes-spec`` leído con **File**).

   **Salidas**

   - **SuperDataset**: una fila por evento factible; ``SPOT_ID``, ``IDX`` y
     ``TIME`` como metadatos (opcional), los atributos generados, los
     horizontes previos ``OUT_k+1..OUT_k+h-1`` y la clase ``CLASS``
     (= ``OUT_k+h``) como variable objetivo. Con ``delta-reg`` la variable
     objetivo es ``CLASS_DELTA`` y ``CLASS`` pasa a metadato.
   - **Events**: los eventos usados, con ``IDX`` y ``FEASIBLE``.
   - **Features Description**: las filas efectivamente usadas.

   **Configuración del modelo (antiguo ``<Model>.cfg``)**

   - *Variable objetivo* y *Horizonte*: la clase es el valor de la variable
     objetivo en el ``h``-ésimo evento futuro con salida, si está a menos de
     ``AheadTolerance × h`` unidades.
   - *Tipo de clase*: ``reg`` o las discretizaciones ``classif3``,
     ``classif3S``, ``classif3crom``, ``classif4``, ``classif5``,
     ``delta-reg``, ``delta-classif`` o puntos de corte personalizados.
   - *Incluir los horizontes previos*: ``removePreviousHorizons = FALSE``.
   - *Frecuencia*: unidad de las ventanas y tolerancias (días, horas o años).
   - *Tipo de ciclo*: define ``FE``, ``FCE`` y ``PREVCYCLE``.
   - *Eventos por horizonte* y *Tolerancia*.
   - *Umbrales de valores ausentes*: un atributo (salvo ``LAST`` y las filas
     con Param7 = 1) queda ausente cuando la proporción de ausentes de la
     variable en el ámbito supera ``missingAttrCalcThreshold`` o el mayor
     hueco consecutivo relativo supera ``missingConsecAttrCalcThreshold``.

   La construcción se ejecuta en segundo plano al pulsar **Generar
   superdataset** (con barra de progreso y posibilidad de cancelar); el
   registro muestra los spots procesados, los avisos y el tamaño resultante.

   **Diferencias respecto al código R**: no se leen ni escriben ficheros; los
   tipos de atributo específicos de proyecto (``SIF``, ``ASIF``, ...) de
   ``definitions.R`` se ignoran con aviso; el comportamiento reproduce la
   versión actual del R (v6, octubre 2024): recuento vacío con restricción =
   0, ``SD`` de un único valor = 0, invierno del 21-dic al 20-mar y otoño
   anterior del 21-sep al 20-dic.
