API documentation for interacting with Galaxy¶
GalaxyInstance¶
-
class
bioblend.galaxy.
GalaxyInstance
(url, key=None, email=None, password=None)[source]¶ A base representation of an instance of Galaxy, identified by a URL and a user’s API key.
After you have created an
GalaxyInstance
object, access various modules via the class fields (see the source for the most up-to-date list):libraries
,histories
,workflows
,datasets
, andusers
are the minimum set supported. For example, to work with histories, and get a list of all the user’s histories, the following should be done:from bioblend import galaxy gi = galaxy.GalaxyInstance(url='http://127.0.0.1:8000', key='your_api_key') hl = gi.histories.get_histories() print "List of histories:", hl
Parameters: - url (string) – A FQDN or IP for a given instance of Galaxy. For example: http://127.0.0.1:8080
- key (string) – User’s API key for the given instance of Galaxy, obtained from the user preferences. If a key is not supplied, an email address and password must be and key will automatically be created for the user.
- email (string) – Galaxy e-mail address corresponding to the user. Ignored if key is supplied directly.
- password (string) – Password of Galaxy account corresponding to the above e-mail address. Ignored if key is supplied directly.
-
__init__
(url, key=None, email=None, password=None)[source]¶ A base representation of an instance of Galaxy, identified by a URL and a user’s API key.
After you have created an
GalaxyInstance
object, access various modules via the class fields (see the source for the most up-to-date list):libraries
,histories
,workflows
,datasets
, andusers
are the minimum set supported. For example, to work with histories, and get a list of all the user’s histories, the following should be done:from bioblend import galaxy gi = galaxy.GalaxyInstance(url='http://127.0.0.1:8000', key='your_api_key') hl = gi.histories.get_histories() print "List of histories:", hl
Parameters: - url (string) – A FQDN or IP for a given instance of Galaxy. For example: http://127.0.0.1:8080
- key (string) – User’s API key for the given instance of Galaxy, obtained from the user preferences. If a key is not supplied, an email address and password must be and key will automatically be created for the user.
- email (string) – Galaxy e-mail address corresponding to the user. Ignored if key is supplied directly.
- password (string) – Password of Galaxy account corresponding to the above e-mail address. Ignored if key is supplied directly.
-
get_retry_delay
¶
-
max_get_attempts
¶
Datasets¶
Contains possible interactions with the Galaxy Datasets
-
class
bioblend.galaxy.datasets.
DatasetClient
(galaxy_instance)[source]¶ -
download_dataset
(dataset_id, file_path=None, use_default_filename=True, wait_for_completion=False, maxwait=12000)[source]¶ Downloads the dataset identified by ‘id’.
Parameters: - dataset_id (string) – Encoded Dataset ID
- file_path (string) – If the file_path argument is provided, the dataset will be streamed to disk at that path (Should not contain filename if use_default_name=True). If the file_path argument is not provided, the dataset content is loaded into memory and returned by the method (Memory consumption may be heavy as the entire file will be in memory).
- use_default_name (boolean) – If the use_default_name parameter is True, the exported file will be saved as file_path/%s, where %s is the dataset name. If use_default_name is False, file_path is assumed to contain the full file path including filename.
- wait_for_completion (boolean) – If wait_for_completion is True, this call will block until the dataset is ready. If the dataset state becomes invalid, a DatasetStateException will be thrown.
- maxwait (float) – Time (in seconds) to wait for dataset to complete. If the dataset state is not complete within this time, a DatasetTimeoutException will be thrown.
Return type: dict
Returns: If a file_path argument is not provided, returns a dict containing the file_content. Otherwise returns nothing.
-
Genomes¶
Contains possible interactions with the Galaxy Histories
-
class
bioblend.galaxy.genomes.
GenomeClient
(galaxy_instance)[source]¶ -
-
install_genome
(func='download', source=None, dbkey=None, ncbi_name=None, ensembl_dbkey=None, url_dbkey=None, indexers=None)[source]¶ Download and/or index a genome.
Parameters:
dbkey DB key of the build to download, ignored unless 'UCSC' is specified as the source ncbi_name NCBI's genome identifier, ignored unless NCBI is specified as the source ensembl_dbkey Ensembl's genome identifier, ignored unless Ensembl is specified as the source url_dbkey DB key to use for this build, ignored unless URL is specified as the source source Data source for this build. Can be: UCSC, Ensembl, NCBI, URL indexers POST array of indexers to run after downloading (indexers[] = first, indexers[] = second, ...) func Allowed values: 'download' Download and index 'index' Index only
Returns:
If no error: dict( status: 'ok', job: <job ID> ) If error: dict( status: 'error', error: <error message> )
-
Histories¶
Contains possible interactions with the Galaxy Histories
-
class
bioblend.galaxy.histories.
HistoryClient
(galaxy_instance)[source]¶ -
-
create_history_tag
(history_id, tag)[source]¶ Create history tag
Parameters: - history_id (str) – Encoded history ID
- tag (str) – Add tag to history
Return type: json object
Returns: Return json object For example:
{'model_class':'HistoryTagAssociation', 'user_tname': 'NGS_PE_RUN', 'id': 'f792763bee8d277a', 'user_value': None}
-
delete_dataset_collection
(history_id, dataset_collection_id)[source]¶ Mark corresponding dataset collection as deleted.
-
delete_history
(history_id, purge=False)[source]¶ Delete a history.
If
purge
is set toTrue
, also purge the history.Note
For the purge option to work, the Galaxy instance must have the
allow_user_dataset_purge
option set toTrue
in theconfig/galaxy.ini
configuration file.
-
download_dataset
(history_id, dataset_id, file_path, use_default_filename=True, to_ext=None)[source]¶ Download a
dataset_id
from history withhistory_id
to a file on the local file system, saving it tofile_path
.
-
download_history
(history_id, jeha_id, outf, chunk_size=4096)[source]¶ Download a history export archive. Use
export_history()
to create an export.Parameters: - history_id (str) – history ID
- jeha_id (str) – jeha ID (this should be obtained via
export_history()
) - outf (file) – output file object, open for writing
- chunk_size (int) – how many bytes at a time should be read into memory
-
export_history
(history_id, gzip=True, include_hidden=False, include_deleted=False, wait=False)[source]¶ Start a job to create an export archive for the given history.
Parameters: - history_id (str) – history ID
- gzip (bool) – create .tar.gz archive if
True
, else .tar - include_hidden (bool) – whether to include hidden datasets in the export
- include_deleted (bool) – whether to include deleted datasets in the export
- wait (bool) – if
True
, block until the export is ready; else, return immediately
Return type: str
Returns: jeha_id
of the export, or empty ifwait
isFalse
and the export is not ready.
-
get_current_history
()[source]¶ Deprecated method.
Just an alias for get_most_recently_used_history().
-
get_histories
(history_id=None, name=None, deleted=False)[source]¶ Get all histories or filter the specific one(s) via the provided
name
orhistory_id
. Provide only one argument,name
orhistory_id
, but not both.If
deleted
is set toTrue
, return histories that have been deleted.Return a list of history element dicts. If more than one history matches the given
name
, return the list of all the histories with the given name.
-
get_most_recently_used_history
()[source]¶ Returns the current user’s most recently used history (not deleted).
-
get_status
(history_id)[source]¶ Returns the state of this history as a dictionary, with the following keys. ‘state’ = This is the current state of the history, such as ok, error, new etc. ‘state_details’ = Contains individual statistics for various dataset states. ‘percent_complete’ = The overall number of datasets processed to completion.
-
show_dataset
(history_id, dataset_id)[source]¶ Get details about a given history dataset. The required
history_id
can be obtained from the datasets’s history content details.
-
show_dataset_collection
(history_id, dataset_collection_id)[source]¶ Get details about a given history dataset collection.
-
show_dataset_provenance
(history_id, dataset_id, follow=False)[source]¶ Get details related to how dataset was created (
id
,job_id
,tool_id
,stdout
,stderr
,parameters
,inputs
, etc...).If
follow
isTrue
, recursively fetch dataset provenance information for all inputs and their inputs, etc....
-
show_history
(history_id, contents=False, deleted=None, visible=None, details=None, types=None)[source]¶ Get details of a given history. By default, just get the history meta information. If
contents
is set toTrue
, get the complete list of datasets in the given history.deleted
,visible
, anddetails
are used only ifcontents
isTrue
and are used to modify the datasets returned and their contents. Setdetails
to ‘all’ to get more information about each dataset.
-
show_matching_datasets
(history_id, name_filter=None)[source]¶ Get dataset details for matching datasets within a history.
Only datasets whose name matches the
name_filter
regular expression will be returned; use plain strings for exact matches and None to match all datasets in the history.
-
update_dataset
(history_id, dataset_id, **kwds)[source]¶ Update history dataset metadata. Some of the attributes that can be modified are documented below.
Parameters: - history_id (str) – Encoded history ID
- name (str) – Replace history dataset name with the given string
- annotation (str) – Replace history dataset annotation with given string
- deleted (bool) – Mark or unmark history dataset as deleted
- visible (bool) – Mark or unmark history dataset as visible
Return type: status_code (int)
-
update_dataset_collection
(history_id, dataset_collection_id, **kwds)[source]¶ Update history dataset collection metadata. Some of the attributes that can be modified are documented below.
Parameters: - history_id (str) – Encoded history ID
- name (str) – Replace history dataset collection name with the given string
- deleted (bool) – Mark or unmark history dataset collection as deleted.
- visible (bool) – Mark or unmark history dataset collection as visible.
Return type: status_code (int)
-
update_history
(history_id, name=None, annotation=None, **kwds)[source]¶ Update history metadata information. Some of the attributes that can be modified are documented below.
Parameters: - history_id (str) – Encoded history ID
- name (str) – Replace history name with the given string
- annotation (str) – Replace history annotation with given string
- deleted (bool) – Mark or unmark history as deleted
- published (bool) – Mark or unmark history as published
- importable (bool) – Mark or unmark history as importable
- tags (list) – Replace history tags with the given list
Return type: status_code (int)
-
Libraries¶
Contains possible interactions with the Galaxy Data Libraries
-
class
bioblend.galaxy.libraries.
LibraryClient
(galaxy_instance)[source]¶ -
copy_from_dataset
(library_id, dataset_id, folder_id=None, message='')[source]¶ Copy a Galaxy dataset into a library.
Parameters: folder_id (str) – id of the folder where to place the uploaded files. If not provided, the root folder will be used
-
create_folder
(library_id, folder_name, description=None, base_folder_id=None)[source]¶ Create a folder in a library.
Parameters: base_folder_id (str) – id of the folder where to create the new folder. If not provided, the root folder will be used
-
create_library
(name, description=None, synopsis=None)[source]¶ Create a data library with the properties defined in the arguments. Return a list of JSON dicts, looking like so:
[{"id": "f740ab636b360a70", "name": "Library from bioblend", "url": "/api/libraries/f740ab636b360a70"}]
-
delete_library
(library_id)[source]¶ Delete a data library identified by library_id.
Warning
Deleting a data library is irreversible - all of the data from the library will be permanently deleted.
-
delete_library_dataset
(library_id, dataset_id, purged=False)[source]¶ Delete a library dataset in a data library.
Parameters: - library_id (str) – library id where dataset is found in
- dataset_id (str) – if of the dataset to be deleted
- purged (bool) – Indicate that the dataset should be purged (permanently deleted)
Return type: dict
Returns: A dictionary containing the dataset id and whether the dataset has been deleted For example:
{u'deleted': True, u'id': u'60e680a037f41974'}
-
get_folders
(library_id, folder_id=None, name=None, deleted=False)[source]¶ Get all the folders or filter specific one(s) via the provided
name
orfolder_id
in data library with idlibrary_id
. Provide only one argument:name
orfolder_id
, but not both.For
name
specify the full path of the folder starting from the library’s root folder, e.g./subfolder/subsubfolder
.If
deleted
is set toTrue
, return folders that have been deleted.Return a list of JSON formatted dicts each containing basic information about a folder.
-
get_libraries
(library_id=None, name=None, deleted=False)[source]¶ Get all the libraries or filter for specific one(s) via the provided name or ID. Provide only one argument:
name
orlibrary_id
, but not both.If
name
is set and multiple names match the given name, all the libraries matching the argument will be returned.Return a list of JSON formatted dicts each containing basic information about a library.
-
set_library_permissions
(library_id, access_in=None, modify_in=None, add_in=None, manage_in=None)[source]¶ Sets the permissions for a library. Note: it will override all security for this library even if you leave out a permission type.
access_in, modify_in, add_in, manage_in expect a list of user id’s OR None
-
show_dataset
(library_id, dataset_id)[source]¶ Get details about a given library dataset. The required
library_id
can be obtained from the datasets’s library content details.
-
show_folder
(library_id, folder_id)[source]¶ Get details about a given folder. The required
folder_id
can be obtained from the folder’s library content details.
-
show_library
(library_id, contents=False)[source]¶ Get information about a library.
If want to get contents of the library (rather than just the library details), set
contents
toTrue
.Return a list of JSON formatted dicts containing library details.
-
upload_file_contents
(library_id, pasted_content, folder_id=None, file_type='auto', dbkey='?')[source]¶ Upload pasted_contents to a data library as a new file.
Parameters: folder_id (str) – id of the folder where to place the uploaded file. If not provided, the root folder will be used
-
upload_file_from_local_path
(library_id, file_local_path, folder_id=None, file_type='auto', dbkey='?')[source]¶ Read local file contents from file_local_path and upload data to a library.
Parameters: folder_id (str) – id of the folder where to place the uploaded file. If not provided, the root folder will be used
-
upload_file_from_server
(library_id, server_dir, folder_id=None, file_type='auto', dbkey='?', link_data_only=None, roles='')[source]¶ Upload all files in the specified subdirectory of the Galaxy library import directory to a library.
Note
For this method to work, the Galaxy instance must have the
library_import_dir
option configured in theconfig/galaxy.ini
configuration file.Parameters: - server_dir (str) – relative path of the subdirectory of
library_import_dir
to upload. All and only the files (i.e. no subdirectories) contained in the specified directory will be uploaded. - folder_id (str) – id of the folder where to place the uploaded files. If not provided, the root folder will be used
- server_dir (str) – relative path of the subdirectory of
-
upload_file_from_url
(library_id, file_url, folder_id=None, file_type='auto', dbkey='?')[source]¶ Upload a file to a library from a URL.
Parameters: folder_id (str) – id of the folder where to place the uploaded file. If not provided, the root folder will be used
-
upload_from_galaxy_filesystem
(library_id, filesystem_paths, folder_id=None, file_type='auto', dbkey='?', link_data_only=None, roles='')[source]¶ Upload a set of files already present on the filesystem of the Galaxy server to a library.
Note
For this method to work, the Galaxy instance must have the
allow_library_path_paste
option set toTrue
in theconfig/galaxy.ini
configuration file.Parameters: - filesystem_paths (str) – file paths on the Galaxy server to upload to the library, one file per line
- folder_id (str) – id of the folder where to place the uploaded files. If not provided, the root folder will be used
- link_data_only (str) – either ‘copy_files’ (default) or ‘link_to_files’. Setting to ‘link_to_files’ symlinks instead of copying the files
-
Quotas¶
Contains possible interactions with the Galaxy Quota
-
class
bioblend.galaxy.quotas.
QuotaClient
(galaxy_instance)[source]¶ -
get_quotas
(deleted=False)[source]¶ Get a list of quotas
Parameters: deleted (Boolean) – Only return quota(s) that have been deleted Return type: list Returns: A list of dicts with details on individual quotas. For example: [{ u'id': u'0604c8a56abe9a50', u'model_class': u'Quota', u'name': u'test ', u'url': u'/api/quotas/0604c8a56abe9a50'}, { u'id': u'1ee267091d0190af', u'model_class': u'Quota', u'name': u'workshop', u'url': u'/api/quotas/1ee267091d0190af'}]
-
show_quota
(quota_id, deleted=False)[source]¶ Display information on a quota
Parameters: - quota_id (string) – Encoded quota ID
- deleted (Boolean) – Search for quota in list of ones already marked as deleted
Return type: dict
Returns: A description of quota For example:
{ u'bytes': 107374182400, u'default': [], u'description': u'just testing', u'display_amount': u'100.0 GB', u'groups': [], u'id': u'0604c8a56abe9a50', u'model_class': u'Quota', u'name': u'test ', u'operation': u'=', u'users': []}
-
Tools¶
Contains possible interaction dealing with Galaxy tools.
-
class
bioblend.galaxy.tools.
ToolClient
(galaxy_instance)[source]¶ -
get_tool_panel
()[source]¶ Get a list of available tool elements in Galaxy’s configured toolbox.
Return type: list Returns: List containing tools (if not in sections) or tool sections with nested tool descriptions.
-
get_tools
(tool_id=None, name=None, trackster=None)[source]¶ Get all tools or filter the specific one(s) via the provided
name
ortool_id
. Provide only one argument,name
ortool_id
, but not both.If
name
is set and multiple names match the given name, all the tools matching the argument will be returned.Parameters: - tool_id (str) – id of the requested tool
- name (str) – name of the requested tool(s)
- trackster (boolean) – if True, only tools that are compatible with Trackster are returned
Return type: Returns: List of tool descriptions.
-
paste_content
(content, history_id, **kwds)[source]¶ Upload a string to a new dataset in the history specified by
history_id
.Parameters: - content (str) – content of the new dataset to upload
- history_id (str) – id of the history where to upload the content
See
upload_file()
for the optional parameters.
-
put_url
(content, history_id, **kwds)¶ Upload a string to a new dataset in the history specified by
history_id
.Parameters: - content (str) – content of the new dataset to upload
- history_id (str) – id of the history where to upload the content
See
upload_file()
for the optional parameters.
-
run_tool
(history_id, tool_id, tool_inputs)[source]¶ Runs tool specified by
tool_id
in history indicated byhistory_id
with inputs fromdict
tool_inputs
.Parameters: tool_inputs (dict) – dictionary of input datasets and parameters for the tool (see below) The
tool_inputs
dict should contain input datasets and parameters in the (largely undocumented) format used by the Galaxy API. Some examples can be found in https://bitbucket.org/galaxy/galaxy-central/src/tip/test/api/test_tools.py .
-
show_tool
(tool_id, io_details=False, link_details=False)[source]¶ Get details of a given tool.
Parameters: - tool_id (str) – id of the requested tool
- io_details (boolean) – if True, get also input and output details
- link_details (boolean) – if True, get also link details
-
upload_file
(path, history_id, **keywords)[source]¶ Upload file specified by
path
to the history specified byhistory_id
.Parameters: - path (str) – path of the file to upload
- history_id (str) – id of the history where to upload the file
- file_name (str) – (optional) name of the new history dataset
- file_type (str) – (optional) Galaxy datatype for the new dataset, default is auto
- dbkey (str) – (optional) genome dbkey
-
ToolShed¶
Interaction with a Galaxy Tool Shed
-
class
bioblend.galaxy.toolshed.
ToolShedClient
(galaxy_instance)[source]¶ -
get_repositories
()[source]¶ Get a list of all repositories in the Tool Shed
Return type: list Returns: Returns a list of dictionaries containing information about repositories present in the Tool Shed. For example: [{u'changeset_revision': u'4afe13ac23b6', u'deleted': False, u'dist_to_shed': False, u'error_message': u'', u'name': u'velvet_toolsuite', u'owner': u'edward-kirton', u'status': u'Installed'}]
Changed in version 0.4.1: Changed method name from
get_tools
toget_repositories
to better align with the Tool Shed concepts
-
install_repository_revision
(tool_shed_url, name, owner, changeset_revision, install_tool_dependencies=False, install_repository_dependencies=False, tool_panel_section_id=None, new_tool_panel_section_label=None)[source]¶ Install a specified repository revision from a specified Tool Shed into this Galaxy instance. This example demonstrates installation of a repository that contains valid tools, loading them into a section of the Galaxy tool panel or creating a new tool panel section. You can choose if tool dependencies or repository dependencies should be installed, use
install_tool_dependencies
orinstall_repository_dependencies
.Installing the repository into an existing tool panel section requires the tool panel config file (e.g., tool_conf.xml, shed_tool_conf.xml, etc) to contain the given tool panel section:
<section id=”from_test_tool_shed” name=”From Test Tool Shed” version=”“> </section>Parameters: - tool_shed_url (string) – URL of the Tool Shed from which the repository should
be installed from (e.g.,
http://testtoolshed.g2.bx.psu.edu
) - name (string) – The name of the repository that should be installed
- owner (string) – The name of the repository owner
- changeset_revision (string) – The revision of the repository to be installed
- install_tool_dependencies (Boolean) – Whether or not to automatically handle tool dependencies (see http://wiki.galaxyproject.org/AToolOrASuitePerRepository for more details)
- install_repository_dependencies (Boolean) – Whether or not to automatically handle repository dependencies (see http://wiki.galaxyproject.org/DefiningRepositoryDependencies for more details)
- tool_panel_section_id (string) – The ID of the Galaxy tool panel section
where the tool should be insterted under.
Note that you should specify either this
parameter or the
new_tool_panel_section_label
. If both are specified, this one will take precedence. - new_tool_panel_section_label (string) – The name of a Galaxy tool panel section that should be created and the repository installed into.
- tool_shed_url (string) – URL of the Tool Shed from which the repository should
be installed from (e.g.,
-
show_repository
(toolShed_id)[source]¶ Display information of a repository from the Tool Shed
Parameters: toolShed_id (string) – Encoded toolShed ID Return type: dictionary Returns: Information about the tool For example: {u'changeset_revision': u'b17455fb6222', u'ctx_rev': u'8', u'owner': u'aaron', u'status': u'Installed', u'url': u'/api/tool_shed_repositories/82de4a4c7135b20a'}
Changed in version 0.4.1: Changed method name from
show_tool
toshow_repository
to better align with the Tool Shed concepts
-
Users¶
Contains possible interaction dealing with Galaxy users.
These methods must be executed by a registered Galaxy admin user.
-
class
bioblend.galaxy.users.
UserClient
(galaxy_instance)[source]¶ -
create_local_user
(username, user_email, password)[source]¶ Create a new Galaxy user.
Note
For this method to work, the Galaxy instance must have the
allow_user_creation
option set toTrue
anduse_remote_user
option set toFalse
in theconfig/galaxy.ini
configuration file.
-
create_remote_user
(user_email)[source]¶ Create a new Galaxy remote user.
Note
For this method to work, the Galaxy instance must have the
allow_user_creation
anduse_remote_user
options set toTrue
in theconfig/galaxy.ini
configuration file. Also note that settinguse_remote_user
will require an upstream authentication proxy server; however, if you do not have one, access to Galaxy via a browser will not be possible.
-
create_user_apikey
(user_id)[source]¶ Create a new api key for a user
Parameters: user_id (string) – Encoded user ID Return type: string Returns: The api key for the user
-
get_users
(deleted=False)[source]¶ Get a list of all registered users. If
deleted
is set toTrue
, get a list of deleted users.Return type: list Returns: A list of dicts with user details. For example: [{u'email': u'a_user@example.com', u'id': u'dda47097d9189f15', u'url': u'/api/users/dda47097d9189f15'}]
-
Visual¶
Contains possible interactions with the Galaxy visualization
-
class
bioblend.galaxy.visual.
VisualClient
(galaxy_instance)[source]¶ -
get_visualizations
()[source]¶ Get a list of visualizations
Return type: list Returns: A list of dicts with details on individual visualizations. For example: [{ u'dbkey': u'eschColi_K12', u'id': u'df1c7c96fc427c2d', u'title': u'AVTest1', u'type': u'trackster', u'url': u'/api/visualizations/df1c7c96fc427c2d'}, { u'dbkey': u'mm9', u'id': u'a669f50f8bf55b02', u'title': u'Bam to Bigwig', u'type': u'trackster', u'url': u'/api/visualizations/a669f50f8bf55b02'}]
-
show_visualization
(visual_id)[source]¶ Display information on a visualization
Parameters: visual_id (string) – Encoded visualization ID Return type: dict Returns: A description of visualization For example: {u'annotation': None,u'dbkey': u'mm9', u'id': u'18df9134ea75e49c', u'latest_revision': { ... }, u'model_class': u'Visualization', u'revisions': [ u'aa90649bb3ec7dcb', u'20622bc6249c0c71'], u'slug': u'visualization-for-grant-1', u'title': u'Visualization For Grant', u'type': u'trackster', u'url': u'/u/azaron/v/visualization-for-grant-1', u'user_id': u'21e4aed91386ca8b'}
-
Workflows¶
Contains possible interactions with the Galaxy Workflows
-
class
bioblend.galaxy.workflows.
WorkflowClient
(galaxy_instance)[source]¶ -
delete_workflow
(workflow_id)[source]¶ Delete a workflow identified by workflow_id.
Warning
Deleting a workflow is irreversible - all workflow data will be permanently deleted.
-
export_workflow_json
(workflow_id)[source]¶ Exports a workflow in json format
Parameters: workflow_id (string) – Encoded workflow ID
-
export_workflow_to_local_path
(workflow_id, file_local_path, use_default_filename=True)[source]¶ Exports a workflow in json format to a given local path.
Parameters: - workflow_id (string) – Encoded workflow ID
- file_local_path (string) – Local path to which the exported file will be saved. (Should not contain filename if use_default_name=True)
- use_default_name (boolean) – If the use_default_name parameter is True, the exported file will be saved as file_local_path/Galaxy-Workflow-%s.ga, where %s is the workflow name. If use_default_name is False, file_local_path is assumed to contain the full file path including filename.
-
get_workflow_inputs
(workflow_id, label)[source]¶ Get a list of workflow input IDs that match the given label. If no input matches the given label, an empty list is returned.
-
get_workflows
(workflow_id=None, name=None, deleted=False, published=False)[source]¶ Get all workflows or filter the specific one(s) via the provided
name
orworkflow_id
. Provide only one argument,name
orworkflow_id
, but not both.If
name
is set and multiple names match the given name, all the workflows matching the argument will be returned.If
deleted
is set toTrue
, return workflows that have been deleted.If
published
is set toTrue
, return published workflows.Return a list of JSON formatted dicts each containing basic information about a workflow.
Return type: list Returns: A list of workflow dicts. For example: [{u'id': u'92c56938c2f9b315', u'name': u'Simple', u'url': u'/api/workflows/92c56938c2f9b315'}]
Imports a new workflow from the shared published workflows
Parameters: workflow_id (string) – Encoded workflow ID Return type: Dict Returns: A description of the workflow. For example: {u'id': u'ee0e2b4b696d9092', u'model_class': u'StoredWorkflow', u'name': u'Super workflow that solves everything!', u'published': False, u'tags': [], u'url': u'/api/workflows/ee0e2b4b696d9092'}
-
import_workflow_from_local_path
(file_local_path)[source]¶ Imports a new workflow given the path to a file containing a previously exported workflow.
-
import_workflow_json
(workflow_json)[source]¶ Imports a new workflow given a json representation of a previously exported workflow.
-
run_workflow
(workflow_id, dataset_map=None, params=None, history_id=None, history_name=None, import_inputs_to_history=False, replacement_params=None)[source]¶ Run the workflow identified by
workflow_id
Parameters: - workflow_id (string) – Encoded workflow ID
- dataset_map (string or dict) – A mapping of workflow inputs to datasets. The datasets
source can be a LibraryDatasetDatasetAssociation (
ldda
), LibraryDataset (ld
), or HistoryDatasetAssociation (hda
). The map must be in the following format:{'<input>': {'id': <encoded dataset ID>, 'src': '[ldda, ld, hda]'}}
(e.g.{'23': {'id': '29beef4fadeed09f', 'src': 'ld'}}
) - params (string or dict) – A mapping of tool parameters that are non-datasets parameters. The map must be in the
following format:
{'blastn': {'param': 'evalue', 'value': '1e-06'}}
- history_id (string) – The encoded history ID where to store the workflow output.
history_id
ORhistory_name
should be provided but not both! - history_name (string) – Create a new history with the given name to store the
workflow output.
history_id
ORhistory_name
should be provided but not both! - import_inputs_to_history (bool) – If
True
, used workflow inputs will be imported into the history. IfFalse
, only workflow outputs will be visible in the given history. - replacement_params (dict) – pattern-based replacements for post-job actions (see below)
Return type: dict
Returns: A dict containing the history ID where the outputs are placed as well as output dataset IDs. For example:
{u'history': u'64177123325c9cfd', u'outputs': [u'aa4d3084af404259']}
The
replacement_params
dict should map parameter names in post-job actions (PJAs) to their runtime values. For instance, if the final step has a PJA like the following:{u'RenameDatasetActionout_file1': { u'action_arguments': {u'newname': u'${output}'}, u'action_type': u'RenameDatasetAction', u'output_name': u'out_file1'}}
then the following renames the output dataset to ‘foo’:
replacement_params = {'output': 'foo'}
see also this thread
-
show_workflow
(workflow_id)[source]¶ Display information needed to run a workflow
Parameters: workflow_id (string) – Encoded workflow ID Return type: list Returns: A description of the workflow and its inputs as a JSON object. For example: {u'id': u'92c56938c2f9b315', u'inputs': {u'23': {u'label': u'Input Dataset', u'value': u''}}, u'name': u'Simple', u'url': u'/api/workflows/92c56938c2f9b315'}
-
Object-oriented Galaxy API¶
-
class
bioblend.galaxy.objects.galaxy_instance.
GalaxyInstance
(url, api_key=None, email=None, password=None)[source]¶ A representation of an instance of Galaxy, identified by a URL and a user’s API key.
Parameters: - url (str) – a FQDN or IP for a given instance of Galaxy. For example:
http://127.0.0.1:8080
- api_key (str) – user’s API key for the given instance of Galaxy, obtained from the Galaxy web UI.
This is actually a factory class which instantiates the entity-specific clients.
Example: get a list of all histories for a user with API key ‘foo’:
from bioblend.galaxy.objects import * gi = GalaxyInstance('http://127.0.0.1:8080', 'foo') histories = gi.histories.list()
-
histories
¶ Client module for Galaxy histories.
-
libraries
¶ Client module for Galaxy libraries.
-
tools
¶ Client module for Galaxy tools.
-
workflows
¶ Client module for Galaxy workflows.
- url (str) – a FQDN or IP for a given instance of Galaxy. For example:
Client¶
Clients for interacting with specific Galaxy entity types.
Classes in this module should not be instantiated directly, but used
via their handles in GalaxyInstance
.
-
class
bioblend.galaxy.objects.client.
ObjClient
(obj_gi)[source]¶ -
get_previews
(name=None, **kwargs)[source]¶ Get object previews (listings).
Previews model entity summaries provided by REST collection URIs, e.g.,
http://host:port/api/libraries
. Being the most lightweight objects associated to the various entities, these are the ones that should be used to retrieve basic info such as id and name.Parameters: name (str) – return only objects with this name Optional boolean kwargs for specific object types:
deleted
(libraries and histories)- if
True
, return only deleted objects published
(workflows)- if
True
, return published workflows
Return type: list of Preview
-
-
class
bioblend.galaxy.objects.client.
ObjHistoryClient
(obj_gi)[source]¶ Interacts with Galaxy histories.
-
create
(name=None)[source]¶ Create a new Galaxy history, optionally setting its name.
Return type: History
Returns: the history just created
-
delete
(id_=None, name=None, purge=False)[source]¶ Delete the history with the given id or name.
Note that the same name can map to multiple histories.
Parameters: purge (bool) – if True
, also purge the historyNote
For the purge option to work, the Galaxy instance must have the
allow_user_dataset_purge
option set toTrue
in theconfig/galaxy.ini
configuration file.
-
-
class
bioblend.galaxy.objects.client.
ObjLibraryClient
(obj_gi)[source]¶ Interacts with Galaxy libraries.
-
create
(name, description=None, synopsis=None)[source]¶ Create a data library with the properties defined in the arguments.
Return type: Library
Returns: the library just created
-
delete
(id_=None, name=None)[source]¶ Delete the library with the given id or name.
Note that the same name can map to multiple libraries.
Warning
Deleting a data library is irreversible - all of the data from the library will be permanently deleted.
-
-
class
bioblend.galaxy.objects.client.
ObjToolClient
(obj_gi)[source]¶ Interacts with Galaxy tools.
-
get
(id_)[source]¶ Retrieve the tool corresponding to the given id.
Return type: Tool
Returns: the tool corresponding to id_
-
-
class
bioblend.galaxy.objects.client.
ObjWorkflowClient
(obj_gi)[source]¶ Interacts with Galaxy workflows.
-
delete
(id_=None, name=None)[source]¶ Delete the workflow with the given id or name.
Note that the same name can map to multiple workflows.
Warning
Deleting a workflow is irreversible - all of the data from the workflow will be permanently deleted.
-
get
(id_)[source]¶ Retrieve the workflow corresponding to the given id.
Return type: Workflow
Returns: the workflow corresponding to id_
-
import_new
(src)[source]¶ Imports a new workflow into Galaxy.
Parameters: src (dict or str) – deserialized (dictionary) or serialized (str) JSON dump of the workflow (this is normally obtained by exporting a workflow from Galaxy). Return type: Workflow
Returns: the workflow just imported
Imports a shared workflow to the user’s space.
Parameters: id (str) – workflow id Return type: Workflow
Returns: the workflow just imported
-
Wrappers¶
A basic object-oriented interface for Galaxy entities.
-
class
bioblend.galaxy.objects.wrappers.
Wrapper
(wrapped, parent=None, gi=None)[source]¶ Abstract base class for Galaxy entity wrappers.
Wrapper instances wrap deserialized JSON dictionaries such as the ones obtained by the Galaxy web API, converting key-based access to attribute-based access (e.g.,
library['name'] -> library.name
).Dict keys that are converted to attributes are listed in the
BASE_ATTRS
class variable: this is the ‘stable’ interface. Note that the wrapped dictionary is accessible via thewrapped
attribute.Parameters: - wrapped (dict) – JSON-serializable dictionary
- parent (
Wrapper
) – the parent of this wrapper - gi (
GalaxyInstance
) – the GalaxyInstance through which we can access this wrapper
-
BASE_ATTRS
= ('id', 'name')¶
-
gi_module
¶ The GalaxyInstance module that deals with objects of this type.
-
is_mapped
¶ True
if this wrapper is mapped to an actual Galaxy entity.
-
class
bioblend.galaxy.objects.wrappers.
Step
(step_dict, parent)[source]¶ Abstract base class for workflow steps.
Steps are the main building blocks of a Galaxy workflow. A step can refer to either an input dataset (type ‘data_input`) or a computational tool (type ‘tool`).
-
BASE_ATTRS
= ('id', 'name', 'input_steps', 'tool_id', 'tool_inputs', 'tool_version', 'type')¶
-
gi_module
¶
-
-
class
bioblend.galaxy.objects.wrappers.
Workflow
(wf_dict, gi=None)[source]¶ Workflows represent ordered sequences of computations on Galaxy.
A workflow defines a sequence of steps that produce one or more results from an input dataset.
-
BASE_ATTRS
= ('id', 'name', 'deleted', 'inputs', 'published', 'steps', 'tags')¶
-
POLLING_INTERVAL
= 10¶
-
convert_input_map
(input_map)[source]¶ Convert
input_map
to the format required by the Galaxy web API.Parameters: input_map (dict) – a mapping from input labels to datasets Return type: dict Returns: a mapping from input slot ids to dataset ids in the format required by the Galaxy web API.
-
dag
¶
-
data_input_ids
¶ Return the list of data input steps for this workflow.
-
export
()[source]¶ Export a re-importable representation of the workflow.
Return type: dict Returns: a JSON-serializable dump of the workflow
-
gi_module
¶
-
input_labels
¶ Return the labels of this workflow’s input steps.
-
inv_dag
¶
-
is_runnable
¶ Return True if the workflow can be run on Galaxy.
A workflow is considered runnable on a Galaxy instance if all of the tools it uses are installed in that instance.
-
run
(input_map=None, history='', params=None, import_inputs=False, replacement_params=None, wait=False, polling_interval=10, break_on_error=True)[source]¶ Run the workflow in the current Galaxy instance.
Parameters: - input_map (dict) – a mapping from workflow input labels to
datasets, e.g.:
dict(zip(workflow.input_labels, library.get_datasets()))
- history (
History
or str) – either a valid history object (results will be stored there) or a string (a new history will be created with the given name). - params (
Mapping
) – parameter settings for workflow steps (see below) - import_inputs (bool) – If
True
, workflow inputs will be imported into the history; ifFalse
, only workflow outputs will be visible in the history. - replacement_params (
Mapping
) – pattern-based replacements for post-job actions (see the docs forrun_workflow()
) - wait (boolean) – whether to wait while the returned datasets are in a pending state
- polling_interval (float) – polling interval in seconds
- break_on_error (boolean) – whether to break as soon as at least one of the returned datasets is in the ‘error’ state
Return type: tuple
Returns: list of output datasets, output history
The
params
dict should be structured as follows:PARAMS = {STEP_ID: PARAM_DICT, ...} PARAM_DICT = {NAME: VALUE, ...}
For backwards compatibility, the following (deprecated) format is also supported:
PARAMS = {TOOL_ID: PARAM_DICT, ...}
in which case PARAM_DICT affects all steps with the given tool id. If both by-tool-id and by-step-id specifications are used, the latter takes precedence.
Finally (again, for backwards compatibility), PARAM_DICT can also be specified as:
PARAM_DICT = {'param': NAME, 'value': VALUE}
Note that this format allows only one parameter to be set per step.
Example: set ‘a’ to 1 for the third workflow step:
params = {workflow.steps[2].id: {'a': 1}}
Warning
This is a blocking operation that can take a very long time. If
wait
is set toFalse
, the method will return as soon as the workflow has been scheduled, otherwise it will wait until the workflow has been run. With a large number of steps, however, the delay may not be negligible even in the former case (e.g., minutes for 100 steps).- input_map (dict) – a mapping from workflow input labels to
datasets, e.g.:
-
tool_ids
¶ Return the list of tool steps for this workflow.
-
-
class
bioblend.galaxy.objects.wrappers.
ContentInfo
(info_dict, gi=None)[source]¶ Instances of this class wrap dictionaries obtained by getting
/api/{histories,libraries}/<ID>/contents
from Galaxy.-
BASE_ATTRS
= ('id', 'name', 'type')¶
-
-
class
bioblend.galaxy.objects.wrappers.
LibraryContentInfo
(info_dict, gi=None)[source]¶ Instances of this class wrap dictionaries obtained by getting
/api/libraries/<ID>/contents
from Galaxy.-
gi_module
¶
-
-
class
bioblend.galaxy.objects.wrappers.
HistoryContentInfo
(info_dict, gi=None)[source]¶ Instances of this class wrap dictionaries obtained by getting
/api/histories/<ID>/contents
from Galaxy.-
BASE_ATTRS
= ('id', 'name', 'type', 'deleted', 'state', 'visible')¶
-
gi_module
¶
-
-
class
bioblend.galaxy.objects.wrappers.
DatasetContainer
(c_dict, content_infos=None, gi=None)[source]¶ Abstract base class for dataset containers (histories and libraries).
Parameters: content_infos (list of ContentInfo
) – info objects for the container’s contents-
BASE_ATTRS
= ('id', 'name', 'deleted')¶
-
dataset_ids
¶
-
get_dataset
(ds_id)[source]¶ Retrieve the dataset corresponding to the given id.
Parameters: ds_id (str) – dataset id Return type: HistoryDatasetAssociation
orLibraryDataset
Returns: the dataset corresponding to ds_id
-
get_datasets
(name=None)[source]¶ Get all datasets contained inside this dataset container.
Parameters: name (str) – return only datasets with this name Return type: list of HistoryDatasetAssociation
or list ofLibraryDataset
Returns: datasets with the given name contained inside this container Note
when filtering library datasets by name, specify their full paths starting from the library’s root folder, e.g.,
/seqdata/reads.fastq
. Full paths are available through thecontent_infos
attribute ofLibrary
objects.
-
-
class
bioblend.galaxy.objects.wrappers.
History
(hist_dict, content_infos=None, gi=None)[source]¶ Maps to a Galaxy history.
-
API_MODULE
= 'histories'¶
-
BASE_ATTRS
= ('id', 'name', 'deleted', 'annotation', 'state_ids', 'tags')¶
-
CONTENT_INFO_TYPE
¶ alias of
HistoryContentInfo
-
DS_TYPE
¶ alias of
HistoryDatasetAssociation
-
download
(jeha_id, outf, chunk_size=4096)[source]¶ Download an export archive for this history. Use
export()
to create an export and get the requiredjeha_id
. Seedownload_history()
for parameter and return value info.
-
export
(gzip=True, include_hidden=False, include_deleted=False, wait=False)[source]¶ Start a job to create an export archive for this history. See
export_history()
for parameter and return value info.
-
gi_module
¶
-
import_dataset
(lds)[source]¶ Import a dataset into the history from a library.
Parameters: lds ( LibraryDataset
) – the library dataset to importReturn type: HistoryDatasetAssociation
Returns: the imported history dataset
-
paste_content
(content, **kwargs)[source]¶ Upload a string to a new dataset in this history.
Parameters: content (str) – content of the new dataset to upload See
upload_file()
for the optional parameters.Return type: HistoryDatasetAssociation
Returns: the uploaded dataset
-
update
(name=None, annotation=None, **kwds)[source]¶ Update history metadata information. Some of the attributes that can be modified are documented below.
Parameters: - name (string) – Replace history name with the given string
- annotation (string) – Replace history annotation with given string
- deleted (boolean) – Mark or unmark history as deleted
- published (boolean) – Mark or unmark history as published
- importable (boolean) – Mark or unmark history as importable
- tags (list) – Replace history tags with the given list
-
upload_dataset
(path, **kwargs)¶ Upload the file specified by path to this history.
Parameters: path (str) – path of the file to upload See
upload_file()
for the optional parameters.Return type: HistoryDatasetAssociation
Returns: the uploaded dataset
-
upload_file
(path, **kwargs)[source]¶ Upload the file specified by path to this history.
Parameters: path (str) – path of the file to upload See
upload_file()
for the optional parameters.Return type: HistoryDatasetAssociation
Returns: the uploaded dataset
-
-
class
bioblend.galaxy.objects.wrappers.
Library
(lib_dict, content_infos=None, gi=None)[source]¶ Maps to a Galaxy library.
-
API_MODULE
= 'libraries'¶
-
BASE_ATTRS
= ('id', 'name', 'deleted', 'description', 'synopsis')¶
-
CONTENT_INFO_TYPE
¶ alias of
LibraryContentInfo
-
DS_TYPE
¶ alias of
LibraryDataset
-
copy_from_dataset
(hda, folder=None, message='')[source]¶ Copy a history dataset into this library.
Parameters: hda ( HistoryDatasetAssociation
) – history dataset to copy into the librarySee
upload_data()
for info on other params.
-
create_folder
(name, description=None, base_folder=None)[source]¶ Create a folder in this library.
Parameters: - name (str) – folder name
- description (str) – optional folder description
- base_folder (
Folder
) – parent folder, orNone
to create in the root folder
Return type: Returns: the folder just created
-
folder_ids
¶
-
get_folder
(f_id)[source]¶ Retrieve the folder corresponding to the given id.
Return type: Folder
Returns: the folder corresponding to f_id
-
gi_module
¶
-
upload_data
(data, folder=None, **kwargs)[source]¶ Upload data to this library.
Parameters: - data (str) – dataset contents
- folder (
Folder
) – a folder object, orNone
to upload to the root folder
Return type: Returns: the dataset object that represents the uploaded content
Optional keyword arguments:
file_type
,dbkey
.
-
upload_from_galaxy_fs
(paths, folder=None, link_data_only=None, **kwargs)[source]¶ Upload data to this library from filesystem paths on the server.
Note
For this method to work, the Galaxy instance must have the
allow_library_path_paste
option set toTrue
in theconfig/galaxy.ini
configuration file.Parameters: - paths (str or
Iterable
of str) – server-side file paths from which data should be read - link_data_only (str) – either ‘copy_files’ (default) or ‘link_to_files’. Setting to ‘link_to_files’ symlinks instead of copying the files
Return type: list of
LibraryDataset
Returns: the dataset objects that represent the uploaded content
See
upload_data()
for info on other params.- paths (str or
-
upload_from_local
(path, folder=None, **kwargs)[source]¶ Upload data to this library from a local file.
Parameters: path (str) – local file path from which data should be read See
upload_data()
for info on other params.
-
upload_from_url
(url, folder=None, **kwargs)[source]¶ Upload data to this library from the given URL.
Parameters: url (str) – URL from which data should be read See
upload_data()
for info on other params.
-
-
class
bioblend.galaxy.objects.wrappers.
Folder
(f_dict, container_id, gi=None)[source]¶ Maps to a folder in a Galaxy library.
-
BASE_ATTRS
= ('id', 'name', 'description', 'item_count')¶
-
gi_module
¶
-
-
class
bioblend.galaxy.objects.wrappers.
Dataset
(ds_dict, container, gi=None)[source]¶ Abstract base class for Galaxy datasets.
-
BASE_ATTRS
= ('id', 'name', 'data_type', 'file_name', 'file_size', 'state', 'deleted', 'file_ext')¶
-
POLLING_INTERVAL
= 1¶
-
container_id
¶ Deprecated property.
Id of the dataset container. Use
container.id
instead.
-
download
(file_object, chunk_size=None)[source]¶ Open dataset for reading and save its contents to
file_object
.Parameters: outf ( file
) – output file objectSee
get_stream()
for info on other params.
-
get_contents
(chunk_size=None)[source]¶ Open dataset for reading and return its full contents.
See
get_stream()
for param info.
-
get_stream
(chunk_size=None)[source]¶ Open dataset for reading and return an iterator over its contents.
Parameters: chunk_size (int) – read this amount of bytes at a time Warning
Due to a change in the Galaxy API endpoint, this method does not work on
LibraryDataset
instances with Galaxyrelease_2014.06.02
andrelease_2014.08.11
. Methods that delegate work to this one are also affected:peek()
,download()
,get_contents()
.
-
peek
(chunk_size=None)[source]¶ Open dataset for reading and return the first chunk.
See
get_stream()
for param info.
-
-
class
bioblend.galaxy.objects.wrappers.
HistoryDatasetAssociation
(ds_dict, container, gi=None)[source]¶ Maps to a Galaxy
HistoryDatasetAssociation
.-
BASE_ATTRS
= ('id', 'name', 'data_type', 'file_name', 'file_size', 'state', 'deleted', 'file_ext', 'tags', 'visible')¶
-
SRC
= 'hda'¶
-
gi_module
¶
-
-
class
bioblend.galaxy.objects.wrappers.
LibraryDatasetDatasetAssociation
(ds_dict, container, gi=None)[source]¶ Maps to a Galaxy
LibraryDatasetDatasetAssociation
.-
SRC
= 'ldda'¶
-
-
class
bioblend.galaxy.objects.wrappers.
LibraryDataset
(ds_dict, container, gi=None)[source]¶ Maps to a Galaxy
LibraryDataset
.-
SRC
= 'ld'¶
-
-
class
bioblend.galaxy.objects.wrappers.
Tool
(t_dict, gi=None)[source]¶ Maps to a Galaxy tool.
-
BASE_ATTRS
= ('id', 'name', 'version')¶
-
POLLING_INTERVAL
= 10¶
-
gi_module
¶
-
run
(inputs, history, wait=False, polling_interval=10)[source]¶ Execute this tool in the given history with inputs from dict
inputs
.Parameters: - inputs (dict) – dictionary of input datasets and parameters for the tool (see below)
- history (
History
) – the history where to execute the tool - wait (boolean) – whether to wait while the returned datasets are in a pending state
- polling_interval (float) – polling interval in seconds
Return type: list of
HistoryDatasetAssociation
Returns: list of output datasets
The
inputs
dict should contain input datasets and parameters in the (largely undocumented) format used by the Galaxy API. Some examples can be found in Galaxy’s API test suite. The value of an input dataset can also be aDataset
object, which will be automatically converted to the needed format.
-
-
class
bioblend.galaxy.objects.wrappers.
Preview
(pw_dict, gi=None)[source]¶ Abstract base class for Galaxy entity ‘previews’.
Classes derived from this one model the short summaries returned by global getters such as
/api/libraries
.-
BASE_ATTRS
= ('id', 'name', 'deleted')¶
-
-
class
bioblend.galaxy.objects.wrappers.
LibraryPreview
(pw_dict, gi=None)[source]¶ Models Galaxy library ‘previews’.
Instances of this class wrap dictionaries obtained by getting
/api/libraries
from Galaxy.-
gi_module
¶
-