International Neuroinformatics Coordinating Facility
Date: 2011-01-10
Reference number of this INCF document: INCF 10-001
Version: 0.7
Category: INCF Discussion Paper
Editor: Ilya Zaslavsky
INCF Atlas Services and Waxholm Markup
Language
Digital Atlasing Infrastructure Task Force
Copyright notice
Copyright © 2011 International Neuroinformatics Coordinating Facility. All rights
reserved.
To obtain additional rights of use, visit http://www.incf.org/legal/.
Warning
This document is not an INCF Standard. This document is an INCF Discussion Paper and
is therefore not an official position of the INCF membership. It is distributed for review
and comment. It is subject to change without notice and may not be referred to as an INCF
Standard. Further, an INCF Discussion Paper should not be referenced as required or
mandatory technology in procurements
i
Contents
INCF Atlas Services and Waxholm Markup Language ................................................. i
Figures ............................................................................................................................... iv
Tables v
Preface ............................................................................................................................... vi
i.
Submitting organizations .................................................................................... vi
ii.
Submission contact points ................................................................................... vi
iii.
Revision history ................................................................................................... vii
iv.
Changes to other INCF Specifications .............................................................. vii
v.
Future work ......................................................................................................... vii
Foreword .............................................................................................................................1
Introduction ........................................................................................................................2
1.
Scope........................................................................................................................3
2.
Conformance ..........................................................................................................3
3.
Normative references .............................................................................................3
4.
Terms and definitions ............................................................................................4
5.
Conventions ............................................................................................................7
5.1.
Symbols (and abbreviated terms) .........................................................................7
5.2.
XML conventions ...................................................................................................8
6.
Core concepts and implementation context .........................................................9
6.1.
INCF Service Oriented Architecture (SOA): INCF Hubs and services, INCF
Central ....................................................................................................................9
6.2.
Atlas hubs and atlas services ...............................................................................13
6.3.
Spatial reference systems and SRS registry ......................................................14
6.4.
List of atlas services at the hub level ..................................................................19
6.5.
List of atlas services as INCF Central ................................................................21
7.
Service signatures and WaxML schemas ..........................................................22
7.1.
Atlas services as WPS profile: the basics ...........................................................22
7.2.
Atlas services and WaxML conventions ............................................................24
7.3.
GetCapabilities .....................................................................................................25
7.4.
DescribeProcess ....................................................................................................27
7.5.
Execute ListSRSs .................................................................................................29
7.6.
Execute DescribeSRS ..........................................................................................32
ii
7.7.
Execute ListTransformations .............................................................................34
7.8.
Execute DescribeTransformation .......................................................................35
7.9.
Execute GetTransformationChain .....................................................................36
7.10. Execute TransformPOI .......................................................................................38
7.11. Execute GetStructureNamesByPOI ...................................................................40
7.12. Execute Get2DImagesByPOI ..............................................................................44
7.13. Execute Retrieve2DImage ...................................................................................47
7.14. Execute GetCorrelationMapByPOI ...................................................................50
7.15. Execute GetGenesByPOI.....................................................................................51
7.16. Execute Get2DImagesByURI ..............................................................................54
7.17. Exception report.....................................................................................................55
Annex A.............................................................................................................................56
A1. Physical implementation of a hub............................................................................57
A2. Extensions: convenience APIs ..................................................................................57
A3. HUB deployment model and additional requirements ..........................................58
A4. Code Design, Management, and Deployment .........................................................59
iii
Figures
Figure 1. INCF SOA: main components....................................................................................... 10
Figure 2. Potential content of an INCF Hub ................................................................................. 11
Figure 3. INCF Central and INCF Hubs ....................................................................................... 11
Figure 4. INCF atlas hubs ............................................................................................................. 14
Figure 5. Spatial Reference Systems .............................................Error! Bookmark not defined.
Figure 6. Sample relational representation of SRS tables............................................................. 18
Figure 7. Schema of the SRSType element .................................................................................. 19
Figure 8. Schematic representation of core components of a hub ................................................ 21
Figure 9. XML schema diagram of the Capabilities response ...................................................... 27
Figure 10. XML schema diagram of ProcessDescription ............................................................. 29
Figure 11. XML schema diagram of the Execute response .......................................................... 29
Figure 12. XML schema diagram of the QueryInfo component. The element is expected to be
included in all Execute requests .................................................................................................... 30
Figure 13. XML schema diagram of ListSRS response ............................................................... 32
Figure 14. XML schema diagram of DescribeSRS response ....................................................... 32
Figure 15. XML schema diagram of ListTransformations response ............................................ 34
Figure 16. XML schema diagram of CoordinateTransformationChainResponse ........................ 38
Figure 17. XML schema diagrams of TransformationResponse and POI .................................... 39
Figure 18. XML schema diagrams of StructureTermsResponse and StructureTerm .................. 44
Figure 19. XML schema diagram of ImagesResponse ................................................................. 46
Figure 20. XML schema diagram of Retrieve2DImages response ............................................... 48
Figure 21. XML schema diagram of CorrelationMap response ................................................... 51
Figure 22. XML schema diagrams of GeneType and GeneExpressionLevel (components of
GetGenesByPOI response) ........................................................................................................... 52
Figure 23. Deployment model of INCF hub ................................................................................. 58
iv
Tables
Table 1. Spatial reference system core characteristics.................................................................. 14
v
Preface
Atlas web services is a term for a group of services created to support information
integration across atlases of the brain. The services return information in Waxholm Markup
Language (WaxML). Together, the WaxML encoding and the Atlas Service interface
specification form the backbone of the INCF Digital Atlasing Infrastructure.
The services and the XML output schema are defined and created through the activities of
the INCF Digital Atlasing Task Force, a collaborative effort that involves neuroscience
atlasing experts from several countries. The focus of this work is integration of atlas data for
rodent brain, however the principles and services expressed below can be applicable to
other species. INCF-DAI Task Force Members are in discussion with INCF about further
standardization of the schema and service signatures.
Suggested additions, changes, and comments on this discussion paper are welcome and
encouraged. Such suggestions may be submitted by INCF portal message, email message,
or by making suggested changes in an edited copy of this document.
The changes made in this document version, relative to the previous version, are tracked by
Microsoft Word, and can be viewed if desired. If you choose to submit suggested changes by
editing this document, please first accept all the current changes, and then make your
suggested changes with change tracking on.
i.
Submitting organizations
The following organizations submitted this Discussion Paper to the International
Neuroinformatics Coordinating Facility as a Request For Comment (RFC):
a) INCF Digital Atlasing Infrastructure Task Force
ii.
Submission contact points
All questions regarding this submission should be directed to the editor:
CONTACT
Ilya Zaslavsky
COMPANY
UCSD
EMAIL
izaslavsky [at]ucsd.edu
vi
iii.
Revision history
Date
2010-09-15
2011-01-10
iv.
Release
0.6
0.7
Author
Paragraph modified
Description
Ilya
Baseline external version
Zaslavsky
and INCFDAI TF
Specification of WaxML and INCF
Atlas Services as implemented in the
September’2010 release. Versions 0.10.5 are internal development versions
Ilya
Throughout
Zaslavsky
and INCF
DAI TF
Specification as implemented in
January’2011 release (transition to
Deegree services, feedback from
implementers and readers)
Changes to other INCF Specifications
Changes in other INCF specifications are not required to accommodate this INCF
specification.
v.
Future work
In future versions of this specification, we intend to discuss harmonization of WaxML and
the atlas services with other relevant standards and conventions used in the neuroscience
community, and add methods and output schemas as requested by atlas implementers and
users.
We anticipate that a community process is organized by which atlas services and their
output schema are discussed and adopted as INCF standards – possibly via a formal process
that involves public discussions and comments, pilot implementations, interoperability
experiments, and eventual adoption vote. After the initial round of specification
development is complete, INCF is expected to continue governing standards development
by monitoring change requests, issuing calls for implementation, developing groups of
related standards as a unified system, and otherwise supporting a transparent community
consensus system of international neuroinformatics standards
vii
Foreword
This document is being provided to INCF for review and discussion by the INCF membership. There may be
potential harmonization work to align WaxML with other specifications.
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights.
INCF shall not be held responsible for identifying any or all such patent rights. However, to date, no such rights
have been claimed or identified.
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims
or other intellectual property rights of which they may be aware that might be infringed by any implementation of
the specification set forth in this document, and to provide supporting documentation.
1
Introduction
During 2008-2009, the INCF Digital Atlasing Task force members started developing
service-oriented infrastructure for rodent brain atlases. The goal is to formally define spatial
reference systems used for rodent brain atlases, transformations between them, and a
collection of service functions that expose the content of the atlases based on point of
interest requests. This work has been tightly integrated with the development of Waxholm
Space, an open source publicly accessible 3D model of mouse brain that is used as the
central reference framework that other spatial reference systems interoperate with.
In September 2009, a first collection of INCF Atlas services was demonstrated. These
services included several initial coordinate transformation services and wrappers over POI
(Point of Interest)-based requests that could be executed over several key online sources of
rodent brain data, including the Allen Brain Atlas and the Edinburgh Mouse Atlas, as well as
a collection of spatially-registered imagery at UCSD.
During 2010, a new INCF-sponsored project focused on converting the initial demo into a
more solid infrastructure. This included formal definitions of coordinate systems and
coordinate transformations for the mouse brain, defining a service interface, developing a
standards-based XML schema for the service output, and conceptualizing components of
INCF SOA as a network of INCF atlas hubs linked to the central metadata catalog. This
document describes the interface specification of hub services and the output XML schema
called Waxholm Markup Language (WaxML). The goal of this first phase is to create a fairly
rigid though minimalistic foundation of INCF SOA, and follow it strictly, to ensure that atlas
hubs and atlas clients exchange information in a systematic and unambiguous manner.
This document has dual purpose. One is to formally specify: a) service interface for atlas
services and b) WaxML as the output XML schema used by such services. This information is
presented in the main (normative) part of the document. Another is to place the services
and the schema in the context of INCF-DAI (Digital Atlasing Infrastructure), describe main
components of this infrastructure (INCF Central, different types of atlas hubs, spatial
reference system registry, transformations registry), and provide information for
developers. This material is partially presented in Section 6 and in the appendix
(informative) section.
Several reports generated in the course of the INCF-DAI TF activities are the basis of this
specification: the 2009 INCF-DA TF report, and the final report for the 2009 demonstration
project (from UCSD.) Versions 0.1-0.4 of the specification were developed internally
between October 2009-March 2010 (Edinburgh INCF DAI meeting). Version 0.5 incorporated
initial comments from members of the Digital Atlasing Infrastructure Task Force and INCF
research staff. Version 0.6 is a significant refactoring and standardization of the previous
text, along with the completion of the first draft of service implementation (September
2010).. Version 0.7 (current) reflects a significant update and service enhancements related
to the transition to Deegree-based services, and several service interface changes based on
feedback from users and developers.
This and related documents can be accessed from the atlasing group space on Google Code:
http://code.google.com/p/incf-dai/ The Google code page includes the WaxML schema,
sample XML output for atlas service requests, coding examples, and source code. The
schema is also available at http://www.incf.org/WaxML/xmlschema.
2
IMPORTANT: Developers are expected to consult the WIKI at
http://code.google.com/p/incf-dai for the most up to date versions of the service
signatures.
The template for this document is based on documents of Open Geospatial Consortium
(www.opengeospatial.org).
1. Scope
This document describes the initial version of the WaxML messaging schema as
implemented in the initial version of the INCF Atlas services. It also lays out strategies for
expanding WaxML to include a variety of POI-based requests in a way conformant with
specifications that are adopted for exchanging spatial information.
The Atlas services API includes a simple set of methods that can be called to discover and
interpret atlas information spatially, and get information about existing spatial reference
frameworks for the brain. The core methods and related XML constructs list and describe
available SRS (Spatial Reference System) and transformations (ListSRSs,
ListTransformations, DescribeSRS, DescribeTransformation), derive and compute spatial
transformations (GetTransformationChain, TransformPOI), and link anatomic labels with
points in space (GetStructureNamesByPOI). These methods are expected to be included in
all atlas hub services. The specification includes two generic POI-based requests that return
objects or properties at specified coordinates (GetObjectsByPOI and GetPropertyByPOI). At
the same time, the WPS-based service approach does not require that all methods are
presented as the generic requests above: atlas hubs may expose additional functionality
following conventions specific to one or more atlas hubs. Such additional requests may have
compatible signatures across hubs, thus making cross-hub queries easier. Several such
methods are also described here (Get2DImagesByPOI, Retrieve2DImage, getGenesByPOI,
etc.) though strictly speaking they are outside the core set of methods that should be
standardized as the first priority. Enabling cross-hub querying for semantically related
methods with different signatures can be accomplished with a mediator at the central server
– but this is out of scope for the document.
2. Conformance
Not applicable at this time.
3. Normative references
The following normative documents contain provisions which, through reference in this text,
constitute provisions of this document. For dated references, subsequent amendments to,
or revisions of, any of these publications do not apply. However, parties to agreements
based on this document are encouraged to investigate the possibility of applying the most
recent editions of the normative documents indicated below. For undated references, the
latest edition of the normative document referred to applies.
3
ISO 1000:1994, SI units and recommendations for the use of their multiples and of certain other
units.
ISO 8601:2004, Data elements and interchange formats— Information interchange
Representation of dates and times
ISO 19101:2003, Geographic Information—Reference Model
ISO/TS 19103:2006, Geographic Information — Conceptual schema language
ISO 19110:2006 , Geographic Information – Feature cataloguing methodology
IETF RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax. (August 1998)
W3C XLink, XML Linking Language (XLink) Version 1.0. W3C Recommendation (27 June
2001)
W3C XML, Extensible Markup Language (XML) 1.0 (Second Edition), W3C Recommendation
(6 October 2000)
W3C XML Namespaces, Namespaces in XML. W3C Recommendation (14 January 1999)
W3C XML Schema Part 1, XML Schema Part 1: Structures. W3C Recommendation (2 May
2001)
W3C XML Schema Part 2, XML Schema Part 2: Datatypes. W3C Recommendation (2 May
2001)
4. Terms and definitions
For the purposes of this document, the following terms and definitions apply.
4.1
application schema
conceptual schema for data required by one or more applications
[ISO 19101]
4.2
attribute <XML>
name-value pair contained in an element
4.3
child element <XML>
immediate descendant element of an element
4.4
coordinate reference system (see spatial reference system)
In geospatial data processing, it represents a coordinate system that is related to the real world by
a datum [ISO 19111]. In this document, we define coordinate reference systems with respect to
anatomic features or image processing artefacts/procedures (see section XXX). Note that a
“coordinate reference system” is treated here as a special case of “spatial reference system”
4
where location is described by coordinates. In a general case of neuroscience-oriented spatial
reference system, location in the brain can be referenced via ontology, or a collection of spatial
rules defined relative to non-problematic anatomic features and/or fiducial points.
4.5
data type
specification of a value domain with operations allowed on values in this domain
[ISO/TS 19103]
EXAMPLE
Integer, Real, Boolean, String, Date (conversion of a data into a series of codes).
Data types include primitive predefined types and user-definable types. All instances of data types lack identity.
4.6
domain
well-defined set
[ISO/TS 19103]
1
A mathematical function may be defined on this set, i.e. in a function f:AB A is the domain of the function f.
2
A domain as in domain of discourse refers to a subject or area of interest.
4.7
element <XML>
basic information item of an XML document containing child elements, attributes and
character data
From the XML Information Set: “Each XML document contains one or more elements, the boundaries of which are
either delimited by start-tags and end-tags, or, for empty elements, by an empty-element tag. Each element has
a type, identified by name, sometimes called its ‘generic identifier’ (GI), and may have a set of attribute
specifications. Each attribute specification has a name and a value.”
4.8
feature
abstraction of real world phenomena. In the neuroinformatics context refers to anatomic features
in the brain
[ISO 19101]
A feature may occur as a type or an instance. Feature type or feature instance should be used when only one is
meant.
4.9
feature association
relationship that links instances of one feature type with instances of the same or different feature
type
[ISO 19110]
5
4.10
grid
network composed of two or more sets of curves in which the members of each set intersect the
members of the other sets in an algorithmic way. In typical neuroinformatics usage, refers to a
2D or 3D regular space tessellation as specified by a recording procedure or device: microscope,
camera, downsampling or other algorithm, 3D reconstruction, etc.
[ISO 19123]
The curves partition a space into grid cells.
4.11
namespace <XML>
collection of names, identified by a URI reference, which are used in XML documents as
element names and attribute names [W3C XML Namespaces]
4.12
property <General Feature Model>
characteristic of a feature type, including attribute, association role, defined behaviour, feature
association, specialization and generalization relationship, constraints
[ISO 19109]
4.13
property <GML>
a child element of a GML object
It corresponds to feature attribute and feature association role in ISO 19109. If a GML property of a feature has an
xlink:href attribute that references a feature, the property represents a feature association role.
4.14
schema
formal description of a model
[ISO 19101]
In general, a schema is an abstract representation of an object's characteristics and relationship to other objects. An
XML schema represents the relationship between the attributes and elements of an XML object (for example, a
document or a portion of a document)
4.15
schema <XML Schema>
collection of schema components within the same target namespace
EXAMPLE
Schema components of W3C XML Schema are types, elements, attributes, groups, etc.
4.16
schema document <XML Schema>
XML document containing schema component definitions and declarations
6
The W3C XML Schema provides an XML interchange format for schema information. A single schema document
provides descriptions of components associated with a single XML namespace, but several documents may
describe components in the same schema, i.e. the same target namespace.
4.17
semantic type
category of objects that share some common characteristics and are thus given an identifying
type name in a particular domain of discourse
4.18
tag <XML>
markup in an XML document delimiting the content of an element
4.19
UML application schema
application schema written in UML according to ISO 19109
4.20
Uniform Resource Identifier (URI)
unique identifier for a resource, structured in conformance with IETF RFC 2396
The general syntax is <scheme>::<scheme-specific-part>. The hierarchical syntax with a namespace is
<scheme>://<authority><path>?<query> - see [RFC 2396].
4.21
value
member of the value-space of a datatype. A value may use one of a variety of scales including
nominal, ordinal, ratio and interval, spatial and temporal. Primitive datatypes may be combined
to form aggregate datatypes with aggregate values, including vectors, tensors and images
[ISO11404].
5. Conventions
5.1.
ABA
AGEA
API
COTS
EMAP
EMAGE
GML
ISO
OGC
OWS
UCSD
UML
WXS
Symbols (and abbreviated terms)
Allen Brain Atlas
Anatomic Gene Expression Atlas
Application Program Interface
Commercial Off The Shelf
Edinburgh Mouse Atlas Project
Edinburgh Mouse Atlas Gene Expression
Geography Markup Languaged
International Organization for Standardization
Open Geospatial Consortium
OGC Web Services
University of California San Diego
Unified Modeling Language
W3C XML Schema Definition Language
7
WaxML
WCS
WHS
WMS
WPS
XML
1D
2D
3D
INCF Waxholm Markup Language
Web Coverage Service
INCF Waxholm Space
Web Mapping Service
Web Processing Service
Extensible Markup Language
One Dimensional
Two Dimensional
Three Dimensional
5.2.
XML conventions
To describe the parts of an XML file in text, this document uses the following conventions:
 Element names are enclosed in brackets, e.g. <element>
 Attributes are prefixed with the @ symbol, e.g. @attribute
 Element text (text content of an element) is enclosed in quotes, e.g. “element text”
The following example XML illustrates these conventions. The example shows a <PlusZ>
element, with a @maxValue attribute and a text value of “Anterior”.
<PlusZ maxValue="9.0" xlin:href="#Anterior">Anterior</PlusZ>
8
6. Core concepts and implementation context
6.1.
INCF Service Oriented Architecture (SOA): INCF
Hubs and services, INCF Central
The goal of INCF Digital Atlasing Infrastructure Task Force is to develop scientific and
technical foundations and development principles and prototypes for a distributed system of
neuroscience resources that can be published, shared and integrated based on spatial
characteristics of their content. These spatial characteristics can include different ways of
referencing location in the brain (by coordinates, by anatomic labels, by spatial placement
rules, verbally), different types of spatial relationships (common topological and metric
relationships, as well as specific spatial predicates used by neuroscientists) and different
types of spatial arrangement and patterns. In the initial version of the INCF atlasing
infrastructure, we address only one manner of spatial data integration across atlases: by
location in the brain defined in a brain spatial reference system.
This distributed system of neuroscience resources is presented as a collection of selfcontained web services that expose location-based functionality and describe spatial
properties of atlases. These services are envisioned to be a part of general INCF
cyberinfrastructure developed to support interoperability between neuroscience resources of
different types.
The INCF-DAI Service-Oriented Architecture (SOA) would rely, where possible, on:
 standard service interfaces and encoding schemas;
 standardized coordinate reference systems, and a service-accessible registry of
reference systems;
 a collection of coordinate transformation services, with Waxholm Space (WHS) at
the center;
 standardized data models for the types of neuroscience data incorporated in the
SOA;
 standard terminology explicated in registered ontologies and available via term
cross-walks where needed.
9
Figure 1. INCF SOA: main components
Figure 1 presents a vision of a neuroscience information system enabling publication and
access to different types of data. . This list of data types is not exhaustive. The information
models for each data type abstract distributed data sources, allowing them to be published
as web services in a standard manner, and then registered and indexed at INCF service
registries. Generally, registration would place each neuroscience resource in a spatial and
semantic framework, and in other frameworks as required by querying over different types
of data. Each of the resource types may be managed in its own registry; in addition the
spatial and semantic registries can be used across data types to support querying by spatial
and semantic attributes where appropriate. Note that a particular physical resource may
expose more than one type of data, e.g. the Allen Brain Atlas (ABA) includes 2D images and
3D volumes, gene expression data and segmentations, some of which share semantic and
spatial frameworks.
From the user perspective, the resources, registries and catalogs will be accessible from
several types of user interfaces: data management, data publication/registration, data
curation, visualization, analysis and annotation. Since in neuroscience atlasing many user
interfaces are unique and tuned to specific types of resources, it is also useful to have a
services interface that supports exchange of spatial information between clients.
At the physical level the resources referenced above can be published at INCF hubs
(NeuroHubs) as web services, and registered at INCF Central.
As shown in Figure 2, a NeuroHub may contain different types of resources exposed as
different types of standard web services, beyond atlas services specifically. They may
10
include, for example, services for other types of data, database and registry management
and harvesting tools, collaboration and other applications.
Figure 2. Potential content of an INCF Hub
Figure 3. INCF Central and INCF Hubs
Different types of neuroscience hubs in INCF SOA could include, for example (see Figure 3):

National hubs: as long as they provide a list of services through GetCapabilities
and DescribeProcess mechanism, and perhaps support RSS (ideally, GeoRSS,
references coordinates in a brain coordinate system) feeds;
11


Community software repositories such as NITRC: as long as they support
GetCapabilities requests and expose their holdings via some standard protocol,
e.g. CSW/ebRIM;
Specialized resources, such as simulation providers or ontology providers and
marked-up resource providers such as NIF: as long as they are exposed via some
discovery and access services that can be used to harvest their metadata
content.
The different atlas hubs and the services they host can be registered at INCF Central. The
functions of the INCF Central server will include:







Allow hub data managers to register their hubs to the INCF Central, and edit hub
metadata;
Support service access to and query of hub registration records;
Support regular harvesting of hub metadata into a collection of INCF Central
tables;
Support discovery hub metadata, including information about known coordinate
reference systems, spatial transformations, functionality of each hub, and
registered spatial datasets (e.g. images);
Spawn data queries to atlas hubs;
Compute chains of coordinate transformations that may involve multiple hubs;
Support subscription/notification of users as information becomes available in a
catalog on a particular topic or area.
In addition to the portal, discovery and registration server (INCF Central), the central facility
may support a co-located INCF hub. Its functions will include: providing space and data
management and other functions for INCF-DAI users who cannot register their resources to
other national or project hubs; maintaining framework datasets and reference systems (in
case of atlasing, it would include, for example, versions of the WHS spatial reference system
and reference datasets); maintaining standards-based wrappers of external hubs; often
used resources from other hubs that would be efficient to cache centrally to ensure their
high availability.
The different types of services are listed in a local NeuroHub service registry (or Neurohub
catalog). The NeuroHub service registry may follow the CSW specification
(http://www.opengeospatial.org/standards/cat), or any other convenient specification, or
just generate a custom capability document in response to a hub-level GetCapabilities
request.
Hub services are expected to follow standard service interface specifications and publish
their capabilities via GetCapabilities method describing the content of the service. For
example, atlas services described below declare their content via GetCapabilities request
which is part of the Web Processing Service interface standard. Other hub services may use
other interface standards as appropriate, as long as they support a Capabilities description
which can be registered at the INCF Central server. At the very least, such capabilities
descriptions would contain service type and endpoint, and general Dublin core metadata.
12
6.2.
Atlas services
An INCF Atlas Service represents a collection of web functions that provide access to brain
atlas resources available in a NeuroHub, as well as translations from specific atlas spatial
reference systems (SRS) or vocabularies local to the hub, to INCF-supported spatial
reference system (currently: WHS) and an ontology management system (currently: NIFbased), respectively.
The role of INCF Central is to support a discovery system over metadata harvested from
distributed atlas services, and let registered users add/update service registrations.
The key INCF-DAI data publishing and registration workflow that involves Atlas
Services and INCF Central, can be described as follows:







A collection of data loaders for specific types of data, available at the hub or on a
local machine, is used by INCF hub manager to ingest and publish data as hub’s
resources.
The loaders populate a data store for each specific type of data (e.g. gene
expression data loader takes Excel or CSV files and puts them into RDBMS).
Indexes are rebuilt and databases are tested for outliers, completeness, etc. A
template data store shall be provided as part of a “standard hub” (see below).
To create a new service instance for the new data, a service template for each
data type is configured to point to the local data store instance where the data
have been ingested (e.g., by editing connection parameters and metadata), and
the service is automatically deployed.
The service registry at the local hub (or directly at INCF Central) is updated to
include a reference to the new service . If the hub maintains a local service
registry, INCF Central should be capable of harvesting this registry rather than
individual services
INCF Central’s registry application automatically re-harvests registered
resources, whether they represent hub catalogs or individual atlas service
capabilities (at regular intervals, or as triggered by service registration).
Once the new service is registered at INCF Central by a hub data manager, INCF
Central curator validates and approves the service, making it available via the
INCF Central catalog, and incorporating hub’s resources into INCF Central’s
federated applications (e.g. computation of coordinate transformations across
hubs) The INCF Central catalog services may support one or more client
applications, e.g. the Whole Brain Catalog, BrainExplorer, and MBAT.
Operational roles envisioned in the above scenario are: a) hub data manager, and b) INCF
Central curator.
13
Figure 4. INCF atlas hubs
Since we often deal with a collection of legacy atlas services with variety of query and
access mechanisms, and established APIs, we make a distinction between “standard” hubs
and “hybrid” hubs. In the former case, the entire atlas service functionality is provided by a
remote hub, while the central facility only maintain service registration, In the latter case,
INCF Central hub will maintain a wrapper of atlasing functions of a resource. This wrapper
will provide a collection of core services and extended hub services (e.g. GetCorrelationMap
described below, which is specific for the ABA hub) that can be further registered at the
INCF Central server. Figure 4 demonstrates a collection of such hybrid hubs that wrap
existing atlas applications and services to expose them as standard atlasing resources.
6.3.
Spatial reference systems and SRS registry
A registry of spatial coordinate systems is one of the key components of global spatial data
infrastructure. In the earth science domain, EPSG Geodetic Parameter Dataset
(http://info.ogp.org.uk/geodesy/Geodetic.html) is widely used. The geospatial SRS registry
at http://www.epsg-registry.org/ contains descriptions of thousands of spatial reference
systems. In particular, it has the following naming conventions when describing coordinate
systems:
Code: EPSG::4326 (this code is used by services and applications to reference the SRS)
Name: WGS 84 (this is a generic name of the SRS; note that versioning is loosely captured
by specifying a year: World Geodetic System 1984)
Type: geographic 2D
For INCF DAI, we propose a similar standards-setting repository of neuroscience coordinate
systems. Figure 5 shows the available coordinate systems, with origin and axis orientation
shown on each diagram with respect to neuroscience orientations.
SRSName, used to refer to a specific SRS, is constructed as a concatenation
"Species_BaseName_Version", as in the following table:
Table 1. Spatial reference system core characteristics
srsCode
srsName
srsBase
INCF:0001 Mouse_WHS_0.9
WHS
srsVersion Species srsDescription
0.9
Mouse WHS initial
14
INCF:0002 Mouse_WHS_1.0
WHS
1.0
Mouse
INCF:0100 Mouse_ABAvoxel_1.0
ABAvoxel
1.0
Mouse
INCF:0101 Mouse_ABAreference_1.0 ABAreference 1.0
Mouse
INCF:0102 Mouse_AGEA_1.0
AGEA
1.0
Mouse
INCF:0200 Mouse_Paxinos_1.0
Paxinos
1.0
Mouse
INCF:0300 Mouse_EMAP-T23_1.0
EMAP-T23
1.0
Mouse
version, with
origin in
back-leftbottom
corner
WHS with
origin shifted
to AC-midline
intersection
SRS used in
ABA 3D
model
SRS in ABA
reference
atlas of
mouse brain
SRS used in
ABA gene
expression
module, a
derivative of
ABAvoxel
SRS in
PaxinosFranklin
stereotaxic
atlas
A T23 model
of EMAP
developing
mouse atlas
The use of INCF:XXXX codes will be encouraged in the next phase, once their interpretation
is established. At the moment this srsCode assignment is arbitrary.
When referring to transformations between coordinate systems, we use the following
naming convention: "inputSrsName_To_outputSrsName_Version", e.g.
Mouse_Paxinos_1.0_To_Mouse_WHS_0.9_v1.0. Further details are in the section on
transformations.
The INCF-DAI SRS registry includes the following tables:

SRS (spatial reference system): contains key attributes of SRS, in particular
relationship between X, Y and Z coordinate axes and orientations in the brain
described in the Orientation table, and a pointer to a reference implementation of
the space. Fields: SRSCode, SRSName, SRSDescription, SRSVersion, SRSAuthor,
SRSDateSubmitted, Origin of the coordinate system, NeuroPlusX, NeuroMinusX (and
the same for Y and Z), RegionOfValidity (some SRSes can be defined only locally to
an anatomic structure or a group of structures), RegionURI (URN pointing to
definition of the area of validity), extents of coordinates in each direction
(DimensionMinX, DimensionMaxX - and the same for Y and Z), Units, SourceURI of
15
the reference implementation, SourceDescriptionURI, SourceFileFormat, Abstract,
DerivedFrom (in case the SRS is derived from another SRS), DerivedMethod

Structure: describes anatomic features segmented in 2D or 3D, and contains the
following fields: StructureCode, StructureName, StructureVersion, StructureType,
SRSCode (i.e. to which space in SRStable this Structure belongs),
StructureVocabulary (vocabulary in which this feature is named), StructureAuthor
(who named and delineated the structure), pointer to spatial objects/SVA/VRML files,
Date of submission, Version, Certainty level (or pointer to certainty description).

Fiducial (or Landmarks): fiducials are points or higher-dimensional features
generally derived from anatomic Structures; they can be used to relate one SRS to
another. Relevant attributes are FiducialCode, FiducialName, FiducialType
(instrument artifact, or derived from a feature), DerivedFrom (or some provenance
description, derivation function (either explicitly encoded or pointing to a function
description), certainty_level (as propagated from location accuracy of anatomic
structures from which the fiducial is derived), AuthorCode, spatial data object
describing the fiducial (point, line, polygon, volume, etc.) .

Orientation: provides interpretation of neuroscience coordinate axes. These axes
may be simple (e.g. describing straight dorsal-ventral orientations), or complex - for
development brain (where the posterior and anterior orientations may be described
as curves rather than straight lines) or tilted volumes/images. The attributes are:
OrientationCode, OrientationName, OrientationDescription, Author (submitter), and
DateSubmitted. The Orientation name may contain standard terms such as
"anterior", "posterior", "left", "right", "dorsal", "ventral (in that case the “Author” is
“standard”), or some functions of those.

Slice: description of individual slices that form up the atlas; this information is
necessary when the atlas space is defined through a collection of 2D plates with
segmented structures rather than by a 3D volume. The attributes include: SliceCode
(typically, the slice # in the atlas), Orientation (coronal, sagittal, horizontal),
SRSCode, ConstantValue (e.g. distance to bregma, distance to midline, depending on
the Orientation of the plate), Xorientation (direction of the horizontal axis on the
plate, with respect to neuroscience orientations), Yorientation (the same for the
vertical axis), Description.
Additional tables in the registry may include: rules_for_fiducials (specifying that, for
example, a particular fiducial/landmark is located at the intersection of AC line and midline,
or at some spatial relationship to one or more segmented anatomic features), authors
(those responsible for defining SRS or their components), vocabularies. A sample relational
schema reflecting the minimal set of tables is shown in Figure 6. Information from this
registry will be available via ListSRSs and DescribeSRS, and potentially via other requests
against additional tables. SRSType element, the key information object returned by these
two requests, is shown in Figure 7.
16
Figure 5. Spatial Reference Systems
17
Figure 6. Sample relational representation of SRS tables
18
Figure 7. Schema of the SRSType element
6.4.
List of atlas services at hub level
We consider the following types of service requests within Atlas Services:
A. Core atlas service requests, expected to be implemented by all or most atlas hubs:





Capability descriptions: GetCapabilities and DescribeProcess. These requests are
mandatory components of Web Processing Service (WPS), which is used as the
interface model for atlas services; they shall be implemented for each atlas service .
Descriptions of available spatial reference systems: ListSRSs, DescribeSRS. These
functions are expected to be supported by an atlas service if the hub hosts one or
more coordinate systems.
Spatial transformations: ListTransformations, DescribeTransformation,
TransformPOI. These methods should be supported by those hubs that publish a
local coordinate system; others may use centrally stored transformations without
declaring their own.
Structure Lookup: GetStructureNamesByPOI. This method should support
structure lookup for canonical set of segmentations of each atlas (we expect that an
atlas comes with a single set of “authoritative” segmentations. If there are multiple
versions of the segmentations by the maintainer of the canonical space, the latest
version is returned (unless an earlier version is requested explicitly).
Two generic POI-based requests: GetObjectsByPOI and GetPropertyByPOI: the
first one returns a list of discrete objects in the vicinity of the point of interest (e.g.
cells, annotations); the second one assumes a continuous field and returns a value
at the specified location, or some aggregate measure computed for this location (e.g.
based on voxel neighborhood of the POI.)
19
B. Atlas service requests that are not mandatory but are likely to be implemented at
one or several hubs. Strictly speaking these methods are outside the scope of atlas
services. However, we include descriptions of several common requests in this
document. The intent is to demonstrate how reliance on WPS standard allows
developers to design, develop, register and consume atlas services even if they
follow different information models. We believe that establishing interoperability at
the level of service interfaces would be the necessary first step towards broader atlas
interoperability, while agreeing on a common information model may take
significantly longer effort. In addition, in our opinion, formulating atlas service
requests in terms that generally follow naming conventions in neuroscience, would
encourage their adoption despite information model imperfections – which remains
an active area of research.




POI-based requests, such as Get2DImagesByPOI; GetCorrelationMapByPOI;
GetGenesByPOI. To the extent possible, method signatures for such requests have
been made uniform across different hubs.
Other methods, including those based on structure names, e.g.
GetGenesByStructureName. While these requests do not refer to atlas coordinate
spaces, or WHS, directly, they may be the only way to connect to atlases for which
spatial transformations have not been or cannot be developed, but structures have
been identified and these names have been shown to correspond to known standard
structure delineations.. While such methods are outside the scope of atlas aervices
they may be needed to support common scenarios where POI-based requests are not
available.
Basic information about the content of atlas services, harvested by INCF central
server: ListGenes, ListStructures, etc.
Registration, monitoring and subscription/notification services. These are undefined,
at present, but include methods to register a hub with the central server, a method
to list all hubs (at the central server), and an “I’m alive” service monitor to alert the
central server of a hubs status, and workload.
C. Atlas services needed for registering data to a common spatial and semantic
framework. These services are not covered by this specification, because they are
internal to each hub’s data management workflows. However, we believe that it is
important to provide an easy path for hub developers to integrate their image and
segmentation data with INCF-DAI: thus, a common specification of registration
services would be useful since these are the most essential components of a hub,
and could find wide cross-hub application. As sketched below, the registration service
requests are intended to support: a) the ability to incorporate various registration
algorithms, and b) integration of registration functions with INCF-DAI, so that the
registration leads to automatic generation of SRS descriptions (DescribeSRS) and
coordinate transformation (TransformPOI) requests.
A spatial registration workflow built on such principles, would include: a) establishing
correspondence between user images or volumes, and the canonical reference space
(e.g. WHS, but also any other SRS defined in INCF-DAI) – using any available
algorithm and user environment, manual or automatic (e.g. based on manually
established fiducials, or automatic entropy-based alignment, etc.). Ideally, the
different algorithms would be available via services, so that users could select the
most appropriate technique; b) the alignment algorithm generates a description of
image spatial reference system, which may be added to the INCF SRS registry if the
spatial reference system is likely to be used for multiple datasets (and become
available via DescribeSRS requests); c) transformations computed in the first step
20
are used to instantiate a coordinate lookup, and a corresponding TransformPOI
request; d) the computed transformations may be also used to generate a warped
version of the initial image or volume, so that it can be aligned with WHS or another
target reference space.
D.
In the future, another group of methods, which supports exchanging location information
between atlases as spatial placement rules (as described in the INCF Atlasing task force
report), will be developed.
6.5.
List of atlas services as INCF Central
INCF Central’s functionality includes registration of atlas services from individual hubs,
harvesting their metadata to support centralized querying across hubs; data discovery and
query orchestration functions. For better performance, INCF Central may cache selected
framework datasets and operations (in particular, spatial operations and transformations);
perform load balancing and service monitoring, and support subscription/notification about
atlas service updates. The following tentative list of services is proposed (maintaining
compatibility with INCF Hubs API as maximally possible):
1. INCF Central’s capability descriptions: GetCapabilities and DescribeProcess,
which will provide INCF Central’s metadata, and reference two types of Execute
requests:
2. Execute requests that spawn one or more identical standard requests to registered
hub services, and union the results. The output schemas of these requests
(GetStructureNamesByPOI, Get2DImagesByPOI, other POI-based requests, as
well as “List” requests such as ListSRSs and ListTransformations) are identical to
respective schemas used by atlas services at individual hubs.
3. Execute requests that rely on harvested information from other hubs in order to
proceed. An example currently implemented at INCF Central is
4.
5. GetTransformationChain, which computes a chain of coordinate transformations
that may involve transformations hosted by multiple hubs
6.
21
7. Service signatures and WaxML schemas
7.1.
Atlas services as WPS profile: the basics
The INCF atlas services hosted by an Atlas hub represent a collection of HTTP GET
requests modeled after the WPS interface specification. Web Processing Service (WPS,
http://www.opengeospatial.org/standards/wps) provides a standard framework for invoking
and chaining web requests, specifically oriented to requests that can be described as spatial
data processing functions. It is selected here as a generic way of describing web
functionality that supports several bindings, allows service chaining with BPEL4WS, and has
several client and catalog implementations.
The general format of the request is:
http://<server-path>/HostServiceController?Service=WPS&version=1.0.0
&request=<WPS_Request>
&Identifier=<identifier_name>
&ResponseForm={format}
&DataInputs={Encoded Inputs}
In the discussion of method signatures below we refer to a base WPS request which takes
the following form:
http://<server-path>/HostServiceController?service=WPS
In order to discover the available processing services at a node, a client would invoke the
service and request a capabilities document:
{BaseServiceUrl}&request=GetCapabilities
This request returns general service capabilities including the version of the service and a
list of function (process) identifiers. A more complete description of functionality
implemented in a WPS service is provided by a DescribeProcess call, which takes the service
version and a method identifier (optionally) as inputs:
{BaseServiceUrl}&version=1.0.0&request=DescribeProcess&Identifier={ProcessT
oDescribe}
Examples of WPS requests in the current implementation are:
http://incf-devlocal.crbs.ucsd.edu/aba/atlas?service=WPS&request=GetCapabilitieshttp://incf-devlocal.crbs.ucsd.edu/aba/atlas?service=WPS&version=1.0.0&request=DescribeProcess&Ident
ifier=Get2DImagesByPOIhttp://incf-devlocal.crbs.ucsd.edu/aba/atlas?service=WPS&version=1.0.0&request=Execute&Identifier=Tr
ansformPOI&DataInputs=transformationCode=Mouse_ABAvoxel_1.0_To_Mouse_AGEA_1.0_
22
v1.0;x=1;y=112;z=162Note that this syntax recognizes that atlas services (invoked as
“atlas?”) are hosted within a hub (“aba”, in this case).
WPS specification support several additional components of the calling requests. For atlas
services, most important of them are:

&lineage=true: includes lineage information in the response (Data Inputs), which
may be useful if responses are saved on disk for future use. For example:
http://incf-devlocal.crbs.ucsd.edu/aba/atlas?service=WPS&version=1.0.0&request=Execute&Identifier=Tr
ansformPOI&lineage=true&DataInputs=transformationCode=Mouse_ABAvoxel_1.0_To_Mou
se_AGEA_1.0_v1.0;x=1;y=112;z=162

&storeExecuteResponse=true: stores the result of the request as a web-accessible
resource, which may be useful if responses are large or need to be processed on the
server without being returned to the client; instead, a URL of the stored response is
returned:
http://incf-devlocal.crbs.ucsd.edu/aba/atlas?service=WPS&version=1.0.0&request=Execute&Identifier=Tr
ansformPOI&storeExecuteResponse=true&DataInputs=transformationCode=Mouse_ABAvox
el_1.0_To_Mouse_AGEA_1.0_v1.0;x=1;y=112;z=162

&status=true: for long-running processes which create a web-accessible resource,
requests a status update:
http://incf-devlocal.crbs.ucsd.edu/aba/atlas?service=WPS&version=1.0.0&request=Execute&Identifier=Tr
ansformPOI&storeExecuteResponse=true&status=true&DataInputs=transformationCode=M
ouse_ABAvoxel_1.0_To_Mouse_AGEA_1.0_v1.0;x=1;y=112;z=162

&RawDataOutput=[TransformPOIOutput]: used when a short response is requested,
only returning process output (when there is only one output), e.g.
http://incf-devlocal.crbs.ucsd.edu/aba/atlas?service=WPS&version=1.0.0&request=Execute&Identifier=Tr
ansformPOI&RawDataOutput=TransformPOIOutput&DataInputs=transformationCode=Mous
e_ABAvoxel_1.0_To_Mouse_AGEA_1.0_v1.0;x=1;y=112;z=162
The WPS specification document provides detailed descriptions of the rules for specifying
these and other inputs.
Draft service output specifications are presented below. They are expected to follow
Waxholm Markup Language (WaxML), a working name for an output schema that we
are designing to provide a uniform information model for the elements that form an atlas:
coordinate reference systems, transformations, POIs, and objects returned on POI-based
requests. Where other standards are available (e.g. for gene expression data, for
23
description of feature geometry, for coordinate information) the respective elements will be
presented in their own namespaces.
7.2.
Atlas services and WaxML conventions
Where feasible, objects and properties are described by a triad: propertyCode,
propertyName and propertyDescription. The “code” is expected to be unique within a hub.
Names and Descriptions don’t need to be unique. For example, a propertyCode may be
“HIP” (or some numeric code), propertyName may be “Hippocampus”, and
propertyDescription may be “Hippocampal area”. Either propertyCode or propertyName may
be used as a Label for display purposes. Similarly, spatial reference systems may have an
srsCode (e.g. "INCF:0001"),srsName (e.g. "Mouse_WHS_0.9") and srsDescription (e.g. "the
original version of the Waxholm reference dataset".) Ideally, property names shall be
accompanied by a persistent URI pointing the property definition in a community vocabulary
system.
The naming standard for atlas service methods we generally follow is:



List: list objects without a query. These requests should support paging capabilities,
and enable harvesting.
Describe: returns a single object using a persistent identifier
Get: returns one or more objects using a submitted query, or a pointer to a service
Objects and properties can be specified in a globally unique way by prepending their codes
with a respective hub and coordinate space or vocabulary name, in the form:
hub:{srs|vocabulary}:code,
e.g. ABA:Mouse_ABAvoxel_1.0:HIP (which stands for Hippocampus labeled “HIP” in the
vocabulary associated with the current ABAvoxel volume and served from the ABA hub).
Depending on the context, the hub prefix can be omitted. In many cases, however, it may
be better to use a descriptive "name" in place of a cryptic "code".
The general agreement is that XML elements (and UML classes, interfaces, associations,
packages, states, use cases, actors) are specified in UpperCamelCase, while attributes (as
well as UML attributes, roles, operations, stereotypes, instances, events, actions) follow the
lowerCamelCase convention. This is generally consistent with business practices (e.g.
http://xml.coverpages.org/ebXML-TechArchv104.pdf)
While the above capitalization rules shall be generally followed, parsers should be caseinsensitive. In the HTTP GET strings, the same capitalization conventions should apply. In
addition, three high-level keywords (service, request and version) are lower-case, while
other components of URLs (e.g. DataInputs, Indentifier) are in UpperCamelCase.
24
Services should support authentication/authorization (where required). In case of atlas
data, authorization would be at the level of spatial registry records.
Services should provide a mechanism for retrieving the best quality record: e.g. multiple
versions of the same image may be registered in a spatial registry, but based on
preferences established by a hub manager, only the most recent version may be available
by default (other versions would require authorization)
7.3.
GetCapabilities
This is a mandatory method to be implemented by each atlas service. The request is:
{BaseService}&request=GetCapabilities
A sample method call (against the atlas service hosted by the ABA hub):
http://incf-dev-local.crbs.ucsd.edu/aba/atlas?service=WPS&request=GetCapabilities
The output includes service metadata (title, abstract, type, version) – which are common for
all OGC service specifications (and hence are in the ows – ‘OGC Web Service’ – namespace).
It also includes a list of functions (processes) that can be called via the WPS Execute
directive (the wps namespace is used here). The functions are grouped within the
wps:ProcessOfferings element; each has an identifier, title, abstract and version.
25
A sample output is (fragment):
<?xml version="1.0" encoding="UTF-8"?>
<wps:Capabilities xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1"
xmlns:ogc="http://www.opengis.net/ogc" xmlns:gml="http://www.opengis.net/gml"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
service="WPS" version="1.0.0" xml:lang="en" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0
http://schemas.opengis.net/wps/1.0.0/wpsGetCapabilities_response.xsd">
<ows:ServiceIdentification xmlns:ows="http://www.opengis.net/ows">
<ows:Title>ABA Atlas Services</ows:Title>
<ows:Abstract> . . .
</ows:Abstract>
<ows:ServiceType>WPS</ows:ServiceType>
<ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
</ows:ServiceIdentification>
<ows:ServiceProvider>
<ows:ProviderName>INCF Digital Atlasing Infrastructure Task Force</ows:ProviderName>
<ows:ProviderSite xlink:href="http://ucsd.edu"></ows:ProviderSite>
<ows:ServiceContact>
<ows:IndividualName>Ilya Zaslavsky</ows:IndividualName>
. . .
</ows:ServiceContact>
</ows:ServiceProvider>
<ows:OperationsMetadata>
<ows:Operation name="GetCapabilities">
<ows:DCP>
<ows:HTTP>
<ows:Get xlink:href="http://incf-dev-local.crbs.ucsd.edu/aba/atlas?"></ows:Get>
<ows:Post xlink:href="http://incf-dev-local.crbs.ucsd.edu/aba/atlas"></ows:Post>
</ows:HTTP>
</ows:DCP>
</ows:Operation>
<ows:Operation name="DescribeProcess">
<ows:DCP>
<ows:HTTP>
<ows:Get xlink:href="http://incf-dev-local.crbs.ucsd.edu/aba/atlas?"></ows:Get>
<ows:Post xlink:href="http://incf-dev-local.crbs.ucsd.edu/aba/atlas"></ows:Post>
</ows:HTTP>
</ows:DCP>
</ows:Operation>
<ows:Operation name="Execute">
<ows:DCP>
<ows:HTTP>
<ows:Get xlink:href="http://incf-dev-local.crbs.ucsd.edu/aba/atlas?"></ows:Get>
<ows:Post xlink:href="http://incf-dev-local.crbs.ucsd.edu/aba/atlas"></ows:Post>
</ows:HTTP>
</ows:DCP>
</ows:Operation>
</ows:OperationsMetadata>
<wps:ProcessOfferings>
<wps:Process wps:processVersion="1.0.0">
<ows:Identifier>GetStructureNamesByPOI</ows:Identifier>
<ows:Title>Get Structure Names by POI</ows:Title>
<ows:Abstract>
The response from this request contains a list of anatomic structure codes and their
descriptions.
</ows:Abstract>
</wps:Process>
</wps:ProcessOfferings>
<wps:Languages>
<wps:Default>
<ows:Language>en</ows:Language>
</wps:Default>
<wps:Supported>
<ows:Language>en</ows:Language>
</wps:Supported>
</wps:Languages>
</wps:Capabilities>
26
Figure 8. XML schema diagram of the Capabilities response
7.4.
DescribeProcess
This method describes inputs and outputs of functions (processes) implemented within an
atlasing service at a hub. The base WPS request is
{BaseService}&version=1.0.0&request=DescribeProcess
Example method call is:
http://incf-dev.crbs.ucsd.edu:8080/atlas-aba?service=WPS&version=1.0.0&request=DescribeProcess
The output of this request provides details of either all processes within the service, or a
single process (specified by identifier). Each process (“ProcessDescription” element) is
characterized by an identifier, title, abstract, version, and process inputs and outputs. Each
process input, in turn, has an identifier, title and abstract, as well as a list of allowed values
if applicable. ProcessOutput includes a reference to the type of output (both default and
supported), and possibly a reference to the schema that the output should comply with.
Process metadata are being further discussed within OGC, and OGC WPS 2.0 (which is now
nearing completion (see http://www.opengeospatial.org/projects/groups/wps2.0swg) may
have additional attributes. In particular, inclusion of semantic annotations in WPS and other
OGC standards would be a useful extension (e.g.
http://portal.opengeospatial.org/files/index.php?artifact_id=34916).
27
A sample example output is (fragment):
<?xml version="1.0" encoding="UTF-8"?>
<wps:ProcessDescriptions xmlns:wps="http://www.opengis.net/wps/1.0.0"
xmlns:ows="http://www.opengis.net/ows/1.1" xml:lang="en-US" version="1.0.0"
service="WPS">
<ProcessDescription wps:processVersion="1.0.0">
<ows:Identifier>DescribeSRS</ows:Identifier>
<ows:Title>Describe SRS</ows:Title>
<ows:Abstract/>
<DataInputs>
<Input>
<ows:Identifier>srsName</ows:Identifier>
<ows:Title>Atlas SRS Name</ows:Title>
<ows:Abstract>The Atlas SRS (Spatial Reference System) name.</ows:Abstract>
<LiteralData>
<ows:AllowedValues>
<ows:Value>Mouse_ABAreference_1.0</ows:Value>
<ows:Value>Mouse_ABAvoxel_1.0</ows:Value>
<ows:Value>Mouse_AGEA_1.0</ows:Value>
<ows:Value>Mouse_EMAP-T26_1.0</ows:Value>
<ows:Value>Mouse_Paxinos_1.0</ows:Value>
<ows:Value>Mouse_WHS_0.9</ows:Value>
<ows:Value>Mouse_WHS_1.0</ows:Value>
</ows:AllowedValues>
</LiteralData>
</Input>
</DataInputs>
<ProcessOutputs>
<Output>
<ows:Identifier>ImageURL</ows:Identifier>
<ows:Title>2D Image at POI result</ows:Title>
<ows:Abstract>2D Image at POI result</ows:Abstract>
<ComplexOutput>
<Default>
<Format>
<MimeType>application/vnd.incf.waxml</MimeType>
<Encoding>UTF-8</Encoding>
<Schema>http://www.incf.org/atlas/WaxML/schema/DescribeSRSResponse.xsd</Schema>
</Format>
</Default>
<Supported>
<Format>
<MimeType>application/vnd.incf.waxml</MimeType>
<Encoding>UTF-8</Encoding>
<Schema>http://www.incf.org/atlas/WaxML/schema/DescribeSRSResponse.xsd</Schema>
</Format>
</Supported>
</ComplexOutput>
</Output>
</ProcessOutputs>
</ProcessDescription>
...
</wps:ProcessDescriptions>
28
Figure 9. XML schema diagram of ProcessDescription
7.5.
Execute ListSRSs
The WPS Execute operation processes the requests and delivers an XML document to the
client (by default: when process execution has been completed), following a schema
generally depicted in Figure 11. ListSRSs is the first of a series of processes invoked via the
WPS Execute mechanism.
Figure 10. XML schema diagram of the Execute response
29
The ListSRS process returns a list of coordinate reference systems with their metadata as
defined in the WaxML schema and discussed in section 6.3. The request shall be
implemented at both atlas hubs and at the INCF central server. Atlas hubs don’t need to
maintain coordinate space definitions that are already registered at the INCF Central server
– but they shall maintain definitions of coordinate spaces that are unique for this hub.
The basic request, in WPS syntax, is:
{BaseService}&version=1.0.0&request=Execute&Identifier=ListSRSs
Example request:
http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&version=1.0.0&request=Execute&Identifier=ListSRSs
The ListSRSResponse structure returned on this request, includes <QueryInfo>, <SRSList>
and <Orientations> as the main components.
<QueryInfo> is a common component of atlas service responses. Populating it is
encouraged though not required. Using <QueryInfo> allows users to re-examine the source
of information and trace the lineage if needed. Often, a single query URL and a list of inputs
is not sufficient to define a source of returned data completely. In this case, additional
<note> elements with @type=”sourceUrl” are suggested.
Figure 11. XML schema diagram of the QueryInfo component. The
element is expected to be included in all Execute requests
The SRSList element nests <SRS> elements which provide brief SRS descriptions. Each SRS
is characterized by its name, code, basename, version and species; includes description,
author, and dates when created and updated. Other attributes closely follow the fields in the
SRS table as described in 6.3.
The <Orientations> element contains descriptions of orientations in the brain as referenced
within the <Neurodimensions> element of SRS description. It is essential for interpreting
(X,Y,Z) coordinates used in SRS with respect to coordinate axes as they are commonly used
in neuroscience. The orientations may be simple (e.g. posterior, ventral, etc.), or some
functions of the simple orientations.
30
<ListSRSResponse xmlns="http://www.incf.org/WaxML/" xmlns:gml="http://www.opengis.net/gml/3.2">
<QueryInfo>
<QueryUrl>http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=ListSRSs</QueryUrl>
</QueryInfo>
<SRSList>
<SRS>
<Name srsCode="INCF:0101" srsBase="ABAreference" srsVersion="1.0" species="Mouse">Mouse_ABAreference_1.0</Name>
<Description>ABAreference</Description>
<Author authorCode="ABA" dateSubmitted="2010-09-14-07:00"/>
<DateCreated>2010-09-14-07:00</DateCreated>
<DateUpdated>2010-09-14-07:00</DateUpdated>
<Origin>bregma</Origin>
<Area structureName="whole brain"/>
<Units uom="mm"/>
<Neurodimensions>
<MinusX maxValue="-6.0">Right</MinusX>
<PlusX maxValue="6.0">Left</PlusX>
<MinusY maxValue="-1.0">Dorsal</MinusY>
<PlusY maxValue="7.0">Ventral</PlusY>
<MinusZ maxValue="-9.0">Posterior</MinusZ>
<PlusZ maxValue="6.0">Anterior</PlusZ>
</Neurodimensions>
<Source format="Slices">http://mouse.brain-map.org/welcome.do</Source>
<DerivedFrom/>
</SRS>
<SRS>
<Name srsCode="INCF:0100" srsBase="ABAvoxel" srsVersion="1.0" species="Mouse">Mouse_ABAvoxel_1.0</Name>
<Description>ABAvoxel</Description>
<Author authorCode="ABA" dateSubmitted="2010-09-14-07:00"/>
<DateCreated>2010-09-14-07:00</DateCreated>
<DateUpdated>2010-09-14-07:00</DateUpdated>
<Origin>front-right-top</Origin>
<Area structureName="whole brain"/>
<Units uom="px"/>
<Neurodimensions>
<MinusX maxValue="0.0">Anterior</MinusX>
<PlusX maxValue="528.0">Posterior</PlusX>
<MinusY maxValue="0.0">Dorsal</MinusY>
<PlusY maxValue="320.0">Ventral</PlusY>
<MinusZ maxValue="0.0">Right</MinusZ>
<PlusZ maxValue="456.0">Left</PlusZ>
</Neurodimensions>
<Source>http://mouse.brain-map.org/welcome.do</Source>
<DerivedFrom/>
</SRS>
</SRSList>
<Orientations>
<Orientation code="Left" gml:id="72" name="Left">
<Description>Left of midline.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Right" gml:id="72" name="Right">
<Description>Right of midline.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Ventral" gml:id="99" name="Ventral">
<Description>Towards the abdomen/front.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Dorsal" gml:id="78" name="Dorsal">
<Description>Toward spinal column/back.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Posterior" gml:id="15" name="Posterior">
<Description>Towards the back.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Anterior" gml:id="62" name="Anterior">
<Description>Towards the front.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
</Orientations>
</ListSRSResponse>
31
Figure 12. XML schema diagram of ListSRS response
7.6.
Execute DescribeSRS
DescribeSRS (srsName) is a companion request that provides detailed information about
a spatial reference system, including SRS metadata (as in the previous request), and
possibly features, fiducials, and other components as specified in the SRS model in Section
6.3. The features, fiducials and slides associated with an SRS may be listed and described
by separate calls, which will be defined once the SRS information model is finalized. A series
of such calls should be sufficient to populate the relational structure describing coordinate
reference systems at the INCF Central.
The basic request, in WPS syntax, is:
{BaseService}&version=1.0.0&request=Execute&Identifier=DescribeSRS&DataIn
puts=srsName={Name}
In the current implementation, the response follows the same schema as in the
ListSRSResponse. In the next implementation, the schema will be extended to include
fiducials because they are important for computing coordinate transformations. A fragment
of the output which includes the fiducials is shown below.
Note that the fiducial encoding in the sample output is a point, and uses a GML (Geography
Markup Language) construct to describe a point in three dimensions. For higher-dimensional
objects, other GML constructs can be used: gml:LineString, gml:Polygon, etc. GML is a
standard for describing geospatial features (http://www.opengeospatial.org/standards/gml).
Figure 13. XML schema diagram of DescribeSRS response
32
<SRS>
<Name srsCode="INCF:0101" srsBase="ABAreference" srsVersion="1.0"
species="Mouse">Mouse_ABAreference_1.0</Name>
<Description>ABAreference</Description>
<Author authorCode="ABA" dateSubmitted="2010-09-14-07:00"/>
<DateCreated>2010-09-14-07:00</DateCreated>
<DateUpdated>2010-09-14-07:00</DateUpdated>
<Origin>bregma</Origin>
<Area structureName="whole brain"/>
<Units uom="mm"/>
<Neurodimensions>
<MinusX maxValue="-6.0">Right</MinusX>
<PlusX maxValue="6.0">Left</PlusX>
<MinusY maxValue="-1.0">Dorsal</MinusY>
<PlusY maxValue="7.0">Ventral</PlusY>
<MinusZ maxValue="-9.0">Posterior</MinusZ>
<PlusZ maxValue="6.0">Anterior</PlusZ>
</Neurodimensions>
<Source format="Slices">http://mouse.brain-map.org/welcome.do</Source>
<DerivedFrom/>
</SRS>
<Orientations>
<Orientation code="Left" gml:id="72" name="Left">
<Description>Left of midline.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Right" gml:id="72" name="Right">
<Description>Right of midline.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Ventral" gml:id="99" name="Ventral">
<Description>Towards the abdomen/front.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Dorsal" gml:id="78" name="Dorsal">
<Description>Toward spinal column/back.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Posterior" gml:id="15" name="Posterior">
<Description>Towards the back.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
<Orientation code="Anterior" gml:id="62" name="Anterior">
<Description>Towards the front.</Description>
<Author dateSubmitted="2010-09-14-07:00" authorCode="standard">Standard</Author>
</Orientation>
</Orientations>
<Fiducials>
<Fiducial>
<Name fiducialCode="XXX" fiducialType="anatomic" >Fiducial Name 1</Name>
<Description>Intersection of AC and ML</Description>
<Author authorCode="ABA" dateSubmitted="2010-09-14-07:00"/>
<Certainty_level/>
<DerivedFrom/>
<gml:Point gml:id="35" srsName="Mouse_ABAReference_1.0">
<gml:pos>1.0 1.0 1.0</gml:pos>
</gml:Point>
</Fiducial>
<Fiducial>
</Fiducial>
</Fiducials>
33
7.7.
Execute ListTransformations
This process lists coordinate transformations available at a hub or registered at INCF
Central.
The base request is:
{BaseService}&version=1.0.0&request=Execute&Identifier=ListTransformations&
DataInputs=inputSrsName={srsName};outputSrsName={srsName};filter={string
}
Example request:
Example:
http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&version=1.0.0&request=Execute&Identifier=ListTransformations&DataIn
puts=inputSrsName=Mouse_Paxinos_1.0;outputSrsName=Mouse_ABAreference_1.0;filter=
Cerebellum
The request takes inputSRSName, outputSRSName, and filter as inputs. All of these inputs
are optional. The filter parameter may be used to restrict listing of transformations to those
implemented for the area of interest (we assume that eventually more accurate coordinate
transformations will be implemented for smaller sections of the brain).
The output of this process lists coordinate transformations. For each of them, it provides the
transformation code, the hub where the transformation is implemented, and the
characteristics of the transformation (inputSRS, outputSRS, version, filter, accuracy). It also
includes a completely formed TransformPOI request (with placeholders for X,Y,Z and filter
inputs).
If inputSRS, outputSRS and filter are not specified, the request returns all coordinate
transformations implemented at a hub or registered at INCF Central.
A TransformationCode is a concatenation in this form:
<inputSRSName>_To_<outputSRSName>_Version
Figure 14. XML schema diagram of ListTransformations response
A sample output:
34
<ListTransformationsResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<QueryInfo>
<TimeCreated>2010-09-14T00:53:39.610-07:00</TimeCreated>
<QueryUrl name="ListTransformations">http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=ListTransformations
&amp;DataInputs=inputSrsName=Mouse_Paxinos_1.0;outputSrsName=Mouse_ABAreference_1.0;filt
er=Cerebellum</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="inputSrsName">
<Value>Mouse_Paxinos_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="outputSrsName">
<Value>Mouse_ABAreference_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="filter">
<Value>Cerebellum</Value>
</Input>
</Criteria>
</QueryInfo>
<TransformationList>
<CoordinateTransformation code="Mouse_Paxinos_1.0_To_Mouse_WHS_0.9_v1.0" hub="UCSD"
inputSrsName="Mouse_Paxinos_1.0" outputSrsName="Mouse_WHS_0.9" filter=”” accuracy=””
version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasucsd?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;D
ataInputs=inputSrsName=Mouse_Paxinos_1.0;outputSrsName=Mouse_WHS_0.9;x=;y=;z=;filter=</C
oordinateTransformation>
<CoordinateTransformation code="Mouse_WHS_0.9_To_Mouse_AGEA_1.0_v1.0" hub="ABA"
inputSrsName="Mouse_WHS_0.9" outputSrsName="Mouse_AGEA_1.0" filter=”” accuracy=””
version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;Da
taInputs=inputSrsName=Mouse_WHS_0.9;outputSrsName=Mouse_AGEA_1.0;x=;y=;z=;filter=</Coord
inateTransformation>
<CoordinateTransformation code="Mouse_AGEA_1.0_To_Mouse_ABAvoxel_1.0_v1.0" hub="ABA"
inputSrsName="Mouse_AGEA_1.0" outputSrsName="Mouse_ABAvoxel_1.0" filter=”” accuracy=””
version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;Da
taInputs=inputSrsName=Mouse_AGEA_1.0;outputSrsName=Mouse_ABAvoxel_1.0;x=;y=;z=;filter=</
CoordinateTransformation>
<CoordinateTransformation code="Mouse_ABAvoxel_1.0_To_Mouse_ABAreference_1.0_v1.0"
hub="ABA" inputSrsName="Mouse_ABAvoxel_1.0" outputSrsName="Mouse_ABAreference_1.0"
filter=”” accuracy=”” version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;Da
taInputs=inputSrsName=Mouse_ABAvoxel_1.0;outputSrsName=Mouse_ABAreference_1.0;x=;y=;z=;f
ilter=</CoordinateTransformation>
</TransformationList>
</ListTransformationsResponse>
7.8.
Execute DescribeTransformation
Not specified in the current version. Discussion of the information model for a spatial
transformation is ongoing.
35
Encoding of Transformation will go beyond the minimal metadata returned by the
ListTransformations method, and may contain: 1) information about the transformation
algorithm, 2) information about the area (domain) for which the transformation is valid, 3)
description of transformation type: linear, polynomial, etc., 4) fiducials on which the
transformation was based, 5) tools used to derive the transformation, 6) pointer to inverse
transformation, 7) author of the transformation, and possibly a citation, 8) distortion volume, 9)
version of the transformation, and any dependencies/lineage, 10) piecewise mesh complexity,
11) piecewise mesh: list of nodes and estimated errors, 12) resolution, 13) comments
7.9.
Execute GetTransformationChain
The GetTransformationChain (inputSrsName, outputSrsName, filter) request has
been implemented to derive a transformation chain between any two known
transformations. For example, if the ABA hub implements
Mouse_AGEA_1.0_To_Mouse_WHS_0.9 and the UCSD hub implements
Mouse_WHS_0.9_To_Mouse_Paxinos_1.0, then a request for a transformation chain
between Mouse_AGEA_1.0 and Mouse_Paxinos_1.0 would return these two transformations,
in this order, taking advantage of INCF-DAI requirement that each hub with a unique
coordinate system at least supports spatial transformations between a local hub SRS and
WHS. The filter parameter may be used to specify the area in the brain for which the
transformation chain will be computed. As mentioned in 7.7, we expect that local
transformations will be developed in addition to whole-brain transformations, providing
better transformation accuracy for certain parts of the brain (e.g. hippocampus). Restricting
chains of coordinate transformations to such conversions, if available, would produce better
transformation accuracy.
The base request is:
{BaseService}&version=1.0.0&request=Execute&Identifier=GetTransformationCh
ain&DataInputs=inputSrsName={srsName};outputSrsName={srsName};filter={s
tring}
Example request:
http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&version=1.0.0&request=Execute&Identifier=GetTransformationChain&Da
taInputs=inputSrsName=Mouse_Paxinos_1.0;outputSrsName=Mouse_ABAreference_1.0;filt
er=Cerebellum
The response is similar to the TransformationList response, except in this case each
transformation has an additional attribute “order”, which refers to the execution sequence of
transformations in the chain.
A sample response is:
36
<CoordinateTransformationChainResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<QueryInfo>
<TimeCreated>2010-09-14T00:56:06.042-07:00</TimeCreated>
<QueryUrl name="GetTransformationChain">http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=GetTransformationCh
ain&amp;DataInputs=inputSrsName=Mouse_Paxinos_1.0;outputSrsName=Mouse_ABAreference_1.0;f
ilter=Cerebellum</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="inputSrsName">
<Value>Mouse_Paxinos_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="outputSrsName">
<Value>Mouse_ABAreference_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="filter">
<Value>Cerebellum</Value>
</Input>
</Criteria>
</QueryInfo>
<CoordinateTransformationChain>
<CoordinateTransformation order="1" code="Mouse_Paxinos_1.0_To_Mouse_WHS_0.9_v1.0"
hub="UCSD" inputSrsName="Mouse_Paxinos_1.0" outputSrsName="Mouse_WHS_0.9" filter=””
accuracy=”” version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasucsd?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;D
ataInputs=inputSrsName=Mouse_Paxinos_1.0;outputSrsName=Mouse_WHS_0.9;x=;y=;z=;filter=</C
oordinateTransformation>
<CoordinateTransformation order="2" code="Mouse_WHS_0.9_To_Mouse_AGEA_1.0_v1.0"
hub="ABA" inputSrsName="Mouse_WHS_0.9" outputSrsName="Mouse_AGEA_1.0" filter=””
accuracy=”” version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;Da
taInputs=inputSrsName=Mouse_WHS_0.9;outputSrsName=Mouse_AGEA_1.0;x=;y=;z=;filter=</Coord
inateTransformation>
<CoordinateTransformation order="3" code="Mouse_AGEA_1.0_To_Mouse_ABAvoxel_1.0_v1.0"
hub="ABA" inputSrsName="Mouse_AGEA_1.0" outputSrsName="Mouse_ABAvoxel_1.0" filter=””
accuracy=”” version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;Da
taInputs=inputSrsName=Mouse_AGEA_1.0;outputSrsName=Mouse_ABAvoxel_1.0;x=;y=;z=;filter=</
CoordinateTransformation>
<CoordinateTransformation order="4"
code="Mouse_ABAvoxel_1.0_To_Mouse_ABAreference_1.0_v1.0" hub="ABA"
inputSrsName="Mouse_ABAvoxel_1.0" outputSrsName="Mouse_ABAreference_1.0" filter=””
accuracy=”” version=”1.0”>http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;Da
taInputs=inputSrsName=Mouse_ABAvoxel_1.0;outputSrsName=Mouse_ABAreference_1.0;x=;y=;z=;f
ilter=</CoordinateTransformation>
</CoordinateTransformationChain>
</CoordinateTransformationChainResponse>
It is expected that this call will be implemented against the table of registered coordinate
transformations at the INCF Central, to support chaining coordinate translation services
hosted by several different hubs. Respective GetTransformationChain methods hosted by
37
each hub may return information about single transformations, or a sequence of
transformations within a family of SRSs hosted by a hub (as in case of the ABA service,
where Mouse_ABAreference, Mouse_ABAvoxel and Mouse_AGEA are supported).
Figure 15. XML schema diagram of CoordinateTransformationChainResponse
7.10. Execute TransformPOI
This is a mandatory method to be exposed by a hub if the hub registers data to a spatial
reference system other than WHS.
It is expected that each hub implements translations between at least one locally-unique
coordinate system, and WHS. For example, the ABA hub currently implements direct and
reverse translations between WHS and AGEA, at the same time supporting translations
between AGEA and ABAvoxel space, and between ABAvoxel and ABAreference. The method
inputs include inputSrsName, outputSrsName, POI coordinates in the inputSrsName space,
and the output type (ResponseForm).
The method signatures are:
WaxMl
{BaseService}&version=1.0.0&request=Execute&Identifier=TransformPOI&DataI
nputs=transformationCode=Mouse_WHS_0.9_To_Mouse_AGEA_1.0_v1.0;x=280.0
;y=112.0&z=162.0
Since this process is expected to be called in multiple application contexts, we provide HTML
and Text requests:
Html:
{BaseService}&version=1.0.0&request=Execute&Identifier=
TransformPOI&DataInputs=transformationCode=Mouse_WHS_0.9_To_Mouse_AG
EA_1.0_v1.0;x=280.0;y=112.0&z=162.0&ResponseForm=text/html
Text:
38
{BaseService}&version=1.0.0&request=Execute&Identifier=
TransformPOI&DataInputs=transformationCode=Mouse_WHS_0.9_To_Mouse_AG
EA_1.0_v1.0;x=280.0;y=112.0&z=162.0&ResponseForm=text/plain
Example method call is:
http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&version=1.0.0&request=Execute&Identifier=TransformPOI&DataInputs=t
ransformationCode=Mouse_WHS_0.9_To_Mouse_AGEA_1.0_v1.0;x=1;y=112;z=162
The POI output follows GML simple features conventions, as shown in the example:
Figure 16. XML schema diagrams of TransformationResponse and POI
39
<TransformationResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gml="http://www.opengis.net/gml/3.2">
<QueryInfo>
<TimeCreated>2010-09-14T01:00:09.520-07:00</TimeCreated>
<QueryUrl name="TransformPOI">http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=TransformPOI&amp;Da
taInputs=transformationCode=Mouse_WHS_0.9_To_Mouse_AGEA_1.0_v1.0;x=1;y=112;z=162
</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="transformationCode">
<Value>Mouse_WHS_0.9_To_Mouse_AGEA_1.0_v1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="x">
<Value>1</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="y">
<Value>112</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="z">
<Value>162</Value>
</Input>
</Criteria>
</QueryInfo>
<POI>
<gml:Point gml:id="35" srsName="Mouse_AGEA_1.0">
<gml:pos>25 2800 4050</gml:pos>
</gml:Point>
</POI>
</TransformationResponse>
An example of “text/plain” output may be:
POI:
srsName: Mouse_ABAvoxel_1.0
Point: x y z
Note that output with ResponseType other than WaxML doesn’t need to include
<QueryInfo>.
7.11. Execute GetStructureNamesByPOI
GetStructureNamesByPOI(POI, outputVocabulary, filter) returns name(s) of
segmented anatomic structures at the point of interest, in a specified vocabulary.
A sample request is:
40
{BaseService}&version=1.0.0&request=Execute&identifier=GetStructureNamesBy
POI&DataInputs=srsName=Mouse_ABAVoxel_1.0;x=295.0;y=113.0;z=146.0;voca
bulary=Mouse_ABAVoxel;filter=structureset:Fine
Or, generating HTML output:
{BaseService}&version=1.0.0&request=Execute&identifier=GetStructureNamesBy
POI&DataInputs=srsName=Mouse_ABAVoxel_1.0;x=295.0;y=113.0;z=146.0;voca
bulary=Mouse_ABAVoxel_1.0; filter=structureset:Fine&ResponseForm=text/html
Example method call (new implementation as per the specification) is:
http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&version=1.0.0&request=Execute&Identifier=GetStructureNamesByPOI&D
ataInputs=srsName=Mouse_ABAvoxel_1.0;x=280;y=112;z=162;vocabulary=Mouse_ABAvo
xel_1.0;filter=structureset:Fine
This service is not mandatory, but expected in a majority of atlas cases, where there is a
correspondence between coordinates and structures.
In the current implementation, the call returns a single structure segmented at a given
point (or, for atlases specified through a collection of slices with often unclosed polygons –
by a nearest label). In future implementations, it will be extended to return a list of
structures ranked by relevance, or proximity to the POI (or by some other defined rule).
The inputs of the request are:



POI is defined as (X,Y,Z) in a known spatial reference system (srsName).
The “vocabulary” term will generally be the same as the spatial reference system.
However, we shall allow for multiple segmentations of the same coordinate space
(e.g. there are canonical Paxinos structures, many of them not closed in the original
atlas; in addition there are results of segmenting 3D space built over Paxinos slices;
other segmentations may be developed over 3D volumes registered to the Paxinos
space). It is expected that vocabularies will be managed by PONS.
In each case, the definition of returned structure may be different. For example, ABA
allows return of “anatomic” or “fine” structures. In the Paxinos case, we may return
the closest label or a collection of labels. This information is specified in the “filter”
string input, as it will be unique for each source. The unique allowable values of the
“filter” element should be specified in DescribeProcess output for each process at
each hub service.
The WaxML output includes a collection of <StructureTerms>. In the expanded case,
StructureTerm definition will also include geometric properties of the structure if they are
available.
41
Notice the use of the gml namespace to describe spatial characteristics of the structure
(centroid and bounding envelope). The GML simple features profile is defined at
http://www.ogcnetwork.net/gml-sf.
The meaning of “feature” vs “structure” should be further discussed and defined. Note that
in OGC standards “features” refer to entities that have geometric properties. “Structure”
(“anatomic structure”) may be reserved for constructs that include multiple geometric
features, and other properties – as is consistent with our usage here.
As mentioned above, in this initial version of the method we do not require that a criterion
for selecting a structure is specified. The rule by which particular structure names, and their
sequence, are returned is up to the hub to specify. Moreover, the currently implemented
version of the request returns a single structure rather than a collection of structures (e.g.
the nearest label, or the smallest segmented for the POI). In the future, the hub may
specify the relationship used to return the structure name explicitly, e.g. “the closest label”,
or “finest structure”, or “parent of structure pointed to with xlink:href. For example:
<structureTerm order=”1” relationship=”finest”>. This extension is slated for future
versions, in the expectation that PONS services will be able to pick up the structure name in
a specified vocabulary, and translate it to other names as needed, for example, for gene
search (in the most typical case, it would translate to a parent structure for which gene
searches are available).
Generally, the rule may be specified explicitly using spatial relationships, e.g. returning a
set of structure names that are in spatial relationship R to the POI, where R can be
constructed based on containment or other topological properties, proximity, etc. (“inside”,
“nearest”, “within 100 microns”, etc.). Additional spatial relationships R may be supported if
ROI is passed as part of the request instead of POI. However, few atlases support ROIbased requests at present (with the exception of the SMART atlas), so this may be
implemented after other hubs move in this direction. Until then, a GetStructureNamesByROI
will belong to extended hub requests.
The “url” element points to a 3D representation of a structure, which could be an octree-or
3D R-tree-indexed collection of voxels, a mesh, a segment set, a 2D polygon stack, a 2D
pixel stack, or a 3D server where the structure can be requested. A companion method
Get3DStructureShape (URI, outputtype), or more generally, DescribeStructure, would
return an XML representation of the structure in a specified format and or a pointer to such
description or a respective web service (returning VRML, SVA, X3D, etc.)
42
<StructureTermsResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<QueryInfo>
<TimeCreated>2010-09-14T01:02:19.080-07:00</TimeCreated>
<QueryUrl name="GetStructureNamesByPOI">http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=GetStructureNamesByPOI&a
mp;DataInputs=srsName=Mouse_ABAvoxel_1.0;x=280;y=112;z=162;vocabulary=Mouse_ABAvoxel_1.0;filt
er=structureset:Fine</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="srsName">
<Value>Mouse_ABAvoxel_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="x">
<Value>280</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="y">
<Value>112</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="z">
<Value>162</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="vocabulary">
<Value>Mouse_ABAvoxel_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="filter">
<Value>structureset:Fine</Value>
</Input>
</Criteria>
</QueryInfo>
<StructureTerms>
<StructureTerm>
<Code codeSpace="Mouse_ABAvoxel_1.0" isDefault="true" structureID="1369">HIP</Code>
<Uri>uri:incf:pons-repository.org:structurenames:Hippocampus</Uri>
<Name>Hippocampus</Name>
<Description>Term - DG derived from ABA hub based on the supplied POI.</Description>
<Feature>
<Centroid>
<gml:Point gml:id="requiredAnyId" srsName="Mouse_ABAvoxel_1.0">
<gml:pos>1 1 1</gml:pos>
</gml:Point>
</Centroid>
<BoundedBy>
<gml:Envelope srsName="Mouse_WHS_1.0">
<gml:lowerCorner axisLabels="right ventral anterior">10 10 10</gml:lowerCorner>
<gml:upperCorner axisLabels="left dorsal posterior">20 20 20</gml:upperCorner>
</gml:Envelope>
</BoundedBy>
<Shape>
<Url srsName="Mouse_ABAvoxel_1.0">URI</Url>
<Format>VRML</Format>
! this will point to web service that returns VRML/SVA/etc
for the structure
</Shape>
</Feature>
</StructureTerm>
</StructureTerms>
</StructureTermsResponse>
43
Note that an atlas hub service may expose more than one set of segmented structures: this
is either handled by the filter string, or by setting up an additional service controller.
In the current implementation, this method (and other POI-based methods) can take POI in
any known coordinate system. Internally, it will perform the necessary coordinate
transformations to request structure names in a spatial reference system understood by the
hub that services this request (in case client uses a different SRS).
Figure 17. XML schema diagrams of StructureTermsResponse and StructureTerm
7.12. Execute Get2DImagesByPOI
Similarly to GetStructureNamesByPOI, this is a method we typically expect to be
implemented by most atlas hubs. Similarly to GetStructureNamesByPOI, hubs are free to
interpret this request to return references to either one or a stack of images, and select a
rule for image selection. The selection may implement search over spatial registry within a
user-defined or predefined tolerance (as in the case of images registered for display in
Smart atlas) or some procedure deriving an appropriate image numerically from POI. We
expect this call to be supported at INCF Central as well, either over the central spatial
registry harvested from individual hubs or as a union of Get2DImagesByPOI requests
against the hubs that support it.
The proposed request is:
44
{BaseService}&version=1.0.0&request=Execute&Identifier=get2DImagesByPOI&
DataInputs=srsName=Mouse_ABAvoxel_1.0;x=263;y=159;z=227;filter=maptype:
coronal;tolerance=1.0
And, in other formats:
Html
{BaseService}&version=1.0.0&request=Execute&Identifier=get2DImagesByPOI&
DataInputs=srsName=Mouse_ABAvoxel_1.0;x=263;y=159;z=227;
filter=maptype:coronal;tolerance=1.0&ResponseForm=text/html
JSON
{BaseService}&version=1.0.0&request=Execute&Identifier=get2DImagesByPOI&
DataInputs=srsName=Mouse_ABAvoxel_1.0;x=263;y=159;z=227;filter=maptype:
coronal;tolerance=1.0&ResponseForm=text/json
Example method call is:
http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&version=1.0.0&request=Execute&Identifier=Get2DImagesByPOI&DataIn
puts=srsName=Mouse_AGEA_1.0;x=6600;y=4000;z=5600;filter=maptype:coronal;toleran
ce=300
The inputs to this request are:



Specification of POI, including X,Y,Z coordinates and their srsCode
Tolerance: the size of the "query prism" around the POI (user-defined; possibly per
hub, since hubs may expose images at different density). Depending on
implementation, it may be a sphere rather than a prism. It is expressed in the units
of the srsName
Filter: any additional hub-specific string defining a rule for selecting images
The request will return a list of images, each with a URL of the image and its spatial
characteristics, and perhaps a thumbnail. The return should be sufficient for the calling
application to present to the user a menu of images, and then formulate an image retrieval
request such that the retrieved image can be positioned correctly and arrives at appropriate
resolution.
The <ImagePosition> element is optional; here it is inserted to illustrate the WaxML
schema. When this information is present, it allows the client to position retrieved images
correctly with respect to other images or volumes already shown in the client. If the image
position is not available (as in the actual call below), the image would be opened in a
separate browser window or frame and won’t be aligned with other images.
Similarly to GetStructureNamesByPOI, a hub may expose more than one set of images: this
is either handled by the filter string, or by setting up an additional service controller.
45
Figure 18. XML schema diagram of ImagesResponse
46
<ImagesResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<QueryInfo>
<QueryUrl name="Get2DImagesByPOI">http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=Get2DImagesByPOI&amp;Dat
aInputs=srsName=Mouse_AGEA_1.0;x=6600;y=4000;z=5600;filter=maptype:coronal</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="srsName">
<Value>Mouse_AGEA_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="x">
<Value>6600</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="y">
<Value>4000</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="y">
<Value>5600</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="filter">
<Value>maptype:coronal</Value>
</Input>
</Criteria>
</QueryInfo>
<Image2Dcollection>
<Image2D>
<ImageSource format="image/jpeg" name="Plxnb1_253_1899" thumbnail="http://www.brainmap.org/aba/api/image?zoom=0&amp;path=production4/Plxnb1_Baylor_7331/zoomify/primary/null/Plx
nb1_253_null_D.aff&amp;mime=2">http://www.brain-map.org/aba/api/image?zoom=1&amp;path=production4/Plxnb1_Baylor_7331/zoomify/primary/null/Plxnb1_253_null_D.aff&amp;mime
=2</ImageSource>
<ImagePosition>
<ImagePlaneEquation srsName="SRS">1 2 3 4</ImagePlaneEquation>
<ImagePlanePlacement srsName="SRS">1 2 3 4 5 6.0</ImagePlanePlacement>
<ImageBoundingBox srsName="SRS" minX="XXX" minY="XXX" minZ="XXX" maxX="XXX"
maxY="XXX" maxZ="XXX" />
</ImagePosition>
</Image2D>
</Image2Dcollection>
</ImagesResponse>
7.13.
Execute Retrieve2DImage
This request wraps different mechanisms implemented at hubs for image retrieval. This
could include static images, or images served via WMS (Web Map Server) protocol, Zoomify,
or other protocols.
Let’s consider it with WMS as an example. WMS implementation specification
(http://www.opengeospatial.org/standards/wms) describes how one requests capabilities
from a map server (GetCapabilities), and then formulates and requests geopositioned
47
images (GetMap), via HTTP. WMS can be setup as an additional standards-compliant hub
service, and declare its capabilities to INCF Central registry similarly to how a WPS-based
service would do it.
The GetMap requests are outside the scope of WaxML and atlas services, although they may
be present in an atlas hub (e.g. they are present in the UCSD hub). Retrieve2DImage
represents a simplified WPS-based interface of GetMap, tuned to retrieval of neuroscience
images.
A sample request is:
{BaseService}&version=1.0.0&request=Execute&Identifier=Retrieve2DImage&Da
taInputs=sourceType=WMS;sourceURL=...;srsName=Mouse_ABAvoxel_1.0;xmin=
...;xmax=...;ymin=...;ymax=...;filter=...
The data inputs in this request are extracted from the response to a previous
Get2DImagesByPOI request (the URL of the image), and from the extent and SRS of the
currently displayed canvas (xmin,xmax,ymin,ymax, srsName).
Example:
http://incf-dev.crbs.ucsd.edu:8080/atlasucsd?service=WPS&version=1.0.0&request=Execute&Identifier=Retrieve2DImage&DataInputs=sourceTy
pe=WMS;sourceURL=http%3A%2F%2Fimage.wholebraincatalog.org%2Fcgibin%2Fmapserv%3Fmap%3Dcrbsatlas%2Fmapfiles%2Fgensat_3363_modified_sm_transformedms.map%26LAYERS%3Dgensat_penk1_09%26FORMAT%3Dpng24%26VERSION%3D1.1.1%26REQU
EST%3DGetMap;srsName=Mouse_ABAvoxel_1.0;xmin=-1.9298;xmax=8.73376;ymin=9.92461;ymax=1.14128;filter=maptype:Sagittal
The response is a URL of image that can be displayed on the client.
Figure 19. XML schema diagram of Retrieve2DImages response
48
<Retrieve2DImageResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<QueryInfo>
<TimeCreated>2010-09-14T01:09:48.363-07:00</TimeCreated>
<QueryUrl name="GetMap">http://incf-dev.crbs.ucsd.edu:8080/atlasucsd?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=Retrieve2DImage&am
p;DataInputs=sourceType=WMS;sourceURL=http%3A%2F%2Fimage.wholebraincatalog.org%2Fcgibin%2Fmapserv%3Fmap%3Dcrbsatlas%2Fmapfiles%2Fgensat_3363_modified_sm_transformedms.map%26LAYERS%3Dgensat_penk1_09%26FORMAT%3Dpng24%26VERSION%3D1.1.1%26REQUEST%3DGetMap;
srsName=Mouse_ABAvoxel_1.0;xmin=-1.9298;xmax=8.73376;ymin=9.92461;ymax=1.14128;filter=maptype:Sagittal</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="sourceType">
<Value>wms-png</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="sourceURL">
<Value>http%3A%2F%2Fimage.wholebraincatalog.org%2Fcgibin%2Fmapserv%3Fmap%3Dcrbsatlas%2Fmapfiles%2Fgensat_3363_modified_sm_transformedms.map%26LAYERS%3Dgensat_penk1_09%26FORMAT%3Dpng24%26VERSION%3D1.1.1%26REQUEST%3DGetMap<
/Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="srsName">
<Value>Mouse_ABAvoxel_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="xmin">
<Value>-1.9298</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="xmax">
<Value>8.73376</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="ymin">
<Value>-9.92461</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="ymax">
<Value>1.14128</Value>
</Input>
</Criteria>
</QueryInfo>
<ImageUrl><![CDATA[http://image.wholebraincatalog.org/cgibin/mapserv?map=crbsatlas/mapfiles/gensat_3363_modified_sm_transformedms.map&LAYERS=gensat_penk1_09&FORMAT=png24&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326&WI
DTH=256&HEIGHT=256&BBOX=-1.9298,-9.92461,8.73376,1.14128]]></ImageUrl>
</Retrieve2DImageResponse>
49
7.14. Execute GetCorrelationMapByPOI
This request is implemented at atlas-ABA service controller only.
A sample request is:
{BaseService}&version=1.0.0&request=Execute&Indentifier=getCorrelationMapB
yPOI&DataInputs=srsName=Mouse_ABAVoxel_1.0;x=263;y=159;z=227;filter=ma
ptype:coronal&ResponseForm=application/waxml
Or in text format:
{BaseService}&version=1.0.0&request=Execute&Indentifier=getCorrelationMapB
yPOI&DataInputs=srsName=Mouse_ABAVoxel_1.0;x=263;y=159;z=227;filter=ma
ptype:coronal&ResponseForm=text/plain
http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&version=1.0.0&request=Execute&Identifier=GetCorrelationMapByPOI&D
ataInputs=srsName=Mouse_ABAvoxel_1.0;x=263;y=159;z=227;filter=maptype:coronal
This method merely returns a URL of a web page to be displayed in a browser:
<CorrelationMapResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<QueryInfo>
<QueryUrl name="GetCorrelationMapByPOI">http://incf-dev.crbs.ucsd.edu:8080/atlasaba?service=WPS&amp;version=1.0.0&amp;request=Execute&amp;Identifier=GetCorrelationMapByPOI&a
mp;DataInputs=srsName=Mouse_ABAvoxel_1.0;x=263;y=159;z=227;filter=maptype:coronal</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="srsName">
<Value>Mouse_ABAvoxel_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="x">
<Value>263</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="y">
<Value>159</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType" name="z">
<Value>227</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="filter">
<Value>maptype:coronal</Value>
</Input>
</Criteria>
</QueryInfo>
<CorrelationUrl>http://mouse.brainmap.org/agea/all_coronal?correlation&amp;seedPoint=6575,3975,5675</CorrelationUrl>
</CorrelationMapResponse>
50
Figure 20. XML schema diagram of CorrelationMap response
7.15. Execute GetGenesByPOI
This request is currently implemented for the ABA and EMAP hubs.
WaxMl
{BaseService}&version=1.0.0&request=Execute&Identifier=GetGenesByPOI&Dat
aInputs=srsName=Mouse_ABAVoxel_1.0;x=263;y=159&z=227&
filter=&ResponseForm=application/waxml
Text Format
{BaseService}&version=1.0.0&request=Execute&Identifier=GetGenesByPOI&Dat
aInputs=srsName=Mouse_ABAVoxel_1.0;x=263;y=159&z=227&filter=&Response
Form=text/plain
51
Figure 21. XML schema diagrams of GeneType and GeneExpressionLevel (components of GetGenesByPOI
response)
52
A sample output of the call:
<GenesResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:xlin="http://www.w3.org/1999/xlink">
<QueryInfo>
<QueryUrl name="GetGenesByPOI">URL</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="srsCode">
<Value>Mouse_ABAVoxel_1.0</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="filter">
<Value>AFilter</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="x">
<Value>263</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="y">
<Value>159</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="y">
<Value>227</Value>
</Input>
</Criteria>
</QueryInfo>
<GenesByPOI>
<Gene>
<!--Codespace required. Ideally it will be a base identifier the org responsible
for the naming-->
<!--gml:id is required, and is used to reference this item in the document-->
<Symbol codeSpace="uri:incf.org" gml:id="AAAAAB">Bmp4</Symbol>
<MarkerAccessionId separator=":">
<Prefix>string</Prefix>
<Identifier>string</Identifier>
<FullIdentifier>string:string</FullIdentifier>
</MarkerAccessionId>
<Name>bone morphogenetic protein 4</Name>
<Organism>mouse</Organism>
</Gene>
<ExpressionLevel>
<!--href references Bmp4 by gml:id-->
<!--references Bmp4 by name.-->
<GeneSymbol xlin:href="#AAAAB"/>
<Stage>TS11</Stage>
<Level>strong</Level>
<ResourceUri>http://www.emouseatlas.org/emagewebapp/pages/emage_entry_page.jsf?id=EMAGE:
86</ResourceUri>
</ExpressionLevel>
</GenesByPOI>
53
</GenesResponse>
7.16. Execute Get2DImagesByURI
This method is not formally a part of atlas services, but is needed as a bridge with PONS. It
is included here to support image requests primarily for images that are not placed in a
specific SRS, but have been tagged with a name of anatomic structure or cell. In particular
this refers to images at the cellular level.
The URI in the request refers to such a name in NIF, and is in the form described in the
GetStructureNameByPOI method output. It is typically a Uniform Resource Name (URN).
The WaxML output is the same as in the Get2DImagesByPOI call, with two exceptions: a)
the <queryinfo> element is different, and b) the <ImagePosition> element is not included.
The sample request is:
{BaseService}&version=1.0.0&request=Execute&Identifier=get2DImagesByURI&
DataInputs=URI=urn:incf:pons-repository.org:structurenames:Hippocampus;
filter=
The inputs are:


URI, pointing to feature definition in the PONS repository
Filter: any additional hub-specific string defining a rule for selecting images
As with the Get2dImagesByPOI, the returned document will contain the <queryinfo>
element and a list of images, each with a URL of the image, and perhaps a thumbnail. As
earlier, the returned information should be sufficient to formulate subsequent requests for
image fragments, or open a specialized 2d image browser.
54
<ImagesResponse xmlns="http://www.incf.org/WaxML/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gml="http://www.opengis.net/gml/3.2">
<QueryInfo>
<QueryUrl name="Get2DImagesByURI ">URL</QueryUrl>
<Criteria>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="URI">
<Value>urn:incf:pons-repository.org:structurenames:Hippocampus</Value>
</Input>
<Input xmlns:wax="http://www.incf.org/WaxML/" xsi:type="wax:InputStringType"
name="filter">
<Value>maptype:coronal</Value>
</Input>
</Criteria>
</QueryInfo>
<Image2Dcollection>
<!--format ~ mime type
{WMS/jpg|WMS/gif|WMS/png|zoomify|image/jpeg|image/png|image/gif|text/html|url} found in
incfRemoteFormatEnum-->
<!--optional thumbnail-->
<!--type is type of service {wms-jpg|wms-png|wms-gif|zoomify|url} from type
incfImageServicesEnum-->
<Image2D>
<ImageSource format="image/jpeg" relavance="0.6" srsName="srscode"
thumbnanil="http://example.com/image.jpg" metadata="URL" type="url">URL</ImageSource>
<ImagePosition>
<ImagePlaneEquation srsName="SRS">1 2 3 4</ImagePlaneEquation>
<ImagePlanePlacement srsName="SRS">1 2 3 4 5 6.0</ImagePlanePlacement>
<Corners>
<Corner position="topleft">
<gml:Point gml:id="image1TopLeft">
<gml:pos srsName="Mouse_ABAvoxel_1.0">1 1 1</gml:pos>
</gml:Point>
</Corner>
<Corner position="bottomleft">
<gml:Point gml:id="image1BOTTOMLEFT">
<gml:pos srsName="Mouse_ABAvoxel_1.0">1 1 1</gml:pos>
</gml:Point>
</Corner>
<Corner position="topright">
<gml:Point gml:id="image1TOPRIGHT">
<gml:pos srsName="Mouse_ABAvoxel_1.0">1 1 1</gml:pos>
</gml:Point>
</Corner>
<Corner position="bottomright">
<gml:Point gml:id="image1BOTTOMRIGHT">
<gml:pos srsName="Mouse_ABAvoxel_1.0">1 1 1</gml:pos>
</gml:Point>
</Corner>
</Corners>
</ImagePosition>
</Image2D>
</Image2Dcollection>
</ImagesResponse>
55
7.17. Exception report
Exceptions should be generated on bad or missing input parameters, values out of bound,
etc. Anytime an atlas server is unable to return a valid response with content, the server
will return a WPS owsExceptionReport:
<ows:ExceptionReport xmlns:ows="http://www.opengis.net/ows/2.0" version="1.0.0"
xml:lang="en-US">
<ows:Exception exceptionCode="NotApplicableCode" locator="locator">
<ows:ExceptionText>Line 1a.</ows:ExceptionText>
<ows:ExceptionText>Line 1b.</ows:ExceptionText>
</ows:Exception>
<ows:Exception exceptionCode="NotApplicableCode" locator="locator">
<ows:ExceptionText>Line 2a.</ows:ExceptionText>
<ows:ExceptionText>Line 2b.</ows:ExceptionText>
</ows:Exception>
</ows:ExceptionReport>
56
Annex A
A1. Physical implementation of a hub
We are considering two types of INCF atlas data hubs, referred to as “standard hub” and
“hybrid hub”. So far, the demo implementation followed a “hybrid hub” model, where some
functions are available from an independently managed legacy server (e.g. ABA,
EMAP/EMAGE, Smart Atlas), while other functions are developed to bring the service in
compliance with the atlas service specification. The remote functionality (local APIs) is
wrapped into standard service requests described earlier. In addition, several core but
missing requests are added: those implementing GetCapabilities and DescribeProcess calls,
spatial transformations, and anatomic structure lookup. In this fairly lightweight model, a
hybrid hub hosts (a) service controller for the hub, with automatically updated
GetCapabilities/DescribeProcess requests as the hub content changes, (b) service wrappers
of remote services, (c) description of local coordinate spaces and transformations to and
from WHS. We assume that such remote hubs do their own database and services
management, and are not interested in additional web presence.
A “standard hub” is intended for atlas groups that don’t have web service presence, and
would like to setup a hub from scratch. In this case, the hub software stack may include
backend services, providing secure access to dataset and collection management, portal
components with a variety of tools, containers for other services, etc. Earlier, we referred to
this setup as “Neurohub.” It is expected that the atlas hub functions (data loaders,
canonical RDBMS schemas, registries, spatial and semantic registration workflows, image
server, atlas hub services etc.) would reside in an “atlas container” implemented within
Neurohub. The standard hub’s application services (as described in section 1) will still be
registered at the INCF Central in the same fashion as those from a hybrid hub.
The purpose of the above outline is to describe functionality and implementation of a hub
from the Atlasing perspective. A description of how the atlas service interacts with other
components of a hub (e.g. portal, collaborative tools, backend data management, etc.) is
beyond the scope of this document. This, however, will become one of the foci at the
implementation stage of atlas hub service. Therefore, we provide a glimpse of the
anticipated hardware and software model of a Neurohub, which will serve as a container for
atlas services.
One of the “standard hubs” we envision will be co-located with the INCF Central server itself
(Figure 3). This hub will be used by researchers who, for any reason, prefer not to stand a
separate hub with the above defined functionality, but rather upload their data to INCF
directly.
A2. Extensions: convenience APIs
We also envision various convenience APIs to be developed over the basic atlas services, as
well as additional language bindings (e.g. Python). For example, translating image corners
from a source SRS to a target SRS, to correctly position an image in a 2D or 3D viewer that
uses the target SRS is often difficult because image corners may be outside valid value
ranges. To resolve this problem, a simple approximate technique may be used (e.g.
transforming the center point of an image along with four vertices of a small congruent
rectangle with the same centerpoint, then extrapolating the transformed values). Such a
service (“TransformImageRectangle”) may use a series of the core TransformPOI calls.
57
A3. HUB deployment model and additional requirements
At the physical level, a NeuroHub may represent a collection of virtual machines (VMs),
managed and load-balanced. These machines could host atlas services (as described
above), data management/data sharing services and backend, collaboration tools, ontology,
resource registry, data discovery system, etc. A more detailed specification of the
deployment model is below.
The VMs comprising a hub are established per functional group (precise VM slicing to be
defined): for database server, collection/data management, atlas services, portal framework
with associated communication/collaboration tools, workflow services, resource registry,
etc. In a standard deployment configuration, 2 physical servers with identical configuration
(primary and failover), plus a single shared storage, will be provided. Figure 23 shows the
physical organization. The system itself can also (based on hardware and VM configuration)
load balance VMs across the two nodes.
Figure 22. Deployment model of INCF hub
The specific set of VMs at each hub would vary. An example of application services would be
the atlas services described above. We anticipate that separate application-level services
(and eventually VMs) would be needed for different hub maintainers (i.e. some data types
58
may be specific for a group. Some of the groups of data types managed by the INCF
infrastructure would include (also shown in Fig 1):















2D images
2D vector segmentations
3D volumes
Connectivity data
Cell models
Electrophysiology data
Surfaces
Phenotype/behavioral data
FMRI (4+D)
Time series
Gene expression data
Distortion fields, numerics
Simulation results and animations
Annotations
Publications
For each of these data type groups, the infrastructure should include: data loaders (or other
services for harvesting, ingesting and registering data of these types); data storage with
canonical relational or XML schemas; registries; spatial and semantic registration
workflows; specialized database or image servers (e.g. servers for large 2D and 3D imagery
such as CCDB); client-side applications for resource registration, curation, visualization,
resource discovery (such as services provided by NIF), analytical workflow composition (e.g.
such as the services provided by projects such as CAMERA), annotation, etc. In some
instances, such components exist, usually as individual tools. Development of these
components as part of the INCF infrastructure depends on the adoption of international
community standards for exchanging data of each type – the process which INCF is wellpositioned to lead.
A4. Code Design, Management, and Deployment
Software technologies





Tomcat – Each hub (ABA, EMAP, UCSD, WHS, etc.) is web service designed to be
deployed
Web Service (WS) – Each hub is a RESTful web service
Java – Program code
XML – All WS responses are XML documents specified with and XML schema
PostgreSQL/PostGIS – Database support
Java technologies



JUnit – Unit testing
Restlet – Facilitates RESTful WS
XMLBeans – Document-object mapping, marshaling, and serializing HTTP responses
Code management tools
59


Maven – Dependency management, builds, version control, and deployment
packaging
Subversion (SVN) – Software Configuration Management (SCM), revision control
Software project structure



Each hub is separate project (atlas-aba, atlas-emap, etc.)
Shared Java code is in the atlas-common project
Shared XML schema is in the AtlasXmlBeans2 project which includes unit tests and
example XML documents
Testing


Unit testing
HTTP server testing
Exception and Error Handling – Anytime a hub server is unable to return a valid response
with content, the server will return a WPS owsExceptionReport.
Development team practices




Comment code
Commit frequently
Commit only code that builds
Development team source code repository – http://code.google.com/p/incfdai/source/browse/
Active source code projects in repository






atlas-aba – Allen Brain Atlas hub
atlas-common – code share across hubs
atlas-emap – Edinburgh Mouse Atlas Project hub
atlas-ucsd – University of California, San Diego hub
atlas-whs – Waxholm Space (WHS) hub
AtlasXmlBeans2 – WaxML XML schema, example Java code, and example XML
documents
Deployment – The deployable Maven projects produce a ".war" (web archive file) which is
easily deployed to any Tomcat server. Note: the Tomcat server should be v6.0.x and Java
should be Java 6.
Documentation





This document
JavaDocs – (JavaDocs are not current pubished.)
Code commenting
Wiki – http://code.google.com/p/incf-dai/w/list
Google Documents – Selected document are shared (including this one) or linked
from other documentation.
60