README for the Semantic Precision and Recall Calculator
=======================================================

Start the tool
--------------

* On Linux: start the file run.sh
* On Windows: start the file run.bat

Alternatively, you can start the tool using the normal start
method for Java JAR files, namely by calling
	java -jar spart.jar

Without passing additional arguments the graphical user interface
is started. This mode is relatively straight forward and thus
is not described in greater detail.

For descriptions on the batchmode continue reading.

Batchmode
---------
For using the batchmode you have to pass the argument --batch to
the tool (e.g. run.bat --batch or java -jar spart.jar --batch).
In the following we describe the additional parameters which have
to follow the --batch switch.

There are two different batchmodes: the general batchmode and the
conference batchmode. Both are described in the following.

General batchmode
-----------------
This is the standard batchmode. It requires two parameters to be passed from
the commandline at runtime.
	SEMANTIC BASEDIR

The first parameter is the name of the semantic
which is to simplify matters only the first part of the name and thus one
of Natural, Pragmatic or Null (for classical measures). The semantic name
is case-insensitive. The second argument is the base-directory whose
subdirectories will be traversed by the batchmode. The format for the
base-directory and its contents is as follows.

basedir/								[ directory passed at commandline ]
	subdir1/							[ directory of first ontology set ]
		onto1.rdf						[ first ontology ]
		onto2.rdf						[ second ontology ]
		refalign.rdf					[ reference alignment ]
		*.rdf							[ alignments to be evaluated ]
	subdir2/
		...

The base-directory may contain an arbitrary number of sub-directories which
in turn may contain (besides the two ontologies and the reference alignment)
an arbitrary number of alignments. These alignments are evaluated according
to the given semantics and with regard to the ontologies and the reference
alignment.

The results are written into an XML file named results.xml which is placed
in the base-directory.


Conference batchmode
--------------------

As the conference test set would be very hard to evaluate using the general
batchmode, we implemented a special batchmode for this test set. This mode
requires three arguments prefixed by a special argument which activates the
conference batchmode.

	--conference THRESHOLD SEMANTIC BASEDIR

The argument "--conference" activates the conference mode. The next argument
specifies the threshold. This is a quirk of the conference evaluation. Only
correspondences with a threshold equal or greater than the specified threshold
are considered during the evaluation, all other correspondences are ignored.
This argument must be parseable into a float type, i.e. 0.2 , 0.5 or 0.7 .
The semantic argument is the same as described for the general batchmode.
The last argument determines the base-directory to work at. Different from the
general mode, the conference mode does not expect subdirectories but expects
the data to be directly in the provided directory. The naming conventions
for these files are as follows (we use regular expressions in the following
descriptions).
The base directory may contain three different types of files: ontologies,
reference alignments and alignments which should be evaluated.
The ontologies have to be named matching the expression [a-zA-Z]*\.owl
The reference alignments have names matching to FIRSTONTO-SECONDONTO\.(rdf|owl|xml)
and the alignments are named MATCHER-FIRSTONTO-SECONDONTO\.(rdf|owl|xml).
FIRSTONTO, SECONDONTO and MATCHER are string matching [a-zA-Z]*
For each possible combinaton of ontologies the name FIRSTONTO-SECONDONTO is
generated and if there exists a corresponding reference alignment each alignment
with an arbitrary matcher name and the correct reference alignment name is
evaluated against the ontologies and the reference alignment.

The results are saved into the base directory as an XML file named results.xml


Software License Agreement for the tool's source code (BSD License)
-------------------------------------------------------------------
Software License Agreement (BSD License)

Copyright (c) 2009 Daniel Fleischhacker <dev@dfleischhacker.de>
All rights reserved.

Redistribution and use of this software in source and binary forms, with or
without modification, are permitted provided that the following conditions
are met:

  1. Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.


Third-Party Components
----------------------
The distributions of spart contain third-party components. These components and
the corresponding licences are given in the following.

* OWL API (http://owlapi.sf.net)
* Pellet (http://clarkparsia.com/pellet) which in turn uses other libraries

For further information regarding the licenses of third-party libraries consult
the files in the licensing/ directory of this distribution.