<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html>
  <head>
  <meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<title>Extract estimated quantities from fit objects. — extract_quantity.stanfit • BayesHMM</title>

<!-- jquery -->
<script src="https://code.jquery.com/jquery-3.1.0.min.js" integrity="sha384-nrOSfDHtoPMzJHjVTdCopGqIqeYETSXhZDFyniQ8ZHcVy08QesyHcnOUpMpqnmWq" crossorigin="anonymous"></script>
<!-- Bootstrap -->

<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>

<!-- Font Awesome icons -->
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous">

<!-- clipboard.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js" integrity="sha384-cV+rhyOuRHc9Ub/91rihWcGmMmCXDeksTtCihMupQHSsi8GIIRDG0ThDc3HGQFJ3" crossorigin="anonymous"></script>

<!-- sticky kit -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/sticky-kit/1.1.3/sticky-kit.min.js" integrity="sha256-c4Rlo1ZozqTPE2RLuvbusY3+SU1pQaJC0TjuhygMipw=" crossorigin="anonymous"></script>

<!-- pkgdown -->
<link href="../pkgdown.css" rel="stylesheet">
<script src="../pkgdown.js"></script>



<meta property="og:title" content="Extract estimated quantities from fit objects. — extract_quantity.stanfit" />

<meta property="og:description" content="This function extracts estimated quantities from fit objects. It works transparently with both Markov-chain Monte Carlo samples returned by draw_samples and maximum a posteriori estimates returned by optimizing. Most of the user-friendly extractors (e.g. extract_alpha) are built upon this function. As such, it was not designed to be used directly by users, except perhaps for the most advanced ones." />
<meta name="twitter:card" content="summary" />



<!-- mathjax -->
<script src='https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></script>

<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->


  </head>

  <body>
    <div class="container template-reference-topic">
      <header>
      <div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar">
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="../index.html">BayesHMM</a>
        <span class="label label-default" data-toggle="tooltip" data-placement="bottom" title="Released package">0.0.1</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav">
        <li>
  <a href="../index.html">
    <span class="fa fa-home fa-lg"></span>
     
  </a>
</li>
<li>
  <a href="../reference/index.html">Reference</a>
</li>
<li class="dropdown">
  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
    Articles
     
    <span class="caret"></span>
  </a>
  <ul class="dropdown-menu" role="menu">
    <li>
      <a href="../articles/introduction.html">An Introduction to BayesHMM</a>
    </li>
    <li>
      <a href="../articles/introduction2.html">An Introduction to BayesHMM</a>
    </li>
  </ul>
</li>
      </ul>
      
      <ul class="nav navbar-nav navbar-right">
        <li>
  <a href="https://github.com/luisdamiano/BayesHMM/">
    <span class="fa fa-github fa-lg"></span>
     
  </a>
</li>
      </ul>
      
    </div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      
      </header>

<div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Extract estimated quantities from fit objects.</h1>
    <small class="dont-index">Source: <a href='https://github.com/luisdamiano/BayesHMM//blob/master/R/fit.R'><code>R/fit.R</code></a></small>
    <div class="hidden name"><code>extract_quantity.stanfit.Rd</code></div>
    </div>

    <div class="ref-description">
    
    <p>This function extracts estimated quantities from fit objects. It works transparently with both Markov-chain Monte Carlo samples returned by <code><a href='draw_samples.html'>draw_samples</a></code> and maximum a posteriori estimates returned by <code><a href='optimizing.html'>optimizing</a></code>. Most of the user-friendly extractors (e.g. <code><a href='extract_alpha.html'>extract_alpha</a></code>) are built upon this function. As such, it was not designed to be used directly by users, except perhaps for the most advanced ones.</p>
    
    </div>

    <pre class="usage"><span class='co'># S3 method for stanfit</span>
<span class='fu'><a href='extract_quantity.html'>extract_quantity</a></span>(<span class='no'>fit</span>, <span class='no'>pars</span>, <span class='kw'>reduce</span> <span class='kw'>=</span> <span class='kw'>NULL</span>,
  <span class='kw'>combine</span> <span class='kw'>=</span> <span class='kw'>NULL</span>, <span class='kw'>chain</span> <span class='kw'>=</span> <span class='st'>"all"</span>, <span class='no'>...</span>)</pre>
    
    <h2 class="hasAnchor" id="arguments"><a class="anchor" href="#arguments"></a>Arguments</h2>
    <table class="ref-arguments">
    <colgroup><col class="name" /><col class="desc" /></colgroup>
    <tr>
      <th>fit</th>
      <td><p>An object returned by <code><a href='fit.html'>fit</a></code>, <code><a href='draw_samples.html'>draw_samples</a></code>, or <code><a href='optimizing.html'>optimizing</a></code>.</p></td>
    </tr>
    <tr>
      <th>pars</th>
      <td><p>A vector of characters with the name of the quantities to be extracted. The characters strings may include regular expressions. Further, wildcards are automatically translated into regex: <em>?</em> matches a single character, while <em>*</em> matches any character string including an empty one. For example, <em>?pred</em> will match both ypred and zpred, and <em>z*</em> will match zstar and zpred.</p></td>
    </tr>
    <tr>
      <th>reduce</th>
      <td><p>A function applied to the samples generated by one chain for each parameters (i.e. "within chain"). Useful if only one or more summary measures of the generated samples is needed (e.g. the median of the generated sample). The function may return one of more elements. In the former case, the dimension is dropped in the returned object (read the <em>Value</em> section below). Note that the user needs to supply a function as an argument, and not a character string with the name of the function. This argument is not used for maximum a posteriori estimates returned by <code><a href='optimizing.html'>optimizing</a></code> since there is only one scalar per quantity.</p></td>
    </tr>
    <tr>
      <th>combine</th>
      <td><p>A function applied to all the extracted quantities as an ensemble. In other words, instead of returning a named list where each element is one quantity, it returns the value returned by the function applied to the whole list (<code>do.call</code>). Useful when all the elements of the list have the same dimension, possibly because it is used in conjunction with the <em>chain</em> and <em>reduce</em> arguments.</p></td>
    </tr>
    <tr>
      <th>chain</th>
      <td><p>Either "all" or any integer number between 1 and the number of chains M. In the latter case, the chain dimension in the returned object is dropped.</p></td>
    </tr>
    <tr>
      <th>...</th>
      <td><p>Arguments to be passed to rstan's <code><a href='http://www.rdocumentation.org/packages/rstan/topics/stanfit-method-extract'>extract</a></code> if the object <em>fit</em> was returned by <code><a href='fit.html'>fit</a></code> or <code><a href='draw_samples.html'>draw_samples</a></code>.</p></td>
    </tr>
    </table>
    
    <h2 class="hasAnchor" id="value"><a class="anchor" href="#value"></a>Value</h2>

    <p>A list of named elements with type and dimension depending on the characteristics of the quantity. If the argument <em>combine</em> is set, the returned value equals to the return value of the function given (e.g. a matrix if <code>cbind</code>) is used).</p>
    
    <h2 class="hasAnchor" id="details"><a class="anchor" href="#details"></a>Details</h2>

    <p>Note that <em>rstan</em> does not provide a unified way to extract quantities from full bayesian and optimization fits, and the structure of the returned objects are not homogeneous. <em>extract_quantity</em> solves these two inconvenients. Additionally, it allows for regex expressions in the name of the quantities to be extracted.</p>
    

    <h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
    <pre class="examples"># NOT RUN {
  extract_quantity(myFit, c("z*"), reduce = mean, chain = 1, combine = cbind))
# }
</pre>
  </div>
  <div class="col-md-3 hidden-xs hidden-sm" id="sidebar">
    <h2>Contents</h2>
    <ul class="nav nav-pills nav-stacked">
      <li><a href="#arguments">Arguments</a></li>
      
      <li><a href="#value">Value</a></li>

      <li><a href="#details">Details</a></li>
      
      <li><a href="#examples">Examples</a></li>
    </ul>

  </div>
</div>

      <footer>
      <div class="copyright">
  <p>Developed by Luis Damiano, Michael Weylandt, Brian Peterson.</p>
</div>

<div class="pkgdown">
  <p>Site built with <a href="http://pkgdown.r-lib.org/">pkgdown</a>.</p>
</div>

      </footer>
   </div>

  

  </body>
</html>

