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

#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

//////////////////////////////////////////////////////////////////////////////
// [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

//////////////////////////////////////////////////////////////////////////////
// [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

//////////////////////////////////////////////////////////////////////////////
// [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

//////////////////////////////////////////////////////////////////////////////
// [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

//////////////////////////////////////////////////////////////////////////////
// [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) GetObservations.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

//////////////////////////////////////////////////////////////////////////////