Analyze Data Using KBase Apps
Once exploring available KBase Apps and determining which ones work with the data objects in your Narrative, you can start analyzing your data.
To add an app, find the app of interest and click its name or the icon to the left of the app name. A box (called a cell) containing the chosen app will appear in the main Narrative panel.
A few things to notice about the app cell:
App Cells have three tabs
Configure (where you set the parameters; it’s what you see when you add a new app cell)
Info
Job Status
Result
The last two tabs are filled in once you run the app; these are discussed later.
The up and down arrows let you move the cell up or down in your Narrative.
The “…” dropdown menu offers several options for showing the code that will execute the app; getting more info (in a separate browser window) about the app; and deleting the cell. These are discussed more in the section called “Revise Your Narrative“.
The "-/+" in the App Cell menu is the collapse/expand cell option. When the App Cell is expanded, the farthest right option will be a "-" to collapse the cell. When the App Cell is collapsed, the farthest right option will be a "+" to expand the cell. You can also double click on an App Cell to expand/collapse the app.
Every app has some parameters (fields) that must be filled in before you can run the app.
After you add an app to your Narrative, the required parameters must be filled in before you can run it. For example, for most apps, you will need to select the input data object(s). Other parameters may also need to be set. A red arrow to the right of a field indicates that it is a required field and you have not yet entered a valid value in it. Once you enter a value, the red arrow should disappear.
Some app fields are “smart” and know which data in your Narrative is valid for that field. These “smart” fields have a pulldown list of data objects that you can choose from. (Remember, only data (of the appropriate type) that you have already added to this particular Narrative will be shown in that list. You can access your data from other Narratives via the My Data and Shared with me tabs in the Data Panel.)
In the example app shown above, the input object field, which is required, has a pulldown list that will be populated with data objects of the appropriate type that you have added to your Narrative. Scientific Name, on the other hand, is a free text field and is optional. The next two fields (Domain and Genetic Code) are also required, but they are pre-filled with default values. You could change their values if you chose, or leave them as they are. Finally, the last field (Output Genome Name) is another free text field. In the screenshot, the Output Genome Name, is not yet filled in; it has a red arrow to the right. The green "Run" button is enabled when all required fields are filled in and the red arrows are gone.
Some apps have optional “advanced options” that you can reveal by clicking on the “advanced options” link at the bottom of the cell.
Save Your Work
As you add to your Narrative, be sure to save your work frequently, using the Save button at the top right of the screen.
When you have filled in all the required fields, the Run button on the left side of the app will be enabled; click it to start running the app. Once clicked, the green Run button will turn to a red Cancel button. When the analysis starts running, you will see information in the Job Status tab.
Depending on the analysis, the analysis might finish within a few seconds or could take hours to run. You can save your Narrative and come back to it later–the analysis will continue running even if you don’t have the Narrative open.
Examine and download results
When an app finishes running, you will see a summary in the Results tab, as well as an output cell below your app cell. Also, if the analysis generates a new data object, that object will be added to your Data Panel.
In the example, the “Annotate Microbial Contigs” app, once run, produced an output cell that provides information about the newly annotated Shewanella genome object.
This output cell has three tabs: Overview (displayed above), Browse Contigs, which lists the large assembled pieces of a genome, and Browse Features, which allows browsing of all the annotated genes.
Different apps create different types of output cells when they run, depending on which type of data object is output by the app. The genome output cell shown above is an example of a Data Viewer. Data Viewers are described in the Explore Data section of this guide.
In addition to creating a new output cell, the app we ran created a new data object and added it to our Narrative. The newly annotated genome object now appears at the top of the Data Panel.
Remember that you can hover over an object in the Data Panel and click the “..." that appears to see more information and options, including an option (see image) for downloading the object in GenBank or JSON format (see the Download Guide for more information). In the future, you will be able to choose from a wider variety of common formats, allowing you to download results to use with other tools and send to colleagues.
KBase’s download functionality is still in development – please check back soon for new download options and improvements, and report any problems to us.
Once you have reviewed your results, you can use your newly generated data in additional analysis steps. Remember, you can click on the data object in the Data Panel to see which KBase Apps work with that data type.
For example, our annotated genome can be used in a number of analyses because it now includes the standard KBase annotations. If you click on the genome in the Data Panel, you see several apps that apply. Among them are the Insert Genomes into Species Tree App that constructs a phylogenetic tree allowing you to see species closely related to your genome. You also can use the Build a Metabolic Model App to draft a metabolic model from the annotated genome.
App input cells that have already been run have a “Reset” button that allows you to redo the analysis, with the option to change any of the parameter settings (including, perhaps, the input data) before rerunning. Rerunning an App will overwrite the information in the App cells, but will not overwrite any data objects in your Narrative unless you use the same output object name again.
If a job fails, you will see an error message in the output cell and/or in the Result tab. If you need help figuring out what went wrong, please contact us with details about what you were doing when the error occurred and what the error message said. Including the contents of the Job Status tab and the URL of your Narrative will help us debug the problem. We are here to help and appreciate your feedback and error reports!
In the next section, we will discuss how you can revise your Narratives.
