Examples

Introduction

ZOOMA can easily be used as a library: the easiest way is to use Spring to configure the various components to give you the behaviour you want from your implementation. You will also need a few config files on your classpath - download the release version and look at the files in the config/ directory for examples and more details, or see here.

If you want to use ZOOMA as a library, you can use it within a maven project by adding the following repository to your pom:

  <repositories>
    <repository>
      <id>zooma-repo</id>
      <name>ZOOMA Mini-SF Repository</name>
      <url>http://zooma.sourceforge.net/maven/repo</url>
    </repository>
  ...
  </repositories>

and then declare the following dependency:

  <dependencies>
    <dependency>
      <groupId>uk.ac.ebi.microarray</groupId>
      <artifactId>zooma-text</artifactId>
      <version>1.0-beta</version>
    </dependency>
  </dependencies>

Examples of Java Code to use ZOOMA

An example configuration file describing one system is attached below. Then, to use this as a library, you would just have to load the config and obtain the "mapper" bean - for example:

  BeanFactory factory =
      new ClassPathXmlApplicationContext("zooma-text.xml");
  TextReportingMapper mapper =
      factory.getBean("textMapper", TextReportingMapper.class);

This code fragment would return a TextReportingMapper, which is optimized to produce a text report describing mappings. As yet, there aren't any Mapper implementations designed for use in a more programmatic context, but it doesn't really matter - we can just use the "generateOutcome()" method on this class. So:

  OntologyMappingOutcome outcome = mapper.generateOutcome("myText");

If we were then to call

  mapper.applyOutcome(outcome);

... we'd generate a text report, but we don't need to do this. The 'outcome' object encapsulates all the information we require. You can obtain mapped terms from the outcome object, for example, using:

  Collection<OntologyMappingHypotheses> hypotheses =
      outcome.getBestHypotheses();
  for (OntologyMappingHypothesis hypothesis : hypotheses) {
      Collection<OntologyTerm> mappedTerms = hypothesis.getOntologyTerms();
  }

See the javadocs for Ontology Mapping Outcome and Ontology Mapping Hypothesis for more information on how to extract information from an outcome.

Example Spring Configuration

This spring config file assembles a TextReportingMapper and wires it up to fetch ontology terms from OLS and Bioportal. Terms are ranked according to preferences specified in the configuration files (see here for more).

Note on "Retrievers"

OntologyRetrievers are used to fetch OntologyTerms from a variety of sources. The configuration below does NOT pre-configure any retrievers for this mapper, so as a result all outcomes would be empty. But, you can easily add new retrievers to fetch candidate terms by calling:

  mapper.addRetriever(new OntocatRetriever());

... for example. This will add a retriever that uses OntoCAT to fetch mapping candidate ontology terms from bioportal and OLS. There are other retriever types available - see the javadocs for more information.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans.xsd">

  <!-- Wiring for zooma, preconfiguring all mapping systems -->

  <!-- configurator bean, loads source and ontology ranking config -->
  <bean id="configurator"
        class="uk.ac.ebi.microarray.zooma.utils.Configurator"
        init-method="loadConfiguration" />

  <!-- config objects extracted from configurator -->
  <bean id="sources"
        factory-bean="configurator"
        factory-method="getSourcesConfig" />

  <bean id="ontologies"
        factory-bean="configurator"
        factory-method="getOntologiesConfig" />

  <bean id="rejectedOntologies"
        factory-bean="configurator"
        factory-method="getRejectedOntologiesConfig" />

  <!-- source ranker, acquired from configurator -->
  <bean id="sourceRanker"
        class="uk.ac.ebi.microarray.zooma.calc.SourceRanker">
    <constructor-arg ref="sources" />
  </bean>

  <!-- ontology ranker, again from configurator -->
  <bean id="ontologyRanker"
        class="uk.ac.ebi.microarray.zooma.calc.OntologyRanker">
    <constructor-arg ref="ontologies" />
    <constructor-arg ref="rejectedOntologies" />
  </bean>

  <!-- hypothesis factory -->
  <bean id="hypothesisFactory"
        class="uk.ac.ebi.microarray.zooma.hypothesis.TrackedHypothesisFactory" />

  <!-- retrievers -->
  <!--
   *** NOTE ***

   OntologyRetrievers are constructed on-the-fly from user specified options,
   and never pre-instantiated here.

   As a consequence, it is necessary to build a formulator template and add new
   retrievers when they are constructed from user-specified parameters

   ************
   -->

  <!-- ontology mapping calculator -->
  <bean id="calculator"
        class="uk.ac.ebi.microarray.zooma.calc.RankingBasedCalculator">
    <property name="sourceRanker" ref="sourceRanker" />
    <property name="ontologyRanker" ref="ontologyRanker" />
  </bean>

  <!-- ontology mapping evaluator -->
  <bean id="evaluator"
        class="uk.ac.ebi.microarray.zooma.eval.DefaultMappingEvaluator">
    <property name="ontologyMappingCalculator" ref="calculator" />
  </bean>

  <!-- all required formulator beans -->
  <bean id="nullHypothesisFormulator"
        class="uk.ac.ebi.microarray.zooma.formulate.NoPossibleMappingFormulator">
    <property name="ontologyMappingHypothesisFactory"
              ref="hypothesisFactory" />
  </bean>

  <!-- this is a template, because it needs retrievers adding -->
  <bean id="formulator"
        class="uk.ac.ebi.microarray.zooma.formulate.ContextSensitiveMappingFormulator">
    <property name="ontologyMappingHypothesisFactory" ref="hypothesisFactory" />
  </bean>

  <!-- mappers -->
  <bean id="textMapper"
        class="uk.ac.ebi.microarray.zooma.mapping.TextReportingMapper">
    <property name="nullHypothesisFormulator" ref="nullHypothesisFormulator" />
    <property name="alternativeHypothesisFormulator" ref="formulator" />
    <property name="evaluator" ref="evaluator" />
    <property name="reportingFails" value="true" />
  </bean>

</beans>