New-estimation-interface.md

+# `data` command
+
+This command initializes the dataset (a `dseries` object). The following options are available: 
+
+* `file`, name of a file (with path if not in the current folder) containing the data. Allowed extensions are `.m`, `.mat` and `.xsl`. 
+* `series`, name of a `dseries` (which must be in the workspace) containing the data.
+* `first_obs`, index (if `file` option is used) or period (if `series` option is used) for the first period of the sample.
+* `last_obs`, index (if `file` option is used) or period (if `series` option is used) for the last period of the sample.
+* `nobs`, number of observations.
+* `xls_sheet`, only if an Excel file is passed to option `file`.
+* `xls_range`, only if an Excel file is passed to option `file`.
+
+Option `file` or `series` is mandatory. Options `file` and `series` cannot be used simultaneously. All the options in the `data` command are saved as fields in `options_.dataset`.
+
+# `estim_params` command
+
+Rely on option names rather than argument positions. This new interface will replace `estimated_params_bounds` and `estimated_params_init`. The following option names are available:
+
+* For the declaration of the priors
+
+|Name | Description|
+| ---          | ---         |
+| shape       | name of the prior distribution |
+| mean         | mean of the prior distribution |
+| median      | median of the prior distribution |
+| truncate    | bounds of the prior distribution |
+| stdev        | standard deviation of the prior distribution |
+| variance    | variance of the prior distribution |
+| mode         | mode of the prior distribution |
+| interval    | specification of the prior distribution from the cumulative distribution function defining an interval covering an arbitrary percentage of the prior mass |
+| shift       | to shift the domain of a distribution (useless if the domain of the distribution is the set of real numbers) |
+| domain      | specify the domain of distributions with bounded support |
+
+* For the declaration of the priors for a MS-DSGE model, in addition to the starred entries above
+
+|Name | Description|
+| ---          | ---         |
+| regimes     | provide a vector of regimes (ordered by chain order) for which the prior is being specified |
+
+* For optimization options (starred entry to be used for MS-DSGE)
+
+|Name | Description|
+| ---          | ---         |
+| bounds      |  enforce the optimizer to look for a mode in a specified interval |
+| init         | initial value for the optimizer | 
+    
+* For the mcmc options
+
+|Name | Description|
+| ---          | ---         |
+| jscale       | scale paramemeter for the jumping distribution specific to a parameter | 
+
+## Syntax examples
+
+The following instructions given as examples are to be used within the `estimated_params` block.
+
+* Declaration of a prior for estimated parameter alpha, specified using mean and variance: 
+     ```
+     alpha.prior(shape=beta,mean=0.3,variance=0.1^2);
+     beta.prior = alpha.prior;
+     ```
+
+ * Declaration of a prior for estimated parameter alpha, specified using the cumulative distribution function: 
+     ```
+     alpha.prior(shape=beta,interval=[0.2,0.4,.9]);
+     ```
+   with this syntax the prior is such that 90% of the prior mass lies between 0.2 and 0.4.
+
+* Shift the domain of a prior distribution: 
+     ```
+     beta.prior(shape=gamma,mode=4,variance=10,shift=+2);
+     sigma.prior(shape=gamma,mode=-1,variance=5,shift=-2);
+     ```
+   In the first case the default domain of the gamma distribution (the set of real positive numbers) is shifted towards infinity in the second case the same distribution is shifted towards minus infinity.
+
+* Specify the (non default) domain of a prior distribution with bounded support: 
+     ```
+     plouf.prior(shape=uniform,domain=[.5,2]);
+     fuolp.prior(shape=beta,mode=1.5,stdev=.05,domain=[1,2]);
+     ```
+  The default domain for the beta and uniform distribution is [0,1].
+
+* Set specific optimization and mcmc options 
+     ```
+     alpha.options(bounds=[0 2],init=1,jscale=.1);
+     beta.options(bounds=[0 1],init=.5,jscale=.3);
+     sigma.options(init=.7,jscale=.1);
+     ```
+ 
+* Declaration of the subsamples (must preceed the declaration of the priors): 
+     ```
+     alpha.subsamples(name1=1950Q3:1957Q4, name2=1958Q1:1983Q2, name3=1983Q3:2011Q2);
+     std(e).subsamples(name1=1950Q3:1957Q4, name2=1958Q1:1983Q2, name3=1983Q3:2011Q2);
+     corr(e,u).subsamples(name1=1950Q3:1957Q4, name2=1958Q1:1983Q2, name3=1983Q3:2011Q2);
+     beta.subsamples = alpha.subsamples;
+     std(u).subsamples = beta.subsamples;
+     ```
+  
+* Declaration of alpha's prior over different subsamples (must follow the declaration of the subsamples): 
+     ```
+     alpha.name1.prior(shape=normal,mode=0.30,stdev=.01);
+     alpha.name2.prior(shape=normal,mode=0.33,stdev=.01);
+     alpha.name3.prior(shape=normal,mode=0.40,stdev=.01);
+     beta.name1.prior(shape=normal,mode=0.30,stdev=.01);
+     beta.name2.prior(shape=normal,mode=0.33,stdev=.01);     
+     beta.name3.prior(shape=normal,mode=0.40,stdev=.01);
+     ```
+* Declaration of alpha's prior over certain regimes would be specified as: 
+    ```
+     alpha.prior(shape=normal, mode=0.30, stdev=.01, regimes=[1,1,ALL]);
+     alpha.prior(shape=normal, mode=0.33, stdev=.01, regimes=[1,2,ALL]);
+     alpha.prior(shape=normal, mode=0.33, stdev=.01, regimes=[1,3,ALL]);
+    ```
+  where the ordering of the entries in the argument to regimes is the same as the markov chain ordering (forced to be consecutive, positive integers indexed at 1). 
+
+* Declaration of a prior for the estimated standard deviation of a structural shock `e`, specified using mean and variance: 
+     ``` 
+     std(e).prior(shape=beta,mean=0.3,variance=0.1^2);
+     ```
+  `e` must be declared as an exogenous variable (with `varexo`).
+
+* Declaration of a prior for the estimated correlation between two structural shocks `e` and `u`, specified using mean and variance: 
+     ```
+     corr(e,u).prior(shape=beta,mean=0.3,variance=0.1^2);
+     ```
+  `e` and `u` must be declared as an exogenous variable (with `varexo`).
+
+* Declaration of a prior for the estimated standard deviation of a measurement error on a variable `y`, specified using mean and variance: 
+     ```
+     std(y).prior(shape=beta,mean=0.3,variance=0.1^2);
+     ``` 
+  `y` is an endogenous variable and must be declared as an observed variable (with `varobs`).
+
+* Declaration of a prior for the estimated correlation between two measurement errors on y and c, specified using mean and variance: 
+     ``` 
+     corr(y,c).prior(shape=beta,mean=0.3,variance=0.1^2);
+     ```
+  `y` and `c` are endogenous variables and must be declared as observed variables (with `varobs`).
+
+
+## Preprocessor generated Matlab code
+
+The preprocessor fills a new matlab structure called `estimation_info`. This structure is organized as follows:
+
+* The first field is a structure specifying the parameters to be estimated.
+  ```
+  estimation_info.parameters.deep.nb = 3;
+  estimation_info.parameters.list = char('alpha','beta','sigma')
+  estimation_info.parameters.structural_innovation.nb = 2;
+  estimation_info.parameters.structural_innovation.list = ĉhar('e','u');
+  estimation_info.parameters.structural_innovation_corr.nb = 1;
+  estimation_info.parameters.structural_innovation_corr.list = char('e___u');
+  estimation_info.parameters.measurement_error.nb = 2;
+  estimation_info.parameters.measurement_error.list = ĉhar('y','c');
+  estimation_info.parameters.measurement_error_corr.nb = 1;
+  estimation_info.parameters.measurement_error_corr.list = char('y___c');
+  ``` 
+  If the some parameters are not stable across the whole sample, these parameters are specific to each subsample. For instance if we estimate the model with one structual break on parameter alpha, we would have instead:
+  ```
+  estimation_info.parameters.deep.nb = 5;
+  estimation_info.parameters.list = char('alpha$1','alpha$2','alpha$3','beta','sigma');
+  estimation_info.parameters.structural_innovation.nb = 2;
+  estimation_info.parameters.structural_innovation.list = ĉhar('e','u');
+  estimation_info.parameters.structural_innovation_corr.nb = 1;
+  estimation_info.parameters.structural_innovation_corr.list = char('e___u');
+  estimation_info.parameters.measurement_error.nb = 2;
+  estimation_info.parameters.measurement_error.list = ĉhar('y','c');
+  estimation_info.parameters.measurement_error_corr.nb = 1;
+  estimation_info.parameters.measurement_error_corr.list = char('y___c');
+  ```
+  where `alpha$1`, `alpha$2` and `alpha$3` correspond to `alpha` for the first, second and third subsamples.
+
+* The second field is a structure specifying the initial conditions for the optimization routine. 
+  ```
+  estimation_info.init.deep = [1.0; .5; .7 ];
+  estimation_info.init.structural_innovation = [.01; .05];
+  estimation_info.init.structural_innovation_corr = [.1];
+  estimation_info.init.measurement_error = [.01; .07];
+  estimation_info.init.measurement_error_corr = [-.1];
+  ```
+  or with the structural break on alpha:
+  ```
+  estimation_info.init.deep = [1.0; 1.1; .9; .5; .7 ];
+  estimation_info.init.structural_innovation = [.01; .05];
+  estimation_info.init.structural_innovation_corr = [.1];
+  estimation_info.init.measurement_error = [.01; .07];
+  estimation_info.init.measurement_error_corr = [-.1];
+  ```
+  If there is no estimated measurement errors in the model (ie `estimation_info.parameters.measurement_error.nb=0`) the `estimation_info.init.measurement_error` and `estimation_info.init.measurement_error_corr` are set to a empty matrices.
+
+* The third field is a structure specifying the bounds for the optimization routine. 
+  ```
+  estimation_info.bounds.deep = [0, 2; 0, 1; -Inf, Inf];
+  estimation_info.bounds.structural_innovation = [0, .01; 0, Inf];
+  estimation_info.bounds.structural_innovation_corr = [-1 1];
+  estimation_info.bounds.measurement_error = [0 Inf; 0 Inf];
+  estimation_info.bounds.measurement_error_corr = [-1 1];
+  ```
+  Default bounds for estimated standard deviations or variance are 0 and Inf. Default bounds for estimated correlations are -1 and 1. Default bounds for estimated deep parameters are -Inf and Inf (meaning no effective bounds for the optimization).
+
+* The fourth field is a structure describing the subsamples (if any). By default each estimated parameter is kept constant along the whole sample. For instance, if there is one unexpected break on the estimated parameter alpha, we would have: 
+  ```
+  estimation_info.subsample.deep.alpha = [ '1950:Q3', '1957:Q4'; '1958Q1', '1983:Q2'; '1983Q3', '2011Q2'];
+  ``` 
+  If there is no unexpected break on the estimated deep parameters then `estimation_info.subsample.deep` is an empty matrix.
+
+An optional field is added if the model is estimated with a Bayesian approach. This field specifies the prior beliefs. For X = 'deep', 'structural_innovation', 'measurement_error', 'structural_innovation_corr' and 'measurement_error_corr' we have the following fields (n\*1 vectors or cell arrays of doubles or n\*2 matrices or cell arrays of doubles): 
+   ```
+   estimation_info.prior.shape.X
+   estimation_info.prior.mean.X
+   estimation_info.prior.stdev.X
+   estimation_info.prior.variance.X
+   estimation_info.prior.mode.X
+   estimation_info.prior.interval.X
+   estimation_info.prior.shift.X
+   estimation_info.prior.domain.X
+   estimation_info.prior.jscale.X
+   ```
\ No newline at end of file