Commits (11)
......@@ -5,3 +5,4 @@
^\.lintr$
^.*\.Rproj$
^\.Rproj\.user$
^\.spelling$
......@@ -23,3 +23,4 @@
/.RData
/.vscode
!/.lintr
inst/doc
variables:
_R_CHECK_CRAN_INCOMING_: "false"
_R_CHECK_CRAN_INCOMING_: "true"
_R_CHECK_FORCE_SUGGESTS_: "true"
CI_IMAGE_NAME: "rocker/verse"
CI_IMAGE_TAG: "3.6.2"
CI_IMAGE_TAG: "4.0.0"
R_PKG_NAME: "DIZutils"
default:
......@@ -15,6 +15,15 @@ stages:
- build
- deploy
Markdown Spellcheck (pipelinecomponents):
stage: build
allow_failure: true
image: pipelinecomponents/markdown-spellcheck:latest
before_script: []
script:
- mdspell --ignore-acronyms "**/*.md" --report
- ls -al
check:
stage: build
allow_failure: true # necessary when having development-packages (in remotes-section of DESCRIPTION)
......
Package: DIZutils
Title: Utilities for DIZ R package development
Version: 0.0.3
Date: 2020-05-07
Title: Utilities for 'DIZ' R Package Development
Version: 0.0.4
Date: 2020-05-27
Authors@R:
c(person(given = "Jonathan M.",
family = "Mang",
......@@ -14,9 +14,11 @@ Authors@R:
comment = c(ORCID = "0000-0003-1866-860X")),
person(given = "MIRACUM - Medical Informatics in Research and Care in University Medicine",
role = "fnd"))
Description: The package provides utilities functions used
in R package development infrastructure inside data integration
centers (DIZ).
Description: Utility functions used for R package development
infrastructure inside the data integration centers ('DIZ') to
standardize and facilitate repetitive tasks such as setting up a
database connection or issuing notification messages and to avoid
redundancy.
License: GPL-3
URL: https://gitlab.miracum.org/miracum/dqa/dizutils
BugReports:
......@@ -25,6 +27,7 @@ Depends:
R (>= 2.10)
Imports:
config,
data.table,
DBI,
RJDBC,
RPostgres,
......@@ -36,10 +39,9 @@ Suggests:
qpdf,
rmarkdown,
testthat
VignetteBuilder:
knitr
biocViews:
Copyright: Universitätsklinikum Erlangen
Encoding: UTF-8
Language: en-US
LazyData: true
RoxygenNote: 7.1.0
......@@ -4,6 +4,10 @@
#'
#' @param pathname A character string. A path name to be cleaned
#' (to have a tailing slash).
#' @return The result is the input but with an tailing slash.
#' @examples
#' clean_path_name("./path/to/file/structure")
#' > "./path/to/file/structure/"
#'
#' @export
#'
......
......@@ -3,6 +3,9 @@
#' run of the app. It will close all open connections to files.
#'
#' @inheritParams feedback
#' @return No return value, called for side effects (see description)
#' @examples
#' close_all_connections("path/to/logfile/dir/")
#'
#' @export
#'
......
......@@ -18,9 +18,21 @@
#' @param db_name A character. Name of the database system.
#' @param db_type A character. Type of the database system. Currently
#' implemented systems are: 'postgres', 'oracle'.
#' @param lib_path A character string. The path to the ojdbc7.jar file.
#' @param lib_path A character string. The path to the ojdbc*.jar file.
#'
#' @inheritParams feedback
#' @return If successful, the result will be the established connection.
#' Otherwise the result will be null.
#' @examples
#' /dontrun{
#' db_con <- DIZutils::db_connection(
#' db_name = "i2b2",
#' db_type = "postgres",
#' headless = true,
#' logfile_dir = "./path/to/logfile/dir/"
#' )}
#'
#' @seealso \code{\link{DBI::dbConnect}}, \code{\link{RPostgres::dbConnect}}
#'
#' @export
#'
......@@ -55,7 +67,10 @@ db_connection <- function(db_name,
password <- Sys.getenv(paste0(db_name, "_PASSWORD"))
} else if (isFALSE(from_env)) {
stopifnot(is.list(settings))
stopifnot(
is.list(settings),
length(settings) >= 4
)
host <- settings$host
port <- settings$port
......@@ -66,7 +81,7 @@ db_connection <- function(db_name,
if (db_type == "ORACLE") {
## create driver
drv <- RJDBC::JDBC("oracle.jdbc.OracleDriver",
classPath = paste0(lib_path, "/ojdbc7.jar"))
classPath = lib_path)
if (isTRUE(from_env)) {
sid <- Sys.getenv(paste0(db_name, "_SID"))
......
......@@ -31,13 +31,24 @@
#' @param findme (Optional, String, default: "")
#' Recommended with length 10.
#' String to find the message in the code.
#' E.g. 10-digit random hex from https://www.browserling.com/tools/random-hex
#' or https://onlinerandomtools.com/generate-random-hexadecimal-numbers
#' E.g. 10-digit random hex from
#' (<https://www.browserling.com/tools/random-hex>) or
#' (<https://onlinerandomtools.com/generate-random-hexadecimal-numbers>)
#' @param logfile_dir (Optional, String, default: "tempdir()")
#' The absolute path to folder where the logfile will be stored.
#' @param headless (Optional, Boolean, default: TRUE)
#' Indicating, if the function is run only in the console (headless = TRUE)
#' or on a GUI frontend (headless = FALSE).
#' @return No return value, called for publishing a message.
#' @examples
#' feedback(
#' print_this = "Error occured when counting source_data",
#' type = "Error",
#' findme = "255bb3695c",
#' logfile_dir = rv$logfile_dir,
#' headless = rv$headless
#' )
#'
#' @export
#'
......@@ -95,6 +106,7 @@ feedback <-
#' Internal use. Use the robust 'feedback' function instead.
#'
#' @inheritParams feedback
#' @return No return value, called for side effects (see description)
#'
feedback_to_console <-
function(print_this,
......@@ -164,6 +176,7 @@ feedback_to_console <-
#' to the gui/user. Everything will also be added to the logfile.
#' Internal use. Use the robust 'feedback' function instead.
#' @inheritParams feedback
#' @return No return value, called for side effects (see description)
#'
feedback_to_ui <-
function(print_this, type, logfile_dir, headless) {
......@@ -204,6 +217,7 @@ feedback_to_ui <-
#' messages to the gui/user via the browser console.
#' Internal use. Use the robust 'feedback' function instead.
#' @inheritParams feedback
#' @return No return value, called for side effects (see description)
#'
feedback_to_logjs <- function(print_this, logfile_dir, headless) {
catch_msg <- paste0("Something went wrong while trying",
......@@ -236,6 +250,7 @@ feedback_to_logjs <- function(print_this, logfile_dir, headless) {
#' to the logfile. Internal use.
#' Use the robust 'feedback' function instead.
#' @inheritParams feedback
#' @return No return value, called for side effects (see description)
#'
feedback_to_logfile <-
function(print_this,
......@@ -275,6 +290,8 @@ feedback_to_logfile <-
#' by hand and call this function several times!
#' Internal use. Use the robust 'feedback' function instead.
#' @inheritParams feedback
#' @return Returns a properly an consistent formatted string containing
#' the parameters handed over to this function.
#'
feedback_get_formatted_string <-
function(print_this, type, findme, prefix, suffix) {
......@@ -299,6 +316,9 @@ feedback_get_formatted_string <-
#' Then a new, empty, logfile "logfile.log" is created.
#'
#' @inheritParams feedback
#' @return No return value, called for side effects (see description)
#' @examples
#' cleanup_old_logfile("path/to/logfile/dir/")
#'
#' @export
#'
......
......@@ -2,6 +2,9 @@
#' @description Converts the first letter of the input string to uppercase
#'
#' @param x A character string. E.g. "hello world" will become "Hello world".
#' @return Returns the input string but with a capital first letter.
#' @examples
#' firstup("first letter will be upper case as return")
#'
#' @export
#'
......
......@@ -9,6 +9,14 @@
#' section in the config.yml-file.
#'
#' @inheritParams feedback
#' @return If successful it returns the config, Null otherwise.
#' @examples
#' config <- get_config(
#' config_file = paste0(utils_path, "/MISC/email.yml"),
#' config_key = "email",
#' logfile_dir = rv$logfile_dir,
#' headless = rv$headless
#' )
#'
#' @export
#'
......
......@@ -7,6 +7,13 @@
#' to get the environment variables with 'SYSTEM_KEY', e.g. 'I2B2_DBNAME')
#'
#' @inheritParams db_connection
#' @return If successful it returns the config, null otherwise.
#' @examples
#' get_config_env(
#' system_name = "i2b2",
#' logfile_dir = "/path/to/logfile/",
#' headless = FALSE
#' )
#'
#' @export
#'
......
#' @title global_env_hack
#' @description Hack variable into global env (bypasses R CMD checks).
#'
#' @param key A character string. The name of the assigned variable
#' @param key A character (!) string. The name of the assigned variable
#' @param val An object. The object that will be assigned to 'key'.
#' @param pos An integer. The position of the environment (default: 1).
#'
#' @seealso \url{http://adv-r.had.co.nz/Environments.html}
#' @return No return value, called for side effects (see description).
#' @examples
#' global_env_hack(
#' key = "utils_path",
#' val = utils_path,
#' pos = 1L
#' )
#'
#' @export
#'
......
......@@ -4,7 +4,11 @@
#'
#' @param x Object 1.
#' @param y Object 2.
#'
#' @return Returns the result of !%in%(x,y)
#' @examples
#' tmp1 <- c("a","b","c")
#' tmp2 <- c("b", "c", "d")
#' tmp1 %notin% tmp2
#' @export
# define %notin% function
# nolint start
......
......@@ -5,6 +5,12 @@
#'
#' @param db_con A DBI database connection.
#' @param sql_statement A character string containing a valid SQL statement.
#' @return Returns the result of the db-query.
#' @examples
#' query_database(
#' db_con = db_con,
#' sql_statement = "SELECT * FROM table_name;"
#' )
#'
#' @export
#'
......
......@@ -7,6 +7,9 @@
#' the file containing the environment variable defintions to be loaded.
#'
#' @seealso \code{Sys.setenv}
#' @return No return value, called for side effects (see description)
#' @examples
#' set_env_vars("./.env")
#'
#' @export
#'
......
......@@ -5,10 +5,83 @@
[![coverage report](https://gitlab.miracum.org/miracum/dqa/dizutils/badges/master/coverage.svg)](https://gitlab.miracum.org/miracum/dqa/dizutils/commits/master)
<!-- badges: end -->
The R package ` DIZutils` provides utilities functions used in DIZ R package development.
The R package `DIZutils` provides utility functions used for R package development infrastructure inside the data integration centers ('DIZ'), to standardize and facilitate repetitive tasks such as setting up a database connection or issuing notification messages and to avoid redundancy.
# Basic functions
# More Infos:
## db_connection
The function `DIZutils::db_connection` provides one simple interface for connecting to various types of databases. It reads neccessary connection settings from the active environment (see below how to use the function `set_env_vars` to set environment variables).
The following database types are currently supported:
* postgres (via the R package [`RPostgres`](https://cran.r-project.org/web/packages/RPostgres/index.html))
* oracle (via the R packages [`RJDBC::JDBC`](https://cran.r-project.org/web/packages/RJDBC/) and [`DBI`](https://cran.r-project.org/web/packages/DBI/))
### postgres
The following environment variables need to be set to the active environment in order to connect with a postgres database:
| Variable | Description |
| ----------------- | ------------------------------------------------------------------------- |
| I2B2_HOST | The hostname/ IP address of your pg instance. |
| I2B2_DBNAME | The name of the pg-database. |
| I2B2_PORT | The port, your pg postgres instance is running on. |
| I2B2_USER | The name of the 'I2B2_USER'. |
| I2B2_PASSWORD | The password of the 'I2B2_USER' of your pg instance. |
To establish the connection, please set those environment variables accordingly and execute the following command. The argument `db_name` is used to detect the corresponding enviroment variables and thus must match with the environment variables' prefix.
```r
db_con <- DIZutils::db_connection(
db_name = "i2b2",
db_type = "postgres"
)
```
### oracle
The following environment variables need to be set to the active environment in order to connect with an oracle database:
| Variable | Description |
| ----------------- | ------------------------------------------------------------------------- |
| MYORACLEDB_HOST | The hostname/ IP address of your oracle instance. |
| MYORACLEDB_DBNAME | The name of the oracle-database. |
| MYORACLEDB_PORT | The port, your oracle postgres instance is running on. |
| MYORACLEDB_USER | The name of the 'MYORACLEDB_USER'. |
| MYORACLEDB_PASSWORD | The password of the 'MYORACLEDB_USER' of your oracle instance. |
To establish the connection, please set those environment variables accordingly and execute the following command. The argument `db_name` is used to detect the corresponding enviroment variables and thus must match with the environment variables' prefix. Furthermore, an ojdbc*.jar-file needs to be provided via the function's `lib_path` argument.
```r
db_con <- DIZutils::db_connection(
db_name = "myoracledb",
db_type = "oracle",
lib_path = "path/to/ojdbc*.jar"
)
```
## set_env_vars
In order to set up a database connection using the function `DIZutils::db_connection`, one needs to provide the required connection settings via environment variables. To facilitate the process of making such environment variables available within the current R session, the function `DIZutils::set_env_vars` works as a wrapper function around the base R method `Sys.setenv`. It takes the file name of a text file with the definitions of the environment variables as input, and sets those environment variables within the current R session.
```r
DIZutils::set_env_vars("path/to/envfile")
```
The design of the `envfile` is based on the [`.env` file for defining environment variables when using docker-compose commands](https://docs.docker.com/compose/env-file/) (currently, neither empty lines nor the using of comments ('#') is being supporte by `DIZutils::set_env_vars`).
To create an `envfile` for connecting with an i2b2 database, the following examplary definitions of environment variables should be written to a simple textfile, e.g. named `envfile`, which can then be passed as argument to `DIZutils::set_env_vars`.
```
I2B2_HOST=123.45.56.8
I2B2_PORT=5432
I2B2_DBNAME=i2b2
I2B2_USER=user
I2B2_PASSWORD=password
```
# More Infos
- about MIRACUM: [https://www.miracum.org/](https://www.miracum.org/)
- about the Medical Informatics Initiative: [https://www.medizininformatik-initiative.de/index.php/de](https://www.medizininformatik-initiative.de/index.php/de)
......@@ -36,15 +36,19 @@ my_desc$set("Copyright", "Universitätsklinikum Erlangen")
my_desc$del("Maintainer")
# Set the version
my_desc$set_version("0.0.3")
my_desc$set_version("0.0.4")
# The title of your package
my_desc$set(Title = "Utilities for DIZ R package development")
my_desc$set(Title = "Utilities for 'DIZ' R Package Development")
# The description of your package
my_desc$set(Description = paste0(
"The package provides utilities functions used in R package development ",
"infrastructure inside data integration centers (DIZ)."
my_desc$set(
Description = paste0(
"Utility functions used for R package development",
" infrastructure inside the data integration centers ('DIZ')",
" to standardize and facilitate repetitive tasks",
" such as setting up a database connection",
" or issuing notification messages and to avoid redundancy."
)
)
......@@ -52,12 +56,15 @@ my_desc$set(Description = paste0(
# The date when description file has been created
my_desc$set("Date" = as.character(Sys.Date()))
# The date package language:
my_desc$set("Language" = "en-US")
# The urls
my_desc$set("URL", "https://gitlab.miracum.org/miracum/dqa/dizutils")
my_desc$set("BugReports", "https://gitlab.miracum.org/miracum/dqa/dizutils/issues")
# Vignette Builder
my_desc$set("VignetteBuilder" = "knitr")
# my_desc$set("VignetteBuilder" = "knitr")
# License
my_desc$set("License", "GPL-3")
......@@ -90,13 +97,13 @@ usethis::use_gpl3_license(name="Universitätsklinikum Erlangen")
usethis::use_package("R", min_version = "2.10", type = "Depends")
## Imports
# usethis::use_package("data.table", type = "Imports")
usethis::use_package("data.table", type = "Imports")
# usethis::use_package("ggplot2", type = "Imports")
# usethis::use_package("ggpubr", type = "Imports")
# usethis::use_package("magrittr", type = "Imports")
# usethis::use_package("polynom", type = "Imports")
usethis::use_package("DBI", type="Imports")
usethis::use_package("RJDBC", type="Imports")
usethis::use_package("RJDBC", type = "Imports")
usethis::use_package("RPostgres", type = "Imports")
usethis::use_package("shiny", type = "Imports")
usethis::use_package("shinyjs", type = "Imports")
......@@ -117,6 +124,7 @@ usethis::use_build_ignore(".gitlab-ci.yml")
usethis::use_build_ignore("data-raw")
usethis::use_build_ignore(".vscode")
usethis::use_build_ignore(".lintr")
usethis::use_build_ignore(".spelling")
# gitignore
usethis::use_git_ignore("/*")
......
......@@ -18,4 +18,5 @@ StripTrailingWhitespace: Yes
BuildType: Package
PackageUseDevtools: Yes
PackageInstallArgs: --no-multiarch --with-keep.source
PackageCheckArgs: NOT_CRAN=F
PackageRoxygenize: rd,collate,namespace,vignette
......@@ -10,10 +10,16 @@ clean_path_name(pathname)
\item{pathname}{A character string. A path name to be cleaned
(to have a tailing slash).}
}
\value{
The result is the input but with an tailing slash.
}
\description{
Function to clean paths to have a tailing slash
}
\examples{
clean_path_name("./path/to/file/structure")
> "./path/to/file/structure/"
\dontrun{
# Both function calls will return "home/test/"
clean_path_name("home/test")
......
......@@ -10,9 +10,16 @@ cleanup_old_logfile(logfile_dir)
\item{logfile_dir}{(Optional, String, default: "tempdir()")
The absolute path to folder where the logfile will be stored.}
}
\value{
No return value, called for side effects (see description)
}
\description{
This function is called once at the beginning of the
runtime of the tool. It checks whether there is an old logfile
and renames it (if existing) to "logfile_20xx-xx-xx-xxxxxx.log".
Then a new, empty, logfile "logfile.log" is created.
}
\examples{
cleanup_old_logfile("path/to/logfile/dir/")
}