= 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 ===