Filtering tools for Galaxy scripting

Description

Filtering tools to reduce a dataset, based on W4M 3-tables format Coded by: M.Petera,

R functions to use in R scripts and wrappers to make things easier

V0: script structure + first function

The W4MLogger Class

Description

This is a simple logger used to make uniform outputs across W4M tools.

See get_logger for example usages.

Arguments

Value

A W4MLogger instance

Author(s)

L.Pavot

See Also

W4MLogger$info, W4MLogger$warning, W4MLogger$error, W4MLogger$debug, W4MLogger$verbose

W4MLogger_.message__

Description

The function W4MLogger$.message__ is the function that gets automatically called when W4MLogger$info, W4MLogger$debug, W4MLogger$warning, W4MLogger$error or W4MLogger$verbose are invoked. This function is not truly internal, so it has to be considered as external, but should not be exported:

This means its has to do type checking of its inputs, and consider parameters as unsafe.

See get_logger for example usages.

Arguments

Value

this logger's instance ( .self )

Log info/warning/error/debug/verbose messages

Description

Call one of the following function when you want a message to be printed or written in a log file:

• your_logger$info("A info message") ;

• your_logger$warning("A warning message") ;

• your_logger$error("A error message") ;

• your_logger$debug("A debug message") ;

• your_logger$verbose.("A verbose. message")

If the corresponding level is activated (with your_logger$set_info(TRUE), your_logger$set_debug(TRUE), etc...), these functions will print the message provided in the terminal and in logs files, if there were some provided at the creation of the logger.

If the corresponding log level is deactivated, these function will not do anything. So, do not hesitate to use them a lot, and activate them when needed.

See get_logger for example usages.

Author(s)

L.Pavot

Adds a file where logs are duplicated

Description

W4MLogger can output logs in file. This function adds a file in which to put logs.

W4MLogger_finalize

Description

The function W4MLogger$finalize is the destructor function of this class. It closes every files that was opened by the logger, or that was provided during execution. It has to be considered internal.

The function W4MLogger$finalize is the destructor function of this class. It closes every files that was opened by the logger, or that was provided during execution. It has to be considered internal.

The function W4MLogger$finalize is the destructor function of this class. It closes every files that was opened by the logger, or that was provided during execution. It has to be considered internal.

The function W4MLogger$finalize is the destructor function of this class. It closes every files that was opened by the logger, or that was provided during execution. It has to be considered internal.

The function W4MLogger$finalize is the destructor function of this class. It closes every files that was opened by the logger, or that was provided during execution. It has to be considered internal.

W4MLogger$set_debug

Description

This method activate or deactivate the logging of debugs messages

Arguments

Value

.self the current W4MLogger instance

W4MLogger$set_error

Description

This method activate or deactivate the logging of errors messages

Arguments

Value

.self the current W4MLogger instance

W4MLogger$set_info

Description

This method activate or deactivate the logging of info messages

Arguments

Value

.self the current W4MLogger instance

Defines in which file logs are duplicated

Description

W4MLogger can output logs in file. This function tells in which file to put logs.

W4MLogger$set_verbose

Description

This method activate or deactivate the logging of verbose messages

Arguments

Value

.self the current W4MLogger instance

W4MLogger$set_warning

Description

This method activate or deactivate the logging of warnings messages

Arguments

Value

.self the current W4MLogger instance

Check Errors

Description

check_err Generic function that stops in error if problems have been encountered, with printing of the corresponding error information.

Usage

check_err(err_stock)

Arguments

Value

NULL (function called for the "stoping" side effects)

Author(s)

M.Petera

check_one_character

Description

Shortcut function to check_param_type_n_length(), to check a unique character string.

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_param_type_n_length

check_parameter_type,check_parameter_length

check_one_complex

Description

Shortcut function to check_param_type_n_length(), to check a unique complex value.

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_param_type_n_length

check_parameter_type,check_parameter_length

check_one_integer

Description

Shortcut function to check_param_type_n_length(), to check a unique integer value.

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_param_type_n_length

check_parameter_type,check_parameter_length

check_one_logical

Description

Shortcut function to check_param_type_n_length(), to check a unique boolean.

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_param_type_n_length

check_parameter_type,check_parameter_length

check_one_numeric

Description

Shortcut function to check_param_type_n_length(), to check a unique numeric value.

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_param_type_n_length

check_parameter_type,check_parameter_length

check_param_type_n_length - to check parameters

Description

Use this function to validate parameters. You're never assured that provided parameters from users are the right type, or length. This may be the case with your own code as well, if you have undetected bugs in your code.

This function helps prevent unpredictable behaviour coming from bad parameters.

It checks the size of vectors, and the type of values. If the parameter is not the good type or length, the program stops with an explanatory error.

Usage

check_param_type_n_length(
  value,
  expected_type,
  expected_size = 1,
  nth = NULL,
  func_name = NULL,
  param_name = NULL,
  or_more = FALSE,
  or_null = FALSE,
  nframe = 1
)

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_parameter_type,check_parameter_length

check_one_integer,check_one_logical,check_one_numeric

check_one_complex,check_one_character

Examples

## here is a simple utility function we will use in this example.
## It is not important
show_last_error <- function(error) {
  dump.frames()
  message(base::attr(last.dump, "error.message"))
}

## The example really starts here
## we have a simple function like this:
custom_message <- function(text) {
  message(sprintf("Message: %s", text))
}

## this function needs to have a character vector as first
## parameter.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(42), error = show_last_error)


## this function needs to have a vector of length 1.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  check_parameter_length(text, 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)


## Or, to be more concise:
custom_message <- function(text) {
  check_param_type_n_length(text, "character", 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)
tryCatch(custom_message(42), error = show_last_error)


## Let's say the text can be 1 or more elements, and can be null.
custom_message <- function(text) {
  check_param_type_n_length(
    text,
    expected_type = "character",
    or_null = TRUE,
    expected_size = 1,
    or_more = TRUE
  )
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(custom_message(c(42, 43)), error = show_last_error)
tryCatch(custom_message(NULL), error = show_last_error)
## no error, because or_null is TRUE
tryCatch(custom_message(character(0)), error = show_last_error)
tryCatch(custom_message(c("uwu", ":3")), error = show_last_error)
## no error, because or_more is TRUE

## With a function that has a lot of parameters, it may be usefull to
## provide the parameter's number. And, because it becomes very long
## to test all those parameters, we will use shortcuts functions
write_msg <- function(
  text,
  font = "owo",
  font_size = 16,
  italic = FALSE,
  bold = FALSE
) {
  check_one_character(text, nth = "1st")
  check_one_character(font, nth = "2nd")
  check_one_numeric(font_size, nth = "3rd")
  check_one_logical(italic, nth = "before last")
  check_one_logical(bold, nth = "last")
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(write_msg(text = 42, "font", 16), error = show_last_error)
tryCatch(write_msg("uwu", font = 1, 16), error = show_last_error)
tryCatch(write_msg("uwu", font_size = "16"), error = show_last_error)
tryCatch(write_msg("uwu", italic = "FALSE"), error = show_last_error)
tryCatch(write_msg("uwu", bold = "FALSE"), error = show_last_error)

check_parameter_length - validate parameter's length

Description

Use this function to validate parameters. You're never assured that provided parameters from users are the right type, or length. This may be the case with your own code as well, if you have undetected bugs in your code.

This function helps prevent unpredictable behaviour coming from bad parameters.

It checks the size of vectors, and the type of values. If the parameter is not the good type or length, the program stops with an explanatory error.

Usage

check_parameter_length(
  value,
  expected_size,
  nth = NULL,
  func_name = NULL,
  param_name = NULL,
  or_more = FALSE,
  nframe = 1
)

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_parameter_type,check_parameter_length

check_one_integer,check_one_logical,check_one_numeric

check_one_complex,check_one_character

Examples

## here is a simple utility function we will use in this example.
## It is not important
show_last_error <- function(error) {
  dump.frames()
  message(base::attr(last.dump, "error.message"))
}

## The example really starts here
## we have a simple function like this:
custom_message <- function(text) {
  message(sprintf("Message: %s", text))
}

## this function needs to have a character vector as first
## parameter.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(42), error = show_last_error)


## this function needs to have a vector of length 1.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  check_parameter_length(text, 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)


## Or, to be more concise:
custom_message <- function(text) {
  check_param_type_n_length(text, "character", 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)
tryCatch(custom_message(42), error = show_last_error)


## Let's say the text can be 1 or more elements, and can be null.
custom_message <- function(text) {
  check_param_type_n_length(
    text,
    expected_type = "character",
    or_null = TRUE,
    expected_size = 1,
    or_more = TRUE
  )
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(custom_message(c(42, 43)), error = show_last_error)
tryCatch(custom_message(NULL), error = show_last_error)
## no error, because or_null is TRUE
tryCatch(custom_message(character(0)), error = show_last_error)
tryCatch(custom_message(c("uwu", ":3")), error = show_last_error)
## no error, because or_more is TRUE

## With a function that has a lot of parameters, it may be usefull to
## provide the parameter's number. And, because it becomes very long
## to test all those parameters, we will use shortcuts functions
write_msg <- function(
  text,
  font = "owo",
  font_size = 16,
  italic = FALSE,
  bold = FALSE
) {
  check_one_character(text, nth = "1st")
  check_one_character(font, nth = "2nd")
  check_one_numeric(font_size, nth = "3rd")
  check_one_logical(italic, nth = "before last")
  check_one_logical(bold, nth = "last")
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(write_msg(text = 42, "font", 16), error = show_last_error)
tryCatch(write_msg("uwu", font = 1, 16), error = show_last_error)
tryCatch(write_msg("uwu", font_size = "16"), error = show_last_error)
tryCatch(write_msg("uwu", italic = "FALSE"), error = show_last_error)
tryCatch(write_msg("uwu", bold = "FALSE"), error = show_last_error)

check_parameter_type - validate parameter's type

Description

Use this function to validate parameters. You're never assured that provided parameters from users are the right type, or length. This may be the case with your own code as well, if you have undetected bugs in your code.

This function helps prevent unpredictable behaviour coming from bad parameters.

It checks the size of vectors, and the type of values. If the parameter is not the good type or length, the program stops with an explanatory error.

Usage

check_parameter_type(
  value,
  expected_type,
  nth = NULL,
  func_name = NULL,
  param_name = NULL,
  or_null = FALSE,
  nframe = 1
)

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

check_parameter_type,check_parameter_length

check_one_integer,check_one_logical,check_one_numeric

check_one_complex,check_one_character

Examples

## here is a simple utility function we will use in this example.
## It is not important
show_last_error <- function(error) {
  dump.frames()
  message(base::attr(last.dump, "error.message"))
}

## The example really starts here
## we have a simple function like this:
custom_message <- function(text) {
  message(sprintf("Message: %s", text))
}

## this function needs to have a character vector as first
## parameter.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(42), error = show_last_error)


## this function needs to have a vector of length 1.
## So, to validate the parameter, we could write:
custom_message <- function(text) {
  check_parameter_type(text, "character")
  check_parameter_length(text, 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)


## Or, to be more concise:
custom_message <- function(text) {
  check_param_type_n_length(text, "character", 1)
  message(base::sprintf("Message: %s", text))
}
tryCatch(custom_message(c("uwu", "owo")), error = show_last_error)
tryCatch(custom_message(42), error = show_last_error)


## Let's say the text can be 1 or more elements, and can be null.
custom_message <- function(text) {
  check_param_type_n_length(
    text,
    expected_type = "character",
    or_null = TRUE,
    expected_size = 1,
    or_more = TRUE
  )
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(custom_message(c(42, 43)), error = show_last_error)
tryCatch(custom_message(NULL), error = show_last_error)
## no error, because or_null is TRUE
tryCatch(custom_message(character(0)), error = show_last_error)
tryCatch(custom_message(c("uwu", ":3")), error = show_last_error)
## no error, because or_more is TRUE

## With a function that has a lot of parameters, it may be usefull to
## provide the parameter's number. And, because it becomes very long
## to test all those parameters, we will use shortcuts functions
write_msg <- function(
  text,
  font = "owo",
  font_size = 16,
  italic = FALSE,
  bold = FALSE
) {
  check_one_character(text, nth = "1st")
  check_one_character(font, nth = "2nd")
  check_one_numeric(font_size, nth = "3rd")
  check_one_logical(italic, nth = "before last")
  check_one_logical(bold, nth = "last")
  message(paste0(base::sprintf("Message: %s", text), collapse = "\n"))
}
tryCatch(write_msg(text = 42, "font", 16), error = show_last_error)
tryCatch(write_msg("uwu", font = 1, 16), error = show_last_error)
tryCatch(write_msg("uwu", font_size = "16"), error = show_last_error)
tryCatch(write_msg("uwu", italic = "FALSE"), error = show_last_error)
tryCatch(write_msg("uwu", bold = "FALSE"), error = show_last_error)

collapse - to paste strings with collapse = ""

Description

collapse does exactly when paste does, but default collapse = ""

Usage

collapse(..., sep = "")

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

collapse(list("a message ", "in multiple", "parts"))

collapse_lines - to paste strings with collapse = "\n"

Description

collapse_lines() does exactly when paste does, but default collapse = "\n"

Usage

collapse_lines(..., sep = "\n")

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

collapse_lines(list("a message ", "in multiple", "parts"))

Convert Parameters

Description

convert_parameters Applies a list of converters to each values on a list. If a value is modified during the conversion (successfull conversion) then, no further convert will be applied to this value, so values are only converted once.

Usage

convert_parameters(args, converters)

Arguments

Value

a named list object with values converted by converters.

Author(s)

L.Pavot

Examples

boolean_converter <- function(x) {
  return(if (x == "TRUE") TRUE else if (x == "FALSE") FALSE else x)
}
parameters <- W4MRUtils::convert_parameters(
  list("x" = "TRUE"),
  c(boolean_converter)
)
print(parameters$`some-parameter`)
## "TRUE" has becomes TRUE.

Convert data frame to numeric.

Description

df_force_numeric Converts integer columns of a data frame into numeric.

Usage

df_force_numeric(df, cols = NULL)

Arguments

Value

The converted data.frame.

Examples

# Convert an integer data frame
df <- data.frame(a = as.integer(c(1, 4)), b = as.integer(c(6, 5)))
df <- W4MRUtils::df_force_numeric(df)

Test type of a data frame.

Description

df_is This function tests if the columns of a data frame are all of the same type.

Usage

df_is(df, type)

Arguments

Value

TRUE or FALSE.

Examples

# Test if a data frame contains only integers
df <- data.frame(a = c(1, 4), b = c(6, 5))
# should return FALSE since in R all integers are converted to
# numeric by default.
W4MRUtils::df_is(df, "integer")
# should return TRUE.
W4MRUtils::df_is(df, "numeric")

Data frame loading from a file.

Description

df_read_table Reads a data frame from a file and possibly convert integer columns to numeric. This function calls the built-in read.table() method and then W4MRUtils::df_force_numeric().

Usage

df_read_table(file, force_numeric = FALSE, ...)

Arguments

Value

The loaded data frame.

Examples

# Load a data frame from a file and convert integer columns
file_path <- system.file(
  "extdata",
  "example_df_read_table.csv",
  package="W4MRUtils"
)
str(W4MRUtils::df_read_table(
  file_path,
  sep = ",",
  force_numeric = TRUE,
  header=TRUE
))

Filtering a data set following the 3-tables format

Description

generic_filter This function allows to filter variables and samples according to factors or numerical values. It needs 3 datasets: the data matrix, the variables' metadata, the samples' metadata. It generates 3 new datasets corresponding to the 3 inputs filtered.

Usage

generic_filter(
  var.data,
  meta.samp.data,
  meta.var.data,
  NUM = FALSE,
  ls.num = NULL,
  FACT = FALSE,
  ls.fact = NULL
)

Arguments

Details

The vectors inside ls.num and ls.fact must follow a dedicated format. For ls.fact, each vector must be constituted of exactly 3 character strings in the following order: (i) the name of a column to filter in one of the metadata table, (ii) the modality inside this column to get rid off, and (iii) "sample" or "variable" depending on the type of metadata you are filtering (i.e. the table that contains the column to filter). For ls.num, each vector must be constituted of 4 to 5 character strings in the following order: (i) "sample" or "variable" depending on the type of metadata you are filtering (i.e. the table that contains the column to filter), (ii) the name of the column to filter in the corresponding metadata table, (iii) the type of numerical filtering to apply, to be chosen from "lower", "upper", "extremity" and "between", (iv) the threshold to be used for filtering (in case the 'iii' argument is "extremity" or "between", it is the lower threshold), and (v) in case the 'iii' argument is "extremity" or "between", the upper threshold.

Value

a list containing the 3 tables, filtered according to the criteria input

Author(s)

M.Petera

get_base_dir - to get... the base directory

Description

get_base_dir

Usage

get_base_dir()

Value

the directory path of the main script. PWD otherwise.

Examples

print(get_base_dir())

Instantiate a Logger

Description

Create a logger of the given name. You can call again get_logger and provide the same name to get the same logger. It will not be recreated unless recreate is TRUE.

Usage

get_logger(name, recreate = FALSE, ...)

Arguments

Details

get_logger

Value

A new W4MLogger instance if it did not exist or if recreate is TRUE. Otherwise, a new W4MLogger instance.

Author(s)

L.Pavot

get_r_env - provides env vars begining with R_*

Description

Returns a list of env vars if the start with R_*.

Usage

get_r_env()

Value

a list of environment variables which begin by R_.

Author(s)

L.Pavot

See Also

run_galaxy_processing

Import two W4M tables

Description

import2 Function to import a metadata table file and its corresponding dataMatrix file. import2 performs checks to ensure the identifiers match between the two tables and stops with an explicit error message in case identifiers do not match.

Usage

import2(pathDM, pathMeta, typeMeta, disable_comm = TRUE)

Arguments

Value

a list containing two elements:

• dataMatrix a data.frame corresponding to the imported dataMatrix table;

• metadata a data.frame corresponding to the imported metadata table

Author(s)

M.Petera

Examples

dm_path <- system.file(
  "extdata",
  "mini_datamatrix.txt",
  package="W4MRUtils"
)
meta_path <- system.file(
  "extdata",
  "mini_variablemetadata.txt",
  package="W4MRUtils"
)

## import considering # is not a comment character
A <- W4MRUtils::import2(dm_path, meta_path, "variable")
print(A$dataMatrix[1:5, 1:5])
print(A$metadata[1:5, ])

## import considering # is a comment character
B <- W4MRUtils::import2(dm_path, meta_path, "variable", disable_comm = FALSE)
print(B$dataMatrix[1:5, 1:5])
print(B$metadata[1:5, ])

Import the three W4M tables

Description

import3 Function to import the three W4M tables from files (dataMatrix, sampleMetadata, variableMetadata) import3 performs checks to ensure the identifiers match between the three tables and stops with an explicit error message in case identifiers do not match.

Usage

import3(pathDM, pathSM, pathVM, disable_comm = TRUE)

Arguments

Value

a list containing three elements:

• dataMatrix a data.frame corresponding to the imported dataMatrix table;

• sampleMetadata a data.frame corresponding to the imported sampleMetadata table;

• variableMetadata a data.frame corresponding to the imported variableMetadata table

Author(s)

M.Petera

Examples

dm_path <- system.file(
  "extdata",
  "mini_datamatrix.txt",
  package="W4MRUtils"
)
vm_path <- system.file(
  "extdata",
  "mini_variablemetadata.txt",
  package="W4MRUtils"
)
sm_path <- system.file(
  "extdata",
  "mini_samplemetadata.txt",
  package="W4MRUtils"
)

## import considering # is not a comment character
A <- W4MRUtils::import3(dm_path, sm_path, vm_path)
print(A$dataMatrix[1:5, 1:5])
print(A$sampleMetadata[1:5, ])
print(A$variableMetadata[1:5, ])

## import considering # is a comment character
B <- W4MRUtils::import3(dm_path, sm_path, vm_path, disable_comm = FALSE)
print(B$dataMatrix[1:5, 1:5])
print(B$sampleMetadata[1:5, ])
print(B$variableMetadata[1:5, ])

in_galaxy_env - check if the script has been run by galaxy

Description

in_galaxy_env returns TRUE if it detects some galaxy-specific environment variables. FALSE otherwise.

Usage

in_galaxy_env()

Value

A logical - whether the script has been run by galaxy or not.

Checking intensities of a data set following the W4M 3-tables format

Description

intens_check This function allows to check the intensities with various statistics, number of missing values and mean fold change. It needs 3 datasets: the data matrix, the variables' metadata, the samples' metadata. It generates 3 new datasets corresponding to the 3 inputs filtered.

Usage

intens_check(
  DM,
  SM,
  VM,
  method,
  chosen.stat,
  class.col,
  test.fold,
  class1,
  fold.frac,
  logarithm,
  graphs.output
)

Arguments

Details

Three methods proposed: (i) 'global' to perform tests for each variable without distinction between samples, (ii) 'one class' to compute test for one class versus all the remaining samples in an 'other' shared class, (iii) 'each class' in case the class columns contains at least two classes and you want to test each of them individually. The function produces a table with the requested indices, plus a PDF output with corresponding graphics.

Value

a dataframe corresponding to the original variableMetadata table completed with additional columns

Author(s)

A.Fernandes, M.Petera

Intensity checking tools for Galaxy scripting

Description

Intensity checking tools to compute indices per variable, based on the W4M 3-tables format Original code of first function by A.Fernandes, updates by M.Petera

R functions to use in R scripts and wrappers to make things easier

V0: script structure + first function (intens_check)

Table match check functions

Description

match2 To check if data_matrix and (variable or sample)metadata match regarding identifiers

Usage

match2(data_matrix, metadata, metadata_type)

Arguments

Value

character vector a list of errors encountered

Author(s)

M.Petera

match3

Description

match3 To check if the 3 standard tables match regarding identifiers

Usage

match3(data_matrix, sample_metadata, variable_metadata)

Arguments

Value

character vector a list of errors encountered

Author(s)

M.Petera

Merging a dataMatrix with a metadata file

Description

metab_merge Function to merge the dataMatrix table with one of its corresponding metadata table (sampleMetadata or variableMetadata)

Usage

metab_merge(DM, meta, metype = "sample")

Arguments

Value

a data.frame corresponding to a combined table with both intensities and metadata

Author(s)

M.Petera

Mini tools for Galaxy scripting

Description

Mini tools for Galaxy scripting Mini tools for Galaxy scripting Coded by: M.Petera,

R functions to use in R scripts and wrappers to make things easier (lightening code, reducing verbose...)

V0: script structure + first functions V1: addition of functions to handle special characters in identifiers V2: addition of a merging function

optparse_character - define a command parameter as string

Description

To be used with optparse_parameters. This function tells the provided parameter is to be parsed as a single string.

Usage

optparse_character(help = "No documentation yet.", short = NULL, default = 0)

Arguments

Value

a list to give to optparse_parameters to build the whole command line parsing tool.

Author(s)

L.Pavot

See Also

optparse_parameters()

Examples

str(optparse_parameters(
  a_parameter = optparse_character(),
  args = list("--a-parameter", "42")
))

optparse_flag - define a command parameter as a trigger

Description

To be used with optparse_parameters. This function tells the provided parameter is a trigger (logical - TRUE/FALSE). When the trigger parameter is not provided in the command line, the value is FALSE. Otherwise, it is TRUE.

Usage

optparse_flag(help = "No documentation yet.", short = NULL, default = FALSE)

Arguments

Value

a list to give to optparse_parameters to build the whole command line parsing tool.

Author(s)

L.Pavot

See Also

optparse_parameters()

Examples

str(optparse_parameters(
  a_parameter = optparse_flag(),
  args = list("--a-parameter")
))

optparse_integer - define a command parameter as an integer

Description

To be used with optparse_parameters. This function tells the provided parameter is to be parsed as an integer.

Usage

optparse_integer(help = "No documentation yet.", short = NULL, default = 0)

Arguments

Value

a list to give to optparse_parameters to build the whole command line parsing tool.

Author(s)

L.Pavot

See Also

optparse_parameters()

Examples

str(optparse_parameters(
  a_parameter = optparse_integer(),
  args = list("--a-parameter", "42")
))

optparse_list - define a command parameter as a list of objects

Description

To be used with optparse_parameters. This function tells the provided parameter is to be parsed as a list of objects. The of parameter tells what type are elements of the list. Each element must be separated by a separator. This separator must be the value given in the sep parameter

Usage

optparse_list(
  help = "No documentation yet.",
  short = NULL,
  default = "",
  of = "character",
  sep = ",",
  truevalues = c("TRUE", "true", "1", "t", "T")
)

Arguments

Value

a list to give to optparse_parameters to build the whole command line parsing tool.

Author(s)

L.Pavot

See Also

optparse_parameters()

Examples

str(optparse_parameters(
  a_parameter = optparse_list(of="numeric"),
  b_parameter = optparse_list(of="integer"),
  c_parameter = optparse_list(of="logical"),
  args = list(
    "--a-parameter", "42.7,72.5",
    "--b-parameter", "42.7,72.5",
    "--c-parameter", "TRUE,FALSE,FALSE,TRUE"
  )
))

optparse_numeric - define a command parameter as an numeric

Description

To be used with optparse_parameters. This function tells the provided parameter is to be parsed as an numeric.

Usage

optparse_numeric(help = "No documentation yet.", short = NULL, default = 0)

Arguments

Value

a list to give to optparse_parameters to build the whole command line parsing tool.

Author(s)

L.Pavot

See Also

optparse_parameters()

Examples

str(optparse_parameters(
  a_parameter = optparse_numeric(),
  args = list("--a-parameter", "42.72")
))

optparse_parameters - parse easily the command line parameters

Description

This function is made to be used with the functions optparse_flag, optparse_numeric, optparse_integer, optparse_character and/or optparse_list

optparse_parameters parses arguments based on its parameters.

You just have to call optparse_parameters with named arguments. Each parameter is the result of either optparse_flag, optparse_numeric, optparse_integer, optparse_character or optparse_list

Usage

optparse_parameters(
  fix_hyphens = TRUE,
  fix_dots = TRUE,
  add_trailing_hyphens = TRUE,
  args = NULL,
  no_optparse = FALSE,
  ...
)

Arguments

Value

A list combining all the elements provided by the optparse_flag, optparse_numeric, optparse_integer, optparse_character and/or optparse_list arguments

Author(s)

L.Pavot

Examples

args <- optparse_parameters(
  a_integer = optparse_integer(),
  a_float = optparse_numeric(),
  a_boolean = optparse_flag(),
  a_character = optparse_character(),
  a_list = optparse_list(of = "numeric"),
  a_char_list = optparse_list(of = "character"),
  a_int_list = optparse_list(of = "integer"),
  args = list(
    "--a-integer",
    "42",
    "--a-float",
    "3.14",
    "--a-boolean",
    "FALSE",
    "--a-character",
    "FALSE",
    "--a-list",
    "1.5,2,3",
    "--a-char-list",
    "1.5,2,3",
    "--a-int-list",
    "1.5,2,3"
  )
)

str(args)

Parse Command arguments

Description

parse_args Replacement for the parseCommandArgs utility from batch. Note that inputs like ⁠script.R some-list c(1, 2, 3)⁠ will result in args$some-list to be the string "c(1, 2, 3)", and not a vector anymore as this ability was permitted by dangerous behaviours from the batch package (the usage of eval which MUST NEVER be used on user's inputs).

To get a list of numeric from users, instead of using the c(1, 2) trick, please, use regular lists parsing:

> args$`some-list`
[1] "1,2"
args$`some-list` <- as.numeric(strsplit(args$`some-list`, ",")[[1]])
> args$`some-list`
[1] 1 2

Usage

parse_args(
  args = NULL,
  convert_booleans = TRUE,
  convert_numerics = TRUE,
  strip_trailing_dash = TRUE,
  replace_dashes = TRUE
)

Arguments

Value

a named list object containing the input parameters in values and the parameters names in names

Author(s)

L.Pavot

Examples

## faking command line parameters:

commandArgs <- function() {
  list(
    "--args",
    "param1", "a value",
    "param2", "42"
  )
}

## extracting command line parameters:
parameters <- W4MRUtils::parse_args(args = commandArgs())
str(parameters)

printf - to format a string and print it

Description

printf calls sprintf of its parameters to build the error message and prints with the given message

Usage

printf(...)

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

file <- "/tmp/test"
printf("Error in file: ", file)

printfp - to paste, format and print a string

Description

printfp calls paste and sprintf of its parameters to build the error message and prints with the given message

Usage

printfp(x, ...)

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

file <- "/tmp/test"
printfp(
  list(
    "Very log error message that needs to be cut on multiple lines,",
    "and paste back together, but there are formatings like",
    "%%s for example, that provides a placeholder for parameters.",
    "Here %%s value is %s."
  ), file
)

printp - to format a string and print it

Description

printp calls sprintf of its parameters to build the error message and prints with the given message

Usage

printp(...)

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

file <- "/tmp/test"
printp("Error in file: ", file)

Reproduce ID

Description

reproduce_id reproduce_id() reinjects original identifiers and original order into final tables

Usage

reproduce_id(data_matrix, metadata, metadata_type, id_match)

Arguments

Value

a named list with two elements: data_matrix: the processed data matrix with its original names and order metadata: the processed metadata, with its original names and order.

Author(s)

M.Petera

Examples

myDM <- data.frame(data = 1:6, a = 2:7, b = 3:8, c = 2:7, d = 3:8, e = 2:7)
myvM <- data.frame(variable = 1:6, x = 4:9, y = 2:7, z = 3:8)

A <- W4MRUtils::stock_id(myDM, myvM, "variable")
myDM <- A$dataMatrix
myvM <- A$Metadata
A <- A$id.match

## processing that may change order or requires specific identifiers format
## ...
datamatrix <- as.data.frame(myDM)
sample_metadata <- as.data.frame(myvM)

B <- W4MRUtils::reproduce_id(datamatrix, sample_metadata, "variable", A)
datamatrix <- B$dataMatrix
sample_metadata <- B$Metadata

run_galaxy_function - automate running functions in galaxy

Description

This function executes the provided function as a galaxy processing This provided function is expected to take two parameters:

• args, a list of command line parameters

• logger, the logger created for the tool

Usage

run_galaxy_function(tool_name, func, ...)

Arguments

Value

NULL (function called to provide checks to the execution of run_galaxy_processing)

Author(s)

L.Pavot

See Also

run_galaxy_processing

run_galaxy_processing - automate running code in galaxy

Description

run_galaxy_processing takes the tool's name, and the code to execute. It detects galaxy-specific environement variable, and show headers and footer if we are in a galaxy env.

It will automatically convert command line parameters using W4MRUtils::parse_args if args is not provided.

Then, it unmangles galaxy parameters (galaxy params / values can be mangled if they contains special characters)

It creates a logger, and provide access to the logger and args variables from withing the code to execute.

Also, before executing the code, if source_files is set to some paths, these paths will be source'd, so the code has access to functions defined in these scripts.

Usage

run_galaxy_processing(
  tool_name,
  code,
  tool_version = "unknown",
  unmangle_parameters = TRUE,
  args = NULL,
  logger = NULL,
  source_files = c(),
  env = NULL,
  do_traceback = FALSE
)

Arguments

Value

NULL (the function only execute the inputed Galaxy-based process in a standardised manner)

Author(s)

L.Pavot

Examples

write_r_file_with_content <- function(content) {
  "
  This function creates a temp R file. It writes the provided
  content in the R file. Then it returns the path of the script.
  "
  path <- tempfile(fileext = ".R")
  file.create(path)
  writeLines(content, con = path)
  return(path)
}
## let's fake a galaxy env
Sys.setenv(GALAXY_SLOTS = 1)
## let's says the tool has been launched with this command line
log_file <- tempfile()
file.create(log_file)
raw_args <- list(
  "--args",
  "--input", "in.csv",
  "--output", "out.csv",
  "--logs", log_file,
  "--one-float", "3.14",
  "--one-integer", "456",
  "--one-logical", "FALSE",
  "--some-floats", "1.5,2.4,3.3",
  "--some-characters", "test,truc,bidule",
  "--debug", "TRUE",
  "--verbose", "FALSE"
)

##
# example 1
##

my_r_script <- write_r_file_with_content('
  my_processing <- function(args, logger) {
    logger$info("The tool is running")
    logger$infof("Input file: %s.", args$input)
    logger$info("The tool ended.")
  }
')

W4MRUtils::run_galaxy_processing(
  "Test tool 1",
  my_processing(args, logger),
  source_file = my_r_script,
  args = W4MRUtils::parse_args(args = raw_args)
)


##
# example 2

## let's say we have a R script with this content:
path <- write_r_file_with_content('
  setup_logger <- function(args, logger) {
    if (!is.null(args$verbose)) {
      logger$set_verbose(args$verbose)
    }
    if (!is.null(args$debug)) {
      logger$set_debug(args$debug)
    }
    if (!is.null(args$logs)) {
      logger$add_out_paths(args$logs)
    }
  }
  stop_logger <- function(logger) {
    logger$close_files()
  }
  processing <- function(args, logger) {
    setup_logger(args, logger)
    logger$info("The tool is working...")
    logger$infof("Input: %s.", args$input)
    logger$info("The tool stoping.")
    stop_logger(logger)
    return(NULL)
  }')


## wrapper script:

args <- W4MRUtils::optparse_parameters(
  input = W4MRUtils::optparse_character(),
  output = W4MRUtils::optparse_character(),
  logs = W4MRUtils::optparse_character(),
  one_float = W4MRUtils::optparse_numeric(),
  one_integer = W4MRUtils::optparse_integer(),
  one_logical = W4MRUtils::optparse_flag(),
  some_floats = W4MRUtils::optparse_list(of = "numeric"),
  some_characters = W4MRUtils::optparse_list(of = "character"),
  debug = W4MRUtils::optparse_flag(),
  verbose = W4MRUtils::optparse_flag(),
  args = raw_args[raw_args != "--args"]
)

W4MRUtils::run_galaxy_processing("A Test tool", args = args, {
  ## processing is from the other R script
  processing(args, logger)
}, source_files = path)

show_galaxy_footer - shows the footer for glaxy tools

Description

This function prints the footer to display in galaxy's tools logs

Usage

show_galaxy_footer(
  tool_name,
  tool_version,
  logger = NULL,
  show_packages = TRUE,
  ellapsed = NULL
)

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

run_galaxy_processing

Examples

show_galaxy_footer("Tool Name", "1.2.0")

show_galaxy_footer(
  tool_name = "Tool Name",
  tool_version = "1.2.0",
  logger = get_logger("Some Tool"),
  show_packages = FALSE,
  ellapsed = "14.5 seconds"
)

show_galaxy_header - shows the header for glaxy tools

Description

This function prints the header to display in galaxy's tools logs

Usage

show_galaxy_header(
  tool_name,
  tool_version,
  args = NULL,
  logger = NULL,
  show_start_time = TRUE,
  show_sys = TRUE,
  show_parameters = TRUE
)

Arguments

Value

NULL

Author(s)

L.Pavot

See Also

run_galaxy_processing

Examples

show_galaxy_header("Tool Name", "1.2.0")
show_galaxy_header(
  tool_name = "Tool Name",
  tool_version = "1.2.0",
  logger = get_logger("Some Tool"),
  show_start_time = FALSE,
  show_sys = FALSE,
  show_parameters = FALSE
)

show_sys - prints env variables related to R

Description

prints env variables related to R

Usage

show_sys()

Value

NULL

Author(s)

L.Pavot

Examples

show_sys()

Shy Lib

Description

shy_lib Function to call packages without printing all the verbose (only getting the essentials, like warning messages for example)

Usage

shy_lib(...)

Arguments

Value

a list of attached packages

Author(s)

M.Petera

Examples

   W4MRUtils::shy_lib("base", "utils")

source_local - source file, from absolute or relative path

Description

source_local Transforms a relative path to an absolute one, and sources the path. This helps source files located relatively to the main script without the need to know from where it was run.

Usage

source_local(..., env = FALSE, do_print = FALSE, keep_source = TRUE)

Arguments

Value

a vector resulting from the sourcing of the files provided.

See Also

source()

Stock ID

Description

stock_id Functions to stock identifiers before applying make.names() and to reinject it into final matrices. stock_id stocks original identifiers and original order needs checked data regarding table match.

Usage

stock_id(data_matrix, metadata, metadata_type)

Arguments

Value

a names list with three elements:

• id.match a data.frame that contains original order of ids, names ;

• dataMatrix the modified data matrix with names sanitized

• Metadata the modified metadata matrix with names sanitized This object can be used in reproduce_id() to replace sanitized names in data matrix by original ones, in the right order.

Author(s)

M.Petera

Examples

myDM <- data.frame(data = 1:6, a = 2:7, b = 3:8, c = 2:7, d = 3:8, e = 2:7)
myvM <- data.frame(variable = 1:6, x = 4:9, y = 2:7, z = 3:8)

A <- W4MRUtils::stock_id(myDM, myvM, "variable")
myDM <- A$dataMatrix
myvM <- A$Metadata
A <- A$id.match

## processing that may change order or requires specific identifiers format
## ...
datamatrix <- as.data.frame(myDM)
sample_metadata <- as.data.frame(myvM)

B <- W4MRUtils::reproduce_id(datamatrix, sample_metadata, "variable", A)
datamatrix <- B$dataMatrix
sample_metadata <- B$Metadata

stopaste - to paste string to a message and stop

Description

stopaste calls paste of its parameters to build the error message and stops with the given message

Usage

stopaste(...)

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

tryCatch({
  file <- "/tmp/test"
  stopaste("Error in file: ", file)
}, error = function(error) {
  print(error)
})

stopaste0 - to paste string to a message and stop

Description

stopaste calls paste0 of its parameters to build the error message and stops with the given message

Usage

stopaste0(...)

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

tryCatch({
  file <- "/tmp/test"
  stopaste0("Error in file: ", file)
}, error = function(error) {
  print(error)
})

stopf - to stop and format message

Description

stopf calls sprintf of its parameters to build the error message and stops with the given message

Usage

stopf(...)

Arguments

Value

NULL

Author(s)

L.Pavot

Examples

tryCatch({
  file <- "/tmp/test"
  stopf("Error in %s file.", file)
}, error = function(error) {
  print(error)
})

unmangle_galaxy_param - revert effects of galaxy manglings.

Description

When running a tool from galaxy, the command line may be altered because some forbidden chars have been translated by galaxy.

This function takes args are invert the galaxy's mangling process.

Usage

unmangle_galaxy_param(args)

Arguments

Value

a named list - with unmangled parameter name and values.

Author(s)

L.Pavot

See Also

run_galaxy_processing, unmangle_galaxy_string

unmangle_galaxy_string - revert effects of galaxy mangling

Description

Revert effect of string mangling from galaxy on the given string.

Usage

unmangle_galaxy_string(string)

Arguments

Value

string - the character vector, fixed.

Author(s)

L.Pavot

See Also

run_galaxy_processing, unmangle_galaxy_param