Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

The BEL Framework tools are designed to work "out of the box". Once you have downloaded and unpacked the installation it should be ready to work. However, there are a few things you need to do first. This section will lead you through the steps necessary to get you started working with the BEL Framework tools.

Anchor
_Toc181078458
_Toc181078458
Download Knowledge

First you need to find some knowledge in the form of BEL Documents to work against. The BEL Portal provides some publically available knowledge to get you started. You can download these BEL Documents from the Downloads section on the BEL Portal. You will need to register first and agree to the license agreement before you can download the content.

  1. Download the small BEL Document named small_corpus.bel from the Downloads section on the BEL Portal This contains a small set of BEL Statements drawn from 57 PubMeds.
  2. Create a folder on your computer and place the BEL document in it. For this tutorial, create a folder called BELDocuments on your computer and add the small_corpus.bel document to it.

Anchor
_Toc181078459
_Toc181078459
Import a BEL Document

This version of the BEL Framework requires that the BEL Framework Document Store has been initialized before you can launch any of the server tools. To initialize the Document Store you must import a BEL Document.

Anchor
_Toc181078460
_Toc181078460
To import a BEL Document:

  1. Open a command window in the BEL Framework installation directory.
  2. Run the DocStoreImport utility by entering the following command. This assumes that the BEL Document you downloaded is in a folder named BELDocuments.

./tools/DocstoreImport.sh --permissive [path]BELDocuments/small_corpus.bel
The --permissive switch allows the importer to continue to import even if there are any syntactic or semantic errors in the BEL Document.
The importer utility will create a local version of BEL Document Store database if it does not already exist and import the XBEL document after first performing syntax and semantic checks on the document and its contents.
$ ./tools/DocstoreImport.sh ~/Desktop/BELDocuments/small_corpus.bel
BEL Framework V1.0: BEL Document Import Utility
Copyright (c) 2011, Selventa. All Rights Reserved.

Validating BEL Document: ~/Desktop/BELDocuments/small_corpus.bel

 

  1. If there were no errors, the Document Store database will be created and the BEL Document imported.

Anchor
_Toc181078461
_Toc181078461
Start the BEL Framework Server

The BEL Framework server hosts the BEL Workbench and BEL Framework Web API applications. You must first start the server in order to access these applications.

Anchor
_Toc181078462
_Toc181078462
Starting the Server

To start the BEL Framework Server:

  1. Make sure you have at least one BEL Document imported to the Document Store.
  2. Open a command window in the BEL Framework installation directory.
  3. Run the StartServer script.

$ ./StartServer.sh
This will launch the Tomcat server that is provided with the distribution.
BEL Server successfully started at http://localhost:8080/
BELWorkbench is available at http://localhost:8080/BELWorkbench
WebAPI is available at http://localhost:8080/BELFrameworkWebAPI


Once the server has started, you will be able to access the BEL Workbench application.

Anchor
_Toc181078463
_Toc181078463
Stopping the Server

Because the server has a live access to the Document Store database it is important that the server be correctly shutdown to avoid any possible corruption of the Document Store database.
To stop the server:

  1. Open a command window in the BEL Framework installation directory.
  2. Run the StopServer script.

$ ./StopServer.sh
This will terminate Tomcat server if it is running and gracefully shut down and database operations that are open.
Server is successfully stopped.
Once the server has been terminated, you will no longer be able to access the BEL Workbench application.

Anchor
_Toc181078464
_Toc181078464
Access the BEL Workbench

The BEL Workbench is a web-based application that allows you to create and manage BEL Documents in a Document Store. To access the BEL Workbench you must first start the BEL Framework server and then point a browser to the application end-point.
To access the BEL Workbench

  1. Make sure you have at least one BEL Document imported to the Document Store.
  2. Start the BEL Framework server.
  3. Using a supported web browser, open a browser window and set the URL to

http://localhost:8080/BELWorkbench

  1. The BEL Workbench application will open in the browser.


Once the BEL Workbench is open you will be able to create new BEL Documents, edit existing BEL Documents.

Anchor
_Toc181078465
_Toc181078465
Create a KAM

Knowledge Assembly Models (KAMs) are graphs representing biological networks that are compiled from one or more BEL Documents. KAMs are created by running the BEL Framework Compiler/Assembler utility.
To compile a BEL Document:

  1. Ensure that one or more BEL Documents are available. You can compile documents stored on your or documents which are stored in a Document Store. This example will compile the small_corpus.bel document that has already been downloaded.
  2. Open a command window in the BEL Framework installation directory.
  3. Run the belc.sh script passing in the parameters to specify which BEL Documents to compile and the name of the KAM to create. This will start the multi-phase compiler/assembler and will create a KAM named test. We will use defaults for most of the operations but you can look at the BEL Framework Compiler/Assembler User Guide for a detailed description of all the command line options available.


$./belc.sh -f ~/Desktop/BELDocuments/small_corpus.bel -k test -d "Test KAM"
The compiler/assembler will start to run and provide a log of the phases and any warnings that are generated as the compiler works. The compiler will generate a lot of warnings from the nlp file.
BEL Framework V1.0: Compiler/Assembler
Copyright (c) 2011, Selventa. All Rights Reserved.

=== Phase I: Compiling proto-networks ===
Compiling 1 BEL Documents
[WARNING]: SYMBOL WARNINGS in NLP Corpus Document (NLP Corpus Document)
reason: 98 invalid symbols
symbol FGB, location http://download.belscripts.org/belframework/ns/mgi-marker-symbols.belns
(rows skipped)
[WARNING]: SEMANTIC FAILURE in NLP Corpus Document
reason: 128 semantic warnings for document
SEMANTIC WARNING in Parameter [namespace=Namespace [prefix=MGI, resourceLocation=http://download.belscripts.org/belframework/ns/mgi-marker-symbols.belns\], value=CRP]
reason: CRP does not exist in MGI: http://download.belscripts.org/belframework/ns/mgi-marker-symbols.belns
SEMANTIC WARNINGS
reason: term failed semantic checks
signature: complexAbundance(F:biologicalProcess,F:proteinAbundance)moleculeAbundance
function signatures: 2
the function argument is not valid for signature complexAbundance(E:moleculeAbundance)moleculeAbundance
the function argument is not valid for signature complexAbundance(F:abundance...)moleculeAbundance
(rows skipped)
=== Phase Complete ===
=== Phase II: Merging proto-networks ===
=== Phase Complete ===
=== Phase III: Expansion and augmentation of composite network ===
=== Phase Complete ===
=== Phase IV: Exporting final network to the KAM Store ===
=== Phase Complete ===
Once the compiler has completed, the KAM will have been generated and available for use in the KAM Store.

Anchor
_Toc181078466
_Toc181078466
Validate the KAM

The KAMs are designed for use only by the BEL Framework APIs. However there are several tools that can be used to check the KAM. The most useful tool for this version of the BEL Workbench is to export the KAM to XGMML so it can be visualized in Cytoscape or other similar applications.

Anchor
_Toc181078467
_Toc181078467
Exporting the KAM to XGMML

To compile a BEL Document:

  1. Compile a KAM using the steps detailed above.
  2. Open a command window in the BEL Framework installation directory.
  3. Run the KamExporter.sh script passing in the parameters to specify which KAM to export and the file name to export it to. This will start the export utility.


$ ./tools/KamExporter.sh -k test –t XGMML -o test.xgmml
In this example the export utility will export the KAM named test to a file named test.xgmml.
Once the exporter has run, you should be able to launch Cytoscape and visualize the KAM.