NAME
SIO::Utils - tools for working with the SIO ontology
SYNOPSIS
use RDF::SIO::Utils;
my $SIO = RDF::SIO::Utils->new();
# auto created RDF::Utils::Trine is there
my $m = $SIO->Trine->temporary_model();
# create a subject to execute annotation and parsing on
my $s = $SIO->Trine->iri('http://mydata.com/patient101');
# we want to add a blood pressure attribute to this patient, using
# the "hasBloodPressure" predicate from our own ontology
# SIO::Utils will automatically add the SIO:has_attribute
# predicate as a second connection to this node
my $BloodPressure = $SIO->addAttribute(model => $m,
node => $s,
predicate => "http://myontology.org/pred/hasBloodPressure",
attributeType => "http://myontology.org/class/BloodPressure",
);
#this is how to handle the success/failure of most calls in this module
if ($BloodPressure){
print "Blood Pressure attribute ID is ",$BloodPressure->as_string,"\n";
} else {
print $SIO->error_message(), "\n";
die; # or do something useful...
}
my $Measurement = $SIO->addMeasurement(model => $m,
node => $BloodPressure,
attributeID => "http://mydatastore.org/observation1",
value => "115",
valueType => "^^int",
unit => "mmHg"
);
print "Measurement node ID is ",$Measurement->as_string,"\n";
print "extracting info from this Measurement:\n";
my ($value, $unit) = $SIO->getUnitValue(model => $m, node => $Measurement);
print "Measurement was - Value: $value\nUnit: $unit\n\n";
my $types = $SIO->getAttributeTypes(
model => $m,
node => $s);
print "\n\nAll Attribute Types:\n ";
print join "\n", @$types, "\n";
my $bp = $SIO->getAttributesByType(
model =>$m,
node => $s,
attributeType =>"http://myontology.org/class/BloodPressure", );
print "Nodes of type 'Blood Pressure':\n";
print join "\n", @$bp, "\n";
print "\nand the piece de resistance...
traverse the whole shebang in one call!\n";
my $data = $SIO->getAttributeMeasurements(
model => $m,
node => $s,
attributeType => "http://myontology.org/class/BloodPressure"
);
foreach my $data_point(@$data){
my ($value, $unit) = ("", "");
($value, $unit) = @$data_point;
print "found Blood Pressure data point: $value, $unit\n";
}
# to dump out the entire model as RDF
use RDF::Trine::Serializer::RDFXML;
my $serializer = RDF::Trine::Serializer::RDFXML->new( );
print $serializer->serialize_model_to_string($m);
print "\n\n"; DESCRIPTION
The Semantic Science Integrated Ontology (SIO) is an upper-ontology designed specifically to represent scientific data. This module helps users create data compliant with this ontology, and parse that data
AUTHORS
Mark Wilkinson (markw at illuminae dot com)
METHODS
new
Usage : my $SIO = SIO::Utils->new();
Function : Create a helper module for the SIO ontology
Returns : a helper module for the SIO ontology
Args : noneaddAttribute
Usage : $SIO->addAttribute(%args);
Function : add a new attribute to an SIO entity
Returns : 0 on failure (check $SIO->error_message after failure for
details. Returns the attribute's Trine node on success.
Args : model - an RDF::Trine::Model to hold results
node - the RDF::Trine::Node to which we will attach the
attribute. This is the "subject" of the triples,
and (duh) should be part of the model above.
predicate - optional, your desired predicate URI.
Defaults to sio:hasAttribute if not provided.
attributeID - optional,the URI of your attribute,
defaults to a bnode, but MUST be typed
attributeType - The rdf:type of your attribute as a URI
value - optional, the value (e.g. 17 or "hi")
valueType - optional, and this varies depending on
what "value:" is. If it is a string, then
enter the language here using "lang:xx" (e.g.
valueType = 'lang:en'). If it is a non-string,
then enter its xsd:type in turtle syntax
(e.g. valueType='^^int')
unit - optional, URI to a Unit Ontology type, or a string
Description: Creates the following structure:
node
has_attribute
attributeID/_bnode
[has_value value]
[has_unit unit]
[rdf_type type] (dflt SIO:attribute)addMeasurement
Usage : $SIO->addMeasurement(%args);
Function : A specialized type of addAttribute - rdf types and
predicates are auto-selected to be compliant with SIO
Returns : 0 on failure (check $SIO->error_message after failure for
details.) Returns the Measurement's Trine node on success.
Args : model - an RDF::Trine::Model to hold results
node - the RDF::Trine::Node to which we will attach the
attribute. This is the "subject" of the triples,
and (duh) should be part of the model above.
attributeID - optional,the URI of your attribute,
defaults to a bnode.
value - required, the value of the measurement. In SIO, all
measurements are **numeric**
valueType - required, values xsd:type in turtle syntax
(e.g. valueType='^^int')
unit - optional, URI to a Unit Ontology type, or a string
Description: Creates the following structure:
node
has_measurement_value
sio:measurement_value(attributeID or bnode)
has_value value
[has_unit unit]getAttributeTypes
Usage : $SIO->getAttributeTypes(%args);
Function : Retrieve a list of attribute types for a given node
Returns : listref of matching RDF::Trine::Nodes,
or listref of [0] on error (see $SIO->error_message)
Args : model - an RDF::Trine::Model with the graph of interest
node - the RDF::Trine::Node to query attributes of
as_string - if set to 'true', the routine will return a
listref of string URIs, instead of Trine nodes.
All arguments are required.getAttributesByType
Usage : $SIO->getAttributesByType(%args);
Function : You specify the rdf:type of the attribute you want
and this routine retrieves all such SIO:attribute nodes
from the node you submit.
Returns : listref of matching RDF::Trine::Nodes,
or listref of [0] on error (see $SIO->error_message)
Args : model - an RDF::Trine::Model with the graph of interest
node - the RDF::Trine::Node to query attributes of
attributeType - the URI of your attribute-type of interest
All arguments are required.getUnitValue
Usage : $SIO->getUnitValue(%args);
Function : You provide an SIO attribute node and this routine
retrieves the value and unit of that node (if available)
Returns : list containing (Value, Unit) as scalars (note that if Unit is
a reference to an ontology node, it will return the URI
of that node, NOT the node as a Trine). If there is no unit,
undef will be returned as the second value of the list.
Returns an empty list on failure.
Args : model - an RDF::Trine::Model with the graph of interest
node - the RDF::Trine::Node to query value/unit of
Description: The routine assumes that your graph has the following
SIO-compliant structure:
SIO:attribute
--has_value--> Value(literal)
--has_unit---> Unit (literal or URI node)
Note that the routine assumes (as per my understanding of
SIO) that only one value and one unit are allowed
for any given attribute, so even if there is more than
one, only one value/unit will returned!getAttributeMeasurements
Usage : $SIO->getAttributeMeasurements(%args);
Function : a short-cut to retrieve SIO-style attribute measurements.
(see Description for expected graph structure)
retrieves value/unit pairs for each measurement of an attribute
Returns : nested listref [[value, unit], [value, unit],...]
for the precise details of the inner listrefs,
see 'getUnitValue' documentation
Args : model - an RDF::Trine::Model with the graph of interest
node - the RDF::Trine::Node to query attributes of
(would be SIO:thing in the diagram below)
attributeType - URI of type of attribute you want the
measurement values for
(e.g. http://myontology.org/SomeAttributeType)
Description: The routine assumes that your graph has the following
SIO-compliant structure:
SIO:thing
--has_attribute--> SIO:attribute
--rdf:type--> your:SomeAttributeType
--has_measurement_value--> SIO:measurement
--has_value--> Value(literal)
--has_unit---> Unit (literal or URI node)
Note that the routine assumes (as per my understanding of
SIO) that only one value and one unit are allowed
for any given SIO:measurement, so even if there is more than
one, only one value/unit will returned!
this subroutine is ~equivalent to:
getAttributesByType(SomeAttributeType)
getAttributesByType(SIO:measurement)
getUnitValue()