Merge pull request #1 from atecon/feature/some-update

Feature/some update
atecon · Mar 8, 2023 · 48d70c2 · 48d70c2
2 parents 0a40a29 + 48da915
commit 48d70c2
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 61 deletions.
diff --git a/src/Makefile b/src/Makefile
@@ -1,22 +1,13 @@
 PKG = auto_arima
 
 $(PKG).gfn: $(PKG).inp $(PKG).spec $(PKG)_help.txt $(PKG)_sample.inp
+	fold -s -w 80 $(PKG)_help.txt | tee $(PKG)_help.txt
 	gretlcli --makepkg $(PKG).inp
 
-#$(PKG).pdf: $(PKG).tex
-#	pdflatex $<
-#	bibtex $(PKG)
-#	pdflatex $<
-#	pdflatex $<
-
-#$(PKG).zip: $(PKG).gfn $(PKG).pdf
-#	echo makepkg $(PKG).zip | gretlcli -b -
-
-#install: $(PKG).zip
-#	echo pkg install $(PKG).zip --local | gretlcli -b -
+#format: $(PKG)_help.txt
 
 install: $(PKG).gfn
 	echo pkg install $(PKG).gfn --local | gretlcli -b -
 
-#clean:
-#	rm -f $(PKG).zip
+clean:
+	rm -f $(PKG).zip
diff --git a/src/auto_arima.gfn b/src/auto_arima.gfn
@@ -2,28 +2,33 @@
 <gretl-functions>
 <gretl-function-package name="auto_arima" needs-time-series-data="true" minver="2020b">
 <author email="atecon@posteo.de">Artur Tarassow</author>
-<version>0.6</version>
-<date>2020-08-04</date>
-<description>Return best ARIMA model according to information criteria value</description>
+<version>0.8</version>
+<date>2023-03-02</date>
+<description>Return best SARIMA(x) model according to information criteria value</description>
 <tags>C22 C52</tags>
 <label>Automatic ARIMA</label>
 <menu-attachment>MAINWIN/Model/TSModels</menu-attachment>
 <help>
 Fit best SARIMA(X) model to univariate time series.
 
-Returns best SARIMAX model according to either AIC, AICc, BIC or HQC value. The function conducts a (brute force) search over possible models within the order constraints provided.
+Returns best SARIMA(X) model according to either AIC, AICc, BIC or HQC value.
+The function conducts a (brute force) search over possible models within the
+order constraints provided.
 
-
-This is an alternative package to the existing gretl armax package written by Yi-Nung Yang which has some limitations, e.g. it does only work for ARMA type models.
+This is an alternative package to the existing gretl &quot;armax&quot; package written by
+Yi-Nung Yang which has some limitations compared to this package (e.g. it does
+only support ARMA type models).
 
 The features of the auto_arima package are:
 - Consideration of seasonal ARIMA models with and without exogenous regressors.
-- Simple API.
-- GUI access through the gretl menu.
-- Public convenience functions for the user for summarizing results, or retrieving the gretl ARIMA command of the 'best' model.
+- Simple user-interface.
+- GUI-access through the gretl menu.
+- Public convenience functions for the user for summarizing results, or
+  retrieving the gretl ARIMA command of the 'best' model.
 - Source code is tested by means of unit-tests to minimize bugs.
 
-Please ask questions and report bugs on the gretl mailing list if possible. Alternatively, create an issue ticket on the github repo (see below).
+Please ask questions and report bugs on the gretl mailing list if possible.
+Alternatively, create an issue ticket on the github repo (see below).
 Source code and test script(s) can be found here:
 https://github.com/atecon/auto_arima
 
@@ -36,12 +41,12 @@ Function:       auto_arima(const series y, const list xlist[null],
 Arguments:
 y:              series, Endogenous variable
 xlist:          list, List of exogenous variables (optional)
-opts:           bundle, Bundle for passing SARIMA parameters and further
+opts:           bundle, Bundle for passing SARIMA(X) parameters and further
                 options (see below for details)
 
 Return:
 Bundle comprising the various items.
------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
 Function:       print_auto_arima_results(const bundle model)
@@ -52,7 +57,7 @@ model:          bundle, Bundle returned by auto_arima() function
 Return:
 No return value. Print summary results for each parameter combination and
 information criteria estimated in tabular form.
------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
 Function:       get_auto_arima_parameters (const bundle model, const string
@@ -66,8 +71,9 @@ model_rank:     int, Compute the SARIMA parameter vector for the n-th
                 best model in terms of the chosen information criteria.
 
 Return:
-Vector of SARIMA parameters of the n-th best model in terms of the chosen information criteria.
------------------------------------------------------------------------
+Vector of SARIMA parameters of the n-th best model in terms of the chosen
+information criteria.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
 Function:       get_auto_arima_command (const bundle model, const string
@@ -82,15 +88,16 @@ model_rank:     int, Consider the n-th best model in terms of the chosen
 
 Return:
 String holding the gretl/ hansl command for estimating the selected model.
------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
-Function:       auto_arima_gui(none)
+Function:       auto_arima_gui(void)
 
 Arguments:
 
 Return:
-A wrapper for the GUI. Prints summary results and returns a bundle with model results.
+A wrapper for the GUI. Prints summary results and returns a bundle with model
+results.
 -----------------------------------------------------------------------
 
 
@@ -104,17 +111,17 @@ auto_arima() function. Currently, the following options are supported:
                      (default 1).
 * with_intercept:    bool, if 1 (or TRUE) an intercept is added to the
                      model, of 0 (or FALSE) no intercept is added (default 1).
-* with_seasonality:  bool, if 1 (or TRUE) seasonal ARIMA parameters
+* with_seasonality:  bool, if 1 (or TRUE) seasonal ARIMA parameter
                      combinations are considered (if the data frequency
                      has seasonality), otherwise seasonal ARIMA parameters
                      are not considered (default 1).
 * estimation_method: string, if &quot;conditional_ml&quot; use conditional maximum
                      likelihood
-* min_p, max_p, min_d, max_d, min_q, max_q, min_P, max_P, min_D, max_D, min_Q, max_Q:               Model parameters (see below for explanations)
-
+* min_p, max_p, min_d, max_d, min_q, max_q, min_P, max_P, min_D, max_D,
+  min_Q, max_Q:      Model parameters (see below for explanations)
 
 
-Default SARIMA parameter values:
+Default SARIMA(X) parameter values:
 --------------------------------
 * min_p          :  scalar, minimum autoregressive order (default 0)
 * max_p          :  scalar, maximum autoregressive order (default 4)
@@ -130,8 +137,16 @@ Default SARIMA parameter values:
 * max_Q          :  scalar, maximum seasonal moving-average order (default 1)
 
 
-
 Changelog:
+- v0.8, February 2023:
+   + Remove line breaks in help text
+   + Fix typos
+
+- v0.7, September 2020:
+   + Bugfix: In case if verbose=0 an error in the arima command was not caught
+     which led to a full stop.
+   + Set default for parameter &quot;verbose&quot; to 0 (do not print details).
+
 - v0.6, August 2020:
    + Fix bug in print_table_and_row_labels(): wrong models where highlighted
      as best ones.
@@ -158,6 +173,16 @@ Changelog:
 
 - v0.5, July 2020:
     + initial release
+
+
+TODO:
+=====
+- Re-think the defaults for the AR part 1 and 4
+- The GUI is quite busy, with all those possible min/max orders. I would
+imagine that for a &quot;quick and dirty&quot; job one would always want to specify the
+_maximum_ order, but in general the _minimum_ order should be always 0.
+Therefore, it may make sense to get rid of most of those boxes, and tell the
+user that to do fancy things one should use scripting.
 </help>
 <gretl-function name="auto_arima" type="bundle">
  <params count="3">
@@ -343,7 +368,7 @@ print_auto_arima_results(self)
 series y = self.y
 if isconst(y) == TRUE
   if self.verbose &gt; 0
-    printError(sprintf(&quot;Endogenous series '%s' is constant..&quot;, self.name_yseries))
+    printError(sprintf(&quot;Endogenous series '%s' is constant.&quot;, self.name_yseries))
   endif
   self.error = TRUE
 endif

diff --git a/src/auto_arima.inp b/src/auto_arima.inp
@@ -5,7 +5,7 @@ function void y_is_constant (bundle *self)
 
     if isconst(y) == TRUE
         if self.verbose > 0
-            printError(sprintf("Endogenous series '%s' is constant..", self.name_yseries))
+            printError(sprintf("Endogenous series '%s' is constant.", self.name_yseries))
         endif
         self.error = TRUE
     endif

diff --git a/src/auto_arima.spec b/src/auto_arima.spec
@@ -1,8 +1,8 @@
 author = Artur Tarassow
 email = atecon@posteo.de
-version = 0.6
-date = 2020-08-04
-description = Return best ARIMA model according to information criteria value
+version = 0.8
+date = 2023-03-02
+description = Return best SARIMA(x) model according to information criteria value
 tags = C22 C52
 min-version = 2020b
 public = auto_arima print_auto_arima_results get_auto_arima_parameters get_auto_arima_command auto_arima_gui print_auto_arima_results_gui

diff --git a/src/auto_arima_help.txt b/src/auto_arima_help.txt
@@ -1,18 +1,23 @@
 Fit best SARIMA(X) model to univariate time series.
 
-Returns best SARIMAX model according to either AIC, AICc, BIC or HQC value. The function conducts a (brute force) search over possible models within the order constraints provided.
+Returns best SARIMA(X) model according to either AIC, AICc, BIC or HQC value.
+The function conducts a (brute force) search over possible models within the
+order constraints provided.
 
-
-This is an alternative package to the existing gretl armax package written by Yi-Nung Yang which has some limitations, e.g. it does only work for ARMA type models.
+This is an alternative package to the existing gretl "armax" package written by
+Yi-Nung Yang which has some limitations compared to this package (e.g. it does
+only support ARMA type models).
 
 The features of the auto_arima package are:
 - Consideration of seasonal ARIMA models with and without exogenous regressors.
-- Simple API.
-- GUI access through the gretl menu.
-- Public convenience functions for the user for summarizing results, or retrieving the gretl ARIMA command of the 'best' model.
+- Simple user-interface.
+- GUI-access through the gretl menu.
+- Public convenience functions for the user for summarizing results, or
+  retrieving the gretl ARIMA command of the 'best' model.
 - Source code is tested by means of unit-tests to minimize bugs.
 
-Please ask questions and report bugs on the gretl mailing list if possible. Alternatively, create an issue ticket on the github repo (see below).
+Please ask questions and report bugs on the gretl mailing list if possible.
+Alternatively, create an issue ticket on the github repo (see below).
 Source code and test script(s) can be found here:
 https://github.com/atecon/auto_arima
 
@@ -25,12 +30,12 @@ Function:       auto_arima(const series y, const list xlist[null],
 Arguments:
 y:              series, Endogenous variable
 xlist:          list, List of exogenous variables (optional)
-opts:           bundle, Bundle for passing SARIMA parameters and further
+opts:           bundle, Bundle for passing SARIMA(X) parameters and further
                 options (see below for details)
 
 Return:
 Bundle comprising the various items.
------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
 Function:       print_auto_arima_results(const bundle model)
@@ -41,7 +46,7 @@ model:          bundle, Bundle returned by auto_arima() function
 Return:
 No return value. Print summary results for each parameter combination and
 information criteria estimated in tabular form.
------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
 Function:       get_auto_arima_parameters (const bundle model, const string
@@ -55,8 +60,9 @@ model_rank:     int, Compute the SARIMA parameter vector for the n-th
                 best model in terms of the chosen information criteria.
 
 Return:
-Vector of SARIMA parameters of the n-th best model in terms of the chosen information criteria.
------------------------------------------------------------------------
+Vector of SARIMA parameters of the n-th best model in terms of the chosen
+information criteria.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
 Function:       get_auto_arima_command (const bundle model, const string
@@ -71,15 +77,16 @@ model_rank:     int, Consider the n-th best model in terms of the chosen
 
 Return:
 String holding the gretl/ hansl command for estimating the selected model.
------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------------------------------
-Function:       auto_arima_gui(none)
+Function:       auto_arima_gui(void)
 
 Arguments:
 
 Return:
-A wrapper for the GUI. Prints summary results and returns a bundle with model results.
+A wrapper for the GUI. Prints summary results and returns a bundle with model
+results.
 -----------------------------------------------------------------------
 
 
@@ -93,17 +100,17 @@ auto_arima() function. Currently, the following options are supported:
                      (default 1).
 * with_intercept:    bool, if 1 (or TRUE) an intercept is added to the
                      model, of 0 (or FALSE) no intercept is added (default 1).
-* with_seasonality:  bool, if 1 (or TRUE) seasonal ARIMA parameters
+* with_seasonality:  bool, if 1 (or TRUE) seasonal ARIMA parameter
                      combinations are considered (if the data frequency
                      has seasonality), otherwise seasonal ARIMA parameters
                      are not considered (default 1).
 * estimation_method: string, if "conditional_ml" use conditional maximum
                      likelihood
-* min_p, max_p, min_d, max_d, min_q, max_q, min_P, max_P, min_D, max_D, min_Q, max_Q:               Model parameters (see below for explanations)
-
+* min_p, max_p, min_d, max_d, min_q, max_q, min_P, max_P, min_D, max_D,
+  min_Q, max_Q:      Model parameters (see below for explanations)
 
 
-Default SARIMA parameter values:
+Default SARIMA(X) parameter values:
 --------------------------------
 * min_p          :  scalar, minimum autoregressive order (default 0)
 * max_p          :  scalar, maximum autoregressive order (default 4)
@@ -119,8 +126,16 @@ Default SARIMA parameter values:
 * max_Q          :  scalar, maximum seasonal moving-average order (default 1)
 
 
-
 Changelog:
+- v0.8, February 2023:
+   + Remove line breaks in help text
+   + Fix typos
+
+- v0.7, September 2020:
+   + Bugfix: In case if verbose=0 an error in the arima command was not caught
+     which led to a full stop.
+   + Set default for parameter "verbose" to 0 (do not print details).
+
 - v0.6, August 2020:
    + Fix bug in print_table_and_row_labels(): wrong models where highlighted
      as best ones.
@@ -147,3 +162,13 @@ Changelog:
 
 - v0.5, July 2020:
     + initial release
+
+
+TODO:
+=====
+- Re-think the defaults for the AR part 1 and 4
+- The GUI is quite busy, with all those possible min/max orders. I would
+imagine that for a "quick and dirty" job one would always want to specify the
+_maximum_ order, but in general the _minimum_ order should be always 0.
+Therefore, it may make sense to get rid of most of those boxes, and tell the
+user that to do fancy things one should use scripting.