{{{
#!comment
}}}
{{{
#!div style="width:15%; float:left; clear:none; margin-right:1em; background:#ffb; border:1px solid #b00; padding-left:1em; padding-right:1em"
[wiki:WikiStart Inicio] [[BR]] [[BR]]
'''MMS''' [[BR]] [wiki:Introduction Introducción] [[BR]] [wiki:Installation Instalación] [[BR]] [[BR]]
'''Paquetes''' [[BR]] [wiki:MMS.1] [[BR]] [wiki:RandVar] [[BR]] [wiki:DecoTools]
}}}
{{{
#!div style="width:50%; margin-left:20%; padding-left:2em; padding-right:2em"
{{{
#!comment
}}}
= DecoTools =
'''Módulo de descomposiciones y dueto's'''
== Introducción ==
Consúltese [wiki:Decompositions] para una discusión sobre el tema.
== 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. El concepto ===
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 tres o más elementos, el total y al menos un par de contribuciones:
{{{
deco = {deco1, deco2, deco3, ...}
^ ^ ^
| | contribution 2
| contribution 1
total
}}}
Véase la función [#Test]
=== 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]
* [#Contribution.Ref]
Para utilizar estas estructuras y reagrupar contribuciones véase la función [#Deco.BaseDefinition].
==== @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)
]]);
}}}
=== Variables auxiliares ===
==== PermutationsLimit ====
{{{Real PermutationsLimit}}}: Límite máximo de contribuciones para que se realize la descomposición canónica exacta.
Se utiliza en las funciones [#Deco.Canonical] y [#Deco.BaseCanonical]. Su valor por defecto es {{{6}}}, lo que ya supone un total de {{{6! = 720}}} permutaciones.
==== SampleSize ====
{{{Real SampleSize}}}: Tamaño por defecto de la muestra de permutaciones para realizar la descomposición canónica.
Se utiliza en las funciones [#Deco.Canonical] y [#Deco.BaseCanonical]. Su valor por defecto es {{{1000}}}.
==== SymmetricMode ====
{{{ Real SymmetricMode }}}: {{{True / False}}} Indica si la muestra de permutaciones para realizar la descomposición canónica se calcula de modo simétrico, alternando una permutación y su inversa.
==== CyclicMode ====
{{{ Real CyclicMode }}}: {{{True / False}}} Indica si la muestra de permutaciones para realizar la descomposición canónica se calcula de modo ciclo, es decir, calculando el ciclo de cada permutación.
Por ejemplo {{{ P1 = [[ 2, 3, 4, 1 ]] }}}, se calcula:
{{{
P2 = [[ 3, 4, 1, 2 ]];
P3 = [[ 4, 1, 2, 3 ]];
P4 = [[ 1, 2, 3, 4 ]];
}}}
Estas opciones consiguen que los efectos de la descomposición convergan antes al valor exacto, si tenemos que el número de contribuciones es mayor que {{{PermutationsLimit}}}.
== Funciones ==
A continuación se describen todas las funciones que ofrece DecoTools:
* [#Deco.Ordered]
* [#Deco.Marginal]
* [#Deco.FirstIn]
* [#Deco.Canonical]
* [#Deco.Canonical.Exact]
* [#Deco.Canonical.Sample]
* [#Deco.Exponential.Canonical]
* [#Deco.BaseOrdered]
* [#Deco.BaseMarginal]
* [#Deco.BaseFirstIn]
* [#Deco.BaseCanonical]
* [#Deco.BaseCanonical.Exact]
* [#Deco.BaseCanonical.Sample]
* [#Deco.Exponential.BaseCanonical]
* [#DueTo.Period]
* [#DueTo.Statistic]
* [#GeneralizedDueTo.Period]
* [#GeneralizedDueTo.Statistic]
* [#InverseDueTo.Period]
* [#Test]
* [#Deco.BaseDefinition]
* [#Deco.SynergyFree]
* [#Deco.BaseSynergyFree]
* [#Deco.Serie.DatCh]
* [#Deco.BaseRelative]
* [#Deco.TotalRelative]
=== Descomposiciones ===
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. En general la linealización de un modelo puede haberse realizado mediante una transformación cualquiera, el problema que solucionan las siguientes funciones consiste en encontrar una descomposición aditiva de un modelo que no era lineal, conocida la descomposición del modelo linealizado y la función de transformación inversa:
{{{
#!java
Set (Set decomposition, Code transf)
}}}
donde {{{decomposition}}} es la descomposición aditiva de partida (la del modelo transformado o linealizado) y {{{tranf}}} es la función inversa de la transformación que nos permitirá encontrar la descomposición aditiva del modelo en términos originales.
La discusión sobre este tema puede verse en: [wiki:Decompositions#Descomposiciónaditivademodelosmultiplicativos Descomposición aditiva de modelos multiplicativos].
==== Deco.Ordered ====
{{{Set Deco.Ordered(Set decomposition, Code transf)}}} [[BR]]
Devuelve la decomposición aditiva ordenada obtenida al aplicar la transformación.
Para más detalles véase: [wiki:Decompositions#Descomposiciónordenada Descomposición ordenada].
==== Deco.Marginal ====
{{{Set Deco.Marginal(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva marginal obtenida al aplicar la transformación.
Para más detalles véase: [wiki:Decompositions#DescomposiciónMarginalodecontribucionesmarginales Descomposición marginal].
==== Deco.FirstIn ====
{{{Set Deco.FirstIn(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva first-in obtenida al aplicar la transformación.
Para más detalles véase: [wiki:Decompositions#DescomposiciónFirstInodecontribucionesprimeras Descomposición first-in].
==== Deco.Canonical ====
{{{Set Deco.Canonical(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva canónica obtenida al aplicar la transformación. [[BR]]
Si el número de contribuciones excede el valor [#PermutationsLimit] se resolverá mediante una muestra de permutaciones de tamaño [#SampleSize].
Para más detalles véase: [wiki:Decompositions#Descomposicióncanónica Descomposición canónica].
==== Deco.Canonical.Exact ====
{{{Set Deco.Canonical.Exact(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva canónica obtenida al aplicar la transformación. [[BR]]
Realiza la descomposición canónica exacta promediando sobre todas las premutaciones independientemente del valor de {{{DecoTools::PermutationsLimit}}}.
==== Deco.Canonical.Sample ====
{{{Set Deco.Canonical.Sample(Set decomposition, Code transf, Real length)}}} [[BR]]
Devuelve la descomposición aditiva canónica obtenida al aplicar la transformación. [[BR]]
Realiza la descomposción canónica sobre una muestra de permutaciones del tamaño indicado.
==== Deco.Exponential.Canonical ====
{{{Set Deco.Exponential.Canonical(Set decomposition)}}} [[BR]]
Devuelve la descomposició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.
PAra más detalles véase el documento: [wiki:DecoTools/Doc01 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-prj.org/ticket/1180 TOL#1180]).
{{{
#!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.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.Canonical(deco0, rExp);
// [[ 33.115, (total)
// 1, (initial effect)
// 12.437, 5.198, 9.282, 5.198
// ]]
}}}
Nótese que las dos primeras descomposiciones: la marginal y la ''first-in'' (o de primera contribución) son inexactas y presentan sinergía (véase: [wiki:Decompositions#Descomposicionesinexactas Descomposiciones inexactas]).
Nótese también que la transformación exponencial presenta un efecto inicial no nulo (véase: [wiki:Decompositions#Efectoinicialdelatransformación Efecto inicial de la transformación]).
=== Descomposiciones base ===
Una situación muy habitual, que además nos facilita eliminar el efecto inicial de la transformación, es aquélla en la que la descomposición presenta una contribución principal sobre la que se pueden referir los efectos de las demás contribuciones. A esta contribución principal la denominaremos '''base''', de modo que una descomposición con base, viene dada por:
{{{
decomposition.base := {total, base, contributions} / total = base + Sum(contributions)
}}}
Las siguientes funciones funciones son unas variantes de las [#Descomposiciones anteriores] que, en general, también presentan la forma:
{{{
#!java
Set (Set decomposition, Code transf)
}}}
La discusión sobre este tema puede verse en: [wiki:Decompositions#Descomposicionesbase Descomposiciones base].
==== Deco.BaseOrdered ====
{{{Set Deco.BaseOrdered(Set decomposition, Code transf)}}} [[BR]]
Devuelve la decomposición aditiva ordenada con contribución base obtenida al aplicar la transformación.
==== Deco.BaseMarginal ====
{{{Set Deco.BaseMarginal(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva marginal con contribución base obtenida al aplicar la transformación.
==== Deco.BaseFirstIn ====
{{{Set Deco.FirstIn(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva first-in con contribución base obtenida al aplicar la transformación.
==== Deco.BaseCanonical ====
{{{Set Deco.BaseCanonical(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva canónica con contribución base obtenida al aplicar la transformación. [[BR]]
Si el número de contribuciones excede el valor [#PermutationsLimit] se resolverá mediante una muestra de permutaciones de tamaño [#SampleSize].
==== Deco.BaseCanonical.Exact ====
{{{Set Deco.BaseCanonical .Exact(Set decomposition, Code transf)}}} [[BR]]
Devuelve la descomposición aditiva canónica con contribución base obtenida al aplicar la transformación. [[BR]]
Realiza la descomposición canónica exacta promediando sobre todas las premutaciones independientemente del valor de {{{DecoTools::PermutationsLimit}}}.
==== Deco.BaseCanonical.Sample ====
{{{Set Deco.BaseCanonical .Sample(Set decomposition, Code transf, Real length)}}} [[BR]]
Devuelve la descomposición aditiva canónica con contribución base obtenida al aplicar la transformación. [[BR]]
Realiza la descomposción canónica sobre una muestra de permutaciones del tamaño indicado.
==== Deco.Exponential.BaseCanonical ====
{{{Set Deco.Exponential.BaseCanonical(Set decomposition)}}} [[BR]]
Devuelve la descomposición aditiva canónica con contribución base obtenida al aplicar la transformación exponencial.
==== Ejemplos ====
Para ilustrar estas funciones seguiremos usando la decomposición de partida [#Ejemplos1 anterior].
{{{
#!java
Set DecoTools::Deco.BaseOrdered(deco0, rExp);
// [[ 33.115, (total)
// 4.482 (base), 2.907, 12.696, 13.030
// ]]
}}}
{{{
#!java
Set DecoTools::Deco.BaseMarginal(deco0, rExp);
// [[ 33.115, (total)
// 4.482 (base), 13.030, 20.933, 13.030,
// -18.359 (synergy)
// ]]
}}}
{{{
#!java
Set DecoTools::Deco.BaseFirstIn(deco0, rExp);
// [[ 33.115, (total)
// 4.482 (base), 2.907, 7.701, 2.907,
// 15.118 (synergy)
// ]]
}}}
{{{
#!java
Set DecoTools::Deco.BaseCanonical(deco0, rExp);
// [[ 33.115, (total)
// 4.482 (base), 7.428, 13.777, 7.428
// ]]
}}}
=== DueTos ===
Unas descomposiciones muy comunes al trabajar con series temporales son las descomposiciones de tipo ''due-to'' (debido a) en las cuales el total se explica respecto a un valor de referencia suyo como la suma de éste más las diferencias causadas por las distintas contribuciones.
Podemos decir que son '''descomposiciones relativas'''.
Lo más habitual es buscar que este valor de referencia sea para cada instante el correspondiente a un número de instantes anterior. En DecoTools se implementaron dos mecanismos: (i) uno que usa estos valores anteriores ({{{.Period}}}) y (ii) otro que usa una función o un estadístico que se aplica sobre las series ({{{.Statistic}}}).
Para más detalles véase [Decompositions#DescomposiciónDueTo Descomposición DueTo].
==== DueTo.Period ====
{{{Set DueTo.Period(Set decomposition, Real period)}}} [[BR]]
Devuelve una descomposición de tipo dueto que explica el total como la suma de un valor base
correspondiente a un periodo anterior más las diferencias debidas a las demás contribuciones.
==== DueTo.Statistic ====
{{{Set DueTo.Statistic(Set decomposition, Code statistic)}}} [[BR]]
Devuelve una descomposición de tipo dueto que explica el total como la suma de un valor base
correspondiente a un estadístico del total más las diferencias debidas a las demás contribuciones.
==== GeneralizedDueTo.Period ====
{{{Set GeneralizedDueTo.Period(Set decomposition, Code transf, Real period)}}} [[BR]]
Devuelve una descomposición de tipo dueto generalizado que explica el total transformado
de manera proporcional al dueto respecto a un periodo anterior del total sin transformar.
Esta función permite obtener una descomposición de tipo dueto (en valores relativos)
aplicando la transformación sin tener que pasar una descomposición anterior.
Si se deseara obtener la descomposición en valores absolutos se necesitarían unos valores iniciales, véase [#InverseDueTo.Period].
==== GeneralizedDueTo.Statistic ====
{{{Set GeneralizedDueTo.Statistic(Set decomposition, Code transf, Code statistic)}}} [[BR]]
Devuelve una descomposición de tipo dueto generalizado que explica el total transformado
de manera proporcional al dueto respecto a un estadítico del total sin transformar.
==== InverseDueTo.Period ====
{{{Set InverseDueTo.Period(Set dueTo, Real period, Set decomposition0)}}} [[BR]]
Obtiene una descomposición a partir de una descomposición de tipo dueto respecto a un periodo anterior
y una descomposición con los valores iniciales.
Podemos ver las descomposiciones de tipo dueto como unas descomposiciones en diferencias, de modo que para invertir estas diferencias
y obtener una descomposición en unidades absolutas, es necesario disponer de unos valores iniciales.
=== Edición ===
==== Test ====
{{{Real Test(Set decomposition)}}} [[BR]]
Comprueba si una descomposición está bien definida, es decir, si el primer elemento (total) es igual a la suma del resto (contribuciones).
==== Deco.BaseDefinition ====
{{{Set Deco.BaseDefinition(Set decomposition, Set definition)}}} [[BR]]
Crea una nueva descomposición a partir de otra agrupando sus contribuciones según se indica en la nueva definición. [[BR]]
La primera contribución nueva será una contribución base y asumirá la diferencia que pudiera haber entre el total y la suma del resto de contribuciones.
==== Deco.SynergyFree ====
{{{Set Deco.SynergyFree(Set decomposition)}}} [[BR]]
Elimina la sinergía de una descomposición repartiéndola proporcionalmente entre las contribuciones.
==== Deco.BaseSynergyFree ====
{{{Set Deco.BaseSynergyFree(Set decomposition, Code transf)}}} [[BR]]
Elimina la sinergía y el posible efecto inicial de la transformación de una descomposición repartiéndola
proporcionalmente entre las contribuciones. [[BR]]
La transformación sólo se usa para determinar si la descomposición tiene efecto inicial.
==== Deco.Serie.DatCh ====
{{{Set Deco.Serie.DatCh(Set decomposition, TimeSet timeset, Code funS)}}} [[BR]]
Hace un cambio de fechado en una descomposición de series temporales.
Véase la función estándar {{{DatCh}}}.
==== Deco.BaseRelative ====
{{{Set Deco.BaseRelative(Set decomposition)}}} [[BR]]
Devuelve la descomposición correspondiente a la diferencia entre el total y la base, en unidades relativas a la base.
==== Deco.TotalRelative ====
{{{Set Deco.TotalRelative(Set decomposition))}}} [[BR]]
Devuelve la descomposición en unidades relativas al total.
== Ejemplos ==
A continuación se enlazan otros ejemplos de uso de DecoTools:
* [wiki:DecoTools/Use02 Ejemplo de uso 02]
}}}