.. index:: mcmc .. _mcmc: .. _mcmcHelper: The properties =============== .. index:: mcmc.pnames .. _mcmc.pnames: pnames ------- mcmc/pnames is a property. .. index:: mcmc.nchains .. _mcmc.nchains: nchains -------- mcmc/nchains is a property. .. index:: mcmc.chain_names .. _mcmc.chain_names: chain_names ------------ mcmc/chain_names is a property. .. index:: mcmc.npop .. _mcmc.npop: npop ----- mcmc/npop is a property. .. index:: mcmc.nparams .. _mcmc.nparams: nparams -------- mcmc/nparams is a property. .. index:: mcmc.draws .. _mcmc.draws: draws ------ mcmc/draws is a property. .. index:: mcmc.psrf .. _mcmc.psrf: psrf ----- mcmc/psrf is a property. .. index:: mcmc.best .. _mcmc.best: best ----- mcmc/best is a property. .. index:: mcmc.log_post .. _mcmc.log_post: log_post --------- mcmc/log_post is a property. The methods ============ .. index:: mcmc.autocorrplot .. _mcmc.autocorrplot: autocorrplot ------------- Plots autocorrelations of a given parameter :: hdl=autocorrplot(obj,pname) hdl=autocorrplot(obj,pname,chain_id) hdl=autocorrplot(obj,pname,chain_id,order) Args: obj (mcmc object): mcmc object pname (string): parameter name chain_id (integer \| {[]}): choice of chain for which to plot the autocorrelation. If empty, all chains are used. order (integer \| {40}): maximum order of the autocorrelation Returns: : - **hdl** [integer]: handle to the plot .. index:: mcmc.brooks_gelman .. _mcmc.brooks_gelman: brooks_gelman -------------- brooks_gelman computes the :cite:`BrooksGelman1998` convergence diagnostics, both the parameteric and the non-parameteric versions INPUTS: - this : mcmc object - do_plot : [true\|{false}\|empty] OUTPUTS: - myoutput [struct] : Contains - UDIAG [by 6] double - 1st column: length of total sequence interval - 2nd column: sum of length of within sequence intervals; used to compute mean length of within sequence intervals - 3nd column: within sequence variance - 4nd column: sum of within sequence variances; used to compute mean within sequence variances - 5nd column: within sequence kurtosis - 6nd column: sum of within sequence kurtoses; used to compute mean within sequence kurtoses - MDIAG [by 6] double - 1st column: length of total sequence interval - 2nd column: sum of length of within sequence intervals; used to compute mean length of within sequence intervals - 3nd column: within sequence variance - 4nd column: sum of within sequence variances; used to compute mean within sequence variances - 5nd column: within sequence kurtosis - 6nd column: sum of within sequence kurtoses; used to compute mean within sequence kurtoses - h [numeric\|empty] : handle to the figures for the multivariate and univariate plots .. index:: mcmc.densplot .. _mcmc.densplot: densplot --------- Plots marginal density of a given parameter :: hdl=densplot(obj,pname) hdl=densplot(obj,pname,chain_id) hdl=densplot(obj,pname,chain_id,N) Args: obj (mcmc object): mcmc object pname (string): parameter name chain_id (integer \| {[]}): choice of chain for which to plot the density. If empty, all chains are used. N (integer \| {250}): Number of point in the kernel density Returns: : - **hdl** [integer]: handle to the plot .. index:: mcmc.draws2struct .. _mcmc.draws2struct: draws2struct ------------- DRAWS2STRUCT Converts MCMC draws to a struct array of individual draws INPUT: k : mcmc object with fields including - k.draws [nparams x ndraws] - k.log_post [1 x ndraws] or [ndraws x 1] OUTPUT: out : 1 x ndraws struct array with fields: - x : [nparams x 1] vector of parameters - f : scalar log posterior value .. index:: mcmc.geweke .. _mcmc.geweke: geweke ------- geweke computes Geweke convergence diagnostics :: convergence=geweke(this) convergence=geweke(this,Opts) convergence=geweke(this,Opts,chain_id) Args: this (mcmc object): mcmc object pname (string): parameter name chain_id (integer \| {1}): choice of chain for which to do the convergence analysis Returns: : - **convergence** [struct]: convergence analysis for each parameter .. index:: mcmc.inefficiency_factors .. _mcmc.inefficiency_factors: inefficiency_factors --------------------- Computes inefficiency_factors of a given parameter :: Ifac=inefficiency_factors(obj) Ifac=inefficiency_factors(obj,pname) Ifac=inefficiency_factors(obj,pname,order) Args: obj (mcmc object): mcmc object pname (string\|cell array): parameter name Returns: : - **Ifac** [scalar\|vector,struct]: inefficiency factors .. index:: mcmc.mcmc .. _mcmc.mcmc: mcmc ----- Constructor for mcmc object :: mcmc_helper = mcmc(draws) mcmc_helper = mcmc(draws, pnames) mcmc_helper = mcmc(draws, pnames, subset) mcmc_helper = mcmc(draws, pnames, subset, ilinres) Args: - **draws** (struct): output from samplers in 3 possible forms - The draws are stored to disk in which case "draws" is a string representing the location of the draws - a structure, output of the samplers when draws are not stored to disk. In this case there is only one chain - a cell array of structures, with each structure as above. Each entry then represents one chain - a two-element cell array {draws,-logposterior} such that the first entry is a np x ndraws x nchain array of parameter values and the second entry is a 1 x ndraws x nchain array of -logPosterior values - **pnames** (cellstr): cell of parameter names - **subset** (cell array\|{empty}): When not empty, subset is a 1 x 2 cell array in which the first cell contains a vector selecting the columns to retain in each chain and the second column contains the chains retained. Any or both of those cell arrays can be empty. Whenever an entry is empty, all the information available is selected. E.g. subsetting with dropping and trimming mysubs={a:b:c,[1,3,5]}. In this example, the first element selected is the one in position "a" and thereafter every "b" element is selected until we reach element in position "c". At the same time, we select markov chains 1,3 and 5. - **ilinres** (function handle\|{empty}): function handle that untransforms the parameters in the presence of linear restrictions. Returns: - **mcmc_helper** : mcmc object Note: - It is the responsibility of the user to provide the names of the parameters as this routine aims to be independent from any estimation procedure or class. If the priors are set in separate structure, their names can easily be obtained via :: pnames = fieldnames(priors); - Alternatively, if using a RISE object, parameter names can be obtained via:: pnames = fieldnames(model.estimation.priors); .. index:: mcmc.meanplot .. _mcmc.meanplot: meanplot --------- Make a plot of cumulative means from the mcmc chain :: hdl = meanplot(mcobj,pname); hdl = meanplot(mcobj,pname,chain_id); Args: mcobj (mcmc object): mcmc object pname (str): parameter to make the mean plot chain_id (vector of int): id of the chain to use Returns: : - **hdl** (handle object): handle to plot object .. index:: mcmc.plot_brooks_gelman .. _mcmc.plot_brooks_gelman: plot_brooks_gelman ------------------- Make a plot of cumulative means from the mcmc chain :: h=plot_brooks_gelman(this,myoutput) h=plot_brooks_gelman(this,myoutput,nparamsPerFigure) Args: this (mcmc object): mcmc object myoutput (struct): output of brooks_gelman nparamsPerFigure [numeric\|{3}]: number of univariate parameters per figure Returns: : - **h** (handle object): handle to all the plots (unvariates and multivariate) .. index:: mcmc.posterior_parameter_statistics .. _mcmc.posterior_parameter_statistics: posterior_parameter_statistics ------------------------------- posterior_parameter_statistics computes posterior parameter statistics :: s = posterior_parameter_statistics(this) s = posterior_parameter_statistics(this,Opts) Args: - this [mcmc object]: mcmc object - Opts [empty\|struct]: options with the following fields - **percnt** [vector\|{[2.5,25,50,75,97.5]}] : vector used in the computation of percentiles -** mh_conf_sig** [scalar\|{0.9}] : used in the computation of Highest Probability Density Intervals. - **npoints** [integer\|{512}] : number of points used in the computation of the density for each parameter - **kernel** [char\|{'normal'}] : kernel used in the computation of the density. Choices are 'epanechnikov'\|'triangular'\|'triweight',... 'uniform'\|'cosine' - **do** [struct] : structure whose fields are the same as the ones for the output. Each item should be true or false, with true triggering the computation of the relevant item. Returns: **s** (struct): output with fields - posterior_mean [struct] : posterior mean - posterior_var [struct] : posterior variance - posterior_std [struct] : posterior standard deviation - posterior_percentiles [struct] : posterior posterior_percentiles as defined by the user - posterior_deciles [struct] : posterior deciles 0.1:0.1:0.9 - posterior_hpd_interval [struct] : Highest probability density intervals - posterior_density [struct] : kernel density estimate .. index:: mcmc.process_draws .. _mcmc.process_draws: process_draws -------------- mcmc.process_draws is a function. [d, fd, summary] = mcmc.process_draws(draws, subset) .. index:: mcmc.psrf_plot .. _mcmc.psrf_plot: psrf_plot ---------- Makes a plot of the "posterior scale reduction factor" i.e. the :cite:`GelmanRubin1992` diagnotics from the chains. :: hdl = psrf_plot(obj, pname) Args: obj (mcmc object): mcmc object pname (char): parameter name. N.B: One of the parameter's name is "multivariate\_" and it represents the aggregated statistics. start (numeric\|{1}\|function handle): iteration at which to start the plot of the PSRF. If a function handle is used then it should take as input the total number of observations and return the point at which to start. e.g. @(x)round(0.5\*x) Returns: - **hdl** (handle object): handle to plot object Warning: - This function requires multiple chains of MCMC samples. See **nchain** option of samplers. .. index:: mcmc.raftery_lewis .. _mcmc.raftery_lewis: raftery_lewis -------------- raftery_lewis computes :cite:`RafteryLewis1992` convergence diagnostics :: convergence=raftery_lewis(this) convergence=raftery_lewis(this,Opts) convergence=raftery_lewis(this,Opts,chain_id) Args: this (mcmc object): mcmc object pname (string): parameter name chain_id (integer \| {1}): choice of chain for which to do the convergence analysis Returns: : - **convergence** [struct]: convergence analysis for each parameter .. index:: mcmc.reload_draws .. _mcmc.reload_draws: reload_draws ------------- subset is a 1 x 2 cell array in which - the first cell contains the columns to retain: can be empty, defaults to all - the second column contains the chains to retain: can be empty, defaults to all .. index:: mcmc.scatterplot .. _mcmc.scatterplot: scatterplot ------------ Make a scatter plot from the mcmc chains :: hdl = scatterplot(mcobj,pname1,pname2); hdl = scatterplot(mcobj,pname1,pname2,chain_id); hdl = scatterplot(mcobj,pname1,pname2,chain_id,varargin); Args: mcobj (mcmc object): mcmc object pname1 (str): x-axis parameter of scatter plot pname2 (str): y-axis parameter of scatter plot chain_id (vector of int): id of the chain to use varargin (varargin): options fed into `scatter `_ function of matlab Returns: : - **hdl** (handle object): handle to plot object .. index:: mcmc.statistics .. _mcmc.statistics: statistics ----------- statistics : statistics from the mcmc chains :: s=statistics(obj); s=statistics(obj,opts); Args: - obj (mcmc object): mcmc object - opts (struct): structure with options of which statistics to compute. for more information see help utils.mcmc.statistics Returns: : - **s** (struct): structure with statistics of interest - **statTab** (table): table representation of some of the statistics .. index:: mcmc.summary .. _mcmc.summary: summary -------- Print summary information about the mcmc draws :: [myMeanStdev, MyQuantiles] = summary(mcobj); [myMeanStdev, MyQuantiles] = summary(mcobj, varargin); Args: mcobj (mcmc object): mcmc object varargin (options): options need to come in pairs: - 'percnt': Quantile points (default: [2.5, 25, 50, 75, 97.5]) - 'batch_size': sampling size of for the computation of thinned standard deviation (SD(batch)), every 'batch_size'th points are used to compute SD(batch). Returns: : - **myMeanStdev** [cell]: mean and standard deviations - **myQuantiles** [cell]: quantile values .. index:: mcmc.traceplot .. _mcmc.traceplot: traceplot ---------- Make a trace plot from the mcmc chains :: hdl = traceplot(mcobj,pname); hdl = traceplot(mcobj,pname,chain_id); hdl = traceplot(mcobj,pname,chain_id,ma_window); Args: mcobj (mcmc object): mcmc object pname (str): parameter to make the trace plot chain_id (vector of int): id of the chain to use ma_window (int): window size if using moving average smoothing. Returns: : - **hdl** (handle object): handle to plot object