<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><meta name="description" content="Creates separate histograms of a quantitative variable by levels of a factor variable."><title>Creates separate histograms by levels. — hist.formula • FSA</title><!-- favicons --><link rel="icon" type="image/png" sizes="16x16" href="../favicon-16x16.png"><link rel="icon" type="image/png" sizes="32x32" href="../favicon-32x32.png"><link rel="apple-touch-icon" type="image/png" sizes="180x180" href="../apple-touch-icon.png"><link rel="apple-touch-icon" type="image/png" sizes="120x120" href="../apple-touch-icon-120x120.png"><link rel="apple-touch-icon" type="image/png" sizes="76x76" href="../apple-touch-icon-76x76.png"><link rel="apple-touch-icon" type="image/png" sizes="60x60" href="../apple-touch-icon-60x60.png"><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.2.2/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.2.2/bootstrap.bundle.min.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- bootstrap-toc --><script src="https://cdn.jsdelivr.net/gh/afeld/bootstrap-toc@v1.0.1/dist/bootstrap-toc.min.js" integrity="sha256-4veVQbu7//Lk5TSmc7YV48MxtMy98e26cf5MrgZYnwo=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- search --><script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/6.4.6/fuse.js" integrity="sha512-zv6Ywkjyktsohkbp9bb45V6tEMoWhzFzXis+LrMehmJZZSys19Yxf1dopHx7WzIKxr5tK2dVcYmaCk2uqdjF4A==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/0.38.0/autocomplete.jquery.min.js" integrity="sha512-GU9ayf+66Xx2TmpxqJpliWbT5PiGYxpaG8rfnBEk1LL8l1KGkRShhngwdXK1UgqhAzWpZHSiYPc09/NwDQIGyg==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/mark.min.js" integrity="sha512-5CYOlHXGh6QpOFA/TeTylKLWfB3ftPsde7AnmhuitiTX4K5SqCLBeKro6sPS8ilsz1Q4NRx3v8Ko2IBiszzdww==" crossorigin="anonymous"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Creates separate histograms by levels. — hist.formula"><meta property="og:description" content="Creates separate histograms of a quantitative variable by levels of a factor variable."><meta property="og:image" content="https://fishr-core-team.github.io/FSA/logo.png"><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></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>
    <a href="#main" class="visually-hidden-focusable">Skip to contents</a>
    

    <nav class="navbar fixed-top navbar-dark navbar-expand-lg bg-primary"><div class="container">
    
    <a class="navbar-brand me-2" href="../index.html">FSA</a>

    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Released version">0.9.5</small>

    
    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>

    <div id="navbar" class="collapse navbar-collapse ms-3">
      <ul class="navbar-nav me-auto"><li class="active nav-item">
  <a class="nav-link" href="../reference/index.html">Reference</a>
</li>
      </ul><form class="form-inline my-2 my-lg-0" role="search">
        <input type="search" class="form-control me-sm-2" aria-label="Toggle navigation" name="search-input" data-search-index="../search.json" id="search-input" placeholder="Search for" autocomplete="off"></form>

      <ul class="navbar-nav"><li class="nav-item">
  <a class="nav-link" href="../news/index.html">
    <span class="fa fa-newspaper"></span>
     
  </a>
</li>
<li class="nav-item">
  <a class="nav-link" href="../index.html">
    <span class="fa fa-home fa"></span>
     
  </a>
</li>
<li class="nav-item">
  <a class="external-link nav-link" href="https://github.com/fishR-Core-Team/FSA">
    <span class="fa fa-github fa"></span>
     
  </a>
</li>
      </ul></div>

    
  </div>
</nav><div class="container template-reference-topic">
<div class="row">
  <main id="main" class="col-md-9"><div class="page-header">
      <img src="../logo.png" class="logo" alt=""><h1>Creates separate histograms by levels.</h1>
      <small class="dont-index">Source: <a href="https://github.com/fishR-Core-Team/FSA/blob/HEAD/R/hist.formula.R" class="external-link"><code>R/hist.formula.R</code></a></small>
      <div class="d-none name"><code>hist.formula.Rd</code></div>
    </div>

    <div class="ref-description section level2">
    <p>Creates separate histograms of a quantitative variable by levels of a factor variable.</p>
    </div>

    <div class="section level2">
    <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="co"># S3 method for formula</span></span>
<span><span class="fu"><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></span><span class="op">(</span></span>
<span>  <span class="va">formula</span>,</span>
<span>  data <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  main <span class="op">=</span> <span class="st">""</span>,</span>
<span>  right <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  pre.main <span class="op">=</span> <span class="st">""</span>,</span>
<span>  xlab <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  ylab <span class="op">=</span> <span class="st">"Frequency"</span>,</span>
<span>  same.breaks <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  breaks <span class="op">=</span> <span class="st">"Sturges"</span>,</span>
<span>  w <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  same.ylim <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  ymax <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  col <span class="op">=</span> <span class="st">"gray90"</span>,</span>
<span>  nrow <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/Round.html" class="external-link">round</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/MathFun.html" class="external-link">sqrt</a></span><span class="op">(</span><span class="va">num</span><span class="op">)</span><span class="op">)</span>,</span>
<span>  ncol <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/Round.html" class="external-link">ceiling</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/MathFun.html" class="external-link">sqrt</a></span><span class="op">(</span><span class="va">num</span><span class="op">)</span><span class="op">)</span>,</span>
<span>  byrow <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  iaxs <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  <span class="va">...</span></span>
<span><span class="op">)</span></span></code></pre></div>
    </div>

    <div class="section level2">
    <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>
    <dl><dt>formula</dt>
<dd><p>A formula. See details.</p></dd>


<dt>data</dt>
<dd><p>An optional data frame that contains the variables in the model.</p></dd>


<dt>main</dt>
<dd><p>A character string used as the main title for when a SINGLE histogram is produced.</p></dd>


<dt>right</dt>
<dd><p>A logical that indicates if the histogram bins are right-closed (left open) intervals (<code>=TRUE</code>) or not (<code>=FALSE</code>; default).</p></dd>


<dt>pre.main</dt>
<dd><p>A character string to be used as a prefix for the main title when multiple histograms are produced. See details.</p></dd>


<dt>xlab</dt>
<dd><p>A character label for the x-axis. Defaults to name of quantitative variable in <code>formula</code>.</p></dd>


<dt>ylab</dt>
<dd><p>A character label for the y-axis. Defaults to “Frequency”.</p></dd>


<dt>same.breaks</dt>
<dd><p>A logical that indicates whether the same break values (i.e., bins) should be used on each histogram. Ignored if <code>breaks</code> or <code>w</code> is provided by the user. Defaults to <code>TRUE</code>.</p></dd>


<dt>breaks</dt>
<dd><p>A single numeric that indicates the number of bins or breaks or a vector that contains the lower values of the breaks. Ignored if <code>w</code> is not <code>NULL</code>. See <code><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></code> for more details.</p></dd>


<dt>w</dt>
<dd><p>A single numeric that indicates the width of the bins to use. The bins will start at “rounded” values depending on the value of <code>w</code>. See <code><a href="lencat.html">lencat</a></code> for more details.</p></dd>


<dt>same.ylim</dt>
<dd><p>A logical that indicates whether the same limits for the y-axis should be used on each histogram. Defaults to <code>TRUE</code>.</p></dd>


<dt>ymax</dt>
<dd><p>A single value that sets the maximum y-axis limit for each histogram or a vector of length equal to the number of groups that sets the maximum y-axis limit for each histogram separately. If <code>NULL</code> (default), then a value will be found.</p></dd>


<dt>col</dt>
<dd><p>A string that indicates the color for the bars on the histogram. Defaults to a light shade of gray (i.e., <code>"gray90"</code>).</p></dd>


<dt>nrow</dt>
<dd><p>A single numeric that contains the number of rows to use on the graphic.</p></dd>


<dt>ncol</dt>
<dd><p>A single numeric that contains the number of columns to use on the graphic.</p></dd>


<dt>byrow</dt>
<dd><p>A single logical that indicates if the histograms should fill rows first (<code>=TRUE</code> or columns first (<code>=FALSE</code>).</p></dd>


<dt>iaxs</dt>
<dd><p>A single logical that indicates whether both axes should be plotted using <code>xaxs="i"</code> and <code>yaxs="i"</code> (the default) or <code>xaxs="r"</code> and <code>yaxs="r"</code> (what R typically does).</p></dd>


<dt>...</dt>
<dd><p>Other arguments to pass through to the default <code><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist()</a></code>.</p></dd>

</dl></div>
    <div class="section level2">
    <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
    

<p>A graphic is produced and nothing is returned unless <code>formula</code> results in only one histogram. In that case, an object of class <code>"histogram"</code> is returned, which is described in <code><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></code>.</p>
    </div>
    <div class="section level2">
    <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
    <p>The formula must be of the form <code>~quantitative</code>, <code>quantitative~1</code>, <code>quantitative~factor</code>, or <code>quantitative~factor*factor2</code> where <code>quantitative</code> is the quantitative variable to construct the histograms for and <code>factor</code> or <code>factor2</code> are factor variables that contain the levels for which separate histograms should be constructed.</p>
<p>If the formula is of the form <code>~quantitative</code> or <code>quantitative~1</code> then only a single histogram of the quantitative variable will be produced. This allows <code>hist.formula()</code> to be used similarly to <code><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist()</a></code> but with a <code>data=</code> argument.</p>
<p>The function produces a single (but see below) graphic that consists of a grid on which the separate histograms are printed. The rows and columns of this grid are determined to construct a plot that is as square as possible. However, the rows and columns can be set by the user with the <code>nrow=</code> and <code>ncol=</code> arguments. If the product of the number of rows and number of columns set by the user is less than the total number of histograms to be constructed then multiple pages of histograms will be produced (each requiring the user to click on the graph to go to the next graph). The x-axis of each separate histogram will be labeled identically. The default x-axis label is the name of the quantitative variable. This can be changed by the user with the <code>xlab=</code> argument.</p>

<p>The default for <code>right=</code> is not the same as that used in <code><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist()</a></code> from <span class="pkg">graphics</span>. Thus, right-open (left-closed) bins are the default.</p>
<p>The <code>iaxs=</code> argument defaults to <code>TRUE</code> so that <code>xaxs="i"</code> and <code>yaxs="i"</code> are used for both axes, which eliminates the “floating” x-axis that R typically plots for histograms.</p>
    </div>
    <div class="section level2">
    <h2 id="note">Note<a class="anchor" aria-label="anchor" href="#note"></a></h2>
    <p>Students often need to look at the distribution of a quantitative variable separated for different levels of a categorical variable. One method for examining these distributions is with <code>boxplot(quantitative~factor)</code>. Other methods use functions in <span class="pkg">Lattice</span> and <span class="pkg">ggplots2</span> but these packages have some learning ‘overhead’ for newbie students. The formula notation, however, is a common way in R to tell R to separate a quantitative variable by the levels of a factor. Thus, this function adds code for formulas to the generic <code>hist</code> function. This allows newbie students to use a common notation (i.e., formula) to easily create multiple histograms of a quantitative variable separated by the levels of a factor.</p>
    </div>
    <div class="section level2">
    <h2 id="ifar-chapter">IFAR Chapter<a class="anchor" aria-label="anchor" href="#ifar-chapter"></a></h2>
    <p>3-Plotting Fundamentals.</p>
    </div>
    <div class="section level2">
    <h2 id="references">References<a class="anchor" aria-label="anchor" href="#references"></a></h2>
    <p>Ogle, D.H. 2016. <a href="https://fishr-core-team.github.io/fishR/pages/books.html#introductory-fisheries-analyses-with-r" class="external-link">Introductory Fisheries Analyses with R</a>. Chapman &amp; Hall/CRC, Boca Raton, FL.</p>
    </div>
    <div class="section level2">
    <h2 id="see-also">See also<a class="anchor" aria-label="anchor" href="#see-also"></a></h2>
    <div class="dont-index"><p>See base <code><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></code> for related functionality and <code><a href="https://rdrr.io/pkg/plotrix/man/multhist.html" class="external-link">multhist</a></code> in <span class="pkg">plotrix</span> for similar functionality.</p></div>
    </div>
    <div class="section level2">
    <h2 id="author">Author<a class="anchor" aria-label="anchor" href="#author"></a></h2>
    <p>Derek H. Ogle, <a href="mailto:DerekOgle51@gmail.com">DerekOgle51@gmail.com</a>, but this implementation is largely a modification of the code provided by Marc Schwartz on the R-help mailing list on 1Jun07.</p>
    </div>

    <div class="section level2">
    <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span><span class="co">## Using the defaults</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></span><span class="op">(</span><span class="va">Sepal.Length</span><span class="op">~</span><span class="va">Species</span>,data<span class="op">=</span><span class="va">iris</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="hist.formula-1.png" alt="" width="700" height="433"></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co">## Add x-labels and use a pre-fix on the main labels</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></span><span class="op">(</span><span class="va">Sepal.Length</span><span class="op">~</span><span class="va">Species</span>,data<span class="op">=</span><span class="va">iris</span>,xlab<span class="op">=</span><span class="st">"Sepal Length (cm)"</span>,</span></span>
<span class="r-in"><span>     pre.main<span class="op">=</span><span class="st">"Species=="</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="hist.formula-2.png" alt="" width="700" height="433"></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co">## Use different breaks and different y-axis limits for each graph</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></span><span class="op">(</span><span class="va">Sepal.Length</span><span class="op">~</span><span class="va">Species</span>,data<span class="op">=</span><span class="va">iris</span>,xlab<span class="op">=</span><span class="st">"Sepal Length (cm)"</span>,</span></span>
<span class="r-in"><span>     same.breaks<span class="op">=</span><span class="cn">FALSE</span>,same.ylim<span class="op">=</span><span class="cn">FALSE</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="hist.formula-3.png" alt="" width="700" height="433"></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co">## Single histogram without grouping using formula notation</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></span><span class="op">(</span><span class="op">~</span><span class="va">Sepal.Length</span>,data<span class="op">=</span><span class="va">iris</span>,xlab<span class="op">=</span><span class="st">"Sepal Length (cm)"</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="hist.formula-4.png" alt="" width="700" height="433"></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co">## Using the bin width argument</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></span><span class="op">(</span><span class="op">~</span><span class="va">Sepal.Length</span>,data<span class="op">=</span><span class="va">iris</span>,xlab<span class="op">=</span><span class="st">"Sepal Length (cm)"</span>,w<span class="op">=</span><span class="fl">1</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="hist.formula-5.png" alt="" width="700" height="433"></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/hist.html" class="external-link">hist</a></span><span class="op">(</span><span class="va">Sepal.Length</span><span class="op">~</span><span class="va">Species</span>,data<span class="op">=</span><span class="va">iris</span>,xlab<span class="op">=</span><span class="st">"Sepal Length (cm)"</span>,w<span class="op">=</span><span class="fl">0.25</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="hist.formula-6.png" alt="" width="700" height="433"></span>
<span class="r-in"><span></span></span>
</code></pre></div>
    </div>
  </main><aside class="col-md-3"><nav id="toc"><h2>On this page</h2>
    </nav></aside></div>


    <footer><div class="pkgdown-footer-left">
  <p></p><p>Developed by <a href="http://derekogle.com" class="external-link">Derek H. Ogle</a>, Jason C. Doll, A. Powell Wheeler, Alexis Dinno.</p>
</div>

<div class="pkgdown-footer-right">
  <p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.7.</p>
</div>

    </footer></div>

  

  

  </body></html>

