NAME

RDF::SIO::Utils - tools for working with the SIO ontology

SYNOPSIS

 use RDF::SIO::Utils;

 my $SIO = RDF::SIO::Utils->new();
 
 # auto created RDF::SIO::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      :    none

addAttribute

 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
                context - optional, URI of the context (for n-quads and named graphs)
 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
                context - optional, URI of the named graph for n-quads
 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()