.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "BIOBLEND" "1" "Nov 23, 2022" "1.0.0" "BioBlend" .SH NAME bioblend \- BioBlend Documentation .SH ABOUT .sp \fI\%BioBlend\fP is a Python library for interacting with the \fI\%Galaxy\fP API. .sp BioBlend is supported and tested on: .INDENT 0.0 .IP \(bu 2 Python 3.7, 3.8, 3.9 and 3.10 .IP \(bu 2 Galaxy release 17.09 and later. .UNINDENT .sp BioBlend\(aqs goal is to make it easier to script and automate the running of Galaxy analyses and administering of a Galaxy server. In practice, it makes it possible to do things like this: .INDENT 0.0 .IP \(bu 2 Interact with Galaxy via a straightforward API: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C from bioblend.galaxy import GalaxyInstance gi = GalaxyInstance(\(aq\(aq, key=\(aqyour API key\(aq) libs = gi.libraries.get_libraries() gi.workflows.show_workflow(\(aqworkflow ID\(aq) wf_invocation = gi.workflows.invoke_workflow(\(aqworkflow ID\(aq, inputs) .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Interact with Galaxy via an object\-oriented API: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C from bioblend.galaxy.objects import GalaxyInstance gi = GalaxyInstance("URL", "API_KEY") wf = gi.workflows.list()[0] hist = gi.histories.list()[0] inputs = hist.get_datasets()[:2] input_map = dict(zip(wf.input_labels, inputs)) params = {"Paste1": {"delimiter": "U"}} wf_invocation = wf.invoke(input_map, params=params) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS About the library name .sp The library was originally called just \fBBlend\fP but we \fI\%renamed it\fP to reflect more of its domain and a make it bit more unique so it can be easier to find. The name was intended to be short and easily pronounceable. In its original implementation, the goal was to provide a lot more support for \fI\%CloudMan\fP and other integration capabilities, allowing them to be \fIblended\fP together via code. \fBBioBlend\fP fitted the bill. .SH INSTALLATION .sp Stable releases of BioBlend are best installed via \fBpip\fP from PyPI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ python3 \-m pip install bioblend .ft P .fi .UNINDENT .UNINDENT .sp Alternatively, the most current source code from our \fI\%Git repository\fP can be installed with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ python3 \-m pip install git+https://github.com/galaxyproject/bioblend .ft P .fi .UNINDENT .UNINDENT .sp After installing the library, you will be able to simply import it into your Python environment with \fBimport bioblend\fP\&. For details on the available functionality, see the \fI\%API documentation\fP\&. .sp BioBlend requires a number of Python libraries. These libraries are installed automatically when BioBlend itself is installed, regardless whether it is installed via \fI\%PyPi\fP or by running \fBpython3 setup.py install\fP command. The current list of required libraries is always available from \fI\%setup.py\fP in the source code repository. .sp If you also want to run tests locally, some extra libraries are required. To install them, run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ python3 setup.py test .ft P .fi .UNINDENT .UNINDENT .SH USAGE .sp To get started using BioBlend, install the library as described above. Once the library becomes available on the given system, it can be developed against. The developed scripts do not need to reside in any particular location on the system. .sp It is probably best to take a look at the example scripts in \fBdocs/examples\fP source directory and browse the \fI\%API documentation\fP\&. Beyond that, it\(aqs up to your creativity :). .SH DEVELOPMENT .sp Anyone interested in contributing or tweaking the library is more then welcome to do so. To start, simply fork the \fI\%Git repository\fP on Github and start playing with it. Then, issue pull requests. .SH API DOCUMENTATION .sp BioBlend\(aqs API focuses around and matches the services it wraps. Thus, there are two top\-level sets of APIs, each corresponding to a separate service and a corresponding step in the automation process. \fINote\fP that each of the service APIs can be used completely independently of one another. .sp Effort has been made to keep the structure and naming of those API\(aqs consistent across the library but because they do bridge different services, some discrepancies may exist. Feel free to point those out and/or provide fixes. .sp For Galaxy, an alternative \fI\%object\-oriented API\fP is also available. This API provides an explicit modeling of server\-side Galaxy instances and their relationships, providing higher\-level methods to perform operations such as retrieving all datasets for a given history, etc. Note that, at the moment, the oo API is still incomplete, providing access to a more restricted set of Galaxy modules with respect to the standard one. .SS Galaxy API .sp API used to manipulate genomic analyses within Galaxy, including data management and workflow execution. .SS API documentation for interacting with Galaxy .SS GalaxyInstance .sp .ce ---- .ce 0 .sp .SS Config .sp Contains possible interaction dealing with Galaxy configuration. .INDENT 0.0 .TP .B class bioblend.galaxy.config.ConfigClient(galaxy_instance: GalaxyInstance) A generic Client interface defining the common fields. .sp All clients \fImust\fP define the following field (which will be used as part of the URL composition (e.g., \fBhttp:///api/libraries\fP): \fBself.module = \(aqworkflows\(aq | \(aqlibraries\(aq | \(aqhistories\(aq | ...\fP .INDENT 7.0 .TP .B get_config() -> dict Get a list of attributes about the Galaxy instance. More attributes will be present if the user is an admin. .INDENT 7.0 .TP .B Return type list .TP .B Returns A list of attributes. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqallow_library_path_paste\(aq: False, \(aqallow_user_creation\(aq: True, \(aqallow_user_dataset_purge\(aq: True, \(aqallow_user_deletion\(aq: False, \(aqenable_unique_workflow_defaults\(aq: False, \(aqftp_upload_dir\(aq: \(aq/SOMEWHERE/galaxy/ftp_dir\(aq, \(aqftp_upload_site\(aq: \(aqgalaxy.com\(aq, \(aqlibrary_import_dir\(aq: \(aqNone\(aq, \(aqlogo_url\(aq: None, \(aqsupport_url\(aq: \(aqhttps://galaxyproject.org/support\(aq, \(aqterms_url\(aq: None, \(aquser_library_import_dir\(aq: None, \(aqwiki_url\(aq: \(aqhttps://galaxyproject.org/\(aq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_version() -> dict Get the current version of the Galaxy instance. .INDENT 7.0 .TP .B Return type dict .TP .B Returns Version of the Galaxy instance For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqextra\(aq: {}, \(aqversion_major\(aq: \(aq17.01\(aq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B module: str = \(aqconfiguration\(aq .UNINDENT .INDENT 7.0 .TP .B whoami() -> dict Return information about the current authenticated user. .INDENT 7.0 .TP .B Return type dict .TP .B Returns Information about current authenticated user For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqactive\(aq: True, \(aqdeleted\(aq: False, \(aqemail\(aq: \(aquser@example.org\(aq, \(aqid\(aq: \(aq4aaaaa85aacc9caa\(aq, \(aqlast_password_change\(aq: \(aq2021\-07\-29T05:34:54.632345\(aq, \(aqmodel_class\(aq: \(aqUser\(aq, \(aqusername\(aq: \(aqjulia\(aq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp .ce ---- .ce 0 .sp .SS Datasets .sp .ce ---- .ce 0 .sp .SS Dataset collections .sp .ce ---- .ce 0 .sp .SS Datatypes .sp .ce ---- .ce 0 .sp .SS Folders .sp .ce ---- .ce 0 .sp .SS Forms .sp .ce ---- .ce 0 .sp .SS FTP files .sp .ce ---- .ce 0 .sp .SS Genomes .SS Groups .sp .ce ---- .ce 0 .sp .SS Histories .sp .ce ---- .ce 0 .sp .SS Invocations .sp .ce ---- .ce 0 .sp .SS Jobs .sp .ce ---- .ce 0 .sp .SS Libraries .sp .ce ---- .ce 0 .sp .SS Quotas .sp .ce ---- .ce 0 .sp .SS Roles .sp .ce ---- .ce 0 .sp .SS Tools .sp .ce ---- .ce 0 .sp .SS Tool data tables .sp .ce ---- .ce 0 .sp .SS Tool dependencies .sp .ce ---- .ce 0 .sp .SS ToolShed .sp .ce ---- .ce 0 .sp .SS Users .sp .ce ---- .ce 0 .sp .SS Visual .sp .ce ---- .ce 0 .sp .SS Workflows .SS Object\-oriented Galaxy API .SS Client .SS Wrappers .SS Usage documentation .sp This page describes some sample use cases for the Galaxy API and provides examples for these API calls. In addition to this page, there are functional examples of complete scripts in the \fBdocs/examples\fP directory of the BioBlend source code repository. .SS Connect to a Galaxy server .sp To connect to a running Galaxy server, you will need an account on that Galaxy instance and an API key for the account. Instructions on getting an API key can be found at \fI\%https://galaxyproject.org/develop/api/\fP . .sp To open a connection call: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from bioblend.galaxy import GalaxyInstance gi = GalaxyInstance(url=\(aqhttp://example.galaxy.url\(aq, key=\(aqyour\-API\-key\(aq) .ft P .fi .UNINDENT .UNINDENT .sp We now have a \fBGalaxyInstance\fP object which allows us to interact with the Galaxy server under our account, and access our data. If the account is a Galaxy admin account we also will be able to use this connection to carry out admin actions. .SS View Histories and Datasets .sp Methods for accessing histories and datasets are grouped under \fBGalaxyInstance.histories.*\fP and \fBGalaxyInstance.datasets.*\fP respectively. .sp To get information on the Histories currently in your account, call: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.histories.get_histories() [{\(aqid\(aq: \(aqf3c2b0f3ecac9f02\(aq, \(aqname\(aq: \(aqRNAseq_DGE_BASIC_Prep\(aq, \(aqurl\(aq: \(aq/api/histories/f3c2b0f3ecac9f02\(aq}, {\(aqid\(aq: \(aq8a91dcf1866a80c2\(aq, \(aqname\(aq: \(aqJune demo\(aq, \(aqurl\(aq: \(aq/api/histories/8a91dcf1866a80c2\(aq}] .ft P .fi .UNINDENT .UNINDENT .sp This returns a list of dictionaries containing basic metadata, including the id and name of each History. In this case, we have two existing Histories in our account, \(aqRNAseq_DGE_BASIC_Prep\(aq and \(aqJune demo\(aq. To get more detailed information about a History we can pass its id to the \fBshow_history\fP method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.histories.show_history(\(aqf3c2b0f3ecac9f02\(aq, contents=False) {\(aqannotation\(aq: \(aq\(aq, \(aqcontents_url\(aq: \(aq/api/histories/f3c2b0f3ecac9f02/contents\(aq, \(aqid\(aq: \(aqf3c2b0f3ecac9f02\(aq, \(aqname\(aq: \(aqRNAseq_DGE_BASIC_Prep\(aq, \(aqnice_size\(aq: \(aq93.5 MB\(aq, \(aqstate\(aq: \(aqok\(aq, \(aqstate_details\(aq: {\(aqdiscarded\(aq: 0, \(aqempty\(aq: 0, \(aqerror\(aq: 0, \(aqfailed_metadata\(aq: 0, \(aqnew\(aq: 0, \(aqok\(aq: 7, \(aqpaused\(aq: 0, \(aqqueued\(aq: 0, \(aqrunning\(aq: 0, \(aqsetting_metadata\(aq: 0, \(aqupload\(aq: 0}, \(aqstate_ids\(aq: {\(aqdiscarded\(aq: [], \(aqempty\(aq: [], \(aqerror\(aq: [], \(aqfailed_metadata\(aq: [], \(aqnew\(aq: [], \(aqok\(aq: [\(aqd6842fb08a76e351\(aq, \(aq10a4b652da44e82a\(aq, \(aq81c601a2549966a0\(aq, \(aqa154f05e3bcee26b\(aq, \(aq1352fe19ddce0400\(aq, \(aq06d549c52d753e53\(aq, \(aq9ec54455d6279cc7\(aq], \(aqpaused\(aq: [], \(aqqueued\(aq: [], \(aqrunning\(aq: [], \(aqsetting_metadata\(aq: [], \(aqupload\(aq: []}} .ft P .fi .UNINDENT .UNINDENT .sp This gives us a dictionary containing the History\(aqs metadata. With \fBcontents=False\fP (the default), we only get a list of ids of the datasets contained within the History; with \fBcontents=True\fP we would get metadata on each dataset. We can also directly access more detailed information on a particular dataset by passing its id to the \fBshow_dataset\fP method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.datasets.show_dataset(\(aq10a4b652da44e82a\(aq) {\(aqdata_type\(aq: \(aqfastqsanger\(aq, \(aqdeleted\(aq: False, \(aqfile_size\(aq: 16527060, \(aqgenome_build\(aq: \(aqdm3\(aq, \(aqid\(aq: 17499, \(aqmetadata_data_lines\(aq: None, \(aqmetadata_dbkey\(aq: \(aqdm3\(aq, \(aqmetadata_sequences\(aq: None, \(aqmisc_blurb\(aq: \(aq15.8 MB\(aq, \(aqmisc_info\(aq: \(aqNoneuploaded fastqsanger file\(aq, \(aqmodel_class\(aq: \(aqHistoryDatasetAssociation\(aq, \(aqname\(aq: \(aqC1_R2_1.chr4.fq\(aq, \(aqpurged\(aq: False, \(aqstate\(aq: \(aqok\(aq, \(aqvisible\(aq: True} .ft P .fi .UNINDENT .UNINDENT .SS Uploading Datasets to a History .sp To upload a local file to a Galaxy server, you can run the \fBupload_file\fP method, supplying the path to a local file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.tools.upload_file(\(aqtest.txt\(aq, \(aqf3c2b0f3ecac9f02\(aq) {\(aqimplicit_collections\(aq: [], \(aqjobs\(aq: [{\(aqcreate_time\(aq: \(aq2015\-07\-28T17:52:39.756488\(aq, \(aqexit_code\(aq: None, \(aqid\(aq: \(aq9752b387803d3e1e\(aq, \(aqmodel_class\(aq: \(aqJob\(aq, \(aqstate\(aq: \(aqnew\(aq, \(aqtool_id\(aq: \(aqupload1\(aq, \(aqupdate_time\(aq: \(aq2015\-07\-28T17:52:39.987509\(aq}], \(aqoutput_collections\(aq: [], \(aqoutputs\(aq: [{\(aqcreate_time\(aq: \(aq2015\-07\-28T17:52:39.331176\(aq, \(aqdata_type\(aq: \(aqgalaxy.datatypes.data.Text\(aq, \(aqdeleted\(aq: False, \(aqfile_ext\(aq: \(aqauto\(aq, \(aqfile_size\(aq: 0, \(aqgenome_build\(aq: \(aq?\(aq, \(aqhda_ldda\(aq: \(aqhda\(aq, \(aqhid\(aq: 16, \(aqhistory_content_type\(aq: \(aqdataset\(aq, \(aqhistory_id\(aq: \(aqf3c2b0f3ecac9f02\(aq, \(aqid\(aq: \(aq59c76a119581e190\(aq, \(aqmetadata_data_lines\(aq: None, \(aqmetadata_dbkey\(aq: \(aq?\(aq, \(aqmisc_blurb\(aq: None, \(aqmisc_info\(aq: None, \(aqmodel_class\(aq: \(aqHistoryDatasetAssociation\(aq, \(aqname\(aq: \(aqtest.txt\(aq, \(aqoutput_name\(aq: \(aqoutput0\(aq, \(aqpeek\(aq: \(aq
\(aq, \(aqpurged\(aq: False, \(aqstate\(aq: \(aqqueued\(aq, \(aqtags\(aq: [], \(aqupdate_time\(aq: \(aq2015\-07\-28T17:52:39.611887\(aq, \(aquuid\(aq: \(aqff0ee99b\-7542\-4125\-802d\-7a193f388e7e\(aq, \(aqvisible\(aq: True}]} .ft P .fi .UNINDENT .UNINDENT .sp If files are greater than 2GB in size, they will need to be uploaded via FTP. Importing files from the user\(aqs FTP folder can be done via running the upload tool again: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.tools.upload_from_ftp(\(aqtest.txt\(aq, \(aqf3c2b0f3ecac9f02\(aq) {\(aqimplicit_collections\(aq: [], \(aqjobs\(aq: [{\(aqcreate_time\(aq: \(aq2015\-07\-28T17:57:43.704394\(aq, \(aqexit_code\(aq: None, \(aqid\(aq: \(aq82b264d8c3d11790\(aq, \(aqmodel_class\(aq: \(aqJob\(aq, \(aqstate\(aq: \(aqnew\(aq, \(aqtool_id\(aq: \(aqupload1\(aq, \(aqupdate_time\(aq: \(aq2015\-07\-28T17:57:43.910958\(aq}], \(aqoutput_collections\(aq: [], \(aqoutputs\(aq: [{\(aqcreate_time\(aq: \(aq2015\-07\-28T17:57:43.209041\(aq, \(aqdata_type\(aq: \(aqgalaxy.datatypes.data.Text\(aq, \(aqdeleted\(aq: False, \(aqfile_ext\(aq: \(aqauto\(aq, \(aqfile_size\(aq: 0, \(aqgenome_build\(aq: \(aq?\(aq, \(aqhda_ldda\(aq: \(aqhda\(aq, \(aqhid\(aq: 17, \(aqhistory_content_type\(aq: \(aqdataset\(aq, \(aqhistory_id\(aq: \(aqf3c2b0f3ecac9f02\(aq, \(aqid\(aq: \(aqa676e8f07209a3be\(aq, \(aqmetadata_data_lines\(aq: None, \(aqmetadata_dbkey\(aq: \(aq?\(aq, \(aqmisc_blurb\(aq: None, \(aqmisc_info\(aq: None, \(aqmodel_class\(aq: \(aqHistoryDatasetAssociation\(aq, \(aqname\(aq: \(aqtest.txt\(aq, \(aqoutput_name\(aq: \(aqoutput0\(aq, \(aqpeek\(aq: \(aq
\(aq, \(aqpurged\(aq: False, \(aqstate\(aq: \(aqqueued\(aq, \(aqtags\(aq: [], \(aqupdate_time\(aq: \(aq2015\-07\-28T17:57:43.544407\(aq, \(aquuid\(aq: \(aq2cbe8f0a\-4019\-47c4\-87e2\-005ce35b8449\(aq, \(aqvisible\(aq: True}]} .ft P .fi .UNINDENT .UNINDENT .SS View Data Libraries .sp Methods for accessing Data Libraries are grouped under \fBGalaxyInstance.libraries.*\fP\&. Most Data Library methods are available to all users, but as only administrators can create new Data Libraries within Galaxy, the \fBcreate_folder\fP and \fBcreate_library\fP methods can only be called using an API key belonging to an admin account. .sp We can view the Data Libraries available to our account using: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.libraries.get_libraries() [{\(aqid\(aq: \(aq8e6f930d00d123ea\(aq, \(aqname\(aq: \(aqRNA\-seq workshop data\(aq, \(aqurl\(aq: \(aq/api/libraries/8e6f930d00d123ea\(aq}, {\(aqid\(aq: \(aqf740ab636b360a70\(aq, \(aqname\(aq: \(aq1000 genomes\(aq, \(aqurl\(aq: \(aq/api/libraries/f740ab636b360a70\(aq}] .ft P .fi .UNINDENT .UNINDENT .sp This gives a list of metadata dictionaries with basic information on each library. We can get more information on a particular Data Library by passing its id to the \fBshow_library\fP method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.libraries.show_library(\(aq8e6f930d00d123ea\(aq) {\(aqcontents_url\(aq: \(aq/api/libraries/8e6f930d00d123ea/contents\(aq, \(aqdescription\(aq: \(aqRNA\-Seq workshop data\(aq, \(aqname\(aq: \(aqRNA\-Seq\(aq, \(aqsynopsis\(aq: \(aqData for the RNA\-Seq tutorial\(aq} .ft P .fi .UNINDENT .UNINDENT .SS Upload files to a Data Library .sp We can get files into Data Libraries in several ways: by uploading from our local machine, by retrieving from a URL, by passing the new file content directly into the method, or by importing a file from the filesystem on the Galaxy server. .sp For instance, to upload a file from our machine we might call: .sp .nf .ft C >>> gi.libraries.upload_file_from_local_path(\(aq8e6f930d00d123ea\(aq, \(aq/local/path/to/mydata.fastq\(aq, file_type=\(aqfastqsanger\(aq) .ft P .fi .sp Note that we have provided the id of the destination Data Library, and in this case we have specified the type that Galaxy should assign to the new dataset. The default value for \fBfile_type\fP is \(aqauto\(aq, in which case Galaxy will attempt to guess the dataset type. .SS View Workflows .sp Methods for accessing workflows are grouped under \fBGalaxyInstance.workflows.*\fP\&. .sp To get information on the Workflows currently in your account, use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.workflows.get_workflows() [{\(aqid\(aq: \(aqe8b85ad72aefca86\(aq, \(aqname\(aq: \(aqTopHat + cufflinks part 1\(aq, \(aqurl\(aq: \(aq/api/workflows/e8b85ad72aefca86\(aq}, {\(aqid\(aq: \(aqb0631c44aa74526d\(aq, \(aqname\(aq: \(aqCuffDiff\(aq, \(aqurl\(aq: \(aq/api/workflows/b0631c44aa74526d\(aq}] .ft P .fi .UNINDENT .UNINDENT .sp This returns a list of metadata dictionaries. We can get the details of a particular Workflow, including its steps, by passing its id to the \fBshow_workflow\fP method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.workflows.show_workflow(\(aqe8b85ad72aefca86\(aq) {\(aqid\(aq: \(aqe8b85ad72aefca86\(aq, \(aqinputs\(aq: {\(aq252\(aq: {\(aqlabel\(aq: \(aqInput RNA\-seq fastq\(aq, \(aqvalue\(aq: \(aq\(aq}}, \(aqname\(aq: \(aqTopHat + cufflinks part 1\(aq, \(aqsteps\(aq: {\(aq250\(aq: {\(aqid\(aq: 250, \(aqinput_steps\(aq: {\(aqinput1\(aq: {\(aqsource_step\(aq: 252, \(aqstep_output\(aq: \(aqoutput\(aq}}, \(aqtool_id\(aq: \(aqtophat\(aq, \(aqtype\(aq: \(aqtool\(aq}, \(aq251\(aq: {\(aqid\(aq: 251, \(aqinput_steps\(aq: {\(aqinput\(aq: {\(aqsource_step\(aq: 250, \(aqstep_output\(aq: \(aqaccepted_hits\(aq}}, \(aqtool_id\(aq: \(aqcufflinks\(aq, \(aqtype\(aq: \(aqtool\(aq}, \(aq252\(aq: {\(aqid\(aq: 252, \(aqinput_steps\(aq: {}, \(aqtool_id\(aq: None, \(aqtype\(aq: \(aqdata_input\(aq}}, \(aqurl\(aq: \(aq/api/workflows/e8b85ad72aefca86\(aq} .ft P .fi .UNINDENT .UNINDENT .SS Export or import a workflow .sp Workflows can be exported from or imported into Galaxy. This makes it possible to archive workflows, or to move them between Galaxy instances. .sp To export a workflow, we can call: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> workflow_dict = gi.workflows.export_workflow_dict(\(aqe8b85ad72aefca86\(aq) .ft P .fi .UNINDENT .UNINDENT .sp This gives us a complex dictionary representing the workflow. We can import this dictionary as a new workflow with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.workflows.import_workflow_dict(workflow_dict) {\(aqid\(aq: \(aqc0bacafdfe211f9a\(aq, \(aqname\(aq: \(aqTopHat + cufflinks part 1 (imported from API)\(aq, \(aqurl\(aq: \(aq/api/workflows/c0bacafdfe211f9a\(aq} .ft P .fi .UNINDENT .UNINDENT .sp This call returns a dictionary containing basic metadata on the new workflow. Since in this case we have imported the dictionary into the original Galaxy instance, we now have a duplicate of the original workflow in our account: .sp .nf .ft C >>> gi.workflows.get_workflows() [{\(aqid\(aq: \(aqc0bacafdfe211f9a\(aq, \(aqname\(aq: \(aqTopHat + cufflinks part 1 (imported from API)\(aq, \(aqurl\(aq: \(aq/api/workflows/c0bacafdfe211f9a\(aq}, {\(aqid\(aq: \(aqe8b85ad72aefca86\(aq, \(aqname\(aq: \(aqTopHat + cufflinks part 1\(aq, \(aqurl\(aq: \(aq/api/workflows/e8b85ad72aefca86\(aq}, {\(aqid\(aq: \(aqb0631c44aa74526d\(aq, \(aqname\(aq: \(aqCuffDiff\(aq, \(aqurl\(aq: \(aq/api/workflows/b0631c44aa74526d\(aq}] .ft P .fi .sp Instead of using dictionaries directly, workflows can be exported to or imported from files on the local disk using the \fBexport_workflow_to_local_path\fP and \fBimport_workflow_from_local_path\fP methods. See the \fI\%API reference\fP for details. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If we export a workflow from one Galaxy instance and import it into another, Galaxy will only run it without modification if it has the same versions of the tool wrappers installed. This is to ensure reproducibility. Otherwise, we will need to manually update the workflow to use the new tool versions. .UNINDENT .UNINDENT .SS Invoke a workflow .sp To invoke a workflow, we need to tell Galaxy which datasets to use for which workflow inputs. We can use datasets from histories or data libraries. .sp Examine the workflow above. We can see that it takes only one input file. That is: .sp .nf .ft C >>> wf = gi.workflows.show_workflow(\(aqe8b85ad72aefca86\(aq) >>> wf[\(aqinputs\(aq] {\(aq252\(aq: {\(aqlabel\(aq: \(aqInput RNA\-seq fastq\(aq, \(aqvalue\(aq: \(aq\(aq}} .ft P .fi .sp There is one input, labelled \(aqInput RNA\-seq fastq\(aq. This input is passed to the Tophat tool and should be a fastq file. We will use the dataset we examined above, under \fI\%View Histories and Datasets\fP, which had name \(aqC1_R2_1.chr4.fq\(aq and id \(aq10a4b652da44e82a\(aq. .sp To specify the inputs, we build a data map and pass this to the \fBinvoke_workflow\fP method. This data map is a nested dictionary object which maps inputs to datasets. We call: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> datamap = {\(aq252\(aq: {\(aqsrc\(aq:\(aqhda\(aq, \(aqid\(aq:\(aq10a4b652da44e82a\(aq}} >>> gi.workflows.invoke_workflow(\(aqe8b85ad72aefca86\(aq, inputs=datamap, history_name=\(aqNew output history\(aq) {\(aqhistory\(aq: \(aq0a7b7992a7cabaec\(aq, \(aqoutputs\(aq: [\(aq33be8ad9917d9207\(aq, \(aqfbee1c2dc793c114\(aq, \(aq85866441984f9e28\(aq, \(aq1c51aa78d3742386\(aq, \(aqa68e8770e52d03b4\(aq, \(aqc54baf809e3036ac\(aq, \(aqba0db8ce6cd1fe8f\(aq, \(aqc019e4cf08b2ac94\(aq]} .ft P .fi .UNINDENT .UNINDENT .sp In this case the only input id is \(aq252\(aq and the corresponding dataset id is \(aq10a4b652da44e82a\(aq. We have specified the dataset source to be \(aqhda\(aq (HistoryDatasetAssociation) since the dataset is stored in a History. See the \fI\%API reference\fP for allowed dataset specifications. We have also requested that a new History be created and used to store the results of the run, by setting \fBhistory_name=\(aqNew output history\(aq\fP\&. .sp The \fBinvoke_workflow\fP call submits all the jobs which need to be run to the Galaxy workflow engine, with the appropriate dependencies so that they will run in order. The call returns immediately, so we can continue to submit new jobs while waiting for this workflow to execute. \fBinvoke_workflow\fP returns the a dictionary describing the workflow invocation. .sp If we view the output History immediately after calling \fBinvoke_workflow\fP, we will see something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> gi.histories.show_history(\(aq0a7b7992a7cabaec\(aq) {\(aqannotation\(aq: \(aq\(aq, \(aqcontents_url\(aq: \(aq/api/histories/0a7b7992a7cabaec/contents\(aq, \(aqid\(aq: \(aq0a7b7992a7cabaec\(aq, \(aqname\(aq: \(aqNew output history\(aq, \(aqnice_size\(aq: \(aq0 bytes\(aq, \(aqstate\(aq: \(aqqueued\(aq, \(aqstate_details\(aq: {\(aqdiscarded\(aq: 0, \(aqempty\(aq: 0, \(aqerror\(aq: 0, \(aqfailed_metadata\(aq: 0, \(aqnew\(aq: 0, \(aqok\(aq: 0, \(aqpaused\(aq: 0, \(aqqueued\(aq: 8, \(aqrunning\(aq: 0, \(aqsetting_metadata\(aq: 0, \(aqupload\(aq: 0}, \(aqstate_ids\(aq: {\(aqdiscarded\(aq: [], \(aqempty\(aq: [], \(aqerror\(aq: [], \(aqfailed_metadata\(aq: [], \(aqnew\(aq: [], \(aqok\(aq: [], \(aqpaused\(aq: [], \(aqqueued\(aq: [\(aq33be8ad9917d9207\(aq, \(aqfbee1c2dc793c114\(aq, \(aq85866441984f9e28\(aq, \(aq1c51aa78d3742386\(aq, \(aqa68e8770e52d03b4\(aq, \(aqc54baf809e3036ac\(aq, \(aqba0db8ce6cd1fe8f\(aq, \(aqc019e4cf08b2ac94\(aq], \(aqrunning\(aq: [], \(aqsetting_metadata\(aq: [], \(aqupload\(aq: []}} .ft P .fi .UNINDENT .UNINDENT .sp In this case, because the submitted jobs have not had time to run, the output History contains 8 datasets in the \(aqqueued\(aq state and has a total size of 0 bytes. If we make this call again later we should instead see completed output files. .SS View Users .sp Methods for managing users are grouped under \fBGalaxyInstance.users.*\fP\&. User management is only available to Galaxy administrators, that is, the API key used to connect to Galaxy must be that of an admin account. .sp To get a list of users, call: .sp .nf .ft C >>> gi.users.get_users() [{\(aqemail\(aq: \(aquserA@example.org\(aq, \(aqid\(aq: \(aq975a9ce09b49502a\(aq, \(aqquota_percent\(aq: None, \(aqurl\(aq: \(aq/api/users/975a9ce09b49502a\(aq}, {\(aqemail\(aq: \(aquserB@example.org\(aq, \(aqid\(aq: \(aq0193a95acf427d2c\(aq, \(aqquota_percent\(aq: None, \(aqurl\(aq: \(aq/api/users/0193a95acf427d2c\(aq}] .ft P .fi .SS Using BioBlend for raw API calls .sp BioBlend can be used to make HTTP requests to the Galaxy API in a more convenient way than using e.g. the \fBrequests\fP Python library. There are 5 available methods corresponding to the most common HTTP methods: \fBmake_get_request\fP, \fBmake_post_request\fP, \fBmake_put_request\fP, \fBmake_delete_request\fP and \fBmake_patch_request\fP\&. One advantage of using these methods is that the API keys stored in the \fBGalaxyInstance\fP object is automatically added to the request. .sp To make a GET request to the Galaxy API with BioBlend, call: .sp .nf .ft C >>> gi.make_get_request(gi.base_url + "/api/version").json() {\(aqversion_major\(aq: \(aq19.05\(aq, \(aqextra\(aq: {}} .ft P .fi .sp To make a POST request to the Galaxy API with BioBlend, call: .sp .nf .ft C >>> gi.make_post_request(gi.base_url + "/api/histories", payload={"name": "test history"}) {\(aqimportable\(aq: False, \(aqcreate_time\(aq: \(aq2019\-07\-05T20:10:04.823716\(aq, \(aqcontents_url\(aq: \(aq/api/histories/a77b3f95070d689a/contents\(aq, \(aqid\(aq: \(aqa77b3f95070d689a\(aq, \(aqsize\(aq: 0, \(aquser_id\(aq: \(aq5b732999121d4593\(aq, \(aqusername_and_slug\(aq: None, \(aqannotation\(aq: None, \(aqstate_details\(aq: {\(aqdiscarded\(aq: 0, \(aqok\(aq: 0, \(aqfailed_metadata\(aq: 0, \(aqupload\(aq: 0, \(aqpaused\(aq: 0, \(aqrunning\(aq: 0, \(aqsetting_metadata\(aq: 0, \(aqerror\(aq: 0, \(aqnew\(aq: 0, \(aqqueued\(aq: 0, \(aqempty\(aq: 0}, \(aqstate\(aq: \(aqnew\(aq, \(aqempty\(aq: True, \(aqupdate_time\(aq: \(aq2019\-07\-05T20:10:04.823742\(aq, \(aqtags\(aq: [], \(aqdeleted\(aq: False, \(aqgenome_build\(aq: None, \(aqslug\(aq: None, \(aqname\(aq: \(aqtest history\(aq, \(aqurl\(aq: \(aq/api/histories/a77b3f95070d689a\(aq, \(aqstate_ids\(aq: {\(aqdiscarded\(aq: [], \(aqok\(aq: [], \(aqfailed_metadata\(aq: [], \(aqupload\(aq: [], \(aqpaused\(aq: [], \(aqrunning\(aq: [], \(aqsetting_metadata\(aq: [], \(aqerror\(aq: [], \(aqnew\(aq: [], \(aqqueued\(aq: [], \(aqempty\(aq: []}, \(aqpublished\(aq: False, \(aqmodel_class\(aq: \(aqHistory\(aq, \(aqpurged\(aq: False} .ft P .fi .SS Toolshed API .sp API used to interact with the Galaxy Toolshed, including repository management. .SS API documentation for interacting with the Galaxy Toolshed .SS ToolShedInstance .SS Categories .SS Repositories .SS Tools .SH CONFIGURATION .sp BioBlend allows library\-wide configuration to be set in external files. These configuration files can be used to specify access keys, for example. .SS Configuration documents for BioBlend .SS BioBlend .INDENT 0.0 .TP .B exception bioblend.ConnectionError(message: str, body: Optional[Union[bytes, str]] = None, status_code: Optional[int] = None) An exception class that is raised when unexpected HTTP responses come back. .sp Should make it easier to debug when strange HTTP things happen such as a proxy server getting in the way of the request etc. @see: body attribute to see the content of the http response .UNINDENT .INDENT 0.0 .TP .B class bioblend.NullHandler(level=0) Initializes the instance \- basically setting the formatter to None and the filter list to empty. .INDENT 7.0 .TP .B emit(record: logging.LogRecord) -> None Do whatever it takes to actually log the specified logging record. .sp This version is intended to be implemented by subclasses and so raises a NotImplementedError. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception bioblend.TimeoutException .UNINDENT .INDENT 0.0 .TP .B bioblend.get_version() -> str Returns a string with the current version of the library (e.g., "0.2.0") .UNINDENT .INDENT 0.0 .TP .B bioblend.init_logging() -> None Initialize BioBlend\(aqs logging from a configuration file. .UNINDENT .INDENT 0.0 .TP .B bioblend.set_file_logger(name: str, filepath: str, level: Union[int, str] = 20, format_string: Optional[str] = None) -> None .UNINDENT .INDENT 0.0 .TP .B bioblend.set_stream_logger(name: str, level: Union[int, str] = 10, format_string: Optional[str] = None) -> None .UNINDENT .SS Config .INDENT 0.0 .TP .B class bioblend.config.Config(path: Optional[str] = None, fp: Optional[IO[str]] = None, do_load: bool = True) BioBlend allows library\-wide configuration to be set in external files. These configuration files can be used to specify access keys, for example. By default we use two locations for the BioBlend configurations: .INDENT 7.0 .IP \(bu 2 System wide: \fB/etc/bioblend.cfg\fP .IP \(bu 2 Individual user: \fB~/.bioblend\fP (which works on both Windows and Unix) .UNINDENT .UNINDENT .SH TESTING .sp If you would like to do more than just a mock test, you need to point BioBlend to an instance of Galaxy. Do so by exporting the following two variables: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ export BIOBLEND_GALAXY_URL=http://127.0.0.1:8080 $ export BIOBLEND_GALAXY_API_KEY= .ft P .fi .UNINDENT .UNINDENT .sp The unit tests, stored in the \fBtests\fP folder, can be run using \fI\%pytest\fP\&. From the project root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pytest .ft P .fi .UNINDENT .UNINDENT .SH GETTING HELP .sp If you have run into issues, found a bug, or can\(aqt seem to find an answer to your question regarding the use and functionality of BioBlend, please use the \fI\%Github Issues\fP page to ask your question. .SH RELATED DOCUMENTATION .sp Links to other documentation and libraries relevant to this library: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%Galaxy API documentation\fP .IP \(bu 2 \fI\%Blend4j\fP: Galaxy API wrapper for Java .IP \(bu 2 \fI\%clj\-blend\fP: Galaxy API wrapper for Clojure .UNINDENT .UNINDENT .UNINDENT .SH INDICES AND TABLES .INDENT 0.0 .IP \(bu 2 \fI\%Index\fP .IP \(bu 2 \fI\%Module Index\fP .IP \(bu 2 \fI\%Search Page\fP .UNINDENT .SH AUTHOR Enis Afgan .SH COPYRIGHT 2012-2022, Enis Afgan .\" Generated by docutils manpage writer. .