Title:	'Galaxy' API Implementation
Version:	0.1.0
Description:	On 'Galaxy' platforms like 'Galaxy Europe' https://usegalaxy.eu, many tools and workflows can run directly on a high-performance computer. 'GalaxyR' connects R with 'Galaxy' platforms API https://usegalaxy.eu/api/docs and allows credential management, uploading data, invoking workflows or tools, checking their status, and downloading results.
URL:	https://github.com/JulFrey/GalaxyR
BugReports:	https://github.com/JulFrey/GalaxyR/issues
License:	GPL-3
Encoding:	UTF-8
Imports:	httr, jsonlite, methods
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
NeedsCompilation:	no
Packaged:	2026-02-02 10:13:27 UTC; julian
Author:	Julian Frey [aut, cre], Zoe Schindler [ctb]
Maintainer:	Julian Frey <julian.frey@wwd.uni-freiburg.de>
Repository:	CRAN
Date/Publication:	2026-02-04 19:30:14 UTC

Resolve the Galaxy base URL

Description

Internal helper that resolves the Galaxy base URL. If the environment variable GALAXY_URL is set, it takes precedence over the value supplied via the galaxy_url argument.

Usage

.resolve_galaxy_url(galaxy_url)

Arguments

Value

Character. The resolved Galaxy base URL.

Trim trailing characters

Description

Internal helper to remove trailing characters (defaults to "/") from a string. Not exported.

Usage

.rtrim(x, char = "/")

Arguments

Value

Character string with trailing characters removed.

Galaxy session object

Description

An S4 class used to carry state across a pipe‑based workflow against a Galaxy instance.

Slots

history_name

Default name to give to a new history.

history_id

Encoded ID of the history on the server.

input_dataset_id

Encoded ID of the last uploaded input dataset.

inputs

A list of tool/workflow inputs to be applied on the next call.

invocation_id

Encoded ID of the last workflow invocation.

output_dataset_ids

Character vector of encoded output dataset IDs.

state

One of "new", "pending", "success" or "error".

galaxy_url

Base URL of the Galaxy instance.

Create a Galaxy session object

Description

Constructor for a Galaxy S4 object used for pipe‑based workflows. The returned object carries identifiers such as history_id, input_dataset_id and invocation_id through subsequent calls.

Usage

galaxy(history_name = "R API request", galaxy_url = "https://usegalaxy.eu")

Arguments

Value

A Galaxy object in state "new".

Delete a Galaxy dataset by ID

Description

Delete a dataset (HDA) from a Galaxy instance using the Galaxy API.

Usage

galaxy_delete_dataset(
  dataset_id,
  purge = TRUE,
  verbose = FALSE,
  galaxy_url = "https://usegalaxy.eu"
)

Arguments

Details

This function performs an HTTP DELETE against the Galaxy /api/datasets/id endpoint. By default it requests a purge (permanent removal) by adding ?purge=true. The Galaxy API key is read from the environment variable GALAXY_API_KEY.

• Make sure Sys.getenv("GALAXY_API_KEY") is set to a valid API key..

• Use caution when running with purge = TRUE as this permanently removes data.

Value

A named list with elements:

success

Logical. TRUE for 2xx responses, otherwise FALSE.

status

Integer. HTTP status code returned by the API.

content

Character. The raw response body (text).

Examples

input_file <- tempfile(fileext = ".txt")
test_text <- "This is an example \nfile."
writeLines(test_text,input_file)
history_id <- galaxy_initialize("test upload")
dataset_id <- galaxy_upload_https(input_file, history_id)

galaxy_delete_dataset(dataset_id)

Delete multiple Galaxy datasets by ID

Description

Convenience wrapper that deletes a vector of dataset IDs using galaxy_delete_dataset. Requests are paced with a small sleep between calls to avoid overwhelming the server.

Usage

galaxy_delete_datasets(
  output_ids,
  purge = TRUE,
  sleep = 0.2,
  galaxy_url = "https://usegalaxy.eu"
)

Arguments

Value

A named list where each element is the return value from galaxy_delete_dataset for the corresponding dataset ID.

Examples

input_file <- tempfile(fileext = ".txt")
input_file2 <- tempfile(fileext = ".txt")
test_text <- "This is an example \nfile."
writeLines(test_text,input_file)
writeLines(test_text,input_file2)
history_id <- galaxy_initialize("test upload")
dataset_id <- galaxy_upload_https(input_file, history_id)
dataset_id2 <- galaxy_upload_https(input_file2, history_id)

galaxy_delete_datasets(list(output_ids = c(dataset_id, dataset_id2)))

Generic for downloading files from a history

Description

galaxy_download_result() is an S4 generic. With x as a character vector of HDA output IDs, all corresponding datasets are downloaded into out_dir using their Galaxy names; duplicate names are disambiguated by appending ⁠_<i>⁠ before the extension. Existing files are not overwritten if overwrite = FALSE, and a warning is issued when a name is adjusted. With x as a Galaxy object its output_dataset_ids and galaxy_url are used; the object is returned invisibly after performing the downloads.

Usage

galaxy_download_result(
  x,
  out_dir = ".",
  galaxy_url = "https://usegalaxy.eu",
  overwrite = FALSE
)

## S4 method for signature 'character'
galaxy_download_result(
  x,
  out_dir = ".",
  galaxy_url = "https://usegalaxy.eu",
  overwrite = FALSE
)

## S4 method for signature 'Galaxy'
galaxy_download_result(x, out_dir = ".", overwrite = FALSE)

Arguments

Value

For the character method, a list of httr responses; for the Galaxy method, the (unchanged) Galaxy object invisibly.

Get information for one or more Galaxy datasets

Description

Retrieves metadata for one or more Galaxy history datasets (HDAs), including name, size, type, state, and deletion status.

Usage

galaxy_get_file_info(file_ids, galaxy_url = "https://usegalaxy.eu")

Arguments

Details

This function queries the /api/datasets/{id} endpoint for each provided dataset ID. If a dataset cannot be retrieved, its fields are returned as NA.

Value

A data.frame with one row per dataset and the columns: id, name, size_bytes, human_size, file_type, state, deleted.

Examples

tmp_dir <- tempdir()
f_name <- "iris.csv"
f_path <- paste(tmp_dir, f_name, sep = "\\")
write.csv(datasets::iris, f_path, row.names = FALSE)

history_id <- galaxy_initialize("IRIS")
file_id <- galaxy_upload_https(f_path, history_id)
galaxy_get_file_info(file_id)

Retrieve detailed metadata for a Galaxy tool

Description

Retrieve detailed metadata for a Galaxy tool

Usage

galaxy_get_tool(
  tool_id,
  galaxy_url = "https://usegalaxy.eu",
  tool_version = NULL
)

Arguments

Value

A list containing the tool metadata as returned by the Galaxy API (inputs, outputs, help text, etc.).

Examples

tool_id <- galaxy_get_tool_id("FastQC")[1]
fastqc_tool <- galaxy_get_tool(tool_id)
fastqc_tool$description

Retrieve Galaxy tool IDs by name

Description

Retrieve Galaxy tool IDs by name

Usage

galaxy_get_tool_id(
  name,
  tools = NULL,
  ignore_case = TRUE,
  galaxy_url = "https://usegalaxy.eu",
  panel_id = NULL
)

Arguments

Value

Character vector of matching tool IDs in decreasing order (usually highest version first). Returns character(0) if no tools match.

Examples

# Fetch the full tool list once, then lookup
tools <- galaxy_list_tools()
galaxy_get_tool_id("FastQC", tools = tools)

# Or let the helper fetch on demand
galaxy_get_tool_id("FastQC")

# Exact, case-sensitive match inside a specific panel
galaxy_get_tool_id("Concatenate datasets",
ignore_case = FALSE, panel_id = "Text Manipulation")

Receive workflow metadata from the API

Description

Receive workflow metadata from the API

Usage

galaxy_get_workflow(workflow_id, galaxy_url = "https://usegalaxy.eu")

Arguments

Value

a structured list with all metadata

Examples

## Not run: 
galaxy_get_workflow("f2db41e1fa331b3e")

## End(Not run)

Retrieve input definitions for a Galaxy workflow

Description

Retrieves and summarizes the input steps required by a Galaxy workflow.

Usage

galaxy_get_workflow_inputs(workflow_id, galaxy_url = "https://usegalaxy.eu")

Arguments

Details

This function queries /api/workflows/{workflow_id} and extracts workflow input steps (data and parameter inputs). The returned step_id values must be used as names in the inputs argument of galaxy_start_workflow.

Value

A data.frame with one row per workflow input and the columns: step_id, name, type, optional, default.

Examples

## Not run: 
galaxy_get_workflow_inputs("f2db41e1fa331b3e")

## End(Not run)

Check whether a Galaxy API key is available

Description

Check whether the environment variable GALAXY_API_KEY is set and non-empty.

Usage

galaxy_has_key()

Value

Logical. TRUE if an API key is available, otherwise FALSE.

Examples

galaxy_has_key() # returns true if api key is set

Galaxy history size Get the disk usage / size of a Galaxy history

Description

The function first tries to read a size/disk_usage field from the history summary endpoint. If that is not present it fetches the history contents and sums dataset sizes (robust to a few different field names used by different Galaxy versions). Results are returned as a data.frame with bytes and a human-readable size.

Usage

galaxy_history_size(
  history_id,
  galaxy_url = "https://usegalaxy.eu",
  include_deleted = FALSE
)

Arguments

Value

data.frame with columns history_id, bytes, human_size

Examples

histories <- galaxy_list_histories()
if(nrow(histories > 0)){
  galaxy_history_size(histories$history_id[1])
} else {
  message("No histories found for current user.")
}

Create a new Galaxy history

Description

galaxy_initialize() is an S4 generic. With no x supplied it creates a new history on the given Galaxy instance and returns its encoded ID. When called with a Galaxy object it uses the object’s history_name and galaxy_url, creates the history, and updates the object with the new history_id and state "pending".

Usage

galaxy_initialize(
  x,
  name = "R API request",
  galaxy_url = "https://usegalaxy.eu"
)

## S4 method for signature 'missing'
galaxy_initialize(name, galaxy_url)

## S4 method for signature 'Galaxy'
galaxy_initialize(x)

Arguments

Details

A valid Galaxy API key is required and must be available via the GALAXY_API_KEY environment variable.

Value

For the default method (x missing), a character scalar history ID. For the Galaxy method, the modified Galaxy object.

Examples

history_id <- galaxy_initialize("My history name")
g <- galaxy(history_name = "My history name")
g <- galaxy_initialize(g)

List Galaxy histories (name and history id)

Description

List Galaxy histories (name and history id)

Usage

galaxy_list_histories(galaxy_url = "https://usegalaxy.eu")

Arguments

Value

data.frame with columns: name, history_id

Examples

histories <- galaxy_list_histories()

List workflow invocations for a given workflow

Description

List workflow invocations for a given workflow

Usage

galaxy_list_invocations(workflow_id, galaxy_url = "https://usegalaxy.eu")

Arguments

Value

data.frame with columns: invocation_id, workflow_id, history_id, state, create_time, update_time

List tools installed on a Galaxy instance

Description

List tools installed on a Galaxy instance

Usage

galaxy_list_tools(
  galaxy_url = "https://usegalaxy.eu",
  in_panel = FALSE,
  panel_id = NULL
)

Arguments

Value

A list corresponding to the parsed JSON returned by Galaxy. If panel_id is provided, a list of tool entries belonging to the requested panel is returned (each entry is the raw tool metadata as provided by Galaxy).

Examples

# All tools (flat list)
tools_list <- galaxy_list_tools()
length(tools_list)

# Panel structure
panel_list <- galaxy_list_tools(in_panel = TRUE)
length(panel_list)

# Tools from a specific panel (match by id or name)
tools_list <- galaxy_list_tools(panel_id = "Get Data")
length(tools_list)

List workflows available to the user

Description

Retrieves workflows accessible to the authenticated user from a Galaxy instance. Optionally includes public (published) workflows if supported by the Galaxy server.

Usage

galaxy_list_workflows(
  include_public = FALSE,
  galaxy_url = "https://usegalaxy.eu"
)

Arguments

Details

By default, only workflows owned by or shared with the current user are returned. When include_public = TRUE, the function will attempt to request published workflows as well. Availability of public workflows depends on the Galaxy instance and version.

Value

A data.frame with one row per workflow and columns including: id, name, published, owner.

Examples

workflows <- galaxy_list_workflows(TRUE)
head(workflows)

Generic for galaxy_poll_tool

Description

Generic for galaxy_poll_tool

Wait for a Galaxy job to complete

S4 method to poll the status of a tool invocation

Usage

galaxy_poll_tool(
  x,
  galaxy_url = "https://usegalaxy.eu",
  poll_interval = 3,
  timeout = 600
)

## S4 method for signature 'character'
galaxy_poll_tool(
  x,
  galaxy_url = "https://usegalaxy.eu",
  poll_interval = 3,
  timeout = 600
)

## S4 method for signature 'Galaxy'
galaxy_poll_tool(x, poll_interval = 3, timeout = 600)

Arguments

Value

For the character method, the final job object; for the Galaxy method, the modified Galaxy object.

Generic for polling workflows

Description

galaxy_poll_workflow() is an S4 generic. With x as a character vector it is treated as a workflow invocation ID; the invocation is polled until it completes and a list of output dataset IDs is returned. With x as a Galaxy object, the invocation_id and galaxy_url are taken from the object, and the object is updated with the resulting output_dataset_ids and state.

Usage

galaxy_poll_workflow(
  x,
  galaxy_url = "https://usegalaxy.eu",
  poll_interval = 30,
  ...
)

## S4 method for signature 'character'
galaxy_poll_workflow(
  x,
  galaxy_url = "https://usegalaxy.eu",
  poll_interval = 30,
  ...
)

## S4 method for signature 'Galaxy'
galaxy_poll_workflow(
  x,
  galaxy_url = "https://usegalaxy.eu",
  poll_interval = 30,
  ...
)

Arguments

Value

For the character method, a list with elements success and output_ids. For the Galaxy method, the modified Galaxy object.

Examples

invocation_id <- "abc123"
galaxy_poll_workflow(invocation_id)

Generic run tool

Description

galaxy_run_tool() is an S4 generic. With x as a character vector it is treated as a history ID; the specified tool is invoked in that history and the job ID is returned. With x as a Galaxy object, the history ID and URL are taken from the object and the object is updated with the job ID.

Usage

galaxy_run_tool(
  x,
  tool_id,
  inputs = NULL,
  dataset_id = NULL,
  galaxy_url = "https://usegalaxy.eu"
)

## S4 method for signature 'character'
galaxy_run_tool(
  x,
  tool_id,
  inputs = NULL,
  dataset_id = NULL,
  galaxy_url = "https://usegalaxy.eu"
)

## S4 method for signature 'Galaxy'
galaxy_run_tool(x, tool_id, inputs = NULL, dataset_id = NULL)

Arguments

Value

For the character method, a job ID; for the Galaxy method, the modified Galaxy object.

Set Galaxy connection parameters for the current R session

Description

Set Galaxy connection parameters for the current R session

Usage

galaxy_set_credentials(
  api_key = NULL,
  username = NULL,
  password = NULL,
  galaxy_url = "https://usegalaxy.eu",
  overwrite = TRUE
)

Arguments

Details

This helper is intended for interactive sessions. It sets the following environment variables using Sys.setenv():

• GALAXY_API_KEY

• GALAXY_URL

• GALAXY_USERNAME

• GALAXY_PASSWORD

Only arguments that are provided (non-NULL) are set.

Value

Invisibly returns a named list of values that were set.

Examples

# This requires valid credentials to your galaxy instance
## Not run: 
galaxy_set_credentials(
  api_key = "your-secret-key",
  username = "your-username",
  password = "your-password",
  galaxy_url = "https://usegalaxy.eu"
)

## End(Not run)

Generic start workflow

Description

galaxy_start_workflow() is an S4 generic. With x as a character vector it is treated as a history ID: the given workflow is invoked in that history and the invocation ID is returned. With x as a Galaxy object, the history ID and URL are taken from the object; the workflow is started and the object is updated with the resulting invocation_id.

Usage

galaxy_start_workflow(
  x,
  workflow_id,
  inputs = NULL,
  dataset_id = NULL,
  galaxy_url = "https://usegalaxy.eu"
)

## S4 method for signature 'character'
galaxy_start_workflow(
  x,
  workflow_id,
  inputs = NULL,
  dataset_id = NULL,
  galaxy_url = "https://usegalaxy.eu"
)

## S4 method for signature 'Galaxy'
galaxy_start_workflow(x, workflow_id, inputs = NULL, dataset_id = NULL)

Arguments

Value

For the character method, a character scalar invocation ID. For the Galaxy method, the modified Galaxy object.

Generic upload ftp

Description

galaxy_upload_ftp() is an S4 generic. With no x supplied it uploads a local file via FTP and registers it in the specified history, returning the encoded dataset ID. When called with a Galaxy object it uses the object's history_id and galaxy_url and updates the object with the new input_dataset_id.

Usage

galaxy_upload_ftp(
  x,
  input_file,
  galaxy_ftp = "ftp.usegalaxy.eu",
  galaxy_url = "https://usegalaxy.eu",
  ...
)

## S4 method for signature 'character'
galaxy_upload_ftp(
  x,
  input_file,
  galaxy_ftp = "ftp.usegalaxy.eu",
  galaxy_url = "https://usegalaxy.eu",
  ...
)

## S4 method for signature 'Galaxy'
galaxy_upload_ftp(
  x,
  input_file,
  galaxy_ftp = "ftp.usegalaxy.eu",
  galaxy_url = "https://usegalaxy.eu",
  ...
)

Arguments

Details

A valid API key (GALAXY_API_KEY) and FTP credentials (GALAXY_USERNAME, GALAXY_PASSWORD) must be available in the environment.

Value

For the default method, a character scalar dataset ID. For the Galaxy method, the modified Galaxy object.

Examples

galaxy_ftp <- "ftp.usegalaxy.eu"
input_file <- tempfile(fileext = ".txt")
writeLines("Example", input_file)
hid <- galaxy_initialize("test upload")
did <- galaxy_upload_ftp(input_file, hid, galaxy_ftp)
g <- galaxy()
g <- galaxy_initialize(g)
g <- galaxy_upload_ftp(g, input_file, galaxy_ftp = galaxy_ftp)

Generic upload file with https

Description

galaxy_upload_https() is an S4 generic. With no x supplied it uploads a local file via HTTPS to the specified history and returns the encoded dataset ID. When called with a Galaxy object it uses the object's history_id and galaxy_url, uploads the file, and updates the object with the new input_dataset_id.

Usage

galaxy_upload_https(
  x,
  input_file,
  wait = FALSE,
  wait_timeout = 600,
  galaxy_url = "https://usegalaxy.eu",
  file_type = "auto",
  dbkey = "?",
  ...
)

## S4 method for signature 'character'
galaxy_upload_https(
  x,
  input_file,
  wait = FALSE,
  wait_timeout = 600,
  galaxy_url = "https://usegalaxy.eu",
  file_type = "auto",
  dbkey = "?",
  ...
)

## S4 method for signature 'Galaxy'
galaxy_upload_https(
  x,
  input_file,
  wait = FALSE,
  wait_timeout = 600,
  galaxy_url = "https://usegalaxy.eu",
  file_type = "auto",
  dbkey = "?",
  ...
)

Arguments

Details

This uses Galaxy's built‑in upload1 tool and performs a multipart form POST. Large files may still require FTP depending on server configuration. A valid API key (GALAXY_API_KEY) must be available in the environment.

Value

For the default method, a character scalar dataset ID. For the Galaxy method, the modified Galaxy object.

Examples

hid <- galaxy_initialize("test upload")
test_file <- tempfile(fileext = ".txt")
writeLines("This is an example test file.", test_file)
file_id <- galaxy_upload_https(hid, test_file)
g <- galaxy()
g <- galaxy_initialize(g)
g <- galaxy_upload_https(g, test_file)