Title:	Run Any CLI Tool on a 'Conda' Environment
Version:	0.1.2
Description:	Simplifies the execution of command line interface (CLI) tools within isolated and reproducible environments. It enables users to effortlessly manage 'Conda' environments, execute command line tools, handle dependencies, and ensure reproducibility in their data analysis workflows.
License:	MIT + file LICENSE
URL:	https://github.com/luciorq/condathis
BugReports:	https://github.com/luciorq/condathis/issues
Depends:	R (≥ 4.0)
Imports:	cli, fs, jsonlite, processx, rlang, stringr, tibble, tools, utils, withr
Suggests:	curl, dplyr, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-06-02 15:29:52 UTC; luciorq
Author:	Lucio Queiroz [aut, cre, cph], Claudio Zanettini [aut, ctb]
Maintainer:	Lucio Queiroz <luciorqueiroz@gmail.com>
Repository:	CRAN
Date/Publication:	2025-06-02 15:40:08 UTC

condathis: Run Any CLI Tool on a 'Conda' Environment

Description

Simplifies the execution of command line interface (CLI) tools within isolated and reproducible environments. It enables users to effortlessly manage 'Conda' environments, execute command line tools, handle dependencies, and ensure reproducibility in their data analysis workflows.

Author(s)

Maintainer: Lucio Queiroz luciorqueiroz@gmail.com (ORCID) [copyright holder]

Authors:

• Claudio Zanettini claudio.zanettini@gmail.com (ORCID) [contributor]

See Also

Useful links:

• https://github.com/luciorq/condathis

• Report bugs at https://github.com/luciorq/condathis/issues

Create a Conda Environment

Description

Create Conda Environment with specific packages installed to be used by run().

Usage

create_env(
  packages = NULL,
  env_file = NULL,
  env_name = "condathis-env",
  channels = c("bioconda", "conda-forge"),
  method = c("native", "auto"),
  additional_channels = NULL,
  platform = NULL,
  verbose = "silent",
  overwrite = FALSE
)

Arguments

Value

An object of class list representing the result of the command execution. Contains information about the standard output, standard error, and exit status of the command.

Examples

## Not run: 
condathis::with_sandbox_dir({
  # Create a Conda environment and install the CLI `fastqc` in it.
  condathis::create_env(
    packages = "fastqc==0.12.1",
    env_name = "fastqc-env",
    verbose = "output"
  )
  #> ! Environment fastqc-env succesfully created.
})

## End(Not run)

Check If Environment Already exists

Description

This function checks whether a specified Conda environment already exists in the available environments. It returns TRUE if the environment exists and FALSE otherwise.

Usage

env_exists(env_name, verbose = "silent")

Arguments

Value

Boolean. TRUE if the environment exists and FALSE otherwise.

Examples

## Not run: 
condathis::with_sandbox_dir({
  # Create the environment
  condathis::create_env(
    packages = "fastqc",
    env_name = "fastqc-env"
  )

  # Check if the environment exists
  condathis::env_exists("fastqc-env")
  #> [1] TRUE

  # Check for a non-existent environment
  condathis::env_exists("non-existent-env")
  #> [1] FALSE
})

## End(Not run)

Retrieve Path To Environment

Description

Retrieve path to where environment should be created. Note: It retrieves the Path even if the environment is not created yet.

Usage

get_env_dir(env_name = "condathis-env")

Arguments

Value

A character string indicating the path where environments will be created.

Examples

condathis::with_sandbox_dir({
  # Get the default environment directory
  condathis::get_env_dir()
  #> "/path/to/condathis/envs/condathis-env"

  # Get the directory for a specific environment
  condathis::get_env_dir("my-env")
  #> "/path/to/condathis/envs/my-env"
})

Retrieve and Create the condathis Data Directory

Description

Retrieves the installation directory for the condathis package, creating it if it does not exist. This function ensures that the package data directory complies with the freedesktop's XDG Base Directory Specification. The base path can be controlled by the XDG_DATA_HOME environment variable. Additionally, on Windows, ⁠%LOCALAPPDATA%⁠ is also accepted as the base installation directory.

Usage

get_install_dir()

Details

If the directory does not exist, it will be created. On macOS, special handling is applied to avoid spaces in the path, as ⁠micromamba run⁠ fails if there are spaces in the path (e.g., in ⁠~/Library/Application Support/condathis⁠). Therefore, Unix-style paths are used on macOS.

Value

A character string representing the normalized, real path to the condathis data directory.

Examples

condathis::with_sandbox_dir({
  condathis::get_install_dir()
  #> /home/username/.local/share/condathis
})

Retrieve Operating System and CPU Architecture

Description

This function retrieves the operating system (OS) name and the CPU architecture of the current system. The output combines the OS and CPU architecture into a single string in the format "<OS>-<Architecture>".

Usage

get_sys_arch()

Value

A character string indicating the operating system and CPU architecture, e.g., "Darwin-x86_64" or "Linux-aarch64".

Examples

# Retrieve the system architecture
condathis::get_sys_arch()
#> [1] "Darwin-x86_64"

Install Micromamba Binaries in the condathis Controlled Path

Description

Downloads and installs the Micromamba binaries in the path managed by the condathis package. Micromamba is a lightweight implementation of the Conda package manager and provides an efficient way to create and manage conda environments.

Usage

install_micromamba(
  micromamba_version = "2.1.1-0",
  timeout_limit = 3600,
  download_method = "auto",
  force = FALSE,
  verbose = "full"
)

Arguments

Details

This function checks if Micromamba is already installed in the condathis controlled path. If not, it downloads the specified version from the official GitHub releases and installs it. On Windows, it ensures the binary is downloaded correctly by setting the download mode to "wb". If the download fails, appropriate error messages are displayed.

Value

Invisibly returns the path to the installed Micromamba binary.

Examples

## Not run: 
condathis::with_sandbox_dir({
  # Install the default version of Micromamba
  condathis::install_micromamba()

  # Install a specific version of Micromamba
  condathis::install_micromamba(micromamba_version = "2.0.2-2")

  # Force reinstallation of Micromamba
  condathis::install_micromamba(force = TRUE)
})

## End(Not run)

Install Packages in a Existing Conda Environment

Description

Install Packages in a Existing Conda Environment

Usage

install_packages(
  packages,
  env_name = "condathis-env",
  channels = c("bioconda", "conda-forge"),
  additional_channels = NULL,
  verbose = "silent"
)

Arguments

Value

An object of class list representing the result of the command execution. Contains information about the standard output, standard error, and exit status of the command.

Examples

## Not run: 
condathis::with_sandbox_dir({
  condathis::create_env(
    packages = "fastqc",
    env_name = "fastqc-env"
  )
  # Install the package `python` in the `fastqc-env` environment.
  # It is not recommended to install multiple packages in the same environment,
  #  # as it defeats the purpose of isolation provided by separate environments.
  condathis::install_packages(packages = "python", env_name = "fastqc-env")
})

## End(Not run)

List Installed Conda Environments

Description

This function retrieves a list of Conda environments installed in the {condathis} environment directory. The returned value excludes any environments unrelated to {condathis}, such as the base Conda environment itself.

Usage

list_envs(verbose = "silent")

Arguments

Value

A character vector containing the names of installed Conda environments. If the command fails, the function returns the process exit status as a numeric value.

Examples

## Not run: 
condathis::with_sandbox_dir({
  # Create environments
  condathis::create_env(
    packages = "fastqc",
    env_name = "fastqc-env"
  )
  condathis::create_env(
    packages = "python",
    env_name = "python-env"
  )

  # List environments
  condathis::list_envs()
  #> [1] "fastqc-env" "python-env"
})

## End(Not run)

List Packages Installed in a Conda Environment

Description

This function retrieves a list of all packages installed in the specified Conda environment. The result is returned as a tibble with detailed information about each package, including its name, version, and source details.

Usage

list_packages(env_name = "condathis-env", verbose = "silent")

Arguments

Value

A tibble containing all the packages installed in the specified environment, with the following columns:

base_url

The base URL of the package source.

build_number

The build number of the package.

build_string

The build string describing the package build details.

channel

The channel from which the package was installed.

dist_name

The distribution name of the package.

name

The name of the package.

platform

The platform for which the package is built.

version

The version of the package.

Examples

## Not run: 
condathis::with_sandbox_dir({
  # Creates a Conda environment with the CLI `fastqc`
  condathis::create_env(
    packages = "fastqc",
    env_name = "fastqc-env"
  )
  # Lists the packages in env `fastqc-env`
  dat <- condathis::list_packages("fastqc-env")
  dim(dat)
  #> [1] 34  8
})

## End(Not run)

Retrieve Path to the micromamba Executable

Description

This function returns the file path to the micromamba executable managed by the condathis package. The path is determined based on the system's operating system and architecture.

Usage

micromamba_bin_path()

Value

A character string representing the full path to the micromamba executable. The path differs depending on the operating system:

Windows

⁠<install_dir>/micromamba/Library/bin/micromamba.exe⁠

Other OS (e.g., Linux, macOS)

⁠<install_dir>/micromamba/bin/micromamba⁠

Examples

condathis::with_sandbox_dir({
  # Retrieve the path to where micromamba executable is searched
  micromamba_path <- condathis::micromamba_bin_path()
  print(micromamba_path)
})

Parse the output of a Condathis command

Description

This function processes the result of a run() call by parsing the specified output stream (stdout or stderr) into individual, trimmed lines.

Usage

parse_output(res, stream = c("stdout", "stderr"))

Arguments

Value

A character vector where each element is a trimmed line from the specified stream.

Examples

# Example result object from condathis::run()
res <- list(
  stdout = "line1\nline2\nline3\n",
  stderr = "error1\nerror2\n"
)

# Parse the standard output
parse_output(res, stream = "stdout")

# Parse the standard error
parse_output(res, stream = "stderr")

Remove a Conda Environment

Description

Remove a Conda environment previously created by create_env().

Usage

remove_env(env_name = "condathis-env", verbose = "silent")

Arguments

Value

An object of class list representing the result of the command execution. Contains information about the standard output, standard error, and exit status of the command.

Examples

## Not run: 
condathis::with_sandbox_dir({
  condathis::create_env(
    packages = "fastqc",
    env_name = "fastqc-env"
  )
  condathis::remove_env(env_name = "fastqc-env")
})

## End(Not run)

Run Command-Line Tools in a Conda Environment

Description

This function allows the execution of command-line tools within a specified Conda environment. It runs the provided command in the designated Conda environment using the Micromamba binaries managed by the condathis package.

Usage

run(
  cmd,
  ...,
  env_name = "condathis-env",
  method = c("native", "auto"),
  verbose = c("silent", "cmd", "output", "full", FALSE, TRUE),
  error = c("cancel", "continue"),
  stdout = "|",
  stderr = "|",
  stdin = NULL
)

Arguments

Details

The run() function provides a flexible way to execute command-line tools within Conda environments. This is particularly useful for reproducible research and ensuring that specific versions of tools are used.

Value

An object of class list representing the result of the command execution. Contains information about the standard output, standard error, and exit status of the command.

See Also

install_micromamba, create_env

Examples

## Not run: 
condathis::with_sandbox_dir({
  ## Create env
  create_env("samtools", env_name = "samtools-env")

  ## Run a command in a specific Conda environment
  samtools_res <- run("samtools", "view", fs::path_package("condathis", "extdata", "example.bam"),
    env_name = "samtools-env"
  )
  parse_output(samtools_res)[1]
  #> [1] "SOLEXA-1GA-1_6_FC20ET7:6:92:473:531\t0\tchr1\t10156..."
})

## End(Not run)

Run a Binary from a Conda Environment Without Environment Activation

Description

Executes a binary command from a specified Conda environment without activating the environment or using its environment variables. This function temporarily clears Conda and Mamba-related environment variables to prevent interference, ensuring that the command runs in a clean environment. Usually this is not what the user wants as this mode of execution does not load environment variables and scripts defined in the environment activate.d, check run() for the stable function to use.

Usage

run_bin(
  cmd,
  ...,
  env_name = "condathis-env",
  verbose = "silent",
  error = c("cancel", "continue"),
  stdout = "|",
  stderr = "|",
  stdin = NULL
)

Arguments

Value

An object of class list representing the result of the command execution. Contains information about the standard output, standard error, and exit status of the command.

Examples

## Not run: 
condathis::with_sandbox_dir({
  # Example assumes that 'my-env' exists and contains 'python'
  # Run 'python' with a script in 'my-env' environment
  condathis::run_bin(
    "python", "-c", "import sys; print(sys.version)",
    env_name = "my-env",
    verbose = "output"
  )

  # Run 'ls' command with additional arguments
  condathis::run_bin("ls", "-la", env_name = "my-env")
})

## End(Not run)

Execute Code in a Temporary Directory

Description

Runs user-defined code inside a temporary directory, setting up a temporary working environment. This function is intended for use in examples and tests and ensures that no data is written to the user's file space. Environment variables such as HOME, APPDATA, R_USER_DATA_DIR, XDG_DATA_HOME, LOCALAPPDATA, and USERPROFILE are redirected to temporary directories.

Usage

with_sandbox_dir(code, .local_envir = base::parent.frame())

Arguments

Details

This function is not designed for direct use by package users. It is primarily used to create an isolated environment during examples and tests. The temporary directories are created automatically and cleaned up after execution.

Value

Returns NULL invisibly.

Examples

condathis::with_sandbox_dir(print(fs::path_home()))
condathis::with_sandbox_dir(print(tools::R_user_dir("condathis")))