Merge pull request #11 from PetterHopp/main

OKplan v0.6.0 (2023-05-30)

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: OKplan
 Title: Tools to facilitate the Planning of the annual Surveillance Programmes
-Version: 0.5.0
-Date: 2022-12-15
+Version: 0.6.0
+Date: 2023-05-30
 Authors@R: 
   c(person(given = "Petter",
            family = "Hopp",
@@ -28,6 +28,7 @@ Imports:
     rmarkdown,
     stats,
     NVIbatch (>= 0.4.0),
+    NVIcheckmate (>= 0.6.0),
     NVIdb (>= 0.3.0),
     NVIpretty (>= 0.4.0),
     NVIrpackages,
@@ -41,6 +42,7 @@ Suggests:
     NVIpackager
 Remotes: 
     NorwegianVeterinaryInstitute/NVIbatch,
+    NorwegianVeterinaryInstitute/NVIcheckmate,
     NorwegianVeterinaryInstitute/NVIdb,
     NorwegianVeterinaryInstitute/NVIpretty,
     NorwegianVeterinaryInstitute/NVIpackager,

NAMESPACE

@@ -5,6 +5,7 @@ export(append_date_generated_line)
 export(append_sum_line)
 export(check_OK_selection)
 export(check_ok_selection)
+export(get_tested_herds)
 export(make_random)
 export(style_sum_line)
 export(write_ok_selection_list)

NEWS

@@ -1,3 +1,20 @@
+OKplan 0.6.0 - (2023-05-30)
+----------------------------------------
+
+New features:
+
+- Created `get_tested_herds` to find herds tested in last year(s) surveillance programmes.
+
+- `write_ok_selection_list` now accepts a list with column formatting information as input to `column_standards`.
+
+
+Other changes:
+
+- Updated translation table for column names to sampling plans.
+
+- Improved function help by including links and standardising argument description.
+
+
 OKplan 0.5.0 - (2022-12-15)
 ---------------------------
 
@@ -47,7 +64,7 @@ New features:
 
 - style_sum_line styles the row with sum of samples.
 
-- write_ok_selection_list writes the selection list based on selected data from okplan file and uses standardize_columns to  select, format and style columns.
+- write_ok_selection_list writes the selection list based on selected data from okplan file and uses standardize_columns to select, format and style columns.
 
 
 Other changes:

R/adjust_samples_to_budget.R

@@ -18,22 +18,27 @@
 #'     multiplied by of a given number (multiplier). For example, if equal
 #'     number of samples should be taken every month the multiplier can be 12,
 #'     if the samples are pooled five and five, the multiplier can be 5. If the
-#'     argument adjust_by is given the multiplier, the sample number will be
-#'     adjusted by the multiplier unless the difference that should be adjusted
+#'     argument \code{adjust_by} is given the multiplier, the sample number will
+#'     be adjusted by the multiplier unless the difference that should be adjusted
 #'     is less than the multiplier. In that case, the sample number will be
-#'     adjusted by a number less than the adjust_by.
+#'     adjusted by a number less than the \code{adjust_by}.
 #'
-#' @param data \[data.frame\] . Data including a column with the sample number
-#'     that should be adjusted.
-#' @param group \[character\]. Vector with group variables.
-#' @param budget The total budgeted sample number or a column in data with the
-#'     budget number of samples (per group).
-#' @param sample_to_adjust \[character\]. The name of the column with the sample
-#'     number per unit that should be adjusted.
-#' @param adjusted_sample \[character\]. The name of the new column with the
-#'     adjusted sample number per unit.
-#' @param adjust_by \[number\]. The maximum number of samples that a sample can
-#'     be adjust by. Defaults to 1.
+#' @param data [\code{data.frame}]\cr
+#'     Data including a column with the sample number that should be adjusted.
+#' @param group [\code{character}]\cr
+#'     Vector with group variables. Defaults to \code{NULL}.
+#' @param budget [\code{numeric(1)} | \code{character(1)}]\cr
+#'     The total budgeted sample number or a column in data with the budget
+#'     number of samples (per group).
+#' @param sample_to_adjust [\code{character(1)}]\cr
+#'     The name of the column with the sample number per unit that should be
+#'     adjusted.
+#' @param adjusted_sample [\code{character(1)}]\cr
+#'     The name of the new column with the adjusted sample number per unit.
+#'     Defaults to "justert_ant_prover".
+#' @param adjust_by [\code{numeric(1)}]\cr
+#'     The maximum number of samples that a sample can be adjust by. Defaults
+#'     to 1.
 #'
 #' @return A data frame with a new column with an adjusted sample number.
 #'
@@ -75,7 +80,7 @@ adjust_samples_to_budget <- function(data,
                                      budget,
                                      sample_to_adjust,
                                      adjusted_sample = "justert_ant_prover",
-                                     adjust_by) {
+                                     adjust_by = 1) {
 
   # ARGUMENT CHECKING ----
   # Object to store check-results

R/append_date_generated_line.R

@@ -1,13 +1,19 @@
-#' @title Add new last row with generated date
-#' @description Function to add new row with generated date. Before the date the pretext is "Datauttrekket ble gjort"
+#' @title Add new last row with the generated date
+#' @description Function to add new row with the generated date. Before the date
+#'     a pretext can be set.
 #'
-#' @details Two rows are dded to the data frame, the first is empty, the second has the generated date in the first column. The
+#' @details Two rows are added to the data frame, the first is empty, the second
+#'     has the generated date in the first column.
 #'
-#' @param data Data frame with data that should get new row with generated date
-#' @param pretext The explaining text before the date value.
-#' @param date Date for generating the data
+#' @param data [\code{data.frame}]\cr
+#'     The data to which an additional row with the generate date should be added.
+#' @param pretext [\code{character}]\cr
+#'     The explaining text before the date value. Defaults to "Datauttrekket ble gjort".
+#' @param date [\code{character}]\cr
+#'     Date for generating the data. Defaults to
+#'     \ifelse{html}{\code{\link[base]{Sys.Date}}}{\code{base::Sys.Date}}.
 #'
-#' @return A data frame with two more rows, one empty and one with generated data in the first column.
+#' @return \code{data.frame} with two additional rows, one empty and one with the generated date in the first column.
 #'
 #' @author Petter Hopp Petter.Hopp@@vetinst.no
 #' @export
@@ -17,16 +23,23 @@
 #' gris_virus_slaktegris_utvalg <- append_date_generated_line(gris_virus_slaktegris_utvalg)
 #' }
 #'
-append_date_generated_line <- function(data, pretext = "Datauttrekket er gjort", date = format(Sys.Date(), "%d/%m/%Y")) {
+append_date_generated_line <- function(data,
+                                       pretext = "Datauttrekket er gjort",
+                                       date = format(Sys.Date(), "%d/%m/%Y")) {
 
-  # Argument checking
+  # ARGUMENT CHECKING ----
+  # Object to store check-results
   checks <- checkmate::makeAssertCollection()
+  # Perform assertions
   checkmate::assert_data_frame(data, add = checks)
   checkmate::assert_character(pretext, add = checks)
   checkmate::assert_character(date, add = checks)
+  # Report errors
   checkmate::reportAssertions(checks)
 
-  # Transforms to data frame as this is more flexible than tibble, i.e. accepts adding character to numeric variable
+  # APPEND LINE WITH GENERATED DATE ----
+  # Transforms to data frame as this is more flexible than tibble, i.e. accepts
+  #     adding character to numeric variable
   data <- as.data.frame(data)
 
   # Includes two empty rows at end of data frame

R/append_sum_line.R

@@ -1,16 +1,24 @@
 #' @title Append row with column sums
-#' @description Appends a new row with column sums for selected columns. A pretext can be placed on the row.
+#' @description Appends a new row with column sums for selected columns. A
+#'     pretext can be placed on the row.
 #'
-#' @details One row is appended to the data frame. The sum is calculated with na.rm = TRUE.
+#' @details One row is appended to the data frame. The sum is calculated with
+#'     \code{na.rm = TRUE}.
 #'
-#'     If a tibble, it is transformed to a data frame to avoid errors if the pretext is to be placed in a numeric variable.
+#'     If a tibble, it is transformed to a data frame to avoid errors if the
+#'     pretext is to be placed in a numeric variable.
 #'
-#' @param data Data frame to which a row should be appended.
-#' @param column Character vector. The column names of columns to sum.
-#' @param pretext The explaining text before the sum, defaults to "Sum".
-#' @param position The position for the pretext, on of c("first", left", "none"). defaults to left.
+#' @param data [\code{data.frame}]\cr
+#'     Data to which a row should be appended.
+#' @param column  [\code{character}]\cr
+#'     The column names of columns to sum.
+#' @param pretext  [\code{character(1)}]\cr
+#'     The explaining text before the sum. Defaults to "Sum".
+#' @param position  [\code{character(1)}]\cr
+#'     The position for the pretext, one of c("first", left", "none"). Defaults
+#'     to "left".
 #'
-#' @return A data frame with an appended row with sums.
+#' @return \code{data.frame} with an appended row with sums.
 #'
 #' @author Petter Hopp Petter.Hopp@@vetinst.no
 #' @export
@@ -28,7 +36,6 @@ append_sum_line <- function(data, column, pretext = "Sum", position = "left") {
   # ARGUMENT CHECKING ----
   # Object to store check-results
   checks <- checkmate::makeAssertCollection()
-
   # Perform assertions
   # data
   checkmate::assert_data_frame(data, add = checks)
@@ -37,8 +44,7 @@ append_sum_line <- function(data, column, pretext = "Sum", position = "left") {
   # pretext
   checkmate::assert_character(pretext, add = checks)
   # position
-  checkmate::assert_choice(position, choices = c("first", "left"), add = checks)
-
+  checkmate::assert_choice(position, choices = c("first", "left", "none"), add = checks)
   # Report errors
   checkmate::reportAssertions(checks)
 

R/check_ok_selection.R

@@ -1,7 +1,8 @@
 #' @title Checks the standard output data frame with the OK selection
 #' @description Standard checks by performing descriptive statistics of
 #'     variables in the standard output data frame with OK selection.
-#'     \code{check_OK_selection} is a wrapper for \code{NVIbatch::output_rendered}.
+#'     \code{check_ok_selection} is a wrapper for
+#'     \ifelse{html}{\code{\link[NVIbatch]{output_rendered}}}{\code{NVIbatch::output_rendered}}.
 #'
 #' @details Gives descriptive statistics of the OK selection. This should
 #'     used to check if the number of selected units per category are
@@ -11,35 +12,39 @@
 #'
 #'     The check must be performed on a data frame with standardised
 #'     column names. This is ensured by using column names as defined for
-#'     "okplan" in \code{data(OKplan::OK_column_standards)}.
+#'     "okplan" in \code{\link{OK_column_standards}}.
 #'
-#'     The default behaviour is to display the resulting html-file in the
+#'     The default behavior is to display the resulting html-file in the
 #'     browser. To save the result in a permanent file, use a permanent
-#'     directory as input to \code{output_dir = }. The resulting file
+#'     directory as input to \code{output_dir}. The resulting file
 #'     can also be sent by email by using additional arguments, see
-#'     \code{NVIbatch::output_rendered}.
+#'     \ifelse{html}{\code{\link[NVIbatch]{output_rendered}}}{\code{NVIbatch::output_rendered}}.
 #'
-#'     If checks are missing, are unnecessary or the headings are to
-#'     cryptic, please give input to improve the rmarkdown file
-#'     "check_ok_selection.Rmd".
+#'     If checks are missing, are unnecessary or the headings are too
+#'     cryptic, please contribute to improve the rmarkdown file
+#'     "check_ok_selection.Rmd", see
+#'     \href{../doc/Contribute_to_OKplan.html}{\code{vignette("Contribute_to_OKplan", package = "OKplan")}}.
 #'
-#' @param input The path to the rmarkdown document with the checks.
+#' @param input [\code{character(1)}]\cr
+#'     The path to the rmarkdown document with the checks.
 #'     Defaults to "check_ok_selection.Rmd" in the \code{OKplan}.
-#' @param output_file \[\code{character(1)}\]. The name of the output
-#'     file.
-#' @param output_dir \[\code{character(1)}\]. The directory to save
-#'     the output file. Defaults to \code{NULL}.
-#' @param data \[\code{data.frame}\].  The table with data describing
-#'     the selection for a OK programme.
-#' @param purpose \[\code{character(1)}\]. String with descriptive
-#'     text to be used in file name and heading of the report.
-#' @param plan_aar \[\code{numeric(1)}\]. The year for which the
-#'     selection is planned. Defaults to next year.
-#' @param display \[\code{logical(1)} | \code{character(1)}\]. Set
-#'     "browser" for the default browser or "viewer" for the R studio
+#' @param output_file [\code{character(1)}]\cr
+#'     The name of the output file.
+#' @param output_dir [\code{character(1)}]\cr
+#'     The directory to save the output file. Defaults to \code{NULL}.
+#' @param data [\code{data.frame}]\cr
+#'     The table with data describing the selection for a OK programme.
+#' @param purpose [\code{character(1)}]\cr
+#'     String with descriptive text to be used in file name and heading of the
+#'     report.
+#' @param plan_aar [\code{numeric(1)}]\cr
+#'     The year for which the selection is planned. Defaults to next year.
+#' @param display [\code{logical(1)} | \code{character(1)}]\cr
+#'     Set "browser" for the default browser or "viewer" for the R studio
 #'      viewer. `TRUE` equals "browser". If `FALSE`, don't display
 #'      the results file. Defaults to "browser".
-#' @param \dots Other arguments to be passed to `NVIbatch::output_rendered`.
+#' @param \dots Other arguments to be passed to
+#'     \ifelse{html}{\code{\link[NVIbatch]{output_rendered}}}{\code{NVIbatch::output_rendered}}.
 #'
 #' @return Generates an html-file with the results of the checks to be displayed in the browser.
 #'

R/data.R

@@ -1,8 +1,12 @@
-#' @title Data: Column standards for OK data frames.
+#' @title Data: Column standards for OK sampling plans.
 #'
-#' @description A data frame with the column standards for data frames and Excel sheets produced when planning of the Norwegian surveillance programmes.
-#'    The raw data for the column standards can be edited in the original Excel table. The the code for preparing of the data frame is written in
-#'    ./data-raw/generate_OK_column_standards. The OK_column_standards is used as input for \code{NVIdb::standardize_columns}.
+#' @description A data frame with the column standards for data frames and Excel
+#'    sheets produced when planning of the Norwegian surveillance programmes.
+#'    The raw data for the column standards can be edited in the original Excel
+#'    table. The the code for preparing of the data frame is written in
+#'    "./data-raw/generate_OK_column_standards". The \code{OK_column_standards}
+#'    is used as input for
+#'    \ifelse{html}{\code{\link[NVIdb]{standardize_columns}}}{\code{NVIdb::standardize_columns}}.
 #'
 #' @format A data frame with 14 variables:
 #' \describe{
@@ -23,5 +27,7 @@
 #'   \item{colclasses}{column class usedto import character strings correctly}
 #'   \item{colorder}{column order when saving standard data and reporting}
 #' }
-#' @source "standardization/colnames_translation_table.xlsx" at NVI's internal net.
+#' @source "colnames_translation_table.xlsx" at NVI's internal net.
+#' @examples
+#' standards <- data(OK_column_standards, package = "OKplan")
 "OK_column_standards"