artma: Automatic Replication Tools for Meta-Analysis

Description

Provides a unified and straightforward interface for performing a variety of meta-analysis methods directly from user data. Users can input a data frame, specify key parameters, and effortlessly execute and compare multiple common meta-analytic models. Designed for immediate usability, the package facilitates transparent, reproducible research without manual implementation of each analytical method. Ideal for researchers aiming for efficiency and reproducibility, it streamlines workflows from data preparation to results interpretation.

Author(s)

Maintainer: Petr Čala 61505008@fsv.cuni.cz

See Also

Useful links:

• https://github.com/PetrCala/artma

• Report bugs at https://github.com/PetrCala/artma/issues

.onLoad hook for package initialization

Description

Called when the package is loaded.

Usage

.onLoad(libname, pkgname)

Arguments

Value

NULL Sets up the package on load

.onUnload hook for package detachment

Description

Called when the package is detached.

Usage

.onUnload(libpath)

Value

NULL Cleans up the package on unload

Note

The box imports no longer work after the package is detached.

Run meta-analysis with artma

Description

Main entry point for the artma package. This function orchestrates the complete meta-analysis workflow: loading options, preparing data, and running specified analytical methods.

Usage

artma(
  data = NULL,
  methods = NULL,
  options = NULL,
  options_dir = NULL,
  open_results = FALSE,
  ...
)

Arguments

Details

The artma() function is the primary way to interact with the artma package. It handles the complete workflow:

1. Options Loading: Loads configuration from an options file (or prompts for creation in interactive mode)

2. Data Preparation: Reads and prepares your data (unless data is provided)

3. Method Execution: Runs the specified analytical methods on your data

4. Results: Returns a structured list of results

Options Files

Options files are YAML configuration files that store all settings for your analysis, including data paths, column mappings, method parameters, and output preferences. They ensure reproducibility and make it easy to manage multiple analysis configurations.

Methods

Methods are analytical functions that perform specific meta-analysis tasks (e.g., funnel plots, Bayesian Model Averaging, effect size calculations). You can run multiple methods in a single call, and they will execute in a predefined order.

Data Parameter

When data is provided, it bypasses the data reading step and uses your data frame directly. The data will still be preprocessed and validated according to your options configuration. This is useful when you already have data loaded in R or want to analyze data programmatically.

Value

[list] A named list containing results from each method, indexed by method name. The structure of each result depends on the specific method.

See Also

• artma::methods.list() - List available methods

• artma::options.create() - Create a new options file

• artma::prepare_data() - Prepare data manually

Examples

## Not run: 
# Interactive mode - will prompt for options and methods
results <- artma()

# Run specific methods with an options file
results <- artma(
  methods = c("funnel_plot", "bma", "fma"),
  options = "my_analysis.yaml"
)

# Run all methods
results <- artma(methods = "all", options = "my_analysis.yaml")

# Use data directly (bypasses file reading)
my_data <- data.frame(
  effect = c(0.5, 0.3, 0.7),
  se = c(0.1, 0.15, 0.12),
  study_id = c("Study A", "Study B", "Study C")
)
results <- artma(data = my_data, methods = "funnel_plot")

# Access results
funnel_result <- results$funnel_plot

## End(Not run)

Get Autonomy Level Description

Description

Get a human-readable description of an autonomy level.

Usage

autonomy.describe(level = NULL)

Arguments

Value

[character] A description of the autonomy level.

Examples

## Not run: 
# Get description of current level
desc <- autonomy.describe()
print(desc)

# Get description of a specific level
desc <- autonomy.describe(5)
print(desc)

## End(Not run)

Get Autonomy Level

Description

Get the current autonomy level. Autonomy controls how much user interaction is required during analysis. Higher levels mean less user interaction and more automatic decision-making.

Usage

autonomy.get()

Value

[integer or NULL] The current autonomy level (1-5), or NULL if not set.

Examples

## Not run: 
# Get current autonomy level
level <- autonomy.get()
print(level)

## End(Not run)

Check if Fully Autonomous

Description

Check if the package is running in fully autonomous mode (level 5).

Usage

autonomy.is_full()

Value

[logical] TRUE if fully autonomous, FALSE otherwise.

Examples

## Not run: 
if (autonomy.is_full()) {
  message("Running in fully autonomous mode")
}

## End(Not run)

Check if Autonomy Level is Set

Description

Check if the autonomy level has been configured.

Usage

autonomy.is_set()

Value

[logical] TRUE if the autonomy level is set, FALSE otherwise.

Examples

## Not run: 
if (!autonomy.is_set()) {
  message("Autonomy level not configured")
}

## End(Not run)

List Available Autonomy Levels

Description

Get information about all available autonomy levels.

Usage

autonomy.levels()

Value

[list] A list of autonomy level definitions.

Examples

## Not run: 
levels <- autonomy.levels()
print(levels)

## End(Not run)

Set Autonomy Level

Description

Set the autonomy level for the current session. This setting controls how much user interaction is required during analysis.

Usage

autonomy.set(level)

Arguments

Value

NULL (invisible)

Examples

## Not run: 
# Set to fully autonomous mode
autonomy.set(5)

# Set to balanced mode
autonomy.set(3)

## End(Not run)

Fix the data config

Description

Regenerate the data config from the dataframe, clearing all overrides.

Usage

config.fix(options_file_name = NULL, options_dir = NULL)

Arguments

Value

[list] The fixed data config.

Get the resolved data config

Description

Returns the fully-resolved data config (base defaults merged with sparse overrides). If var_name is provided, returns only that variable's config entry.

Usage

config.get(var_name = NULL, options_file_name = NULL, options_dir = NULL)

Arguments

Value

[list] The fully-resolved data config (or a single entry).

View sparse config overrides

Description

Returns only the sparse overrides that are actually persisted in the options file – i.e., only non-default field values.

Usage

config.overrides(options_file_name = NULL, options_dir = NULL)

Arguments

Value

[list] The sparse overrides (only non-default values).

Reset variable config to defaults

Description

Removes all overrides for a specific variable (or all variables), resetting them to auto-detected defaults.

Usage

config.reset(var_name = NULL, options_file_name = NULL, options_dir = NULL)

Arguments

Value

[list] The updated fully-resolved data config (invisibly).

Set per-variable config overrides

Description

Sets specific config fields for a variable. Only non-default values are persisted to the options file.

Usage

config.set(var_name, ..., options_file_name = NULL, options_dir = NULL)

Arguments

Value

[list] The updated fully-resolved data config (invisibly).

Preview data

Description

Open a data frame in R's viewer. Data can be supplied as a file path, a data frame, or loaded from an options file (with the same prompt flow as artma() when no options are given).

Usage

data.preview(
  data = NULL,
  options = NULL,
  options_dir = NULL,
  preprocess = TRUE
)

Arguments

Details

Three data sources are supported:

• Path: pass a length-one character path to a data file. With preprocess = FALSE, the file is read without loading options (raw read). With preprocess = TRUE, options are loaded and the full pipeline is applied.

• Data frame: pass a data frame. With preprocess = FALSE, it is viewed as-is. With preprocess = TRUE, options are loaded and preprocess + compute are applied before viewing.

• NULL: data comes from the chosen options file (same "select or create options file" flow as artma() with empty arguments). With preprocess = TRUE (default), the full pipeline (read, preprocess, compute) is run. With preprocess = FALSE, only the data as read from file (with column standardization from options) is shown, without preprocessing or computed columns.

In non-interactive mode, when data is NULL and options is NULL, no viewer is shown (consistent with artma()).

Value

Invisible NULL. Opens the data in the standard R viewer (utils::View()).

See Also

• artma - Run meta-analysis methods

• prepare_data() - Prepare data manually

• options.load - Load options

Examples

## Not run: 
# Preview data from options file (prompts for file if NULL)
data.preview(options = "my_analysis.yaml")

# Preview raw file without loading options
data.preview("/path/to/data.csv", preprocess = FALSE)

# Preview preprocessed data from a path (uses options for standardization)
data.preview("/path/to/data.csv", options = "my_analysis.yaml")

# Preview a data frame as-is
data.preview(mtcars, preprocess = FALSE)

## End(Not run)

Disallow dir.create() Function Calls

Description

This linter flags any usage of the dir.create() function, which is not permitted in the codebase. Using dir.create() can lead to unintended side effects such as creating directories during script execution. Instead, consider alternative approaches for managing directories.

Usage

dir_create_linter()

Get valid box path

Description

Construct a box path that will allow box imports for the current package. This is done by adding the package path to the box path option if it is not already there.

Usage

get_valid_boxpath(libname, pkgname)

Arguments

Allow Guard Clause if Statements Without Braces

Description

Wraps lintr::indentation_linter() to avoid emitting indentation warnings for guard-clause style if statements where a single, indented expression immediately follows the condition on the next line. This keeps the rest of the indentation behavior intact while permitting the brace-less guard clause convention adopted in the codebase.

Usage

indentation_guard_clause_linter(indent = 2L, ...)

Arguments

Invoke methods

Description

Pass a vector of runtime methods to invoke, together with a data frame to invoke these methods on, and invoke them.

Usage

invoke_runtime_methods(methods, df, ...)

Arguments

Value

[list] Results of the invocations, indexed by method names.

Internal example: df <- data.frame(...) invoke_runtime_methods(c("funnel_plot", "bma", "fma"), df)

Check if the package is being loaded via devtools::load_all()

Description

Check if the package is being loaded via devtools::load_all()

Usage

is_devtools_load()

Value

TRUE if loaded via devtools, FALSE otherwise

List methods

Description

Print all runtime methods supported by artma into the console.

Usage

methods.list()

Value

NULL Prints the available methods into the console.

Open a directory in the system file browser

Description

Open a directory in the system file browser

Usage

open_dir_in_browser(dir)

Arguments

Value

The directory path (invisibly).

Copy user options

Description

Provide a name of a user options file to copy from, and a name of a file to copy to, and copy from the 'from' file to the 'to' file.

Usage

options.copy(
  options_file_name_from = NULL,
  options_file_name_to = NULL,
  options_dir = NULL,
  should_overwrite = NULL
)

Arguments

Value

NULL

Create user options

Description

Create a new user options file from an options template.

Usage

options.create(
  options_file_name = NULL,
  options_dir = NULL,
  template_path = NULL,
  user_input = list(),
  should_validate = TRUE,
  should_overwrite = FALSE,
  action_name = "creating"
)

Arguments

Value

NULL

Delete user options

Description

Provide a name of a user options file to delete, and delete that file.

Usage

options.delete(
  options_file_name = NULL,
  options_dir = NULL,
  skip_confirmation = FALSE
)

Arguments

Value

NULL

Fix user options file

Description

Fix a user options file by setting the default values for missing options.

Usage

options.fix(
  options_file_name = NULL,
  options_dir = NULL,
  template_path = NULL,
  force_default_overwrites = TRUE
)

Arguments

Details

The function will attempt to load the user options file and validate it. If any errors are found, the function will attempt to fix them by setting the default values for the missing options.

Value

NULL Fixes the user options file.

Options Help

Description

Prints information for each requested option (or all options if options is NULL).

Usage

options.help(options = NULL, template_path = NULL)

Arguments

Value

Invisibly returns NULL, printing the requested information to the console.

List available user options

Description

Retrieves the list of the existing options files and returns their names as a character vector. By default, this retrieves the names of the files including the yaml suffix, but can be modified to retrieve options verbose names instead.

Usage

options.list(options_dir = NULL, should_return_verbose_names = FALSE)

Arguments

Value

[vector, character] A character vector with the names of the options available.

Load user options

Description

Load user options by their name and return them as a list.

Usage

options.load(
  options_file_name = NULL,
  options_dir = NULL,
  create_options_if_null = TRUE,
  load_with_prefix = TRUE,
  template_path = NULL,
  should_validate = TRUE,
  should_set_to_namespace = FALSE,
  should_add_temp_options = FALSE,
  should_return = TRUE
)

Arguments

Details

In case the options name is not passed, the function will attempt to load the current options configuration. If none is found, it will then attempt to load the default options. If that fails too, an error is raised.

Value

[list|NULL] The loaded options as a list or NULL.

Modify User Options

Description

Modify an existing user options file with new values.

Usage

options.modify(
  options_file_name = NULL,
  options_dir = NULL,
  template_path = NULL,
  user_input = list(),
  should_validate = TRUE
)

Arguments

Value

NULL

Options Open

Description

Open an options file for editing. Must be run interactively. The editor is resolved from: (1) cli.editor option, (2) VISUAL/EDITOR env vars, or (3) system default file handler.

Usage

options.open(options_file_name = NULL, options_dir = NULL)

Arguments

Value

NULL Opens the file for editing

Print default user options directory

Description

Prints the full path to the directory where user options are stored by default

Usage

options.print_default_dir(...)

Arguments

Value

NULL Prints the default directory to console.

Remove user options

Description

Provide a name of a user options file to remove, and remove that file.

Usage

options.remove(
  options_file_name = NULL,
  options_dir = NULL,
  skip_confirmation = FALSE
)

Arguments

Details

This function is an alias for options.delete and behaves identically.

Value

NULL

Validate a user options file against an options template.

Description

This function reads a YAML template and an options file, flattens both structures, and then checks that:

• Every option defined in the template is present in the options file.

• The value for each option is of the correct type.

• (Optionally) It warns about extra options in the file that are not defined in the template.

Usage

options.validate(
  options_file_name = NULL,
  options_dir = NULL,
  should_flag_redundant = FALSE,
  template_path = NULL,
  failure_action = "abort_verbose"
)

Arguments

Details

For each problem found (missing option or type mismatch), an error message is printed.

Value

[list] The validation errors

Print method for box_plot results

Description

Print method for box_plot results

Usage

## S3 method for class 'artma_box_plot'
print(x, ...)

Arguments

Value

x invisibly

Print method for funnel_plot results

Description

Print method for funnel_plot results

Usage

## S3 method for class 'artma_funnel_plot'
print(x, ...)

Arguments

Value

x invisibly

Print method for t_stat_histogram results

Description

Print method for t_stat_histogram results

Usage

## S3 method for class 'artma_t_stat_histogram'
print(x, ...)

Arguments

Value

x invisibly

Read the last export directory from the marker file

Description

Read the last export directory from the marker file

Usage

read_last_export_dir()

Value

The directory path, or NULL if the marker does not exist or the recorded directory no longer exists.

Get Results Directory Path

Description

Returns the resolved path to the output directory where analysis results (tables, graphics) are saved. The path is printed and returned invisibly. When called without arguments, tries to use the most recently exported directory without prompting for an options file.

Usage

results.dir(options = NULL, options_dir = NULL)

Arguments

Value

[character] The resolved output directory path (invisibly).

Examples

## Not run: 
# Get the most recent results directory
results.dir()

# Get results dir for a specific options file
results.dir(options = "my_analysis.yaml")

## End(Not run)

Open Results Directory

Description

Opens the output directory in the system file browser (Finder on macOS, Explorer on Windows, or the default file manager on Linux). When called without arguments, tries to open the most recently exported results directory without prompting for an options file.

Usage

results.open(options = NULL, options_dir = NULL, use_last = TRUE)

Arguments

Value

[character] The resolved output directory path (invisibly).

Examples

## Not run: 
# Open the most recent results (no prompt if a recent export exists)
results.open()

# Force options-based resolution (will prompt if needed)
results.open(use_last = FALSE)

# Open results for a specific options file
results.open(options = "my_analysis.yaml")

## End(Not run)

Runtime Setup

Description

A function user as a wrapper for runtime functions invocation to ensure crucial fucntionality, such as imports, etc., all work as expected.

Usage

runtime_setup(FUN, options_file_name = NULL, options_dir = NULL)

Arguments

Get Visualization Settings

Description

Get the current visualization settings. Returns all settings as a list, or a single setting by name.

Usage

viz.get(option = NULL)

Arguments

Value

A named list of all visualization settings, or a single setting value.

Examples

## Not run: 
# Get all visualization settings
viz.get()

# Get just the current theme
viz.get("theme")

# Get export path
viz.get("export_path")

## End(Not run)

Set Visualization Settings

Description

Set visualization options for the current session. Only provided arguments are changed; others remain unchanged.

Usage

viz.set(
  theme = NULL,
  export_graphics = NULL,
  export_path = NULL,
  graph_scale = NULL
)

Arguments

Value

Previous settings (invisibly), enabling easy restoration.

Examples

## Not run: 
# Change theme
viz.set(theme = "purple")

# Enable export with custom path
viz.set(export_graphics = TRUE, export_path = "./output/plots")

# Save and restore settings
prev <- viz.set(theme = "red")
# ... do work ...
do.call(viz.set, prev)

## End(Not run)

List Available Themes

Description

Get the names of all available visualization themes.

Usage

viz.themes()

Value

[character] Vector of valid theme names.

Examples

## Not run: 
viz.themes()
# [1] "blue" "yellow" "green" "red" "purple"

## End(Not run)