//::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
/** @author  John Miller
 *  @version 1.6
 *  @date    Sat Apr 30 13:32:23 EDT 2016
 *  @see     LICENSE (MIT style license file).
 *
 *  @title   The `forecaster` Package Object
 */

package scalation.analytics

import scalation.{DATA_DIR, ⁄}

import scalation.linalgebra.{VectoD, VectorD}
import scalation.util.Error

//::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
/** The `forecaster` package contains classes, traits and objects for forecaster.
 *  @see `DiffTest` for testing of the 'diff' and 'undiff' methods.
 */
package object forecaster extends Error
{
    /** The relative path for base directory
     */
    val BASE_DIR = DATA_DIR + "analytics" + ⁄ + "forecaster" + ⁄

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the '1'-st difference on vector/time-series 'y'.  For efficiency,
     *  this method is destructive of 'y' (make a copy to preserve).
     *  Note, it stores the first value in the original times-series in the first
     *  position of the differenced vector.
     *  @param y  the vector/time-series to be differenced 
     */
    def diff (y: VectoD)
    {
        for (i <- y.dim - 1 to 1 by -1) y(i) -= y(i-1)
    } // diff

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the 'd'-th difference on vector/time-series 'y'.  For efficiency,
     *  this method is destructive of 'y' (make a copy to preserve).
     *  @param y  the vector/time-series to be differenced 
     *  @param d  the order or number of differences to be taken
     */
    def diff (y: VectoD, d: Int)
    {
        if (d < 1) flaw ("diff", s"requires the number of differences $d > 0")
        for (k <- 1 to d) diff (y)
    } // diff

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the '1'-st inverse-difference on vector/time-series 'y'.  For efficiency,
     *  this method is destructive of 'y' (make a copy to preserve).
     *  Restores the original time-series if 'y(0)' holds first value in original time-series. 
     *  @param y  the vector/time-series to be inverse-differenced
     */
    def diffinv (y: VectoD)
    {
        for (i <- 1 until y.dim) y(i) += y(i-1)
    } // diffinv

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the 'd'-th inverse-difference on vector/time-series 'y'.  For efficiency,
     *  this method is destructive of 'y' (make a copy to preserve).
     *  Restores the original time-series if 'y(0)' holds first value in original time-series. 
     *  @param y  the vector/time-series to be inverse-differenced 
     *  @param d  the order or number of inverse-differences to be taken
     */
    def diffinv (y: VectoD, d: Int)
    {
        if (d < 1) flaw ("diffinv", s"requires the number of inverse-differences $d > 0")
        for (k <- 1 to d) diffinv (y)
    } // diffingv

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the '1'-st seasonal difference on vector/time-series 'y'.  For efficiency,
     *  this method is destructive of 'y' (make a copy to preserve).
     *  @param y  the vector/time-series to be differenced
     *  @param s  the seasonal period
     */
    def sdiff (y: VectoD, s: Int)
    {
        if (s < 2) flaw ("sdiff", s"requires the seasonal period $s > 1")
        for (i <- y.dim - 1 to s by -1) y(i) -= y(i-s)
    } // sdiff

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the 'd'-th seasonal difference on vector/time-series 'y'.  For efficiency,
     *  this method is destructive of 'y' (make a copy to preserve).
     *  @param y  the vector/time-series to be differenced 
     *  @param d  the order or number of differences to be taken
     *  @param s  the seasonal period
     */
    def sdiff (y: VectoD, d: Int, s: Int)
    {
        if (d < 1) flaw ("sdiff", s"requires the number of differences $d > 0")
        if (s < 2) flaw ("sdiff", s"requires the seasonal period $s > 1")
        for (k <- 1 to d) sdiff (y, s)
    } // sdiff

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the '1'-st seasonal inverse-difference on vector/time-series 'y'.  For
     *  efficiency, this method is destructive of 'y' (make a copy to preserve).
     *  Restores the original time-series if 'y(0)' holds first value in original time-series. 
     *  @param y  the vector/time-series to be inverse-differenced
     *  @param s  the seasonal period
     */
    def sdiffinv (y: VectoD, s: Int)
    {
        if (s < 2) flaw ("sdiffinv", s"requires the seasonal period $s > 1")
        for (i <- s until y.dim) y(i) += y(i-s)
    } // sdiffinv

    //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    /** Take the 'd'-th seasonal inverse-difference on vector/time-series 'y'.  For
     *  efficiency, this method is destructive of 'y' (make a copy to preserve).
     *  Restores the original time-series if 'y(0)' holds first value in original time-series. 
     *  @param y  the vector/time-series to be inverse-differenced 
     *  @param d  the order or number of inverse-differences to be taken
     *  @param s  the seasonal period
     */
    def sdiffinv (y: VectoD, d: Int, s: Int)
    {
        if (d < 1) flaw ("sdiffinv", s"requires the number of inverse-differences $d > 0")
        if (s < 2) flaw ("sdiffinv", s"requires the seasonal period $s > 1")
        for (k <- 1 to d) sdiffinv (y, s)
    } // sdiffinv

} // forecaster package object