https://github.com/cran/cutpointr
Tip revision: 4408233eb8624dea85ecf18e86d50c296165c3f2 authored by Christian Thiele on 13 April 2022, 17:12:29 UTC
version 1.1.2
version 1.1.2
Tip revision: 4408233
cutpointr_user_functions.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="author" content="Christian Thiele" />
<meta name="date" content="2022-04-13" />
<title>User-defined functions for estimation methods and metrics</title>
<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
var i, h, a;
for (i = 0; i < hs.length; i++) {
h = hs[i];
if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6
a = h.attributes;
while (a.length > 0) h.removeAttribute(a[0].name);
}
});
</script>
<script>// Hide empty <a> tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) -->
// v0.0.1
// Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020.
document.addEventListener('DOMContentLoaded', function() {
const codeList = document.getElementsByClassName("sourceCode");
for (var i = 0; i < codeList.length; i++) {
var linkList = codeList[i].getElementsByTagName('a');
for (var j = 0; j < linkList.length; j++) {
if (linkList[j].innerHTML === "") {
linkList[j].setAttribute('aria-hidden', 'true');
}
}
}
});
</script>
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>
<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
var sheets = document.styleSheets;
for (var i = 0; i < sheets.length; i++) {
if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
try { var rules = sheets[i].cssRules; } catch (e) { continue; }
for (var j = 0; j < rules.length; j++) {
var rule = rules[j];
// check if there is a div.sourceCode rule
if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue;
var style = rule.style.cssText;
// check if color or background-color is set
if (rule.style.color === '' && rule.style.backgroundColor === '') continue;
// replace div.sourceCode by a pre.sourceCode rule
sheets[i].deleteRule(j);
sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
}
}
})();
</script>
<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap;
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }
code > span.kw { color: #555; font-weight: bold; }
code > span.dt { color: #902000; }
code > span.dv { color: #40a070; }
code > span.bn { color: #d14; }
code > span.fl { color: #d14; }
code > span.ch { color: #d14; }
code > span.st { color: #d14; }
code > span.co { color: #888888; font-style: italic; }
code > span.ot { color: #007020; }
code > span.al { color: #ff0000; font-weight: bold; }
code > span.fu { color: #900; font-weight: bold; }
code > span.er { color: #a61717; background-color: #e3d2d2; }
</style>
</head>
<body>
<h1 class="title toc-ignore">User-defined functions for estimation methods and metrics</h1>
<h4 class="author">Christian Thiele</h4>
<h4 class="date">2022-04-13</h4>
<div id="user-defined-functions" class="section level1">
<h1>User-defined functions</h1>
<div id="method" class="section level2">
<h2>method</h2>
<p>User-defined functions can be supplied to <code>method</code>, which is the function that is responsible for returning the optimal cutpoint. To define a new method function, create a function that may take as input(s):</p>
<ul>
<li><code>data</code>: A <code>data.frame</code> or <code>tbl_df</code></li>
<li><code>x</code>: (character) The name of the predictor variable</li>
<li><code>class</code>: (character) The name of the class variable</li>
<li><code>metric_func</code>: A function for calculating a metric, e.g. accuracy. Note that the method function does not necessarily have to accept this argument</li>
<li><code>pos_class</code>: The positive class</li>
<li><code>neg_class</code>: The negative class</li>
<li><code>direction</code>: <code>">="</code> if the positive class has higher x values, <code>"<="</code> otherwise</li>
<li><code>tol_metric</code>: (numeric) In the built-in methods, all cutpoints will be returned that lead to a metric value in the interval [m_max - tol_metric, m_max + tol_metric] where m_max is the maximum achievable metric value. This can be used to return multiple decent cutpoints and to avoid floating-point problems.</li>
<li><code>use_midpoints</code>: (logical) In the built-in methods, if TRUE (default FALSE) the returned optimal cutpoint will be the mean of the optimal cutpoint and the next highest observation (for direction = “>”) or the next lowest observation (for direction = “<”) which avoids biasing the optimal cutpoint.</li>
<li><code>...</code>: Further arguments that are passed to <code>metric</code> or that can be captured inside of <code>method</code></li>
</ul>
<p>The function should return a data frame or tibble with one row, the column <code>optimal_cutpoint</code>, and an optional column with an arbitrary name with the metric value at the optimal cutpoint.</p>
<p>For example, a function for choosing the cutpoint as the mean of the independent variable could look like this:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1"></a>mean_cut <-<span class="st"> </span><span class="cf">function</span>(data, x, ...) {</span>
<span id="cb1-2"><a href="#cb1-2"></a> oc <-<span class="st"> </span><span class="kw">mean</span>(data[[x]])</span>
<span id="cb1-3"><a href="#cb1-3"></a> <span class="kw">return</span>(<span class="kw">data.frame</span>(<span class="dt">optimal_cutpoint =</span> oc))</span>
<span id="cb1-4"><a href="#cb1-4"></a>}</span></code></pre></div>
<p>If a <code>method</code> function does not return a metric column, the default <code>sum_sens_spec</code>, the sum of sensitivity and specificity, is returned as the extra metric column in addition to accuracy, sensitivity and specificity.</p>
<p>Some <code>method</code> functions that make use of the additional arguments (that are captured by <code>...</code>) are already included in <strong>cutpointr</strong>, see the list at the top. Since these functions are arguments to <code>cutpointr</code> their code can be accessed by simply typing their name, see for example <code>oc_youden_normal</code>.</p>
</div>
<div id="metric" class="section level2">
<h2>metric</h2>
<p>User defined <code>metric</code> functions can be used as well. They are mainly useful in conjunction with <code>method = maximize_metric</code>, <code>method = minimize_metric</code>, or one of the other minimization and maximization functions. In case of a different <code>method</code> function <code>metric</code> will only be used as the main out-of-bag metric when plotting the result. The <code>metric</code> function should accept the following inputs as vectors:</p>
<ul>
<li><code>tp</code>: Vector of true positives</li>
<li><code>fp</code>: Vector of false positives</li>
<li><code>tn</code>: Vector of true negatives</li>
<li><code>fn</code>: Vector of false negatives</li>
<li><code>...</code>: Further arguments</li>
</ul>
<p>The function should return a numeric vector, a matrix, or a <code>data.frame</code> with one column. If the column is named, the name will be included in the output and plots. Avoid using names that are identical to the column names that are by default returned by <strong>cutpointr</strong>, as such names will be prefixed by <code>metric_</code> in the output. The inputs (<code>tp</code>, <code>fp</code>, <code>tn</code>, and <code>fn</code>) are vectors. The code of the included metric functions can be accessed by simply typing their name.</p>
<p>For example, this is the <code>misclassification_cost</code> metric function:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1"></a><span class="kw">library</span>(cutpointr)</span>
<span id="cb2-2"><a href="#cb2-2"></a>misclassification_cost</span></code></pre></div>
<pre><code>## function (tp, fp, tn, fn, cost_fp = 1, cost_fn = 1, ...)
## {
## misclassification_cost <- cost_fp * fp + cost_fn * fn
## misclassification_cost <- matrix(misclassification_cost,
## ncol = 1)
## colnames(misclassification_cost) <- "misclassification_cost"
## return(misclassification_cost)
## }
## <bytecode: 0x0000000022dbcf70>
## <environment: namespace:cutpointr></code></pre>
</div>
</div>
<!-- code folding -->
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>
