CCR downtime is scheduled for Tuesday 26 October 2021. Details: https://ubccr.freshdesk.com/support/discussions/topics/13000030322 close

Developing tools on GHub

GHub members use existing tools to build their own computational tools. A tool can be as simple as a useful scientific script with a web-enabled user interface, as complex as an elaborate workflow that uses remote data and submits jobs to high-performance computing resources, or anywhere in between.

We have a wealth of documentation available to guide you; this page will get you oriented to our tool development information.

Contents

  1. What is a Tool?
  2. Starting development
  3. Developing with Jupyter Notebooks
  4. Essential tool developer resources
  5. Tool Metadata
  6. More information
  7. VHub's Developing Tools Knowledge Base

Computational Tools on GHub

Tools on GHub are a type of computational Resource that you can create, publish, and share. These computational tools place a user interface on your working scientific code. In addition, you associate background information such as citations and documentation with your computational tool, and release the whole package in a citable way. Refer to our Computational Tool Gallery for examples of tools that other users have deployed.

The Hub supports several different types of resources; Tools are only one. All have elements in common.

What features are included for Tools?

All Resources on the Hub include an abstract, citations, supporting documentation, and topic tagging. As the creator of a Resource, you can assign a development team of other GHub users who work on the source code, the supporting documentation, and the descriptive metadata that describe the Tool. The source code for your Tool is maintained in a subversion or git repository, determined when you register the tool for the first time.

New versions of the Resource can be released as needed. The Hub provides a fully guided development lifecycle that enables you to collect the needed information to document your tool. Once released, the Resource supports an area for user questions and answers, citations, a usage report, and user-contributed wishlists.

Who has access to Tools?

You can control who has access to a Resource you create, and Tools are no exception. We recommend you set the Resource's Group to GHub and the Access Level to Public. You can choose to make your tool open source, or keep its source code private.

Any registered GHub user can create a GHub Resource, tools included. Only users named to the Resource's development team may edit the code and metadata.


Starting development

Supposing you have a working Python3 script that you'd like to deploy as a tool on GHub. To start the tool development process, you can:

  1. Upload your Python script to your GHub home directory.
  2. Register a new Tool on GHub.
  3. Create a user interface to your script, using the Jupyter Notebooks (Jupyter10) tool.

We recommend undertaking new tool development using the Workspace10 and Jupyter10 tools. These GHub tools are so-called because they run in Debian 10 containers.

If you want to extend the functionality of your computational tool, or provide new features, you can make a new release at any time. To learn about the stages in the tool development lifecycle, read Tool Development Overview. Managing this lifecycle is done with the Tool Development Pipeline.


Developing Tools with Jupyter Notebooks

The Jupyter10 tool supports kernels with common Python packages, and a handy notebook interface. You can use it to run calculations, visualize results, submit jobs to CCR's high-performance computing cluster, publish notebooks, develop tools, and more. Refer to the Jupyter Examples tool for editable notebooks with code examples and specifics about this installation.

This screenshot shows a running Jupyter Notebook. Refer below for examples and documentation.

Selecting a kernel in a Juptyer Notebook

Some useful resources for creating and running Jupyter notebooks and tools:


Essential tool developer resources

A good choice for user interface development in Jupyter Notebooks is the hublib.ui Python library, included with all Python kernels in our Jupyter Notebooks install. Refer to the Jupyter Examples tool to see this Python library, and others, in action.

Here are some other useful articles for tool development:


Tool Metadata

When you publish a tool Resource on GHub, you have the opportunity to comprehensively describe the tool, its use, its origin, attributions, and provenance, along with other information, together called metadata. We ask that tool contributors honor these requirements, so that tool users understand the uses and limitations of your contribution.

When publishing a tool, please include at a minimum a summary of the following information on the landing page that you create for the tool:

  • Abstract/General description
  • Input data specification
  • Output data specification
  • References and citations
  • Sources of error, caveats
  • Credits, including responsible team
  • How to use the tool

As needed, more comprehensive descriptions of the tool, user guides, and background information can be uploaded and associated with the resource as Supporting Documentation.

For Jupyter-based tools, we also ask that developers make use of a template notebook that describes the tool, guides its users, and specifies input and output requirements, right inside the notebook.


More information


Not registered? Join us on GHub! Register now.