Galaxy Code Documentation Release
Total Page:16
File Type:pdf, Size:1020Kb
Galaxy Code Documentation Release Galaxy Team June 29, 2015 Contents 1 Contents 3 1.1 Galaxy API Documentation.......................................3 1.2 lib..................................................... 43 1.3 Releases................................................. 370 2 Indices and tables 377 Python Module Index 379 i ii Galaxy Code Documentation, Release Galaxy is an open, web-based platform for accessible, reproducible, and transparent computational biomedical re- search. • Accessible: Users without programming experience can easily specify parameters and run tools and workflows. • Reproducible: Galaxy captures information so that any user can repeat and understand a complete computational analysis. • Transparent: Users share and publish analyses via the web and create Pages, interactive, web-based documents that describe a complete analysis. Two copies of the Galaxy code doumentation are published by the Galaxy Project • Galaxy-Dist: This describes the code in the most recent official release of Galaxy. • Galaxy-Central: Describes the current code in the development branch of Galaxy. This is the latest checkin, bleeding edge version of the code. The documentation should never be more than an hour behind the code. Both copies are hosted at ReadTheDocs, a publicly supported web site for hosting project documentation. If you have your own copy of the Galaxy source code, you can also generate your own version of this documentation: $ cd doc $ make html The generated documentation will be in doc/build/html/ and can be viewed with a web browser. Note that you will need to install Sphinx and a fair number of module dependencies before this will produce output. For more on the Galaxy Project, please visit the project home page. Contents 1 Galaxy Code Documentation, Release 2 Contents CHAPTER 1 Contents 1.1 Galaxy API Documentation 1.1.1 Background In addition to being accessible through a web interface, Galaxy can also be accessed programmatically, through shell scripts and other programs. The web interface is appropriate for things like exploratory analysis, visualization, con- struction of workflows, and rerunning workflows on new datasets. The web interface is less suitable for things like • Connecting a Galaxy instance directly to your sequencer and running workflows whenever data is ready. • Running a workflow against multiple datasets (which can be done with the web interface, but is tedious). • When the analysis involves complex control, such as looping and branching. The Galaxy API addresses these and other situations by exposing Galaxy internals through an additional interface, known as an Application Programming Interface, or API. 1.1.2 Quickstart Log in as your user, navigate to the API Keys page in the User menu, and generate a new API key. Make a note of the API key, and then pull up a terminal. Now we’ll use the display.py script in your galaxy/scripts/api directory for a short example: % ./display.py my_key http://localhost:4096/api/histories Collection Members ------------------ #1: /api/histories/8c49be448cfe29bc name: Unnamed history id: 8c49be448cfe29bc #2: /api/histories/33b43b4e7093c91f name: output test id: 33b43b4e7093c91f The result is a Collection of the histories of the user specified by the API key (you). To look at the details of a particular history, say #1 above, do the following: % ./display.py my_key http://localhost:4096/api/histories/8c49be448cfe29bc Member Information ------------------ state_details: {'ok': 1, 'failed_metadata': 0, 'upload': 0, 'discarded': 0, 'running': 0, 'setting_metadata': 0, 'error': 0, 'new': 0, 'queued': 0, 'empty': 0} 3 Galaxy Code Documentation, Release state: ok contents_url: /api/histories/8c49be448cfe29bc/contents id: 8c49be448cfe29bc name: Unnamed history This gives detailed information about the specific member in question, in this case the History. To view history contents, do the following: % ./display.py my_key http://localhost:4096/api/histories/8c49be448cfe29bc/contents Collection Members ------------------ #1: /api/histories/8c49be448cfe29bc/contents/6f91353f3eb0fa4a name: Pasted Entry type: file id: 6f91353f3eb0fa4a What we have here is another Collection of items containing all of the datasets in this particular history. Finally, to view details of a particular dataset in this collection, execute the following: % ./display.py my_key http://localhost:4096/api/histories/8c49be448cfe29bc/contents/6f91353f3eb0fa4a Member Information ------------------ misc_blurb: 1 line name: Pasted Entry data_type: txt deleted: False file_name: /Users/yoplait/work/galaxy-stock/database/files/000/dataset_82.dat state: ok download_url: /datasets/6f91353f3eb0fa4a/display?to_ext=txt visible: True genome_build: ? model_class: HistoryDatasetAssociation file_size: 17 metadata_data_lines: 1 id: 6f91353f3eb0fa4a misc_info: uploaded txt file metadata_dbkey: ? And now you’ve successfully used the API to request and select a history, browse the contents of that history, and then look at detailed information about a particular dataset. For a more comprehensive Data Library example, set the following option in your galaxy.ini as well, and restart galaxy again: admin_users = [email protected] library_import_dir = /path/to/some/directory In the directory you specified for ‘library_import_dir’, create some subdirectories, and put (or symlink) files to import into Galaxy into those subdirectories. In Galaxy, create an account that matches the address you put in ‘admin_users’, then browse to that user’s preferences and generate a new API Key. Copy the key to your clipboard and then use these scripts: % ./display.py my_key http://localhost:4096/api/libraries Collection Members ------------------ 0 elements in collection % ./library_create_library.py my_key http://localhost:4096/api/libraries api_test 'API Test Library' 4 Chapter 1. Contents Galaxy Code Documentation, Release Response -------- /api/libraries/f3f73e481f432006 name: api_test id: f3f73e481f432006 % ./display.py my_key http://localhost:4096/api/libraries Collection Members ------------------ /api/libraries/f3f73e481f432006 name: api_test id: f3f73e481f432006 % ./display.py my_key http://localhost:4096/api/libraries/f3f73e481f432006 Member Information ------------------ synopsis: None contents_url: /api/libraries/f3f73e481f432006/contents description: API Test Library name: api_test % ./display.py my_key http://localhost:4096/api/libraries/f3f73e481f432006/contents Collection Members ------------------ /api/libraries/f3f73e481f432006/contents/28202595c0d2591f61ddda595d2c3670 name: / type: folder id: 28202595c0d2591f61ddda595d2c3670 % ./library_create_folder.py my_key http://localhost:4096/api/libraries/f3f73e481f432006/contents 28202595c0d2591f61ddda595d2c3670 api_test_folder1 'API Test Folder 1' Response -------- /api/libraries/f3f73e481f432006/contents/28202595c0d2591fa4f9089d2303fd89 name: api_test_folder1 id: 28202595c0d2591fa4f9089d2303fd89 % ./library_upload_from_import_dir.py my_key http://localhost:4096/api/libraries/f3f73e481f432006/contents 28202595c0d2591fa4f9089d2303fd89 bed bed hg19 Response -------- /api/libraries/f3f73e481f432006/contents/e9ef7fdb2db87d7b name: 2.bed id: e9ef7fdb2db87d7b /api/libraries/f3f73e481f432006/contents/3b7f6a31f80a5018 name: 3.bed id: 3b7f6a31f80a5018 % ./display.py my_key http://localhost:4096/api/libraries/f3f73e481f432006/contents Collection Members ------------------ /api/libraries/f3f73e481f432006/contents/28202595c0d2591f61ddda595d2c3670 name: / type: folder id: 28202595c0d2591f61ddda595d2c3670 /api/libraries/f3f73e481f432006/contents/28202595c0d2591fa4f9089d2303fd89 name: /api_test_folder1 type: folder id: 28202595c0d2591fa4f9089d2303fd89 /api/libraries/f3f73e481f432006/contents/e9ef7fdb2db87d7b 1.1. Galaxy API Documentation 5 Galaxy Code Documentation, Release name: /api_test_folder1/2.bed type: file id: e9ef7fdb2db87d7b /api/libraries/f3f73e481f432006/contents/3b7f6a31f80a5018 name: /api_test_folder1/3.bed type: file id: 3b7f6a31f80a5018 % ./display.py my_key http://localhost:4096/api/libraries/f3f73e481f432006/contents/e9ef7fdb2db87d7b Member Information ------------------ misc_blurb: 68 regions metadata_endCol: 3 data_type: bed metadata_columns: 6 metadata_nameCol: 4 uploaded_by: nate@... metadata_strandCol: 6 name: 2.bed genome_build: hg19 metadata_comment_lines: None metadata_startCol: 2 metadata_chromCol: 1 file_size: 4272 metadata_data_lines: 68 message: metadata_dbkey: hg19 misc_info: uploaded bed file date_uploaded: 2010-06-22T17:01:51.266119 metadata_column_types: str, int, int, str, int, str Other parameters are valid when uploading, they are the same parameters as are used in the web form, like ‘link_data_only’ and etc. The request and response format should be considered alpha and are subject to change. 1.1.3 API Design Guidelines The following section outlines guidelines related to extending and/or modifing the Galaxy API. The Galaxy API has grown in an ad-hoc fashion over time by many contributors and so clients SHOULD NOT expect the API will conform to these guidelines - but developers contributing to the Galaxy API SHOULD follow these guidelines. • API functionality should include docstring documentation for consumption by readthedocs.org. • Developers should familiarize themselves with the HTTP status code definitions http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. The API responses should properly set the status code according to the result - in particular 2XX responses should be used for successful requests, 4XX for various kinds of client errors, and 5XX