Changes between Initial Version and Version 1 of DecoTools/Use02

Timestamp:

May 20, 2011, 11:26:41 AM (14 years ago)

Author:

Pedro Gea

Comment:

--

DecoTools/Use02

@@ +1 @@
+= Ejemplo de uso 02 =
+
+A continuación se incorpora un ejemplo de uso del paquete DecoTools.
+
+El código en SVN del ejemplo puede verse en: [source:branches/PRE-1.0/DecoTools/samples/use_decomposition_02.tol use_decomposition_02.tol].
+Puede descargarsedesde allí, yendo al final de la página y haciendo clic en el enlace: Download in other formats: Original Format.
+
+== Definición ==
+{{{
+#!java
+#Require DecoTools;
+
+//////////////////////////////////////////////////////////////////////////////
+// [1] Definición
+// 
+// Sea un modelo multiplicativa que linealizamos mediante un logaritmo
+// de la forma:
+//   Log(Observations) = Output = Sum(ExpTerms) + Noise
+
+// Admitamos que son tres términos explicativos y generamos los siguientes
+// datos ficticios a modo de ejemplo:
+
+Real PutRandomSeed(2143);
+Date begin = y2009;
+Date end = y2011m12;
+
+Serie noise = SubSer(Serie Gaussian(3, 1, Monthly), begin, end);
+Serie expTerm1 = SubSer(Serie Gaussian(0, 0.5, Monthly), begin, end);
+Serie expTerm2 = SubSer(Serie Rand(-0.25, 0.25, Monthly), begin, end);
+Serie expTerm3 = SubSer(Serie Gaussian(0.3, 0.1, Monthly), begin, end);
+
+Serie output = noise + expTerm1 + expTerm2 + expTerm3;
+
+// Con estos datos disponemos de la descomposición de partida u original:
+Set deco1 = [[ output, noise, expTerm1, expTerm2, expTerm3 ]];
+
+// Comprobamos que verifica ser una descomposición aditiva válida:
+Real ok1 = DecoTools::Test(deco1);
+}}}
+
+== Reagrupar una descomposición ==
+
+{{{
+#!java
+//////////////////////////////////////////////////////////////////////////////
+// [2] Reagrupar una descomposición
+
+// Es bastante común querer reagrupar los términos de una descomposición
+// sumando varios términos explicativos que tienen algo en común e incluso
+// restándoles un valor de referencia.
+
+// Para ello usaremos la función: 
+//  * DecoTools::Deco.BaseDefinition
+// y las estructuras: 
+//  * DecoTools::@Contribution.Def 
+//  * DecoTools::@Contribution.Ref
+
+// Al usar esta función la primera contribución resultante (denominada base)
+// asumirá la diferencia que pudiera haber entre el total y la suma del resto
+// de contribuciones.
+
+// Pongamos algunos ejemplos:
+
+// (a) Se desea unir  el primer término explicativo con el noise
+//     y denominarlo base
+
+Set deco2a = DecoTools::Deco.BaseDefinition(deco1, [[
+  DecoTools::@Contribution.Def("base", Copy(Empty)),
+  DecoTools::@Contribution.Def("expTerm2", [[ 
+    DecoTools::@Contribution.Ref("expTerm2", 0)
+  ]]),
+  DecoTools::@Contribution.Def("expTerm3", [[ 
+    DecoTools::@Contribution.Ref("expTerm3", 0)
+  ]])
+]]);
+
+// Esto se interpreta como: el término expTerm2 queda tal cual, lo mismo para
+// el expTerm3 y el resto (noise y expTerm1) se suman creando la base.
+
+// (b) Se desea dejar el noise como término base y sumar los términos 1 y 3
+
+Set deco2b = DecoTools::Deco.BaseDefinition(deco1, [[
+  DecoTools::@Contribution.Def("noise", Copy(Empty)),
+  DecoTools::@Contribution.Def("expTerm13", [[ 
+    DecoTools::@Contribution.Ref("expTerm1", 0),
+    DecoTools::@Contribution.Ref("expTerm3", 0)
+  ]]),
+  DecoTools::@Contribution.Def("expTerm2", [[ 
+    DecoTools::@Contribution.Ref("expTerm2", 0)
+  ]])
+]]);
+
+// (c) Se desea sumar los términos 1 y 2 y restar al término 3 su media,
+//     dejándola junto con le noise como contribución base.
+
+Set deco2c = DecoTools::Deco.BaseDefinition(deco1, [[
+  DecoTools::@Contribution.Def("noise", Copy(Empty)),
+  DecoTools::@Contribution.Def("expTerm12", [[ 
+    DecoTools::@Contribution.Ref(2, 0), // 2 -> expTerm1
+    DecoTools::@Contribution.Ref(3, 0)  // 3 -> expTerm2
+  ]]),
+  DecoTools::@Contribution.Def("expTerm3_mean0", [[ 
+    DecoTools::@Contribution.Ref(4, Code AvrS) // 4 -> expTerm3
+  ]])
+]]);
+
+// En este ejemplo nos referimos a las contribuciones de referencia con sus
+// índices y no con sus nombres.
+// Nótese que la contribución 1 es el segundo elemento (el noise). 
+}}}
+
+== Descomposición canónica ==
+{{{
+#!java
+//////////////////////////////////////////////////////////////////////////////
+// [3] Descomposición canónica
+
+// La descomposición canónica habitual es la que podríamos denominar
+// descomposición canónica con contribución base, en la que la primera
+// contribución se mantiene fija (habitualmente el noise) y se permutan
+// el resto de contribuciones.
+
+// La descomposición base-canónica de deco1, considerando que ésta se obtuvo
+// linealizando con el logaritmo es:
+
+Set deco3 = DecoTools::Deco.BaseCanonical(deco1, FindCode("Real", "Exp"));
+
+// Esta descomposición se hace recorriendo todas las permutaciones de las
+// contribuciones. Cuando el número de contribuciones es mayor de:
+Real DecoTools::PermutationsLimit;
+// y el número de permutaciones será:
+Real Factorial(DecoTools::PermutationsLimit+1);
+// o mayor se usará sólo una muestra de las permutaciones de tamaño:
+Real DecoTools::SampleSize;
+
+// Afortunadamente para la transformación exponenecial (modelos 
+// multiplicativos) disponemos de un algoritmo eficiente con el que obtener
+// la descomposición exacta, sin tener que muestrear:
+
+Set deco3_2 = DecoTools::Deco.Exponential.BaseCanonical(deco1); // == deco3
+}}}
+
+== DueTo ==
+{{{
+#!java
+//////////////////////////////////////////////////////////////////////////////
+// [4] DueTo
+
+// Básicamente un dueto es una descomposición propia de series temporales
+// donde cada instante del total se explica repecto a un instante anterior
+// como la suma de éste y las diferencias debidas a las contribuciones.
+
+// (a) Por ejemplo, el dueto respecto al mes anterior de deco1 sería:
+
+Set deco4a = DecoTools::DueTo.Period(deco1, 1);
+
+// (b) También podemos hacer el dueto de la descomposición de las 
+//     observaciones (Exp(output)) a partir de deco3
+
+Set deco4b = DecoTools::DueTo.Period(deco3, 1);
+
+// Hay un mecanismo de obtener una descomposición de tipo due-to para las
+// observaciones (en términos originales, no lienalizados) sin pasar por una
+// descomposición previa (como la descomposición canónica).
+// A este mecanismo podríamos denominarlo dueto generalizado y construyen el 
+// dueto de manera proporcional al dueto que obtendríamos sin aplicar la 
+// transformación.
+
+// (c) Obtengamos el dueto generalizado de deco1. 
+// El resultado es comparable, pero distinto al anterior deco4b.
+
+Set deco4c = DecoTools::GeneralizedDueTo.Period(deco1,
+  FindCode("Serie", "Exp"), 1);
+
+// A menudo el dueto de interés es en un fechado distinto, en el que las
+// series presenta periodicidad.
+// En el ejemplo que nos ocupa podría ser el fechado anual (Yearly).
+
+// Para calcular este dueto periódico es necesario hacer el cálculo
+// en fechado mensual con un periodo 12 y luego agregar los resultados
+// haciendo un cambio de fechado.
+
+// Nótese que en el caso de los dueto generalizados NO es lo mismo que 
+// agregar primero y hacer el dueto después.
+
+// (d) Al dueto generalizado y periódico se le conoce en general como dueto
+//     o dueto secuencial sin más calificativos.
+//     Calculemos este 'dueto' para deco1
+
+Set deco4d = {
+  Set aux = DecoTools::GeneralizedDueTo.Period(deco1,
+    FindCode("Serie", "Exp"), 12);
+  Set DecoTools::Deco.Serie.DatCh(aux, Yearly, SumS)
+};
+
+// (e) Un dueto periodico como el anterior (pero distinto) puede 
+//     obtenerse también desde la descomposición canónica deco3
+
+Set deco4e = {
+  Set aux = DecoTools::DueTo.Period(deco3, 12);
+  Set DecoTools::Deco.Serie.DatCh(aux, Yearly, SumS)
+};
+
+// Nótese que en este caso (sin usar dueto generalizado) los dos pasos
+// se pueden conmutar ya que son operaciones lineales.
+
+Set deco4e_2 = {
+  Set aux = DecoTools::Deco.Serie.DatCh(deco3, Yearly, SumS);
+  DecoTools::DueTo.Period(aux, 1)
+}; // == deco4e
+}}}
+
+== Representaciones relativas ==
+{{{
+#!java
+//////////////////////////////////////////////////////////////////////////////
+// [5] Representaciones relativas
+
+// En ocasiones, sobre todo en el caso de los dueto, es interesante
+// disponer de las descomposiciones en unidades relativas.
+// A continuación presentamos dos posibilidades.
+
+// (a) Representar la diferencia entre el total y la base (primera 
+//     contribución) de una descomposición (normalmente un dueto) en 
+//     unidades relativas a la base.
+//     Así de:
+//       {total, base, contrib1, contrib2, ....}
+//     obtenemos:
+//       {total/base-1, contrib1/base, contrib2/base, ...}
+
+Set deco5a = DecoTools::Deco.BaseRelative(deco4d);
+
+// Esta representación (pero ordenada) se utiliza para los gráficos de dueto
+// o gráficos en cascada.
+
+// (b) Representar una descomposición en unidades relativas al total.
+//     Así de:
+//       {total, contrib1, contrib2, ....}
+//     obtenemos:
+//       {1, contrib1/total, contrib2/total, ...}
+
+Set deco5b = DecoTools::Deco.TotalRelative(deco4d);
+}}}
+
+== Uso en MMS ==
+{{{
+#!java
+//////////////////////////////////////////////////////////////////////////////
+// [6] Uso en MMS
+
+// MMS incorpora algunos mecanismos de descomposición implementados
+// sobre la descomposición de partida:
+//   mmsDeco0 = {output, noise, expTerm1, expTerm2, ...}
+
+// Tomamos deco1 como la decomposición de partida de MMS y
+// la siguiente reagrupación de las contribuciones:
+
+Set contributions = [[
+  DecoTools::@Contribution.Def("noise", Copy(Empty)),
+  DecoTools::@Contribution.Def("expTerm13", [[ 
+    DecoTools::@Contribution.Ref("expTerm1", 0),
+    DecoTools::@Contribution.Ref("expTerm3", 0)
+  ]]),
+  DecoTools::@Contribution.Def("expTerm2", [[ 
+    DecoTools::@Contribution.Ref("expTerm2", 0)
+  ]])
+]];
+
+// (a) GetOutput.Decomposition(contributions)
+//     Simplemente usa: Deco.BaseDefinition 
+
+Set deco6a = DecoTools::Deco.BaseDefinition(deco1, contributions);
+
+// (b) GetObservations.Decomposition(contributions)
+//     Combina: Deco.BaseDefinition y Deco.BaseCanonical
+
+Set deco6b = {
+  Set aux = DecoTools::Deco.BaseDefinition(deco1, contributions);
+  DecoTools::Deco.BaseCanonical(deco1, FindCode("Real", "Exp"))
+};
+
+// La transformación la obtiene MMS del submodelo correspondiente
+
+// (c) GetOutput.SequentialDueTo(contributions)
+//     Combina: Deco.BaseDefinition,  DecoTools::GeneralizedDueTo.Period,
+//              DecoTools::Deco.Serie.DatCh y DecoTools::Deco.BaseRelative
+
+Set deco6C = {
+  Set aux = DecoTools::Deco.BaseDefinition(deco1, contributions);
+  Set aux2 = DecoTools::GeneralizedDueTo.Period(deco1,
+    FindCode("Serie", "Exp"), 12);
+  Set aux3 = DecoTools::Deco.Serie.DatCh(aux2, Yearly, SumS);
+  DecoTools::Deco.BaseRelative(aux3)
+};
+
+// El periodo 12 y el fechado armónico los obtiene MMS a partir de la
+// estructura ARIMA del submodelo correspondiente
+
+//////////////////////////////////////////////////////////////////////////////
+}}}