Tripal Galaxy API Functions¶

group tripal_galaxy_api

programming interface (API) for integrating Tripal and Galaxy. It uses the blend4php library to communicate with a remote Galaxy instances but ensures that other developers who want to integrate with the features of the Tripal Galaxy module cab do so.

Functions

tripal_galaxy_add_galaxy(array $values)

Adds a new Galaxy server to Tripal.

Return

object The newly created Galaxy object or FALSE on error. If the record already exists the object is returned and no duplicated record is added.

Parameters

$values: An associative array containing the following key/value pairs: - servername: A human-readable name for the Galaxy server. The servername must be unique and not already present. - description: (optional) a description about this server. - url: The full URL for the server (e.g. https://usegalaxy.org/) - username: The name of the user to connect as. - api_key: The API key of the user. This allows Tripal to access the Galaxy server’s RESTful API services. - uid: The Drupal User ID who created this record.

tripal_galaxy_add_workflow(int $galaxy_id, array $values, bool $create_webform = TRUE)

Adds a remote Galaxy Workflow to Tripal.

Return

object A workflow object or FALSE on error. If the workflow has already been added, then the workflow object is returned and no duplicate record is added.

Parameters

$galaxy_id: An ID of the galaxy server.
$values: An associative array used to specify the workflow. The workflow can be identified using the Galaxy workflow ID provided using the ‘workflow_id’ key or using the workflow name provided using the ‘workflow_name’ key.
$create_webform: If TRUE, creates a webform for the end-user to submit this workflow using the Tripal website. It will automatically create a history for this workflow on the remote Galaxy server as well.

tripal_galaxy_check_submission_status(int $sid = NULL, bool $force = FALSE)

Checks and updates the status of a Galaxy workflow.

Return

bool Returns TRUE on successful checking of the status, FALSE if a problem occured.

Parameters

$sid: The submission ID of the workflow.
$force: If a workflow submission is already completed this function will quickly return and not check the status again. Setting the $force argument to TRUE will force the function to check the status.

tripal_galaxy_create_history(GalaxyInstance $galaxy, string $history_name)

Creates a history on the Galaxy server.

Return

array A history array for the created history.

Parameters

$galaxy:
$history_name:

tripal_galaxy_delete_expired_histories()¶

Deletes expired histories.

Walks through the tripal_galaxy_workflow_submission table and deletes any workflows older in days than specified in the tripal_galaxy_history_days_limit system variable.

tripal_galaxy_delete_remote_history(int $galaxy_id, string $history_name)

Deletes a single remote history from the remote galaxy server.

Return

bool TRUE if the deletion was successful, FALSE otherwise.

Parameters

$galaxy_id: A unique ID for the galaxy server. If this is provided no other arguments are needed.
$history_name: The name of the history to retrieve. If the history doesn’t exist then it will be created.

tripal_galaxy_download_file(stdClass $submission, array $dataset, int $uid)

Downloads a file from a Galaxy history.

Downloads a single file from a history. The file will be stored in the user’s Tripal space and count towards their quota. If the file has already been downloaded it will be retrieved again and overwrite any existing file.

Return

object Returns a Drupal File object.

Parameters

$submission: A submission object as obtained by the tripal_galaxy_get_submission() function.
$dataset: An array describing the dataset as returned by the tripal_galaxy_get_dataset() or tripal_galaxy_get_datasets() functions.
$uid: The user that should own this file after it is downloaded.

Exceptions

Exception:

tripal_galaxy_get_active_submissions()¶

Retrieves a list of all workflow submissions that have not completed.

Return: array An array of submission objects.

tripal_galaxy_get_connection(int $galaxy_id)

Retrieves a GalaxyInstance objects using a galaxy_id.

Return

GalaxyInstance A galaxyInstance object or FALSE on error.

Parameters

$galaxy_id: The ID of a galaxy server.

tripal_galaxy_get_dataset(stdClass $submission, $dataset_id)

Retrieves a single datasets for a workflow invocation.

This function returns a single datasets as reported by the remote Galaxy server. The key/value pairs of the array are dependent on the Galaxy server version.

Return

array An array of datasets as reporte by the Remote Galaxy server.

Parameters

$submission: An object for the submission as returned by the tripal_galaxy_get_sumbission() function.
The: ID of the dataset to retrieve.

Exceptions

Exception:

tripal_galaxy_get_datasets(stdClass $submission)

Retrieves a list of datasets for a workflow invocation.

This function returns an array of datasets as reported by the remote Galaxy server. The key/value pairs of the array are dependent on the Galaxy server version.

Note, this function may take a few seconds to complete as it must communicate with the remote Galaxy server to retrieve dataset information.

Return

array An array of datasets as reporte by the Remote Galaxy server.

Parameters

$submission: An object for the submission as returned by the tripal_galaxy_get_sumbission() function.

Exceptions

Exception:

tripal_galaxy_get_files_dir()¶

Returns the URI where the Tripal Galaxy module stores files.

This function also ensures that the path exists by creating it.

Return: string|bool A Drupal URI indicating the location where Galaxy files are housed. Returns FALSE if the location does not exist or cannot be created.

tripal_galaxy_get_galaxies()¶

Retrieves a list of Galaxy servers that are known to Tripal.

Return: array An associative array of galaxy server objects. Note, the returned objects are different from the GalaxyInstance objects provided by blend4php. These objects house the information that Tripal maintains about each of these servers.

tripal_galaxy_get_galaxy(int $galaxy_id)

Retrieves a Galaxy object.

Return

object A galaxy object Note, the returned object is different from the GalaxyInstance object provided by blend4php. This objects house the information that Tripal maintains about each the servers. Returns FALSE on error.

Parameters

$galaxy_id: The ID of the galaxy server to retrieve. A list of all galxy servers known to Tripal can be retrieved using the tripal_galaxy_get_galaxies() function.

tripal_galaxy_get_history(GalaxyInstance $galaxy, string $history_name)

Retrieves a history by name from Galaxy.

You must first create the history using tripal_galaxy_create_history() if it does not already exist.

Return

array|bool A history array for the specified history or FALSE if the history could not be found.

Parameters

$galaxy: A GalaxyInstance object.
$history_name: The name of the history to retrieve. If the history doesn’t exist then it will be created.

tripal_galaxy_get_history_name( $submission)

Constructs the history name for a given submission.

Return

string The history name.

Parameters

$submission: A submission object that contains the galaxy_workflow_id, sid, and submit_date properties.

tripal_galaxy_get_submission(int $sid)

Retrieves a workflow submission object using the submission ID.

The returned submission object includes all information about the submission. If the submission has been invoked then the ‘errors’ element will have more information about the run including the history information, the history name, and the state of the history_contents from the last time the status of the submission was checked. If the status of the submission is ‘Completed’ then the history_contents should contain all the history contents.

Return

object An object containing the submission information.

Parameters

$sid: The submission ID of the workflow.

tripal_galaxy_get_user_submissions(int $userid)

Retrieve all submission IDs for a user.

Return

array A list of submission ids.

Parameters

$userid: User id number.

tripal_galaxy_get_workflow_defaults(GalaxyInstance $galaxy, string $workflow_id)

Retrieves an array of settings used by the workflow.

This is a helpful function to help a developer understand how the $parameters array should be structured when passing into the tripal_galaxy_invoke_workflow() function.

Return

bool|array An array compatible with the $parameters argument for the tripal_galaxy_invoke_wokflow(). Values are populatd with appropriate defaults. Returns FALSE if the workflow settings could not be retrieved.

Parameters

$galaxy: A GalaxyInstance object.
$workflow_id: The ID of the workflow to retrieve settings for. This is the Galaxy ID for the workflow not Tripal’s internal workflow ID.

tripal_galaxy_get_workflows(array $values = [])

Retrieves a list of workflows integrated with Tripal.

The returned workflows can be filtered using a set of matching criteria given by the $values argument. This list only includes workflows that have been integrated with Tripal and not the list of workflows available on a remote galaxy server. Use blend4php functions to retrieve a list of workflows available on a remote Galaxy server.

Return

array An array of workflow objects.

Parameters

$values: An associative array used to find workflows. The following keys are supported: - galaxy_id: finds all workflows that match the given galayx_id. - id: finds the workflow with this specific workflow ID. - workflow_id: the ID of the workflow on the remote Galaxy instance. - name: finds the workflow with a given name. Note: the workflow name is not guranteed to be unique. - status: finds all workflows whose status matches the value provided. Any combination of the keys can be used.

tripal_galaxy_init_submission( $workflow, $user)

Initializes a new workflow submission record.

This function creates the record for the submission.

Return

int|bool The submission ID on success, FALSE on failure.

Parameters

$workflow: An workflow object as generated by the tripal_galaxy_get_workflow() function.
$user: The Drupal User object. This is the user who owns the submission.

tripal_galaxy_invoke_workflow(GalaxyInstance $galaxy, $submission, array $parameters, array $inputs, array $history)

Invokes all submitted workflows that are in the ‘Waiting’ state.

This function can be called by the tripal Job system hence the $job argument. For Tripal v2 the job_id is passed, for Tripal v3 a job object is passed so we’ll handle both cases.

Parameters

$galaxy: An instance of a GalaxyInstance object.
$submission: A Galaxy workflow submission object. This object can be retrieved using the tripal_galaxy_get_submission() function.

$parameters: A mapping of tool parameters that are non-datasets parameters. The map must be in the following format:

[
  {step_id_or_UUID} => [
    {param_name} => {value}
  ],
  {step_id_or_UUID} => [
    {param_name} =>
    {value}
  ]
];

$inputs: An array of file inputs. These files should already be uploaded to the history on the Galaxy server. This array contains a mapping of workflow inputs to datasets and dataset collections. The datasets source can be a LibraryDatasetDatasetAssociation (ldda), LibraryDataset (ld), HistoryDatasetAssociation (hda), or HistoryDatasetCollectionAssociation (hdca). The map must be in the following format.
```
[
  {step index} => [
    'id' => {encoded dataset ID},
    'src' => {'ldda'|'ld'|'hda'|'hdca'},
  ],
];
```
The id’s are data set IDs and can be found using the data set class’s index() function. The data set must be present in a history, and the data set ‘state’ must be ‘ok’ and ‘deleted’ must be set to FALSE. The {step index> is the numeric value of the step in the workflow where the file is used.
$history: A history record as returned by the function tripal_galaxy_get_history().

tripal_galaxy_test_connection(array $connect)

Tests if a Galaxy server is accessible.

Return

bool Returns TRUE if accessible. FALSE otherwise. A Drupal message is also provided that indicates if the test was successful.

Parameters

$connect: An array of the following: - galaxy_id: A unique ID for the galaxy server. If this is provided no other arguments are needed. - host: The DNS hostname of the galaxy server. - port: The TCP port for the server. - use_https: Set to TRUE of the server uses HTTPS If the ‘galaxy_id’ is provided then no other values are needed. Use the host, port and use_https arguments if testing connection to a server that has not yet been added.

tripal_galaxy_upload_file( $galaxy, int $fid, string $history_id, array $history_contents)

Uploads a file to a given history on Galaxy.

Return

array An array of the dataset details from Galaxy for the uploaded file.

Parameters

$galaxy: An instance of a Galaxy server object.
$fid: The Drupal managed file ID.
$history_id: The history ID.
$history_contents: The Galaxy history contents array as returned by the GalaxyHistoryContents::index function.

Exceptions

Exception: