= DecoTools =

'''Módulo de descomposiciones y dueto's'''

== Introducción ==

... Véase [wiki:Decompositions]

== Definición ==

El paquete de descomposiciones y dueto's [wiki:DecoTools] ofrece un conjunto de funciones para la creación de descomposiciones aditivas. 

=== La descomposición ===

La unidad elemental sobre la que se construye todo el módulo es la ''decomposición''. En el paquete se denomina '''decomposición''' (aditiva) a todo conjunto de datos donde el primero de ellos denominado '''total''' es igual a la suma del resto, a los que se denominan '''contribuciones'''.

{{{
decomposition := {total, contributions} / total = Sum(contributions)
}}}

Por ejemplo:
{{{
#!java
a = {5, 2, 2, 1}    // OK
b = {4.4, 3.3, 1.0} // NO
c = {10}            // NO
}}}
el conjunto {{{a}}} es una descomposición, mientras que {{{b}}} y {{{c}}} no lo son.

Una descomposición se caracteriza así por tener dos o más elementos, siendo:
{{{
deco = {deco1, deco2, deco3, ...}
          ^      ^      ^
          |      |      contribution 2
          |      contribution 1
          total
}}}

=== Agrupación de contribuciones ===

Al trabajar con descomposiciones es bastante común querer agrupar las contribuciones y obtener así una nueva decomposición con menos contribuciones.
Para ello en DecoTools se crean dos estructuras TOL con las que definir cómo reagrupar una decomposición: 

==== @Contribution.Def ====

{{{Struct @Contribution.Def}}} es una estructura que permite definir una nueva contribución como combinación de contribuciones de referencia.
Sus argumentos son:
 * {{{Text Name}}}: Nombre de la nueva contribución.
 * {{{SetOf{@Contribution.Def} Contributions}}}: Conjunto de contribuciones de referencia que conformarán la nueva contribución.

==== @Contribution.Ref ====

{{{Struct @Contribution.Ref}}} es una estructura que permite definir una contribución de referencia.
Sus argumentos son:
 * {{{[Real|Text] Info}}}: Nombre de la contribución de referencia o su índice en la descomposición de referencia.
 * {{{[Real|Serie|...|Code] BasePart}}}: Parte que se sustrae a la contribución de referencia a la hora de crear la nueva contribución. Puede ser un valor fijo o una función que lo obtenga al aplicarla sobre la contribución.

==== Ejemplos ====

{{{
#!java
// Definición de una nueva contribución que agrupa (suma) 
// las tres primeras contribuciones de referencia:
Set @Contribution.Def("TresPrimeras", [[
  @Contribution.Ref(1, 0),
  @Contribution.Ref(2, 0),
  @Contribution.Ref(3, 0)
]]);
}}}

{{{
#!java
// Definición de una nueva contribución que suma dos series 
// (contribuciones) restándoles un nivel dado por su primer dato:
Set @Contribution.Def("DosSinNivel", [[
  @Contribution.Ref("SerieA", FirstS),
  @Contribution.Ref("SerieB", FirstS)
]]);
}}}

Para otros ejemplos véase [#Deco.BaseDefinition]

== Funciones ==

=== Descomposiciones por transformación ===

Una de las situaciones más comunes al crear una descomposición aditiva es partir de la descomposición de un modelo multiplicativo al que se tomaron logaritmos.

La discusión sobre este tema puede verse en: [wiki:Decompositions#Descomposiciónaditivademodelosmultiplicativos Descomposición aditiva de modelos multiplicativos]).

==== Deco.Marginal ====

{{{Set Deco.Marginal(Set decomposition, Code transf)}}} [[BR]]
Devuelve la decomposición aditiva marginal obtenida al aplicar la transformación.

==== Deco.FirstIn ====

{{{Set Deco.FirstIn(Set decomposition, Code transf)}}} [[BR]]
Devuelve la decomposición aditiva primera obtenida al aplicar la transformación.

==== Deco.Ordered ====

{{{Set Deco.Ordered(Set decomposition, Code transf)}}} [[BR]]
Devuelve la decomposición aditiva ordenada obtenida al aplicar la transformación.

==== Deco.Canonical ====

{{{Set Deco.Canonical(Set decomposition, Code transf)}}} [[BR]]
Devuelve la decomposición aditiva canónica obtenida al aplicar la transformación.
Se resolverá mediante una muestra de las permutaciones cuyo número no supera la variable {{{DecoTools::SampleSize}}}

==== Deco.Exponential.Canonical ====

{{{Set Deco.Exponential.Canonical(Set decomposition)}}} [[BR]]
Devuelve la decomposición aditiva canónica obtenida al aplicar la transformación exponencial.

Esta función utiliza un algoritmo que permite, para la transformación exponencial, calcular el promedio sobre todas las permutaciones sin calcularlas.
Véase el documento: ''Descomposición aditiva de contribuciones multiplicativas''

==== Ejemplos ====

Tomemos como ejemplo para ilustrar las funciones la siguiente descomposición de partida con 4 contribuciones:
{{{
#!java
Set deco0 = [[3.5, 1.5, 0.5, 1.0, 0.5]];
}}}
y sea {{{rExp}}} la transformación exponencial:
{{{
#!java
Code rExp = FindCode("Real", "Exp");
}}}
que se define para evitar la advertencia que causa su sobrecarga (véase [https://www.tol-project.org/ticket/1180 TOL#1180]).

{{{
#!java
Set DecoTools::Deco.Marginal(deco0, rExp);
// [[ 33.115, (total)
//    1, (initial effect)
//    25.726, 13.030, 20.933, 13.030, 
//    -40.604 (synergy)
// ]]
}}}
{{{
#!java
Set DecoTools::Deco.FirstIn(deco0, rExp);
// [[ 33.115, (total)
//    1, (initial effect)
//    3.482, 0.649, 1.718, 0.649, 
//    25.617 (synergy)
// ]]
}}}
{{{
#!java
Set DecoTools::Deco.Ordered(deco0, rExp);
// [[ 33.115, (total)
//    1, (initial effect)
//    3.482, 2.907, 12.696, 13.030
// ]]
}}}
{{{
#!java
Set DecoTools::Deco.Canonical(deco0, rExp);
//> [Deco.Canonical] La descomposición se realizará sobre una muestra de 1000 permutaciones escogidas al azar.
Set DecoTools::Deco.Exponential.Canonical(deco0);
// [[ 33.115, (total)
//    1, (initial effect)
//    12.437, 5.198, 9.282, 5.198
// ]]
}}}