Welcome to the starting point of the developer and technical documentation. If you are a user looking for more information about Noctua, please see the main site.
(Current development is very rapid, so some of these docs may be out of date.)
This repository contains the graphical editor frontend (Noctua) and messenger server (Barista) which communicates with Minerva, a service layer that allows create/read/update/delete operations on an OWL Model.
The current preview instance is available at: http://noctua.berkeleybop.org; for a toy example model, see the scratch model.
You must start with a modern version of Node.js (say >=0.12.3). Due to gcc requirements for Node.js modules, you’ll need a relatively new system, we’ll be using Ubuntu 16.04 LTS.
All of the tooling is built around that and should install easily with:
npm install
Noctua makes use of jsPlumb and BBOP components developed for AmiGO.
Before you do anything, you’ll need to create a startup.yaml that will define your environment. There are examples available in config/startup.yaml.*. For example, for local noctua-only development, you could try:
cp config/startup.yaml.noctua-dev ./startup.yaml
For more information about the configuration examples, see here.
After configuring your startup, run `gulp build`:
./node_modules/.bin/gulp build
Or, if you have “./node_modules/.bin” in your path:
gulp build
The the gulpfile.js and the startup.yaml are not necessary to run the services, they merely wrap getting the different variables coordinated for the command line options for each of the services.
Tha available gulp tasks are:
- doc - build the docs, available in doc/
- test - need more here
- build - assemble the apps for running
- watch - development file monitor
- clean - clean out /doc and /deploy
You must have a Minerva backend running somewhere and target it with Barista and Noctua. In this dev example, we’ll assume that you need that as well. Everybody is different, but I’ll give my local dev environment as an example. Minerva is packaged with the noctua repo.
The first step is to create the Blazegraph journal from your OWL models directory. This will require the necessary variables (e.g. NOCTUA_STORE) to be defined in startup.yaml. To make the journal, run:
gulp batch-minerva-create-journal
After the journal has been properly created you can start Minerva:
gulp run-minerva
This would run minerva as defined in your startup.yaml, probably defaulting to port 6800.
Learn more about Minerva here.
Everybody is different, but depending on you local startup.yaml default, if can be as simple as:
gulp run-barista
This will startup Barista aimed at the local Minerva instance running on default ports.
Barista needs two files to run: users.yaml and groups.yaml. Examples can be found here.
Everybody is different, but depending on you local startup.yaml default, if can be as simple as:
gulp run-noctua
This will startup the client aimed at the local Barista instance running on default ports.
The full developer documentation currently cuts across a decent swath of different projects. An overview could start like:
- JS API Minerva/Barista request manager: https://github.com/berkeleybop/bbop-manager-minerva
- JS API Minerva request objects/protocol: https://github.com/berkeleybop/minerva-requests
- Minerva request API gross concepts: https://github.com/berkeleybop/bbop-manager-minerva/wiki/MinervaRequestAPI
- Example client project: https://github.com/geneontology/noctua-repl
- Architecture diagram: https://www.lucidchart.com/documents/edit/2a21c669-f8ff-4f94-b118-cefe7ca370db/0
- Models that are currently known (either in memory or file) are found under [Current State] > select “Usable” > [Jump]
- To create a new model from a class and a DB, use [Wizard] > (fill out first sections) > [Generate]; this operation could take tens of minutes depending on the complexity
- To create a new model from just a DB, use [Wizard] > (fill out second section) > [Generate]; this operation may take minutes depending on the size of the GAF to be loaded
- Directly loading by copy-and-paste is not currently tested
- A new instance can be created by filling in the form on the left side of the display
- Double clicking edges and instances allows the editing of evidence and comments
- Clicking on the green box upper-left of an instance allows you to view and edit the instance type information
- By dragging the blue circle in the upper-right of an instance to anywhere on a different instance will allow you to create a relation between the two
- A complex expression can be added by opening the instance type
editor and
- Selecting: enabled_by
- Entering an expression of the form: “GO:0043234 and (‘has part’ some UniProtKB:P0002) and (‘has part’ some UniProtKB:P0003)”
- Model meta information can be edited by selecting [Model] > [Edit annotations] from the top menu
- [Model] > [Soft refresh] gets a fully updated model from the server; this is what you’ll use for the time being when another user makes a change to the model
- [Model] > [Reset] complete reloads everything from the server from scratch
- To export to a text file (Manchester syntax), use [Export]
- To save your current model, select [Model] > [Save]; your model should now be available from the landing page
- Dragging on the background of the model allows you to pan around without using the scrollbars
- Under [Views], there are various zooming options
- To reduce clutter, the “part of” relation can be hidden by selecting [View] > [Show/hide “part of”]
- The minimum space you start with is 800x600px. If you need more, try reseting your model–the space you can use will grow with it.
The bulk of major issues and feature requests are handled by the tracker (https://github.com/geneontology/noctua/issues). If something is not mentioned here or in the tracker, please contact Seth or Chris.
- Sometimes, when moving instance or relations near a boundary, the relations will fall out of sync; either move nearby instances or refresh the model
- Sometimes, when editing an instance, the relations (edges) will fall out of sync; either move nearby instances or refresh the model
- The endpoint scheme is reversed between creation and instantiation
- TODO, etc.
This should be deployable in most JS environments. It should be
noted that we do most development on Ubuntu 12.04 using Chris Lea’s
repo. Also, our alpha deployment environment is RedHat’s OpenShift,
so we’re hoping this is fairly flexible.
We do have people who have run the whole stack easily on OS X.