Skip to content

Latest commit

 

History

History
183 lines (136 loc) · 7.2 KB

README.org

File metadata and controls

183 lines (136 loc) · 7.2 KB
Raw

The Noctua (Editor + Barista + Minerva) Stack

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.

Installation

You must start with a modern version of Node.js (say >=0.12.3). 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.

Running

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

Minerva (optional)

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.

gulp run-minerva

This would run minerva as defined in your startup.yaml, probably defaulting to port 6800.

Learn more about Minerva here.

Barista (optional)

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.

Client/Graph Editor (previously “Noctua”)

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.

Development documentation

The full developer documentation currently cuts across a decent swath of different projects. An overview could start like:

How to use demo

Generating/selecting a model

  • 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

Instances and edges

  • 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)”

Models

  • 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

General navigation

  • 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.

Known issues

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.

Deployment

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.