documentation, file permissions

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AMR
-Version: 1.8.2.9093
+Version: 1.8.2.9094
-Date: 2023-01-14
+Date: 2023-01-19
 Title: Antimicrobial Resistance Data Analysis
 Description: Functions to simplify and standardise antimicrobial resistance (AMR)
   data analysis and to work with microbial and antimicrobial properties by

NEWS.md

@@ -1,4 +1,4 @@
-# AMR 1.8.2.9093
+# AMR 1.8.2.9094
 
 *(this beta version will eventually become v2.0! We're happy to reach a new major milestone soon!)*
 

R/custom_microorganisms.R

@@ -37,11 +37,11 @@
 #' 
 #' There are two ways to automate this process:
 #' 
-#' **Method 1:** Save the microorganisms to a local or remote file (can even be the internet). To use this method:
+#' **Method 1:** Using the [option `AMR_custom_mo`][AMR-options], which is the preferred method. To use this method:
 #' 
 #'    1. Create a data set in the structure of the [microorganisms] data set (containing at the very least column "genus") and save it with [saveRDS()] to a location of choice, e.g. `"~/my_custom_mo.rds"`, or any remote location.
 #'    
-#'    2. Set the file location to the `AMR_custom_mo` \R option: `options(AMR_custom_mo = "~/my_custom_mo.rds")`. This can even be a remote file location, such as an https URL. Since options are not saved between \R sessions, it is best to save this option to the `.Rprofile` file so that it will loaded on start-up of \R. To do this, open the `.Rprofile` file using e.g. `utils::file.edit("~/.Rprofile")`, add this text and save the file:
+#'    2. Set the file location to the `AMR_custom_mo` \R option: `options(AMR_custom_mo = "~/my_custom_mo.rds")`. This can even be a remote file location, such as an https URL. Since options are not saved between \R sessions, it is best to save this option to the `.Rprofile` file so that it will be loaded on start-up of \R. To do this, open the `.Rprofile` file using e.g. `utils::file.edit("~/.Rprofile")`, add this text and save the file:
 #'
 #'       ```r
 #'       # Add custom microorganism codes:
@@ -50,7 +50,7 @@
 #'       
 #'       Upon package load, this file will be loaded and run through the [add_custom_microorganisms()] function.
 #' 
-#' **Method 2:** Save the microorganism directly to your `.Rprofile` file. An important downside is that this requires to load the `AMR` package at every start-up. To use this method:
+#' **Method 2:** Loading the microorganism directly from your `.Rprofile` file. An important downside is that this requires the `AMR` package to be installed or else this method will fail. To use this method:
 #' 
 #'    1. Edit the `.Rprofile` file using e.g. `utils::file.edit("~/.Rprofile")`.
 #'
@@ -58,8 +58,7 @@
 #'
 #'       ```r
 #'        # Add custom antibiotic drug codes:
-#'        library(AMR)
+#'        AMR::add_custom_microorganisms(
-#'        add_custom_microorganisms(
 #'          data.frame(genus = "Enterobacter",
 #'                     species = "asburiae/cloacae")
 #'        )
@@ -71,7 +70,6 @@
 #' @export
 #' @examples
 #' \donttest{
-#'
 #' # a combination of species is not formal taxonomy, so
 #' # this will result in only "Enterobacter asburiae":
 #' mo_name("Enterobacter asburiae/cloacae")
@@ -102,13 +100,15 @@
 #' 
 #' # the function tries to be forgiving:
 #' add_custom_microorganisms(
-#'   data.frame(GENUS = "ESCHERICHIA / KLEBSIELLA SLASHLINE",
+#'   data.frame(GENUS = "BACTEROIDES / PARABACTEROIDES SLASHLINE",
 #'              SPECIES = "SPECIES")
 #' )
-#' mo_name("ESCHERICHIA / KLEBSIELLA")
+#' mo_name("BACTEROIDES / PARABACTEROIDES")
-#' mo_rank("ESCHERICHIA / KLEBSIELLA")
+#' mo_rank("BACTEROIDES / PARABACTEROIDES")
+#' 
 #' # taxonomy still works, although a slashline genus was given as input:
-#' mo_family("Escherichia/Klebsiella")
+#' mo_family("Bacteroides/Parabacteroides")
+#' 
 #' 
 #' # for groups and complexes, set them as species or subspecies:
 #' add_custom_microorganisms(
@@ -208,8 +208,10 @@ add_custom_microorganisms <- function(x) {
   x$family[which(x$family == "" & genus_to_check != "")] <- AMR_env$MO_lookup$family[match(genus_to_check[which(x$family == "" & genus_to_check != "")], AMR_env$MO_lookup$genus)]
   
   # fill in other columns that are used in internal algorithms
+  x$prevalence <- NA_real_
+  x$prevalence[which(genus_to_check != "")] <- AMR_env$MO_lookup$prevalence[match(genus_to_check[which(genus_to_check != "")], AMR_env$MO_lookup$genus)]
+  x$prevalence[is.na(x$prevalence)] <- 1.25
   x$status <- "accepted"
-  x$prevalence <- 1
   x$ref <- paste("Self-added,", format(Sys.Date(), "%Y"))
   x$kingdom_index <- AMR_env$MO_lookup$kingdom_index[match(genus_to_check, AMR_env$MO_lookup$genus)]
   # complete missing kingdom index, so mo_matching_score() will not return NA

R/mo_property.R

@@ -777,7 +777,7 @@ mo_info <- function(x, language = get_AMR_locale(), keep_synonyms = getOption("A
 
   info <- lapply(x, function(y) {
     c(
-      list(identifier = x),
+      list(mo = as.character(x)),
       mo_taxonomy(y, language = language, keep_synonyms = keep_synonyms),
       list(
         status = mo_status(y, language = language, keep_synonyms = keep_synonyms),
@@ -894,6 +894,8 @@ mo_validate <- function(x, property, language, keep_synonyms = keep_synonyms, ..
     return(set_clean_class(x, new_class = c("mo", "character")))
   } else if (property == "snomed") {
     return(sort(as.character(eval(parse(text = x)))))
+  } else if (property == "prevalence") {
+    return(as.double(x))
   } else {
     # everything else as character
     return(as.character(x))

R/options.R

@@ -0,0 +1,39 @@
+# ==================================================================== #
+# TITLE                                                                #
+# AMR: An R Package for Working with Antimicrobial Resistance Data     #
+#                                                                      #
+# SOURCE                                                               #
+# https://github.com/msberends/AMR                                     #
+#                                                                      #
+# CITE AS                                                              #
+# Berends MS, Luz CF, Friedrich AW, Sinha BNM, Albers CJ, Glasner C    #
+# (2022). AMR: An R Package for Working with Antimicrobial Resistance  #
+# Data. Journal of Statistical Software, 104(3), 1-31.                 #
+# doi:10.18637/jss.v104.i03                                            #
+#                                                                      #
+# Developed at the University of Groningen and the University Medical  #
+# Center Groningen in The Netherlands, in collaboration with many      #
+# colleagues from around the world, see our website.                   #
+#                                                                      #
+# This R package is free software; you can freely use and distribute   #
+# it for both personal and commercial purposes under the terms of the  #
+# GNU General Public License version 2.0 (GNU GPL-2), as published by  #
+# the Free Software Foundation.                                        #
+# We created this package for both routine data analysis and academic  #
+# research and it was publicly released in the hope that it will be    #
+# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY.              #
+#                                                                      #
+# Visit our website for the full manual and a complete tutorial about  #
+# how to conduct AMR data analysis: https://msberends.github.io/AMR/   #
+# ==================================================================== #
+
+#' Options for the AMR package
+#'
+#' This is an overview of the package-specific [options()] you can set in the `AMR` package.
+#' @section Options:
+#' * `AMR_custom_ab`: allows to use custom antimicrobial drugs with this package. This is explained in [add_custom_antimicrobials()].
+#' * `AMR_custom_mo`: allows to use custom microorganisms with this package. This is explained in [add_custom_microorganisms()].
+#' @keywords internal
+#' @name AMR-options
+# @export
+NULL

man/AMR-options.Rd

@@ -0,0 +1,17 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/options.R
+\name{AMR-options}
+\alias{AMR-options}
+\title{Options for the AMR package}
+\description{
+This is an overview of the package-specific \code{\link[=options]{options()}} you can set in the \code{AMR} package.
+}
+\section{Options}{
+
+\itemize{
+\item \code{AMR_custom_ab}: allows to use custom antimicrobial drugs with this package. This is explained in \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}}.
+\item \code{AMR_custom_mo}: allows to use custom microorganisms with this package. This is explained in \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}}.
+}
+}
+
+\keyword{internal}

man/add_custom_microorganisms.Rd

@@ -22,10 +22,10 @@ This function will fill in missing taxonomy for you, if specific taxonomic colum
 
 There are two ways to automate this process:
 
-\strong{Method 1:} Save the microorganisms to a local or remote file (can even be the internet). To use this method:
+\strong{Method 1:} Using the , which is the preferred method. To use this method:
 \enumerate{
 \item Create a data set in the structure of the \link{microorganisms} data set (containing at the very least column "genus") and save it with \code{\link[=saveRDS]{saveRDS()}} to a location of choice, e.g. \code{"~/my_custom_mo.rds"}, or any remote location.
-\item Set the file location to the \code{AMR_custom_mo} \R option: \code{options(AMR_custom_mo = "~/my_custom_mo.rds")}. This can even be a remote file location, such as an https URL. Since options are not saved between \R sessions, it is best to save this option to the \code{.Rprofile} file so that it will loaded on start-up of \R. To do this, open the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}, add this text and save the file:
+\item Set the file location to the \code{AMR_custom_mo} \R option: \code{options(AMR_custom_mo = "~/my_custom_mo.rds")}. This can even be a remote file location, such as an https URL. Since options are not saved between \R sessions, it is best to save this option to the \code{.Rprofile} file so that it will be loaded on start-up of \R. To do this, open the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}, add this text and save the file:
 
 \if{html}{\out{<div class="sourceCode r">}}\preformatted{# Add custom microorganism codes:
 options(AMR_custom_mo = "~/my_custom_mo.rds")
@@ -34,14 +34,13 @@ options(AMR_custom_mo = "~/my_custom_mo.rds")
 Upon package load, this file will be loaded and run through the \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} function.
 }
 
-\strong{Method 2:} Save the microorganism directly to your \code{.Rprofile} file. An important downside is that this requires to load the \code{AMR} package at every start-up. To use this method:
+\strong{Method 2:} Loading the microorganism directly from your \code{.Rprofile} file. An important downside is that this requires the \code{AMR} package to be installed or else this method will fail. To use this method:
 \enumerate{
 \item Edit the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}.
 \item Add a text like below and save the file:
 
 \if{html}{\out{<div class="sourceCode r">}}\preformatted{ # Add custom antibiotic drug codes:
- library(AMR)
+ AMR::add_custom_microorganisms(
- add_custom_microorganisms(
    data.frame(genus = "Enterobacter",
               species = "asburiae/cloacae")
  )
@@ -52,7 +51,6 @@ Use \code{\link[=clear_custom_microorganisms]{clear_custom_microorganisms()}} to
 }
 \examples{
 \donttest{
-
 # a combination of species is not formal taxonomy, so
 # this will result in only "Enterobacter asburiae":
 mo_name("Enterobacter asburiae/cloacae")
@@ -83,13 +81,15 @@ mo_info("Enterobacter asburiae/cloacae")
 
 # the function tries to be forgiving:
 add_custom_microorganisms(
-  data.frame(GENUS = "ESCHERICHIA / KLEBSIELLA SLASHLINE",
+  data.frame(GENUS = "BACTEROIDES / PARABACTEROIDES SLASHLINE",
              SPECIES = "SPECIES")
 )
-mo_name("ESCHERICHIA / KLEBSIELLA")
+mo_name("BACTEROIDES / PARABACTEROIDES")
-mo_rank("ESCHERICHIA / KLEBSIELLA")
+mo_rank("BACTEROIDES / PARABACTEROIDES")
+
 # taxonomy still works, although a slashline genus was given as input:
-mo_family("Escherichia/Klebsiella")
+mo_family("Bacteroides/Parabacteroides")
+
 
 # for groups and complexes, set them as species or subspecies:
 add_custom_microorganisms(