AMR/docs/reference/ab_from_text.html

294 lines
21 KiB
HTML

<!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.0"><title>Retrieve Antimicrobial Drug Names and Doses from Clinical Text — ab_from_text • AMR (for R)</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"><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script><!-- Bootstrap --><link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.4.0/flatly/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.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"><!-- 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><!-- 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><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><link href="../extra.css" rel="stylesheet"><script src="../extra.js"></script><meta property="og:title" content="Retrieve Antimicrobial Drug Names and Doses from Clinical Text — ab_from_text"><meta property="og:description" content="Use this function on e.g. clinical texts from health care records. It returns a list with all antimicrobial drugs, doses and forms of administration found in the texts."><meta property="og:image" content="https://msberends.github.io/AMR/logo.svg"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:creator" content="@msberends"><meta name="twitter:site" content="@univgroningen"><!-- 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 data-spy="scroll" data-target="#toc">
<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" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<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">AMR (for R)</a>
<span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">1.8.1.9007</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"></span>
Home
</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
<span class="fa fa-question-circle"></span>
How to
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu"><li>
<a href="../articles/AMR.html">
<span class="fa fa-directions"></span>
Conduct AMR analysis
</a>
</li>
<li>
<a href="../articles/resistance_predict.html">
<span class="fa fa-dice"></span>
Predict antimicrobial resistance
</a>
</li>
<li>
<a href="../articles/datasets.html">
<span class="fa fa-database"></span>
Data sets for download / own use
</a>
</li>
<li>
<a href="../articles/PCA.html">
<span class="fa fa-compress"></span>
Conduct principal component analysis for AMR
</a>
</li>
<li>
<a href="../articles/MDR.html">
<span class="fa fa-skull-crossbones"></span>
Determine multi-drug resistance (MDR)
</a>
</li>
<li>
<a href="../articles/WHONET.html">
<span class="fa fa-globe-americas"></span>
Work with WHONET data
</a>
</li>
<li>
<a href="../articles/SPSS.html">
<span class="fa fa-file-upload"></span>
Import data from SPSS/SAS/Stata
</a>
</li>
<li>
<a href="../articles/EUCAST.html">
<span class="fa fa-exchange-alt"></span>
Apply EUCAST rules
</a>
</li>
<li>
<a href="../reference/mo_property.html">
<span class="fa fa-bug"></span>
Get properties of a microorganism
</a>
</li>
<li>
<a href="../reference/ab_property.html">
<span class="fa fa-capsules"></span>
Get properties of an antibiotic
</a>
</li>
<li>
<a href="../articles/benchmarks.html">
<span class="fa fa-shipping-fast"></span>
Other: benchmarks
</a>
</li>
</ul></li>
<li>
<a href="../reference/index.html">
<span class="fa fa-book-open"></span>
Manual
</a>
</li>
<li>
<a href="../authors.html">
<span class="fa fa-users"></span>
Authors
</a>
</li>
<li>
<a href="../news/index.html">
<span class="far fa-newspaper"></span>
Changelog
</a>
</li>
</ul><ul class="nav navbar-nav navbar-right"><li>
<a href="https://github.com/msberends/AMR" class="external-link">
<span class="fab fa-github"></span>
Source Code
</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>Retrieve Antimicrobial Drug Names and Doses from Clinical Text</h1>
<small class="dont-index">Source: <a href="https://github.com/msberends/AMR/blob/HEAD/R/ab_from_text.R" class="external-link"><code>R/ab_from_text.R</code></a></small>
<div class="hidden name"><code>ab_from_text.Rd</code></div>
</div>
<div class="ref-description">
<p>Use this function on e.g. clinical texts from health care records. It returns a <a href="https://rdrr.io/r/base/list.html" class="external-link">list</a> with all antimicrobial drugs, doses and forms of administration found in the texts.</p>
</div>
<div id="ref-usage">
<div class="sourceCode"><pre class="sourceCode r"><code><span class="fu">ab_from_text</span><span class="op">(</span>
<span class="va">text</span>,
type <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"drug"</span>, <span class="st">"dose"</span>, <span class="st">"administration"</span><span class="op">)</span>,
collapse <span class="op">=</span> <span class="cn">NULL</span>,
translate_ab <span class="op">=</span> <span class="cn">FALSE</span>,
thorough_search <span class="op">=</span> <span class="cn">NULL</span>,
info <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/interactive.html" class="external-link">interactive</a></span><span class="op">(</span><span class="op">)</span>,
<span class="va">...</span>
<span class="op">)</span></code></pre></div>
</div>
<div id="arguments">
<h2>Arguments</h2>
<dl><dt>text</dt>
<dd><p>text to analyse</p></dd>
<dt>type</dt>
<dd><p>type of property to search for, either <code>"drug"</code>, <code>"dose"</code> or <code>"administration"</code>, see <em>Examples</em></p></dd>
<dt>collapse</dt>
<dd><p>a <a href="https://rdrr.io/r/base/character.html" class="external-link">character</a> to pass on to <code>paste(, collapse = ...)</code> to only return one <a href="https://rdrr.io/r/base/character.html" class="external-link">character</a> per element of <code>text</code>, see <em>Examples</em></p></dd>
<dt>translate_ab</dt>
<dd><p>if <code>type = "drug"</code>: a column name of the <a href="antibiotics.html">antibiotics</a> data set to translate the antibiotic abbreviations to, using <code><a href="ab_property.html">ab_property()</a></code>. Defaults to <code>FALSE</code>. Using <code>TRUE</code> is equal to using "name".</p></dd>
<dt>thorough_search</dt>
<dd><p>a <a href="https://rdrr.io/r/base/logical.html" class="external-link">logical</a> to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to <code>TRUE</code> will take considerably more time than when using <code>FALSE</code>. At default, it will turn <code>TRUE</code> when all input elements contain a maximum of three words.</p></dd>
<dt>info</dt>
<dd><p>a <a href="https://rdrr.io/r/base/logical.html" class="external-link">logical</a> to indicate whether a progress bar should be printed, defaults to <code>TRUE</code> only in interactive mode</p></dd>
<dt>...</dt>
<dd><p>arguments passed on to <code><a href="as.ab.html">as.ab()</a></code></p></dd>
</dl></div>
<div id="value">
<h2>Value</h2>
<p>A <a href="https://rdrr.io/r/base/list.html" class="external-link">list</a>, or a <a href="https://rdrr.io/r/base/character.html" class="external-link">character</a> if <code>collapse</code> is not <code>NULL</code></p>
</div>
<div id="details">
<h2>Details</h2>
<p>This function is also internally used by <code><a href="as.ab.html">as.ab()</a></code>, although it then only searches for the first drug name and will throw a note if more drug names could have been returned. Note: the <code><a href="as.ab.html">as.ab()</a></code> function may use very long regular expression to match brand names of antimicrobial agents. This may fail on some systems.</p><div class="section">
<h3 id="argument-type">Argument <code>type</code><a class="anchor" aria-label="anchor" href="#argument-type"></a></h3>
<p>At default, the function will search for antimicrobial drug names. All text elements will be searched for official names, ATC codes and brand names. As it uses <code><a href="as.ab.html">as.ab()</a></code> internally, it will correct for misspelling.</p>
<p>With <code>type = "dose"</code> (or similar, like "dosing", "doses"), all text elements will be searched for <a href="https://rdrr.io/r/base/numeric.html" class="external-link">numeric</a> values that are higher than 100 and do not resemble years. The output will be <a href="https://rdrr.io/r/base/numeric.html" class="external-link">numeric</a>. It supports any unit (g, mg, IE, etc.) and multiple values in one clinical text, see <em>Examples</em>.</p>
<p>With <code>type = "administration"</code> (or abbreviations, like "admin", "adm"), all text elements will be searched for a form of drug administration. It supports the following forms (including common abbreviations): buccal, implant, inhalation, instillation, intravenous, nasal, oral, parenteral, rectal, sublingual, transdermal and vaginal. Abbreviations for oral (such as 'po', 'per os') will become "oral", all values for intravenous (such as 'iv', 'intraven') will become "iv". It supports multiple values in one clinical text, see <em>Examples</em>.</p>
</div>
<div class="section">
<h3 id="argument-collapse">Argument <code>collapse</code><a class="anchor" aria-label="anchor" href="#argument-collapse"></a></h3>
<p>Without using <code>collapse</code>, this function will return a <a href="https://rdrr.io/r/base/list.html" class="external-link">list</a>. This can be convenient to use e.g. inside a <code><a href="https://dplyr.tidyverse.org/reference/mutate.html" class="external-link">mutate()</a></code>):<br><code>df %&gt;% mutate(abx = ab_from_text(clinical_text))</code></p>
<p>The returned AB codes can be transformed to official names, groups, etc. with all <code><a href="ab_property.html">ab_*</a></code> functions such as <code><a href="ab_property.html">ab_name()</a></code> and <code><a href="ab_property.html">ab_group()</a></code>, or by using the <code>translate_ab</code> argument.</p>
<p>With using <code>collapse</code>, this function will return a <a href="https://rdrr.io/r/base/character.html" class="external-link">character</a>:<br><code>df %&gt;% mutate(abx = ab_from_text(clinical_text, collapse = "|"))</code></p>
</div>
</div>
<div id="stable-lifecycle">
<h2>Stable Lifecycle</h2>
<p><img src="figures/lifecycle_stable.svg" style='margin-bottom:"5"'><br>
The <a href="lifecycle.html">lifecycle</a> of this function is <strong>stable</strong>. In a stable function, major changes are unlikely. This means that the unlying code will generally evolve by adding new arguments; removing arguments or changing the meaning of existing arguments will be avoided.</p>
<p>If the unlying code needs breaking changes, they will occur gradually. For example, an argument will be deprecated and first continue to work, but will emit a message informing you of the change. Next, typically after at least one newly released version on CRAN, the message will be transformed to an error.</p>
</div>
<div id="read-more-on-our-website-">
<h2>Read more on Our Website!</h2>
<p>On our website <a href="https://msberends.github.io/AMR/">https://msberends.github.io/AMR/</a> you can find <a href="https://msberends.github.io/AMR/articles/AMR.html">a comprehensive tutorial</a> about how to conduct AMR data analysis, the <a href="https://msberends.github.io/AMR/reference/">complete documentation of all functions</a> and <a href="https://msberends.github.io/AMR/articles/WHONET.html">an example analysis using WHONET data</a>.</p>
</div>
<div id="ref-examples">
<h2>Examples</h2>
<div class="sourceCode"><pre class="sourceCode r"><code><span class="co"># mind the bad spelling of amoxicillin in this line, </span>
<span class="co"># straight from a true health care record:</span>
<span class="fu">ab_from_text</span><span class="op">(</span><span class="st">"28/03/2020 regular amoxicilliin 500mg po tds"</span><span class="op">)</span>
<span class="fu">ab_from_text</span><span class="op">(</span><span class="st">"500 mg amoxi po and 400mg cipro iv"</span><span class="op">)</span>
<span class="fu">ab_from_text</span><span class="op">(</span><span class="st">"500 mg amoxi po and 400mg cipro iv"</span>, type <span class="op">=</span> <span class="st">"dose"</span><span class="op">)</span>
<span class="fu">ab_from_text</span><span class="op">(</span><span class="st">"500 mg amoxi po and 400mg cipro iv"</span>, type <span class="op">=</span> <span class="st">"admin"</span><span class="op">)</span>
<span class="fu">ab_from_text</span><span class="op">(</span><span class="st">"500 mg amoxi po and 400mg cipro iv"</span>, collapse <span class="op">=</span> <span class="st">", "</span><span class="op">)</span>
<span class="co"># \donttest{</span>
<span class="co"># if you want to know which antibiotic groups were administered, do e.g.:</span>
<span class="va">abx</span> <span class="op">&lt;-</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="st">"500 mg amoxi po and 400mg cipro iv"</span><span class="op">)</span>
<span class="fu"><a href="ab_property.html">ab_group</a></span><span class="op">(</span><span class="va">abx</span><span class="op">[[</span><span class="fl">1</span><span class="op">]</span><span class="op">]</span><span class="op">)</span>
<span class="kw">if</span> <span class="op">(</span><span class="kw"><a href="https://rdrr.io/r/base/library.html" class="external-link">require</a></span><span class="op">(</span><span class="st"><a href="https://dplyr.tidyverse.org" class="external-link">"dplyr"</a></span><span class="op">)</span><span class="op">)</span> <span class="op">{</span>
<span class="fu"><a href="https://tibble.tidyverse.org/reference/tibble.html" class="external-link">tibble</a></span><span class="op">(</span>clinical_text <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"given 400mg cipro and 500 mg amox"</span>,
<span class="st">"started on doxy iv today"</span><span class="op">)</span><span class="op">)</span> <span class="op"><a href="https://magrittr.tidyverse.org/reference/pipe.html" class="external-link">%&gt;%</a></span>
<span class="fu"><a href="https://dplyr.tidyverse.org/reference/mutate.html" class="external-link">mutate</a></span><span class="op">(</span>abx_codes <span class="op">=</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="va">clinical_text</span><span class="op">)</span>,
abx_doses <span class="op">=</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="va">clinical_text</span>, type <span class="op">=</span> <span class="st">"doses"</span><span class="op">)</span>,
abx_admin <span class="op">=</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="va">clinical_text</span>, type <span class="op">=</span> <span class="st">"admin"</span><span class="op">)</span>,
abx_coll <span class="op">=</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="va">clinical_text</span>, collapse <span class="op">=</span> <span class="st">"|"</span><span class="op">)</span>,
abx_coll_names <span class="op">=</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="va">clinical_text</span>,
collapse <span class="op">=</span> <span class="st">"|"</span>,
translate_ab <span class="op">=</span> <span class="st">"name"</span><span class="op">)</span>,
abx_coll_doses <span class="op">=</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="va">clinical_text</span>,
type <span class="op">=</span> <span class="st">"doses"</span>,
collapse <span class="op">=</span> <span class="st">"|"</span><span class="op">)</span>,
abx_coll_admin <span class="op">=</span> <span class="fu">ab_from_text</span><span class="op">(</span><span class="va">clinical_text</span>,
type <span class="op">=</span> <span class="st">"admin"</span>,
collapse <span class="op">=</span> <span class="st">"|"</span><span class="op">)</span><span class="op">)</span>
<span class="op">}</span>
<span class="co"># }</span>
</code></pre></div>
</div>
</div>
<div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
<nav id="toc" data-toggle="toc" class="sticky-top"><h2 data-toc-skip>Contents</h2>
</nav></div>
</div>
<footer><div class="copyright">
<p></p><p>Developed by Matthijs S. Berends, Christian F. Luz, Dennis Souverein, Erwin E. A. Hassing.</p>
</div>
<div class="pkgdown">
<p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.3.</p>
</div>
</footer></div>
</body></html>