= 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 (más detalles [wiki:Decompositions#Descomposiciónaditivadesubmodelosmultiplicativos aquí]).

==== Deco.Marginal ====

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


==== 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
// ]]
}}}