• 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 [[http://noctua.berkeleybop.org][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 [[https://github.com/geneontology/minerva][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 [[http://noctua.berkeleybop.org/editor/graph/gomodel:55ad81df00000001][the scratch model]].

** Installation

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 [[https://jsplumbtoolkit.com/][jsPlumb]] and [[http://github.com/berkeleybop][BBOP]] components developed for [[https://github.com/geneontology/amigo/][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 [[https://github.com/geneontology/noctua/tree/master/config#configurations][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.

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 [[https://github.com/geneontology/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.

Barista needs two files to run: users.yaml and
groups.yaml. Examples can be found [[https://github.com/geneontology/go-site/metadata][here]].

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

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