Derivation

Derivation

Derivation(derivation_java)

Wrapper class for uk.ac.cam.cares.jps.base.derivation.Derivation.java.

This class provides a simplified interface for interacting with the Derivation object returned when creating synchronous derivations for new information.

Only two methods are provided here, all other methods in Java can be accessed via self.derivation.nameOfJavaMethod(args).

Methods:

Name	Description
getIri	Returns the IRI of the Derivation instance
getBelongsToIris	Returns the IRIs of the entities that belong to the Derivation instance

Parameters:

Name	Type	Description	Default
derivation_java		The Java derivation object	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def __init__(self, derivation_java):
    """
    Initialises the Derivation instance.

    Args:
        derivation_java: The Java derivation object
    """
    self.derivation = derivation_java

getIri

getIri() -> str

Returns the IRI of the Derivation instance.

Returns:

Name	Type	Description
str	str	IRI of the Derivation instance

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def getIri(self) -> str:
    """
    Returns the IRI of the Derivation instance.

    Returns:
        str: IRI of the Derivation instance
    """
    return self.derivation.getIri()

getBelongsToIris

getBelongsToIris(outputRdfType: str) -> List[str]

Returns the IRIs of the entities that belongsTo the Derivation instance.

Parameters:

Name	Type	Description	Default
outputRdfType	str	IRI of the rdf:type of the entities that belongsTo the Derivation instance	required

Returns:

Type	Description
List[str]	List[str]: List of IRIs of the entities that belongsTo the Derivation instance

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def getBelongsToIris(self, outputRdfType: str) -> List[str]:
    """
    Returns the IRIs of the entities that belongsTo the Derivation instance.

    Args:
        outputRdfType (str): IRI of the rdf:type of the entities that belongsTo the Derivation instance

    Returns:
        List[str]: List of IRIs of the entities that belongsTo the Derivation instance
    """
    return self.derivation.getBelongsToIris(outputRdfType)

DerivationInputs

DerivationInputs(derivationInputs)

Wrapper class for uk.ac.cam.cares.jps.base.derivation.DerivationInputs.java.

This class provides methods to handle derivations within Python derivation agents, referencing to the corresponding methods in the Java class. For implementation details, please refer to the Java code.

Methods:

Name	Description
getDerivationIRI	Returns the IRI of the derivation.
getInputs	Returns the inputs of the derivation as a dictionary.
getIris	Returns the IRIs of the inputs of the specified rdf:type.
get_inputs_ogm_by_rdf_type	Returns the inputs as objects of the specified rdf:type.
get_inputs_ogm	Returns the inputs as objects of the specified class.
get_inputs_ogm_assume_one	Returns a single input object of the specified class.

Parameters:

Name	Type	Description	Default
derivationInputs		The Java DerivationInputs object	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def __init__(self, derivationInputs) -> None:
    """
    Initialises the DerivationInputs instance.

    Args:
        derivationInputs: The Java DerivationInputs object
    """
    self.derivation_inputs = derivationInputs

getDerivationIRI

getDerivationIRI() -> str

Returns the IRI of the derivation.

Returns:

Name	Type	Description
str	str	IRI of the derivation

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def getDerivationIRI(self) -> str:
    """
    Returns the IRI of the derivation.

    Returns:
        str: IRI of the derivation
    """
    return self.derivation_inputs.getDerivationIRI()

getInputs

getInputs() -> Dict[str, List[str]]

Returns the inputs of the derivation as a dictionary.

Returns:

Type	Description
Dict[str, List[str]]	Dict[str, List[str]]: Inputs of the derivation in the format of {rdf_type: [iris]}

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def getInputs(self) -> Dict[str, List[str]]:
    """
    Returns the inputs of the derivation as a dictionary.

    Returns:
        Dict[str, List[str]]: Inputs of the derivation in the format of {rdf_type: [iris]}
    """
    return ast.literal_eval(str(self.derivation_inputs.getInputs()))

getIris

getIris(rdfType) -> Union[List[str], None]

Returns the IRIs of the inputs of the specified rdf:type.

Parameters:

Name	Type	Description	Default
rdfType	str	IRI of the rdf:type of the inputs	required

Returns:

Type	Description
Union[List[str], None]	List[str]: List of IRIs of the inputs, or None if no inputs are found

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def getIris(self, rdfType) -> Union[List[str], None]:
    """
    Returns the IRIs of the inputs of the specified rdf:type.

    Args:
        rdfType (str): IRI of the rdf:type of the inputs

    Returns:
        List[str]: List of IRIs of the inputs, or None if no inputs are found
    """
    iris = self.derivation_inputs.getIris(rdfType)
    return list(iris) if iris is not None else None

get_inputs_ogm_by_rdf_type

get_inputs_ogm_by_rdf_type(rdf_type: str, sparql_client, recursive_depth: int = 0) -> List[BaseClass]

Returns the inputs as objects of the specified rdf:type (when using object graph mapper).

Parameters:

Name	Type	Description	Default
rdf_type	str	IRI of the rdf:type	required
sparql_client		The SPARQL client to query the knowledge graph	required
recursive_depth	int	The depth of recursive queries (default is 0)	0

Returns:

Type	Description
List[BaseClass]	List[BaseClass]: List of objects of the specified rdf:type

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def get_inputs_ogm_by_rdf_type(
    self,
    rdf_type: str,
    sparql_client,
    recursive_depth: int = 0
) -> List[BaseClass]:
    """
    Returns the inputs as objects of the specified rdf:type (when using object graph mapper).

    Args:
        rdf_type (str): IRI of the rdf:type
        sparql_client: The SPARQL client to query the knowledge graph
        recursive_depth (int): The depth of recursive queries (default is 0)

    Returns:
        List[BaseClass]: List of objects of the specified rdf:type
    """
    return BaseClass.pull_from_kg(
        iris=self.getIris(rdf_type),
        sparql_client=sparql_client,
        recursive_depth=recursive_depth
    )

get_inputs_ogm

get_inputs_ogm(clz: Type[_T], sparql_client, recursive_depth: int = 0) -> List[_T]

Returns the inputs as objects of the specified class.

Parameters:

Name	Type	Description	Default
clz	Type[_T]	The class of the objects to return	required
sparql_client		The SPARQL client to query the knowledge graph	required
recursive_depth	int	The depth of recursive queries (default is 0)	0

Returns:

Type	Description
List[_T]	List[_T]: List of objects of the specified class

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def get_inputs_ogm(
    self,
    clz: Type[_T],
    sparql_client,
    recursive_depth: int = 0
) -> List[_T]:
    """
    Returns the inputs as objects of the specified class.

    Args:
        clz (Type[_T]): The class of the objects to return
        sparql_client: The SPARQL client to query the knowledge graph
        recursive_depth (int): The depth of recursive queries (default is 0)

    Returns:
        List[_T]: List of objects of the specified class
    """
    return clz.pull_from_kg(
        iris=self.getIris(clz.rdf_type),
        sparql_client=sparql_client,
        recursive_depth=recursive_depth
    )

get_inputs_ogm_assume_one

get_inputs_ogm_assume_one(clz: Type[_T], sparql_client, recursive_depth: int = 0) -> _T

Returns a single input object of the specified class.

Parameters:

Name	Type	Description	Default
clz	Type[_T]	The class of the object to return	required
sparql_client		The SPARQL client to query the knowledge graph	required
recursive_depth	int	The depth of recursive queries (default is 0)	0

Raises:

Type	Description
Exception	If the number of objects found is not exactly one

Returns:

Name	Type	Description
_T	_T	The single object of the specified class

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def get_inputs_ogm_assume_one(
    self,
    clz: Type[_T],
    sparql_client,
    recursive_depth: int = 0
) -> _T:
    """
    Returns a single input object of the specified class.

    Args:
        clz (Type[_T]): The class of the object to return
        sparql_client: The SPARQL client to query the knowledge graph
        recursive_depth (int): The depth of recursive queries (default is 0)

    Raises:
        Exception: If the number of objects found is not exactly one

    Returns:
        _T: The single object of the specified class
    """
    objects = self.get_inputs_ogm(clz=clz, sparql_client=sparql_client, recursive_depth=recursive_depth)
    if len(objects) != 1:
        raise Exception(f"""Input type {clz.rdf_type} assumed one for derivation {self.getDerivationIRI()},
            encounterred {len(objects)}: {' '.join([o.triples() for o in objects])}""")
    return next(iter(objects))

DerivationOutputs

DerivationOutputs(derivationOutputs)

Wrapper class for uk.ac.cam.cares.jps.base.derivation.DerivationOutputs.java.

This class provides methods to handle derivations within Python derivation agents, referencing to the corresponding methods in the Java class. For implementation details, please refer to the Java code.

Methods:

Name	Description
createNewEntity	Creates a new entity with the given IRI and rdf:type.
createNewEntityWithBaseUrl	Creates a new entity with a base URL and rdf:type.
addTriple	Adds a triple to the derivation outputs.
addLiteral	Adds a literal to the derivation outputs.
addLiteralWithDataType	Adds a literal with a specified data type to the derivation outputs.
addGraph	Adds a whole rdflib.Graph to the derivation outputs.
add_outputs_ogm	Adds objects of a specified class to the derivation outputs.

Parameters:

Name	Type	Description	Default
derivationOutputs		The Java DerivationOutputs object	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def __init__(self, derivationOutputs) -> None:
    """
    Initialises the DerivationOutputs instance.

    Args:
        derivationOutputs: The Java DerivationOutputs object
    """
    self.derivation_outputs = derivationOutputs

createNewEntity

createNewEntity(iri, rdfType)

Creates a new entity with the given IRI and rdf:type.

Parameters:

Name	Type	Description	Default
iri	str	IRI of the new entity	required
rdfType	str	IRI of the rdf:type of the new entity	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def createNewEntity(self, iri, rdfType):
    """
    Creates a new entity with the given IRI and rdf:type.

    Args:
        iri (str): IRI of the new entity
        rdfType (str): IRI of the rdf:type of the new entity
    """
    self.derivation_outputs.createNewEntity(iri, rdfType)

createNewEntityWithBaseUrl

createNewEntityWithBaseUrl(baseUrl, rdfType)

Creates a new entity with the given base URL and rdf:type, adds the new entity to derivation outputs, then returns the initialised IRI.

Parameters:

Name	Type	Description	Default
baseUrl	str	Base URL for the new entity	required
rdfType	str	IRI of the rdf:type of the new entity	required

Returns:

Name	Type	Description
str		IRI of the newly created entity.

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def createNewEntityWithBaseUrl(self, baseUrl, rdfType):
    """
    Creates a new entity with the given base URL and rdf:type, adds the new entity to derivation outputs, then returns the initialised IRI.

    Args:
        baseUrl (str): Base URL for the new entity
        rdfType (str): IRI of the rdf:type of the new entity

    Returns:
        str: IRI of the newly created entity.
    """
    return self.derivation_outputs.createNewEntityWithBaseUrl(baseUrl, rdfType)

addTriple

addTriple(s, p, o)

Adds a triple to the derivation outputs. Note that only one addTriple function is provided here, the two functions taking TriplePattern is NOT provided for simplicity of java-python data structure conversion.

Parameters:

Name	Type	Description	Default
s	str	Subject of the triple	required
p	str	Predicate of the triple	required
o	str	Object of the triple	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def addTriple(self, s, p, o):
    """
    Adds a triple to the derivation outputs.
    Note that only one addTriple function is provided here, the two functions taking TriplePattern is NOT provided for simplicity of java-python data structure conversion.

    Args:
        s (str): Subject of the triple
        p (str): Predicate of the triple
        o (str): Object of the triple
    """
    self.derivation_outputs.addTriple(s, p, o)

addLiteral

addLiteral(s, p, o)

Adds a literal to the derivation outputs. Note that only one addLiteral is provided here as the correct method to use will be decided by java automatically.

Parameters:

Name	Type	Description	Default
s	str	Subject of the triple	required
p	str	Predicate of the triple	required
o	Union[str, Literal]	Literal object of the triple	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def addLiteral(self, s, p, o):
    """
    Adds a literal to the derivation outputs.
    Note that only one addLiteral is provided here as the correct method to use will be decided by java automatically.

    Args:
        s (str): Subject of the triple
        p (str): Predicate of the triple
        o (Union[str, Literal]): Literal object of the triple
    """
    self.derivation_outputs.addLiteral(s, p, o)

addLiteralWithDataType

addLiteralWithDataType(s, p, o, dataType)

Adds a literal with a specified data type to the derivation outputs. Note that this method corresponds to addLiteral(String, String, String, String) in DerivationOutputs.java, but renamed in python due to limitations of overloading in python.

Parameters:

Name	Type	Description	Default
s	str	Subject of the triple	required
p	str	Predicate of the triple	required
o	str	Literal object of the triple	required
dataType	str	Data type of the literal	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def addLiteralWithDataType(self, s, p, o, dataType):
    """
    Adds a literal with a specified data type to the derivation outputs.
    Note that this method corresponds to addLiteral(String, String, String, String) in `DerivationOutputs.java`,
    but renamed in python due to limitations of overloading in python.

    Args:
        s (str): Subject of the triple
        p (str): Predicate of the triple
        o (str): Literal object of the triple
        dataType (str): Data type of the literal
    """
    self.derivation_outputs.addLiteral(s, p, o, dataType)

addGraph

addGraph(g: Graph)

Adds a whole rdflib.Graph to the derivation outputs.

Parameters:

Name	Type	Description	Default
g	Graph	The graph to add to the derivation outputs	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def addGraph(self, g: Graph):
    """
    Adds a whole rdflib.Graph to the derivation outputs.

    Args:
        g (Graph): The graph to add to the derivation outputs
    """
    for s, p, o in g:
        try:
            if p.toPython() == RDF.type.toPython():
                self.createNewEntity(s.toPython(), o.toPython())
            else:
                # add data properties
                if isinstance(o, Literal):
                    if isinstance(o.toPython(), Literal):
                        # if o.toPython() is a Literal instance, then it's returning itself
                        # this means the datatype provided to initialise o is NOT presented in rdflib.term.XSDToPython
                        # therefore, it cannot be cast to native python type
                        # but str(o) will return the lexical_or_value used
                        self.addLiteralWithDataType(s.toPython(), p.toPython(), str(o), o._datatype.toPython())
                    else:
                        # .toPython() works out what's the most suitable python class and cast to it
                        self.addLiteral(s.toPython(), p.toPython(), o.toPython())
                # add object properties
                else:
                    self.addTriple(s.toPython(), p.toPython(), o.toPython())
        except Exception as exc:
            raise Exception(f"Failed to add: {s.n3()} {p.n3()} {o.n3()}") from exc

add_outputs_ogm

add_outputs_ogm(objects: Union[BaseClass, List[BaseClass]])

Adds objects of a specified class to the derivation outputs.

Parameters:

Name	Type	Description	Default
objects	Union[BaseClass, List[BaseClass]]	The objects to add to the derivation outputs	required

Source code in JPS_BASE_LIB/python_wrapper/twa/data_model/derivation.py

def add_outputs_ogm(self, objects: Union[BaseClass, List[BaseClass]]):
    """
    Adds objects of a specified class to the derivation outputs.

    Args:
        objects (Union[BaseClass, List[BaseClass]]): The objects to add to the derivation outputs
    """
    if isinstance(objects, BaseClass):
        objects = [objects]
    iris = [o.instance_iri for o in objects]
    self.addGraph(KnowledgeGraph.all_triples_of_nodes(iris))