<p><div><div><div><div data-show-faces="false" data-height="21" data-width="100" data-layout="button_count" data-send="true" data-href="https://www.r-bloggers.com/usage-of-ruler-package/"></div></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="http://www.questionflow.org/2017/12/05/usage-of-ruler-package/"> QuestionFlow </a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<p> Usage examples of ruler package: dplyr-style exploration and validation of data frame like objects.</p>
<div>
<h1>Prologue</h1>
<p>My <a rel="nofollow" href="http://www.questionflow.org/2017/11/28/rule-your-data-with-tidy-validation-reports-design/" target="_blank">previous post</a> tells a story about design of my <a rel="nofollow" href="https://echasnovski.github.io/ruler/" target="_blank">ruler</a> package, which presents tools for “… creating data validation pipelines and tidy reports”. This package offers a framework for exploring and validating data frame like objects using <a rel="nofollow" href="http://dplyr.tidyverse.org/" target="_blank">dplyr</a> grammar of data manipulation.</p>
<p>This post is intended to show some close to reality <code>ruler</code> usage examples. Described methods and approaches reflect package design. Along the way you will learn why Yoda and Jabba the Hutt are “outliers” among core “Star Wars” characters.</p>
<p>For more information see <a rel="nofollow" href="https://echasnovski.github.io/ruler/" target="_blank">README</a> (for relatively brief comprehensive introduction) or <a rel="nofollow" href="https://echasnovski.github.io/ruler/articles/" target="_blank">vignettes</a> (for more thorough description of package capabilities).</p>
<p><strong>Beware</strong> of a lot of code.</p>
</div>
<div>
<h1>Overview</h1>
<pre><code>suppressMessages(library(dplyr))
suppressMessages(library(purrr))
library(ruler)</code></pre>
<p>The general way of performing validation with <code>ruler</code> can be described with following steps:</p>
<ul>
<li><strong>Formulate a validation task</strong>. It is usually stated in the form of a yes-no question or true-false statement about some part (data unit) of an input data frame. Data unit can be one of: data [as a whole], group of rows [as a whole], column [as a whole], row [as a whole], cell. For example, <em>does every column contain elements with sum more than 100?</em>.</li>
<li><strong>Create a <code>dplyr</code>-style validation function</strong> (rule pack) which checks desired data unit for obedience to [possibly] several rules:
<ul>
<li>Create <code>dplyr</code> code for “interactive” validation. <strong>Note</strong> to use only <a rel="nofollow" href="https://echasnovski.github.io/keyholder/reference/keyholder-supported-funs.html" target="_blank">functions supported by keyholder package</a>. An example with “enough_sum” as a rule name:</li>
</ul>
<pre><code>mtcars %>% summarise_all(funs(enough_sum = sum(.) > 100))</code></pre>
<ul>
<li>Use <code>ruler</code>’s function <code>rules()</code> instead of explicit or implicit usage of <code>funs()</code>:</li>
</ul>
<pre><code>mtcars %>% summarise_all(rules(enough_sum = sum(.) > 100))</code></pre>
<ul>
<li>Modify code to create <a rel="nofollow" href="http://magrittr.tidyverse.org/reference/pipe.html" target="_blank">magrittr functional sequence</a> by replacing input variable name by a <code>.</code>:</li>
</ul>
<pre><code>. %>% summarise_all(rules(enough_sum = sum(.) > 100))</code></pre>
<ul>
<li>Wrap with <a rel="nofollow" href="https://echasnovski.github.io/ruler/reference/rule-packs.html" target="_blank">rule specification function</a> to explicitly identify validated data unit and to name rule pack. In this case it is <code>col_packs()</code> for column data unit with “is_enough_sum” as rule pack name:</li>
</ul>
<pre><code>col_packs(
  is_enough_sum = . %>% summarise_all(rules(is_enough = sum(.) > 100))
)</code></pre>
</li>
<li><strong>Expose data to rules</strong> to obtain validation result (exposure). Use <code>ruler</code>’s <code>expose()</code> function for that. It doesn’t modify contents of input data frame but creates/updates <code>exposure</code> attribute. <a rel="nofollow" href="https://echasnovski.github.io/ruler/reference/exposure.html" target="_blank">Exposure</a> is a list with information about used rule packs (<a rel="nofollow" href="https://echasnovski.github.io/ruler/reference/packs_info.html" target="_blank">packs_info</a>) and tidy data validation report (<a rel="nofollow" href="https://echasnovski.github.io/ruler/reference/ruler-report.html" target="_blank">report</a>).</li>
<li><strong>Act after exposure</strong>. It can be:
<ul>
<li>Observing validation results with <code>get_exposure()</code>, <code>get_packs_info()</code> or <code>get_report()</code>.</li>
<li>Making assertions if specific rules are not followed in desired way.</li>
<li>Imputing input data frame based on report.</li>
</ul>
</li>
</ul>
<p>In examples we will use <a rel="nofollow" href="http://dplyr.tidyverse.org/reference/starwars.html" target="_blank">starwars</a> data from <code>dplyr</code> package (to celebrate an upcoming new episode). It is a tibble with every row describing one “Star Wars” character. Every example starts with a validation task stated <em>in italic</em> and performs validation from beginning to end.</p>
</div>
<div>
<h1>Create rule packs</h1>
<div>
<h2>Data</h2>
<p>■ <em>Does <code>starwars</code> have 1) number of rows 1a) more than 50; 1b) less than 60; 2) number of columns 2a) more than 10; 2b) less than 15?</em></p>
<pre><code>check_data_dims &lt;- data_packs(
  check_dims = . %>% summarise(
    nrow_low = nrow(.) >= 50, nrow_up = nrow(.) &lt;= 60,
    ncol_low = ncol(.) >= 10, ncol_up = ncol(.) &lt;= 15
  )
)

starwars %>%
  expose(check_data_dims) %>%
  get_exposure()
##   Exposure
## 
## Packs info:
## # A tibble: 1 x 4
##         name      type             fun remove_obeyers
##        </code></pre></div></div>