Querying / Examining BrainML Models

This site was created by the Laboratory of Neuroinformatics to describe BrainML and to serve as a repository for BrainML models. See here and other links for more information. This document describes how to query and view BrainML models on this site. Procedures for submitting models are covered elsewhere.

There are two modes for accessing models through this site. The first uses an HTML interface suitable for browser use, while the second uses a raw HTTP interface suitable for software clients. Below the HTML interface is described first, then the software client interface.

The entry point to browsing available models is the Model Schemas link at the upper left. Clicking this will show you a list of models currently stored in the repository. From here:

• Clicking the name of a model will take you to its description page.
• Clicking the submitter will take you to an information page on the submitter, including a list of all the models they've submitted.
• Clicking the latest version number and date will take you to the description page for the latest version of the model (see below).

Each model may have multiple versions. Due to the complex and dynamically evolving nature of the subject matter, the submitter of a model may eventually wish to modify it, either to add support for more complete metadata or to better organize the way existing metadata is handled. They do this not by changing the model that has been submitted, but by submitting a new version of it. This allows the integrity of existing data using the previous version to be preserved, since software tools can still access the model description.

Ordinarily if you have not used a model before you will be interested only in its latest version, to which direct access is provided from the model list page.

Accessing a version's page, either from the model list, or through the model's page, brings up information on and full access to a model's components. These include structure files, which are XML Schemas describing the entities and fields making up the model, and the vocabulary files describing the terms and units that may be used to fill the fields.

Structure files may be viewed directly in raw form in one of two alternative formats. The first format is the so-called XML Schema Compact Syntax (XSCS), a more readable version of the second format, the standard XML syntax.

Vocabulary files may be viewed directly in raw XML form. There are generally three types of "vocabulary file". The first is a hierarchical list of terms conforming to the vocabulary schema ("vocabulary.xsd") within the BrainMetaL model. The second is a list of units of measure conforming to the units schema ("units.xsd") within the BrainMetaL model. The third type is not really a vocabulary file, but an XML instance document conforming to the structure schemas for the model, included as an illustrative example.

The last row in the top information table on the version information page provides links for "Viewing" the structure or vocabulary for a model. These links provide for HTML-formatted displays that are better for quickly understanding the content of a model than the raw schema and XML documents themselves.

It is possible to search for models by key word, using the search box on the Model Schemas page.

While the set of interrelated dynamic HTML pages described above provides a convenient way for users to access models, software clients do not need the HTML formatting, and would in fact be hindered by it. It is therefore possible to access the functionality of BrainML.org through simple HTTP requests which return XML-formatted responses.

BrainML Model schemas and vocabulary files can be retrieved directly using simple HTTP requests following certain conventions. For example, consider the schema "cortex.xsd" under the namespace "urn:bml/brainml.org:med.cornell.edu/Cortex/2".

The first type of HTTP request would use the URL "http://brainml.org/schemas/med.cornell.edu/     Cortex/2/cortex.xsd".
Here, the namespace portion after "urn:bml/brainml.org:" is placed after the URL base "http://brainml.org/schemas", and the filename "cortex.xsd" is appended with a slash. The same convention can be applied to any model.

Alternatively, the namespace can be fed as a CGI query as in "http://brainml.org/isr.do?     ns=urn:bml/brainml.org:med.cornell.edu/Cortex/2     &file=cortex.xsd&action=getFile".
(Line breaks are for display purposes only and should not be included in URL.) This format is more general than the first format in that you can request other "actions" besides 'getFile' (which will just return the raw file). These will be documented in a future release.

Models can be searched for by keyword by using a CGI query of the form: "http://brainml.org/viewModels.do?keywords=...", where '...' should be replaced by comma or space-separated keyword terms. (Spaces must be expressed as URL-encoded '%20'.) The return from this query is in HTML, and not well-suited for software client use.

Improving the client interface to model search is a priority for current BrainML.org development.