.. default-domain:: dynare

.. |br| raw:: html

    <br>

####################
Dynare misc commands
####################

.. matcomm:: send_endogenous_variables_to_workspace ;

    Puts the simulation results for the endogenous variables stored in ``oo_.endo_simul`` 
    into vectors with the same name as the respective variables into the base workspace.

.. matcomm:: send_exogenous_variables_to_workspace ;

    Puts the simulation results for the exogenous variables stored in ``oo_.exo_simul`` 
    into vectors with the same name as the respective variables into the base workspace.

.. matcomm:: send_irfs_to_workspace ;

    Puts the IRFs stored in ``oo_.irfs`` into vectors with the same name into the base workspace.

.. command:: prior_function(OPTIONS);

    Executes a user-defined function on parameter draws from the prior
    distribution. Dynare returns the results of the computations for
    all draws in an `ndraws` by :math:`n` cell array named
    ``oo_.prior_function_results``.

    *Options*

    .. option:: function = FUNCTION_NAME

        The function must have the following header ``output_cell =
        FILENAME(xparam1,M_,options_,oo_,estim_params_,bayestopt_,dataset_,dataset_info)``,
        providing read-only access to all Dynare structures. The only
        output argument allowed is a :math:`1 \times n` cell array,
        which allows for storing any type of output/computations. This
        option is required.

    .. option:: sampling_draws = INTEGER

        Number of draws used for sampling. Default: 500.

    |br|

.. command:: posterior_function(OPTIONS);

    Same as the :comm:`prior_function` command but for the
    posterior distribution. Results returned in
    ``oo_.posterior_function_results``.

    *Options*

    .. option:: function = FUNCTION_NAME

        See :opt:`prior_function_function <function = FUNCTION_NAME>`.

    .. option:: sampling_draws = INTEGER

        See :opt:`prior_function_sampling_draws <sampling_draws = INTEGER>`.

    |br|

.. command:: generate_trace_plots(CHAIN_NUMBER);

    Generates trace plots of the MCMC draws for all estimated
    parameters and the posterior density for the specified Markov Chain(s)
    ``CHAIN_NUMBER``. If ``CHAIN_NUMBER`` is a vector of integers, the trace plots
    will plot contains separate lines for each chain.

    |br|

.. matcomm:: internals FLAG ROUTINENAME[.m]|MODFILENAME

   Depending on the value of ``FLAG``, the ``internals`` command
   can be used to run unitary tests specific to a MATLAB/Octave
   routine (if available), to display documentation about a
   MATLAB/Octave routine, or to extract some informations about the
   state of Dynare.

   *Flags*

   ``--test``

        Performs the unitary test associated to ROUTINENAME (if this
        routine exists and if the matlab/octave ``.m`` file has
        unitary test sections).

        *Example*

            ::

                >> internals --test ROUTINENAME

            if ``routine.m`` is not in the current directory, the full
            path has to be given::

            >> internals --test ../matlab/fr/ROUTINENAME

   ``--display-mh-history``

        Displays information about the previously saved MCMC draws
        generated by a ``.mod`` file named MODFILENAME. This file must
        be in the current directory.

        *Example*

            ::

                >> internals --display-mh-history MODFILENAME

   ``--load-mh-history``

        Loads into the MATLAB/Octave’s workspace informations
        about the previously saved MCMC draws generated by a ``.mod``
        file named MODFILENAME.

        *Example*

            ::

                >> internals --load-mh-history MODFILENAME

        This will create a structure called ``mcmc_informations``
        (in the workspace) with the following fields:

        ``Nblck``

            The number of MCMC chains.

        ``InitialParameters``

            A ``Nblck*n``, where ``n`` is the number of estimated
            parameters, array of doubles. Initial state of
            the MCMC.

        ``LastParameters``

            A ``Nblck*n``, where ``n`` is the number of estimated
            parameters, array of doubles. Current state of
            the MCMC.

        ``InitialLogPost``

            A ``Nblck*1`` array of doubles. Initial value of the
            posterior kernel.

        ``LastLogPost``

            A ``Nblck*1`` array of doubles. Current value of the
            posterior kernel.

        ``InitialSeeds``

            A ``1*Nblck`` structure array. Initial state of the random
            number generator.

        ``LastSeeds``

            A ``1*Nblck`` structure array. Current state of the random
            number generator.

        ``AcceptanceRatio``

            A ``1*Nblck`` array of doubles. Current acceptance ratios.

   |br|

.. matcomm:: prior [OPTIONS[ ...]];

   Prints information about the prior distribution given the provided
   options. If no options are provided, the command returns the list of
   available options.

   *Options*

   .. option:: table

      Prints a table describing the marginal prior distributions
      (mean, mode, std., lower and upper bounds, HPD interval).

   .. option:: moments

      Computes and displays first and second order moments of the
      endogenous variables at the prior mode (considering the
      linearized version of the model).

   .. option:: moments(distribution)

      Computes and displays the prior mean and prior standard
      deviation of the first and second moments of the endogenous
      variables (considering the linearized version of the model) by
      randomly sampling from the prior.  The results will also be
      stored in the ``prior`` subfolder in a
      ``_endogenous_variables_prior_draws.mat`` file.

   .. option:: optimize

      Optimizes the prior density (starting from a random initial
      guess). The parameters such that the steady state does not
      exist or does not satisfy the Blanchard and Kahn conditions
      are penalized, as they would be when maximizing the posterior
      density. If a significant proportion of the prior mass is
      defined over such regions, the optimization algorithm may fail
      to converge to the true solution (the prior mode).

   .. option:: simulate

      Computes the effective prior mass using a Monte-Carlo. Ideally
      the effective prior mass should be equal to 1, otherwise
      problems may arise when maximising the posterior density and
      model comparison based on marginal densities may be
      unfair. When comparing models, say :math:`A` and :math:`B`,
      the marginal densities, :math:`m_A` and :math:`m_B`, should be
      corrected for the estimated effective prior mass
      :math:`p_A\neq p_B \leq 1` so that the prior mass of the
      compared models are identical.

   .. option:: plot

      Plots the marginal prior density.

   |br|

.. matcomm:: search VARIABLENAME[ OPTION]

   Searches all occurrences of a variable in a model, and prints the
   equations where the variable appear in the command line window. If OPTION is
   set to `withparamvalues`, the values of the parameters (if available) are
   displayed instead of the name of the parameters. Requires the `json` command
   line option to be set.

   *Example*

      Assuming that we already ran a `.mod` file and that the workspace has not
      been cleaned after, we can search for all the equations containing variable `X`

      ::

         >> search X

         Y = alpha*X/(1-X)+e;

         diff(X) = beta*(X(-1)-mX) + gamma1*Z + gamma2*R + u;

      To replace the parameters with estimated or calibrated parameters:

      ::

         >> search X withparamvalues

         Y = 1.254634*X/(1-X)+e;

         diff(X) = -0.031459*(X(-1)-mX) + 0.1*Z - 0.2*R + u;

   |br|


.. matcomm:: dplot [OPTION VALUE[ ...]]

   Plot expressions extracting data from different dseries objects.

   *Options*

   .. option:: --expression EXPRESSION

      ``EXPRESSION`` is a mathematical expression involving variables
      available in the dseries objects, dseries methods, numbers or
      parameters. All the referenced objects are supposed to be
      available in the calling workspace.

   .. option:: --dseries NAME

      ``NAME`` is the name of a dseries object from which the
      variables involved in ``EXPRESSION`` will be extracted.

   .. option:: --range DATE1:DATE2

      This option is not mandatory and allows to plot the expressions
      only over a sub-range. ``DATE1`` and ``DATE2`` must be dates as
      defined in :ref:`dates in a mod file`.

   .. option:: --style MATLAB_SCRIPT_NAME

      Name of a Matlab script (without extension) containing Matlab
      commands to customize the produced figure.

   .. option:: --title MATLAB_STRING

      Adds a title to the figure.

   .. option:: --with-legend

      Prints a legend below the produced plot.

   *Remarks*

    - More than one --expression argument is allowed, and they must come first.

    - For each dseries object we plot all the expressions. We use two
      nested loops, the outer loop is over the dseries objects and the
      inner loop over the expressions. This determines the ordering of
      the plotted lines.

    - All dseries objects must be defined in the calling workspace, if a
      dseries object is missing the routine throws a warning (we only
      build the plots for the available dseries objects), if all dseries
      objects are missing the routine throws an error.

    - If the range is not provided, the expressions cannot involve leads or lags.

   *Example*

      ::

         >> toto = dseries(randn(100,3), dates('2000Q1'), {'x','y','z'});
         >> noddy = dseries(randn(100,3), dates('2000Q1'), {'x','y','z'});
         >> b = 3;
         >> dplot --expression 2/b*cumsum(x/y(-1)-1) --dseries toto --dseries noddy --range 2001Q1:2024Q1 --title 'This is my plot'

      will produce plots for ``2/b*cumsum(x/y(-1)-1)``, where ``x`` and
      ``y`` are variables in dseries objects ``toto`` and ``noddy``, in
      the same figure.