dynare-misc-commands.rst

.. default-domain:: dynare

.. |br| raw:: html

    <br>

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

.. command:: prior_function(OPTIONS);

    |br| 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 $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.

.. command:: posterior_function(OPTIONS);

    |br| 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>`.

.. command:: generate_trace_plots(CHAIN_NUMBER);

    |br| Generates trace plots of the MCMC draws for all estimated
    parameters and the posterior density in the specified Markov Chain
    ``CHAIN_NUMBER``.

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

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

    ``--info``

        Prints on screen the internal documentation of ROUTINENAME (if
        this routine exists and if this routine has a texinfo internal
        documentation header). The path to ``ROUTINENAME`` has to be
        provided, if the routine is not in the current directory.

        *Example*

            ::

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

            At this time, will work properly for only a small number
            of routines. At the top of the (available) MATLAB/Octave
            routines a commented block for the internal documentation
            is written in the GNU texinfo documentation format. This
            block is processed by calling texinfo from
            MATLAB. Consequently, texinfo has to be installed on your
            machine.

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

        |br| 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.

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