• How to install
  • From CRAN
  • From GitHub
  • Locally
• Understanding artma
  • If you are a user
  • If you are a developer
• Using options
  • Creating an options file
  • Loading an options file
  • Adding new options
  • Controlling verbosity
• Using methods
  • Using available methods
  • Defining custom methods

You can install artma directly from CRAN using

install.packages("artma")

To install the package from GitHub, leverage the remotes package and call

GH_REPO_PATH <- "PetrCala/artma"
remotes::install_github(GH_REPO_PATH)

Note that you can pass a number of arguments to the install_github function. This allows you to install from different branches, tags, etc., if you so desire.

You can use the devtools package to install this project locally as a package. To do so, clone the repository onto your machine as described in README-dev.md, navigate to the cloned folder in your R console, and call:

devtools::load_all()

## The folowing should now work
artma::run()
artma::methods.list()
# etc.

The package includes several comprehensive vignettes that we highly recommend reading to understand the core philosophy and functionality. These vignettes provide detailed explanations, examples, and best practices for using the package effectively. You can access them through the standard R documentation system or on our website.

We have a whole README file for developers, so feel free to take a look there.

We leverage the in-built R options namespace to define custom runtime options. However, artma provides a vast number of custom options to fit your needs, so we use a custom-tailored solution to ensure your options are easily accessible and do not interfere with other R runtime options.

All artma related options are stored in hierarchical .yaml files, stored in a temporary options folder. This folder, together with the options files themselves, is created at runtime, such as when invoking artma::options.create().

A user options file holds a hierarchical structure, such as in the following exmample:

# In a custom user options .yaml file
general:
  specific:
    option1: "value1"

If you do not have a user options file at a runtime of an artma runtime method, you will be prompted to create one upon the call to that function, right before that function main body runs.

In case you wish to do so explicitly, you can call artma::options.create().

You can load an options file by providing its name to runtime functions that require it, such as artma::run(). We explicitly advice against loading the the options in a persistent manner, so that different options do not interfere with each other across different sessions or invocations.

For example, providing a name of a custom user options file would look as follows:

artma::run(
  options_file_name="my_custom_options.yaml", # if not provided, you will be prompted to enter the name through the R console
  options_dir="path/to/your/options" # optional, defaults to a temporary folder
)

Upon providing the name of the options file to use, this file is read, and the options loaded into the options() namespace just for the duration of the invocation of the given function. For the duration of that function function, his makes the options available like so:

# Within a function that loads an option file
option_value <- getOption("artma.general.specific.option1") # Stores 'value1'

Notice that each option is automatically prefixed by the name of the package. This is to ensure that the options do not mix with other packages, or R base options.

The package provides configurable verbosity levels through the options file. You can control how much information is displayed during package operations by setting the verbose option in your options file. The verbosity levels are:

The verbosity level is controlled by an integer value, with higher numbers indicating more verbose output. The default level is 3.

To change the verbosity level, simply modify the verbose value in your options file. For example, to set minimal verbosity (only errors), you would set:

verbose: 1

The verbosity level can be set differently for each options file, allowing you to have different levels of detail for different analyses or workflows.

Remember that you can set the option value using the following call:

artma::options.modify(
  option_file_name="your_opt_file.yaml",
  list('verbose' = 1)
)

To check the current verbosity level, run getOption('artma.verbose').

Methods (or runtime methods) is what we recognize as the main executable functionality of the package. In other words, these methods are what the package suppports and recognizes during its runtime.

All of these are defined in inst/artma/methods. The contents of this folder, namely its .R scripts, are imported during runtime, and loaded as recognized methods. Consequently, the contents folder should ideally be used exclusively to store the runtime methods, and nothing else.

To see what methods are available, you can run artma::methods.list(). The output of this function should mirror the contents of the methods folder.

If you wish to use a custom method in the artma package, it should be enough to add it to the methods folder. However, it must adhere to several principles in order to be parsed corretly:

• Each method (module) recognized by artma must have a run function. This serves as the entrypoint for the method. The function must accept the several specific parameters, common across all runtime methods. To see these, open the definition of any of the existing methods and search for non-default parameters. These are the ones you have to use in every case.

If you wish to use any custom parameters for your function, you can define them through options. To understand how to do so, see the Adding new options section.