Package 'Rega'

Description

Mark Required Fields with a Prefix

Usage

add_required_str(p, r, req_str = "* ")

Arguments

Value

A character vector with required fields prefixed and ordered to appear before non-required fields.

Examples

# Mark required fields with a prefix
add_required_str(c("Name", "Id", "Age"), c("Id", "Name"))

Description

Format Aliases from a Table

Usage

aliases_formatter(tab, params)

Arguments

Value

A named list where each name corresponds to a formatted column name, and values are non-NA elements of the respective column.

Examples

tab <- data.frame(Alias = c("name1", "name2", NA), Value = c(1, 2, 3))
aliases_formatter(tab, params = list())

Description

This function dynamically creates an API function based on a given operation definition and API specification. The generated function handles URL construction, parameter validation, request execution, and response parsing.

Usage

api_function_factory(
  op,
  api,
  verbosity = 0,
  bearer_token = NULL,
  token_url = .EGA_TOKEN_URL
)

Arguments

Value

A dynamically generated function that performs the specified API operation. The function accepts arguments corresponding to operation parameters and executes the request using httr2.

Examples

api <- extract_api()
opdefs <- extract_operation_definitions(api)

# Generate an API function for a specific operation
f <- api_function_factory(
    opdefs[["get__files"]], api,
    bearer_token = "my_key"
)

# Call the generated function with parameters (requires credentials)
try(
    result <- f(status = "value1", prefix = "value2")
)

Description

This function converts API-style names with underscores into human-readable labels by replacing underscores with spaces and applying title case.

Usage

api_name_to_label(x)

Arguments

Value

A character vector with API names converted to human-readable labels.

Examples

api_name_to_label(c("first_name", "last_name", "instument_model"))

Description

Format a Column Table

Usage

column_table_formatter(tab, params)

Arguments

Value

A cleaned data frame with column names set from the first row, empty rows removed, and whitespace trimmed from all values.

Examples

df <- data.frame(
    ...1 = c("* Alias", "Sample1", "Sample2"),
    ...2 = c("* Phenotype", "wt", "ko"),
    ...3 = c("Description", NA, NA)
)

column_table_formatter(df, list())

Description

This function creates a named list of functions for interacting with an API, based on its specification and operation definitions.

Usage

create_client(api, ...)

Arguments

Value

A named list of functions, where each function corresponds to an API operation. The function names match the operation IDs from the specification.

Examples

client <- create_client(
    extract_api(),
    bearer_token = "my_key", verbosity = 1
)

# Call an operation using the client (requires credentials)
try(
    result <- client$get__files(status = "value1", prefix = "value2")
)

Description

This function parses the extdata/ega_full_template_v3.xlsx using the bundled parser parameter file in extdata/default_parser_params.yaml to extract information for EGA submission into format that can be easily passed into EGA API endpoints.

Usage

default_parser(metadata_file, param_file = NULL)

Arguments

Value

List of data frames or lists. Submission information parsed from the xlsx file.

Examples

default_parser(
    system.file("extdata/submission_example.xlsx", package = "Rega")
)

Description

Used to validate internal consistency of submission metadata parsed using the default parser. Performs several checks on EGA dataset for submission, ensuring that aliases for studies, experiments, samples, runs, analyses and datasets are are properly linked, as they will be replaced with provisional or accession IDs during submission process. Displays a success message if all validation passed or a summary message if validation failed. In addition it returns a data frame with validation details.

Usage

default_validator(meta, aliases = NULL)

Arguments

Value

Data frame. Validator object that includes all performed validations and their statistics (number of passes, fails and NAs, or whether errors or warnings were encountered during validation)

Examples

minimal_metadata <- list(
    aliases = list(
        studies = "Study1", experiments = "Experiment1",
        datasets = "Dataset1", samples = "Sample1", runs = "Run1",
        analyses = "Analysis1"
    ),
    files = tibble::tibble(
        file = "raw.fastq.gz", ega_file = list("raw.fastq.gz.c4gh")
    ),
    submission = tibble::tibble(title = "Submission"),
    studies = tibble::tibble(
        study = "Study1", title = "Study Title",
        description = "Study Description",
        study_type = "Whole Genome Sequencing"
    ),
    samples = tibble::tibble(
        alias = "Sample1", phenotype = "wild-type",
        biological_sex = "female", subject_id = "ID1"
    ),
    experiments = tibble::tibble(
        study = "Study1", experiment = "Experiment1",
        design_description = "Experiment Design",
        library_selection = "RANDOM", instrument_model_id = 1L,
        library_layout = "SINGLE", library_strategy = "WGS",
        library_source = "GENOMIC"
    ),
    runs = tibble::tibble(
        run = "Run1", experiment = "Experiment1", run_file_type = "srf",
        alias = "Sample1", files = list("raw.fastq.gz.c4gh")
    ),
    datasets = tibble::tibble(
        dataset = "Dataset1", title = "Dataset Title",
        description = "Dataset Description",
        policy_accession_id = "EGAP00000000001",
        dataset_types = list("Whole genome sequencing"),
        runs = list("Run1")
    )
)

default_validator(minimal_metadata)

Description

Deletes a submission identified by its ID using the client and logs the response if a logfile is specified.

Usage

delete_submission(id, client = NULL, logfile = NULL, ...)

Arguments

Value

A list containing the response for the submission deletion.

Examples

mock_client <- list(
    delete__submissions__provisional_id =
        function(id) list(status = "deleted")
)
delete_submission("5678901", mock_client)

Description

Deletes all data associated with a submission ID using the client and logs the responses if a logfile is specified.

Usage

delete_submission_contents(id, client = NULL, logfile = NULL, ...)

Arguments

Value

A list of responses for the deletion of associated datasets, analyses, runs, experiments, samples, and studies.

Examples

mock_client <- list(
    "delete__submissions__provisional_id__datasets" =
        function(id) list(status = "deleted")
)
delete_submission_contents(5678901, client = mock_client)

Description

A named list of functions used to coerce delimited strings into specific data types during metadata processing.

Usage

DELIM_CONVERTERS

Format

A named list:

pubmed_ids

Coerces values to integer.

Examples

df <- list(pub_sheet = data.frame(
    pubmed_ids = c("  123456,  789", NA, "1001  ")
))

process_delimited_column(
    df, "pubmed_ids", separator = ",", converters = DELIM_CONVERTERS
)

Description

ega_oauth implements the EGA OAuth resource owner password flow, as defined by Section 4.3 of RFC 6749. It allows the user to supply their password once, exchanging it for an access token that can be cached locally. Please avoid entering the password directly when calling this function as it will be captured by .Rhistory.

Usage

ega_oauth(
  req,
  username = .get_ega_username(),
  password = .get_ega_password(),
  token_url = .EGA_TOKEN_URL
)

Arguments

Value

returns a modified HTTP request that will use OAuth

Examples

req <- httr2::request("https://example.com/")

# Request OAuth with default credentials
try(oauth_req <- ega_oauth(req))

# Request OAuth with custom credentials
oauth_req <- ega_oauth(req, username = "user", password = "pass")

Description

This function retrieves an API token from the European Genome-Phenome Archive (EGA) using user credentials.

Usage

ega_token(
  username = .get_ega_username(),
  password = .get_ega_password(),
  token_url = .EGA_TOKEN_URL
)

Arguments

Value

A list containing the token details if successful. Actual token value can be retrieved by token$access_token

Examples

try(
    ega_token(username = "my_username", password = "my_password")
)

try(
    ega_token(token_url = "https://www.example.com")
)

Description

This function parses an API specification file (JSON or YAML) and extracts relevant details.

Usage

extract_api(spec_file = NULL, host = NULL)

Arguments

Value

A list containing the parsed API specification, including the host and basePath elements. If the specification file lacks required elements, appropriate warnings or errors are raised.

Examples

# Extract API details from a default YAML specification file
api <- extract_api()

# Extract API details with a custom host
api <- extract_api(host = "https://api.example.com")

Description

This function extracts operation definitions from an API specification, including HTTP methods, paths, parameters, request bodies, and responses.

Usage

extract_operation_definitions(api)

Arguments

Value

A named list of operations, where each name corresponds to an operation ID. If operation Id is not found in the specification, unique one will be created. Each operation contains:

• method: HTTP method (e.g., GET, POST).

• path: Endpoint path.

• parameters: List of operation parameters.

• requestBody: Details of the request body (if any).

• responses: Possible responses for the operation.

• security: Security requirements for the operation.

Examples

# Extract operation definitions from a parsed API specification
opdefs <- extract_operation_definitions(extract_api())
opdefs[["post__submissions"]]

Description

Extracts the specific resource identifier (e.g., "users", "datasets") from the path of an httr2 response object by parsing the segment immediately following ⁠/api/⁠.

Usage

extract_resource_name(resp)

Arguments

Value

A character string containing the resource name.

Examples

resp <- httr2::response(
    method = "GET",
    url = "https://www.example.com/api/files"
)
extract_resource_name(resp)

Description

Query the remote client for requested file prefix, test whether a file is found for every element of file_list and return the server response.

Usage

fetch_files(file_list, client = NULL)

Arguments

Value

Data frame. Parsed response from client API for requested files.

Examples

mock_client <- list(
    get__files = function(prefix = NULL) {
        data.frame(provisional_id = 12345, ega_relative_path = prefix)
      }
)
fetch_files(c("file_a", "file_b"), mock_client)

Description

Format File Table with EGA File Paths

Usage

file_formatter(tab, params)

Arguments

Value

A formatted data frame with cleaned column names, and updated ega_file paths based on file and relative path information.

Examples

params <- list(prefix = "", crypt_ext = "c4gh", prepend_slash = FALSE)

# Dummy data, first row will be moved to column names
tab <- data.frame(
    x1 = c("file", "value1", "value2"),
    x2 = c("ega_inbox_relative_path", NA, "proj1")
)

file_formatter(tab, params)

Description

This function filters out elements from a character vector that match a specified regular expression pattern, removing ID fields.

Usage

filter_id_fields(x, pattern = NULL)

Arguments

Value

A character vector with elements matching the pattern removed.

Examples

# Filter out default ID fields
fields <- c("accession_id", "policy_accession_id", "name", "provisional_id")
filter_id_fields(fields)

# Filter with a custom pattern
filter_id_fields(fields, pattern = "_id")

Description

Submits the finalisation request for a submission identified by either an accession or provisional ID. Validates the release date and sends optional dataset changelogs.

Usage

finalise_submission(
  id,
  release_date,
  dataset_changelogs = data.frame(),
  client = NULL,
  logfile = NULL,
  ...
)

Arguments

Value

The API response object from the finalisation request.

Examples

# Requires credentials
try(
    finalise_submission("123456", "2025-12-31")
)

Description

Use First Row as Column Names for a Data Frame

Usage

first_row_to_colnames(df, to_api = TRUE)

Arguments

Value

A data frame with updated column names and the first row removed.

Examples

df <- data.frame(id = c("A B", "C D_"), value = c("* E F", "GH"))

first_row_to_colnames(df)
first_row_to_colnames(df, to_api = FALSE)

Description

If NA values are present in any of the columns to be nested, they will be removed. If the column is not present it will be added with NA as a single value.

Usage

fold_column(tab, column_prefix, new_name)

Arguments

Value

A data frame with the specified columns nested into a single column.

Examples

tab <- data.frame(id = c(1, 2), name.1 = c("A1", NA), name.2 = c("B1", "B2"))
fold_column(tab, "name", "folded_column")

Description

Formats and processes chromosome-related metadata from an input object by applying chromosome group lookups or splitting chromosome strings from the EGA enums.

Usage

format_chromosomes(metadata)

Arguments

Value

A list of formatted chromosome data extracted or computed from the input metadata.

Examples

# Mock metadata data frame
metadata <- list(
    analyses = data.frame(
        chromosomes = I(list(
            NA,
            list("group1--1--chr1--name1", "group2--3--chr3--name3"),
            "group1--2--chr2--name2"
        )),
        chromosome_groups = c("group1", NA, "group3"),
        stringsAsFactors = FALSE
    ),
    select_input_data = list(
        chromosomes = c("group1--1--chr1--name1", "group1--2--chr2--name2")
    )
)

format_chromosomes(metadata)

Description

Retrieve Chromosome Belonging to a Group

Usage

get_chr_group(group_id, chr_enum, sep = "--")

Arguments

Value

An integer vector of chromosome IDs corresponding to the specified group ID.

Examples

get_chr_group(
    "group1", c("group1--1--chr1--name1", "group2--2--chr2--name2")
)

Description

Searches for entries across specified EGA metadata types that match a given title string. Returns a list of data frames for each type.

Usage

get_entry_by_title(title, type = NULL, client = NULL, logfile = NULL, ...)

Arguments

Value

A named list of data frames containing entries matching the title.

Examples

# Requires credentials
try(
    get_entry_by_title("My Study", type = "studies")
)

Description

This function retrieves the values of a specified enum from an API by invoking the corresponding client function.

Usage

get_enum(client, enum_name, enum_prefix = "get__enums__")

Arguments

Value

The values of the specified enum.

Examples

# Create API client with mock api_key
client <- create_client(extract_api(), token_url = "ABCD")

# Retrieve enum values from the API client (requires credentials to work)
try(
    platform_models <- get_enum(client, enum_name = "platform_models")
)

Description

Retrieve a Formatter Function by Type of Submission Metadata Table

Usage

get_formatter(x, params)

Arguments

Value

The formatter function corresponding to the specified table.

Examples

# Load formatter params
params <- yaml::read_yaml(system.file(
    "extdata/default_parser_params.yaml",
    package = "Rega"
))

# Dummy data, first row will be moved to column names
tab <- data.frame(
    x1 = c("file", "value1", "value2"),
    x2 = c("ega_inbox_relative_path", NA, "proj1")
)

ff <- get_formatter("files", params)
ff_params <- get_formatter_params("files", params)

ff(tab, ff_params)

Description

Retrieve Formatter Parameters by Name

Usage

get_formatter_params(x, params)

Arguments

Value

A list of parameters for the specified formatter.

Examples

# Load formatter params
params <- yaml::read_yaml(system.file(
    "extdata/default_parser_params.yaml",
    package = "Rega"
))

# Dummy data, first row will be moved to column names
tab <- data.frame(
    x1 = c("file", "value1", "value2"),
    x2 = c("ega_inbox_relative_path", NA, "proj1")
)

ff <- get_formatter("files", params)
ff_params <- get_formatter_params("files", params)

ff(tab, ff_params)

Description

Retrieve the Schema for an API Operation

Usage

get_operation_schema(op)

Arguments

Value

The schema for the operation's JSON request body, or NULL if no schema is defined.

Examples

# Get operations from API
opdefs <- extract_operation_definitions(extract_api())

# Retrieve the schema for a specific operation
schema <- get_operation_schema(opdefs[["post__submissions"]])

Description

This function retrieves existing data from an API or submits new data if it does not exist, with optional error handling and retrieval options.

• If no data is present in the database, supplied data will be inserted.

• If there is data already present in the database and the number of records don't match, error will raised.

• If the number of records match and retrieve is set to TRUE data will be retrieved from database and nothing will be inserted. If retrieve is set to FALSE, error will be raised.

Usage

get_or_post(
  submission_id,
  data,
  client,
  endpoint,
  retrieve = FALSE,
  id_type = "provisional"
)

Arguments

Value

A data frame containing the response from the API.

Examples

# Create mock client for API endpoint
mock_client <- list(
    get__submissions__provisional_id__endpoint = function(id) {
        message("Mock GET request")
        # Simulate an empty response (no existing data)
        return(NULL)
    },
    post__submissions__provisional_id__endpoint = function(id, body) {
        message("Mock POST request")
        message(body) # Simulate returning submitted data
    }
)

# Create mock data to test the function
test_data <- data.frame(id = 1:3, value = c("A", "B", "C"))

# Test the function with mock data and client
result <- get_or_post(
    submission_id = 12345,
    data = test_data,
    client = mock_client,
    endpoint = "endpoint",
    retrieve = FALSE
)

Description

This function extracts property names from a schema, optionally filters out ID fields, and applies formatting such as marking required fields and prettifying the labels.

Usage

get_properties(schema, filter_ids = TRUE)

Arguments

Value

A character vector of formatted property names and indications of required fields.

Examples

schemas <- get_schemas(extract_api())

# Extract and format properties from a schema
get_properties(schemas[[5]])

# Extract properties without filtering ID fields
get_properties(schemas[[6]], filter_ids = FALSE)

Description

This function extracts and returns schemas related to requests from the API specification.

Usage

get_schemas(api)

Arguments

Value

A list of schemas whose names contain "Request", filtered from the schemas element of the API specification.

Examples

# Extract request schemas from an API specification
request_schemas <- get_schemas(extract_api())

Description

Count how many sentences are in a character string, based on terminal punctuation marks ., !, or ? following an alphanumeric character. If there is no punctuation character at the end, it will still count it as another sentence.

Usage

get_sentence_number(text)

Arguments

Value

An integer scalar giving the number of sentences in text.

Examples

get_sentence_number("First sentence. Second sentence? Third!")

Description

Retrieves data associated with a submission ID using the client and logs the responses if a logfile is specified.

Usage

get_submission(id, client = NULL, logfile = NULL, ...)

Arguments

Value

A list of responses including submission data and associated datasets, analyses, runs, experiments, samples, and studies.

Examples

mock_client <- list(
    "get__submissions__accession_id" = function(id) list(data = id),
    "get__submissions__accession_id__datasets" =
        function(id) list(datasets = id)
)
get_submission("EGAB12345678901", mock_client)

Description

Compute the number of words in each element of a character vector using non-word separators.

Usage

get_word_number(text)

Arguments

Value

An integer vector giving the number of words per element of text.

Examples

get_word_number(c("one two", "three four five"))

Description

Determines whether a specified sheet is present and contains at least one non-NA value in the provided metadata.

Usage

has_linked_sheets(metadata, colname)

Arguments

Value

A logical vector indicating whether each element of metadata contains the specified column with at least one non-NA value.

Examples

metadata <- list(
    sheet1 = list(sheet_name = c(1, NA)),
    sheet2 = list(other_name = NA)
)
has_linked_sheets(metadata, "sheet_name")

Description

Verifies whether the input string matches the format of a valid accession identifier based on a specified schema.

Usage

is_accession(x, schema = NULL)

Arguments

Value

A logical vector indicating which values are accession IDs.

Examples

is_accession("EGAB00000000001", "submission") # TRUE
is_accession("EGA12345678901", "sample") # FALSE

Description

Determine if input values match the format of provisional IDs, either as whole-number numerics or as character strings of at least two digits without leading zeros.

Usage

is_provisional(x)

Arguments

Value

A logical vector indicating which values are provisional IDs.

Examples

is_provisional(c(10, 11, 3.5, 9))

Description

Checks whether a given HTTP method is valid based on a predefined list of accepted methods (matches on lowercase).

Usage

is_valid_http_method(m)

Arguments

Value

A logical value: TRUE if m is a valid HTTP method, otherwise FALSE.

Examples

is_valid_http_method("GET") # TRUE
is_valid_http_method("get") # TRUE
is_valid_http_method("DELETE") # TRUE
is_valid_http_method("foo") # FALSE
is_valid_http_method(NULL) # FALSE

Description

Convert Prettified Labels to API Names

Usage

label_to_api_name(x, req_str = "* ")

Arguments

Value

A character vector with labels converted to API-style names.

Examples

label_to_api_name(c("* First Name", "Last Name"))
label_to_api_name(c("# Instrument Model", "# Fragment SD"), req_str = "# ")

Description

Data frames representing metadata sheets that contain column names corresponding to sheet_name containing an ID reference (to a first column in sheet_name) will be replaced with the rest of the values nested as a list.

Usage

link_sheet(metadata, sheet_name)

Arguments

Value

A list of updated metadata with the specified values replaced based on referenced values present in sheet_name.

Examples

# Link data from a specific sheet to other sheets in metadata
metadata <- list(
    sheet1 = data.frame(id = c(1, 2), linked_sheet = c("A", "B")),
    linked_sheet = data.frame(id = c("A", "B"), value = c(10, 20))
)
updated_metadata <- link_sheet(metadata, "linked_sheet")

Description

This function adds a new column to a data frame by mapping values from an existing column through a lookup table.

Usage

lut_add(df, to, from, lut)

Arguments

Value

The input data frame with the added column.

Examples

df <- data.frame(id = c("A", "B", "C"), stringsAsFactors = FALSE)
lut <- list(A = 1, B = 2, C = 3)
lut_add(df, "value", "id", lut)

Description

Merges a target column with a source column in a linked sheet's data, processing it into a format suitable for JSON parsing. Includes API-specific adjustments for certain data.

Usage

merge_linked_sheet(target, source, dat, sheet)

Arguments

Value

A data frame containing the merged data, or an empty list if the target is entirely NA.

Examples

target <- c(1, 2, 3)
source <- "id"
dat <- data.frame(id = c(1, 2, 3), value = c("A", "B", "C"))
merge_linked_sheet(target, source, dat, "collaborators")

Description

Adds multiple columns to a data frame by applying multiple lookup tables, each defined by a set of arguments specifying the new column, the source column, and the lookup table.

Usage

multi_lut_add(df, ...)

Arguments

Value

The input data frame with the added columns.

Examples

df <- data.frame(id = c("A", "B", "C"), stringsAsFactors = FALSE)
lut1 <- list(A = 1, B = 2, C = 3)
lut2 <- list(A = "x", B = "y", C = "z")
multi_lut_add(df, list("value1", "id", lut1), list("value2", "id", lut2))

Description

Replaces NA values in a list with empty lists, preserving the original structure of the list. Doesn't work on nested lists.

Usage

na_to_empty_list(l)

Arguments

Value

A list where any NA values have been replaced with empty lists.

Examples

input_list <- list(1, NA, "text", NA)
na_to_empty_list(input_list)

Description

This function creates a new submission and associates all specified data with it. Following data has to be present in the request data object: submission studies, experiments, samples, runs, analyses, datasets. The files associated with the submission must be present in the EGA Inbox and they are fetched and matched according to Inbox path. In case the submission is interrupted or fails, all the information entered into EGA database is rolled back apart from the submission itself. If the workflow successfully creates a submission, but fails in the following steps, the returned submission ID can be used as a parameter to the workflow to continue entering data into existing submission. If logfile is specified, the responses from successfully executed steps (even if the error occurs), will be saved.

Usage

new_submission(
  dat,
  client = NULL,
  logfile = NULL,
  submission_id = NULL,
  retrieve = FALSE,
  ...
)

Arguments

Value

List of data frames. Parsed response objects from httr2 requests

Examples

minimal_metadata <- list(
    aliases = list(
        studies = "Study1", experiments = "Experiment1",
        datasets = "Dataset1", samples = "Sample1", runs = "Run1",
        analyses = "Analysis1"
    ),
    files = tibble::tibble(
        file = "raw.fastq.gz", ega_file = list("raw.fastq.gz.c4gh")
    ),
    submission = tibble::tibble(title = "Submission"),
    studies = tibble::tibble(
        study = "Study1", title = "Study Title",
        description = "Study Description",
        study_type = "Whole Genome Sequencing"
    ),
    samples = tibble::tibble(
        alias = "Sample1", phenotype = "wild-type",
        biological_sex = "female", subject_id = "ID1"
    ),
    experiments = tibble::tibble(
        study = "Study1", experiment = "Experiment1",
        design_description = "Experiment Design",
        library_selection = "RANDOM", instrument_model_id = 1L,
        library_layout = "SINGLE", library_strategy = "WGS",
        library_source = "GENOMIC"
    ),
    runs = tibble::tibble(
        run = "Run1", experiment = "Experiment1", run_file_type = "srf",
        alias = "Sample1", files = list("raw.fastq.gz.c4gh")
    ),
    datasets = tibble::tibble(
        dataset = "Dataset1", title = "Dataset Title",
        description = "Dataset Description",
        policy_accession_id = "EGAP00000000001",
        dataset_types = list("Whole genome sequencing"),
        runs = list("Run1")
    )
)

ega <- create_client(extract_api(), verbosity = 0)

# Requires credentials
try(
    new_submission(minimal_metadata, ega)
)

Description

Parses the body of a body of httr2 response object from the EGA API, handling JSON and plain text content, and formats it into a tibble for further processing.

Usage

parse_ega_body(resp)

Arguments

Value

A tibble containing the parsed and formatted response data. If the response is plain text without a JSON-like structure, a one-column tibble is returned with the raw content.

Examples

# Example with JSON response
json_resp <- httr2::response(
    method = "GET",
    url = "https://www.example.com/api/files",
    status = 200,
    headers = list("content-type" = "application/json"),
    body = charToRaw('[{"id": 1, "name": "test"}]')
)
parse_ega_body(json_resp)

# Example with plain text response
text_resp <- httr2::response(
    method = "POST",
    url = "https://www.example.com/api/submissions",
    status = 200,
    headers = list("content-type" = "text/plain"),
    body = charToRaw("Sample response text")
)
parse_ega_body(text_resp)

Description

This function parses an enum, represented as a data frame or character vector, into a formatted string for display or further use.

Usage

parse_enum(enum, sep = "--")

Arguments

Value

A single string representing the parsed enum. Rows are joined by newlines and multiple enum fields are joined by sep.

Examples

# Parse an enum as a data frame
df_enum <- data.frame(key = c("A", "B"), value = c("1", "2"))
parse_enum(df_enum)

# Parse an enum as a character vector
vec_enum <- c("A", "B", "C")
parse_enum(vec_enum)

Description

Extracts the JSON body from a response and ensures the output is structured as a list of objects. Named lists (single records) are wrapped in a parent list to maintain consistency for downstream unnesting.

Usage

parse_json_body(resp)

Arguments

Value

A list of lists, where each inner list represents a record.

Examples

json_resp <- httr2::response(
    method = "GET",
    url = "https://www.example.com/api/files",
    status = 200,
    headers = list("content-type" = "application/json"),
    body = charToRaw('[{"id": 1, "name": "test"}]')
)
parse_json_body(json_resp)

Description

Processes a text response by either parsing it as JSON (if structured with curly braces or square brackets) or returning it as a list. Null JSON elements are converted to empty lists to facilitate unnesting.

Usage

parse_text_body(resp)

Arguments

Value

A list of parsed data or a tibble if the content is raw text.

Examples

text_resp <- httr2::response(
    method = "POST",
    url = "https://www.example.com/api/submissions",
    status = 200,
    headers = list("content-type" = "text/plain"),
    body = charToRaw("Sample response text")
)
parse_text_body(text_resp)

Description

This function processes chromosome data by extracting unique chromosome IDs and labels or retrieving chromosome group information from a lookup where applicable.

Usage

process_chromosomes(chr_data, select_input_data)

Arguments

Value

A data frame with chromosome id and label if chromosomes are present. If only chromosome groups exist, returns the result of lookup against the select_input_data with get_chr_group(). If neither are present, returns an empty list.

Examples

select_input_data <- list(
    chromosomes = c("group1--1--chr1--name1", "group1--2--chr2--name2")
)

chr_data_1 <- list(
    chromosomes = list("group1--1--chr1--name1", "group2--3--chr3--name3"),
    chromosome_groups = NA_character_
)
process_chromosomes(chr_data_1, select_input_data)

chr_data_2 <- list(
    chromosomes = NA,
    chromosome_groups = "group1"
)

process_chromosomes(chr_data_2, select_input_data)

Description

The specified column name is searched for across all the data frames. If the column is pubmed_ids, values are converted to integers.

Usage

process_delimited_column(
  metadata,
  column_name,
  separator,
  converters = DELIM_CONVERTERS
)

Arguments

Value

A list of updated metadata with the specified column split into lists based on the delimiter and trimmed.

Examples

metadata <- list(
    sheet1 = data.frame(pubmed_ids = c("123; 456", "130; 789; 102", NA))
)

process_delimited_column(metadata, "pubmed_ids", ";")

Description

Rolls back specified endpoints for a submission identified by its accession ID using the client and logs the responses if a logfile is specified.

Usage

rollback_submission(id, endpoints, client = NULL, logfile = NULL, ...)

Arguments

Value

A list of responses from the rollback operations for each endpoint.

Examples

mock_client <- list(
    "put__submissions__accession_id__datasets__rollback" =
        function(id) list(status = "rolled back")
)
rollback_submission("EGAB00000000001", list("datasets"), mock_client)

Description

Format a Row Table

Usage

row_table_formatter(tab, params)

Arguments

Value

A cleaned and formatted tibble with correctly organized rows and columns, whitespace trimmed, and folding applied to specified columns.

Examples

# Formatter parameters
params <- list(fold = "extra_attributes")

# Sample data frame
df <- data.frame(
    ...1 = c("* Study", "* Title", "Extra Attributes", "Extra Attributes"),
    ...2 = c("Study1", "Title1", "A", "B"),
    ...3 = c("* Study", "* Title", "Extra Attributes", NA),
    ...4 = c("Study2", "Title2", "C", NA)
)

row_table_formatter(df, params)

Description

Validates uniqueness of sample aliases by comparing input against existing records in the EGA database. Throws an error if duplicates are found and retrieval is not enabled.

Usage

samples_in_db(samples, client = NULL, retrieve = FALSE)

Arguments

Value

Logical TRUE if validation passes.

Examples

my_client <- list(
    get__samples = function(prefix = NULL) {
        data.frame(alias = c("unique_sample1", "unique_sample_2"))
      }
)

samples_in_db(c("sample1", "sample2"), client = my_client, retrieve = FALSE)

Description

This function saves a list of API responses to a specified log file in YAML format.

Usage

save_log(responses, logfile)

Arguments

Value

Invisibly returns NULL

Examples

responses <- list(status = "success", data = list(a = 1, b = "text"))
save_log(responses, logfile = NULL)

Description

Creates a closure function to display sequential progress messages for a specified number of steps.

Usage

step_msg(steps)

Arguments

Value

A function that takes a message string as input and displays it along with the current step and total steps. The step count increments automatically with each call.

Examples

stepper <- step_msg(3)
stepper("Initializing") # "Step 1/3 - Initializing"
stepper("Processing") # "Step 2/3 - Processing"
stepper("Finalizing") # "Step 3/3 - Finalizing"

Description

This function iterates over rows of a data frame, submitting each row to a specified API endpoint function, and combines the responses into a single data structure.

Usage

submit_table(tab, id, endpoint_func)

Arguments

Value

Data frame. A combined response object from the API.

Examples

tab <- data.frame(a = 1:2, b = c("x", "y"))
mock_endpoint <- function(id, body) list(id = id, body = body)
submit_table(tab, 12345, mock_endpoint)

Description

Wraps a logic function in a tryCatch block to handle errors during a specific submission step, optionally triggering a rollback function.

Usage

try_step(step_name, logic_fn, rollback_fn, responses, logfile)

Arguments

Value

The result of logic_fn().

Examples

try_step(
    "test", function() 1 + 1, function() print("fail"), list(), "log.txt"
)

Description

Converts a list into a single-row data frame with unboxed elements if all elements have a length of 1. Otherwise, an error is raised.

Usage

unbox_list(l)

Arguments

Value

A data frame with unboxed elements, suitable for JSON conversion.

Examples

input_list <- list(a = 1, b = "text", c = TRUE)
unbox_list(input_list)

Description

This function converts a single row of a data frame into an unboxed JSON object, effectively removing the array structure.

Usage

unbox_row(row)

Arguments

Value

A JSON object with unboxed values for the input row.

Examples

row <- data.frame(a = 1, b = "text", stringsAsFactors = FALSE)[1, ]
unbox_row(row)

Description

Handles retrieval or deletion of data associated with a submission accession/provisional ID using a specified client and method.

Usage

use_submission(id, method, client = NULL)

Arguments

Value

A named list containing responses for datasets, analyses, runs, experiments, samples, and studies.

Examples

mock_client <- list(
    "get__submissions__accession_id__datasets" = function(id) {
        list(data = id)
    },
    "delete__submissions__provisional_id__datasets" =
        function(id) list(status = "deleted")
)
use_submission("EGAB12345678901", "get", mock_client)

Description

Function handles oneOf directives in a way that it in a case of validation fail, it displays the overall result of the validation as first and then it tests separately against all oneOf sub schemas.

Usage

validate_schema(payload, schema)

Arguments

Value

Logical value indicating whether the payload is valid. If invalid, the result includes an errors attribute detailing the validation errors.

Examples

schema <- list(
    type = "object",
    properties = list(
        id = list(type = "integer"),
        title = list(type = "string")
    ),
    required = c("id")
)

payload_true <- data.frame(id = c(12345), title = c("abcd"))
payload_false <- data.frame(id = c("12345"), title = c(0.355))

validate_schema(jsonlite::unbox(payload_true), schema)
validate_schema(jsonlite::unbox(payload_false), schema)

Description

Convert Validation Results to a Message

Usage

validation_to_msg(v)

Arguments

Value

A character string summarizing the validation results. If validation errors are present, they are included in the message; otherwise, a success message is returned.

Examples

validation_result <- FALSE
attr(validation_result, "errors") <- data.frame(
    field = c("name"),
    message = c("Missing")
)
msg <- validation_to_msg(validation_result)
message(msg)

Description

Creates a custom error handler for managing errors during a workflow step. Logs responses, executes additional expressions, and stops execution with a detailed message and a stack trace.

Usage

workflow_error_handler(step, responses, logfile, ...)

Arguments

Value

A function to handle errors during the specified workflow step.

Examples

handler <- workflow_error_handler(
    step = "submission",
    responses = list(),
    logfile = NULL
)

tryCatch("Example code without error", error = handler)