ont-app.igraph.core — ont-app/igraph 0.2.0

Abstractions over a graph object, intended to sit alongside the other basic clojure data structures such as maps, vectors and sets.

add-to-graph clj/s multimethod

Returns g, with to-add added Where

• g is a Graph
• to-add is interpetable as a set of triples Dispatched according to triples-format

assert-unique clj/s

fn [g s p o] -> g', asserting a unique triple in immutable graph.

• Wrapper around assert-unique-fn

assert-unique! clj/s

fn [g s p o] -> g', asserting a unique triple in mutable graph.

• Wrapper around assert-unique-fn

assert-unique-fn clj/s

(assert-unique-fn context g s p o)

Returns g', replacing any existing [s p *] with [s p o] per context Where

• g is a graph
• context := m s.t. (keys m) = #{:add-fn :subtrct-fn}
• add-fn is one of #{add, add! claim} appropriate to g's modification protocol
• subtract-fn is one of #{subtract, subtract! retract} appropriate to g's modification protocol

claim-unique clj/s

fn [g s p o] -> g', asserting a unique triple in an accumulate-only graph .

• Wrapper around assert-unique-fn

flatten-description clj/s

(flatten-description p-o)

Returns p-o description with singletons broken out into scalars Where

• p-o := {p #{o}, ...}, normal form at 'description' level of a graph.

IGraph clj/s protocol

An abstraction for S-P-O graphs

ask clj/s

(ask g s p o)

Returns truthy value iff [s p o] appears in g Where

• g is a graph
• s is subject of some triples in g
• p is predicate of some triples in g
• o appears in triple [s p o] in g

get-o clj/s

(get-o g s p)

Returns {o ...} for s and p in g, or nil. Where

• g is a graph
• s is subject of some triples in g
• p is predicate of some triples in g
• o appears in triple [s p o] in g

get-p-o clj/s

(get-p-o g s)

Returns {p #{o ...}} associated with s in g, or nil. Where

• g is a graph
• s is subject
• p and o are in triples := [s p o] in g

invoke clj/s

(invoke g)

(invoke g s)

(invoke g s p)

(invoke g s p o)

Applies g as a function to the rest of its arguments, representing triples [s p o] in g respectively. p may optionally be a traversal function (See traverse docs)

• (g) -> {s {p #{o...}...}...} ;; = (normal-form g)
• (g s) -> {p #{o...}, ...} ;; = (get-p-o g)
• (g s p) -> #{o ...} ;; = (match-or-traverse g s p)
• (g s p o) -> o iff [s p o] is in g ;; = (match-or-traverse g s p o)

mutability clj/s

(mutability g)

Returns one of ::read-only ::immutable ::mutable ::accumulate-only

normal-form clj/s

(normal-form g)

Returns {s {p #{o...}...}...} Where

• s is the subject of a triple := [s p o] in g
• p is predicate of same
• o is the object of same

query clj/s

(query g q)

Returns #{binding ...} for query spec q applied to g Where

• binding := {var value, ...}
• q is a query specification suitable for the native format of g
• g is a graph
• var is a variable specified in q
• value is a value found in g bounded to var per q

subjects clj/s

(subjects g)

Returns (s...) for g Where

• s is a subject in one or more triples in g
• g is a graph.

IGraphAccumulateOnly clj/s protocol

claim clj/s

(claim g to-add)

Returns g, with to-add added to g's associated transactor. Throws an exception if (mutability g) != ::accumulate-only Where

• g is a mutable graph
• to-add is in triples-format NOTE: see Datomic documentation for the 'add' operation for details

retract clj/s

(retract g to-retract)

Returns g with comm reset to head Side-effect: to-retract retracted from comm Throws an exception if (mutability g) != ::accumulate-only. Where

• g is a graph
• comm is a datomic-style transactor to-retract is in triples-removal-format NOTE: see Datomic documentation for details

IGraphImmutable clj/s protocol

add clj/s

(add g to-add)

Returns g', with to-add added to its contents. Throws a ::ReadOnly exception if (read-only? g) Where

• g is a graph
• to-add is in triples-format

subtract clj/s

(subtract g to-subtract)

Returns g' with to-subtract removed from its contents. Throws an exception if (mutability g) != ::immutable Where

• g is an immutablegraph
• to-subtract is in triples-removal-format

IGraphMutable clj/s protocol

add! clj/s

(add! g to-add)

Returns g, with to-add added to its contents. Throws an exception if (mutability g) != ::mutable Where

• g is a mutable graph
• to-add is in triples-format

subtract! clj/s

(subtract! g to-subtract)

Returns g with to-subtract removed from its contents. Throws a ::ReadOnly exception if (read-only? g) Where

• g is a graph
• to-subtract is in triples-removal-format

IGraphSet clj/s protocol

Basic set operations between graphs.

difference clj/s

(difference g1 g2)

Returns an IGraph whose normal form contains all statements in g1 not present in g2.

intersection clj/s

(intersection g1 g2)

Returns an IGraph whose normal form contains all and only statements shared by both g1 and g2

union clj/s

(union g1 g2)

Returns an IGraph whose normal form contains all triples from g1 and g2

match-or-traverse clj/s multimethod

Returns values appropriate for (g s p) or (g s p o) invocations Where

• o is an object in g
• s is a subject in g
• p is either a predicate in g or a traversal function accumulating a set, starting with an empty accumulator and queue of [s] (see docs for traverse) NOTE: Implementers of IGraph will typically use this method for IFn invoke members involving a p argument.

maybe-traverse-link clj/s

(maybe-traverse-link p)

Returns traversal function (fn [g context, acc queue]...) -> [context, acc', queue'], Where

• acc' includes node and and as many os as are linked from node by p in g
• queue := [node ...], nodes to visit in traversal
• p is a predicate in g
• g is a graph

NOTE: typically used as one component in a traversal path. cf the '?' operator in SPARQL property paths

normal-form? clj/s

(normal-form? m)

Returns true iff m is in normal form for IGraph.

normalize-flat-description clj/s

(normalize-flat-description m)

Returns a normalized p-o description of m Where

• m is a plain clojure map

on-js-reload cljs

(on-js-reload)

p-dispatcher clj/s

(p-dispatcher _g_ _s_ p)

(p-dispatcher _g_ _s_ p _o_)

Returns :traverse or :match, as a basis for dispatching standard invoke methods involving a p argument, which may be either a value to match or a traversal function.

read-from-file clj

(read-from-file g path)

returns g with the contents of path added Where

• g implements IGraph
• path is an edn file containing a normal-form representation of some graph, typically the output of save-to-file.

reduce-spo clj/s

(reduce-spo f acc g)

Returns acc' s.t. (f acc s p o) -> acc' for every triple in g Where

• f := (fn [acc s p o] -> acc'
• acc is any value, a reduction accumlator
• s p o constitute a triple in g
• g implements IGraph NOTE: C.f. reduce-kv

remove-from-graph clj/s multimethod

Returns g, with to-remove removed Where

• g is a Graph
• to-add is interpetable as a set of triples Dispatched according to triples-removal-format

t-comp clj/s

(t-comp comp-spec)

Returns a traversal function composed of elements specified in comp-spec Where

• comp-spec := {:path [spec-element, ...] spec-element {:fn traversal-fn :doc docstring :into initial-acc (default []) :local-context-fn local-fn (default nil) :update-global-context global-fn ( default nil) } } Or Alternatively, [traversal-fn-or-property-name, ...] for the short form.
• spec-element is typically a keyword naming a stage in the traversal, though it can also be a direct reference to a traversal function, in which case it will be equivalent to {:fn spec-element}
• traversal-fn-generator := (fn [spec-element]...) -> traversal-fn, to be invoked in cases where there is no spec-element in comp-spec, traverse-link is the typical choice here.
• traversal-fn := (fn [g context acc queue]...) -> [context' acc' queue']
• context is a traversal context conforming to the traverse function (see docs)
• update-fn := (fn [global-context local-context] ...) -> global-context' This is provided in case there is some coordination that needs to be provided between stages in a composed traversal.
• initial-acc is the (usually empty) container used to initial the acc of the traversal stage being specified
• local-context-fn := [global-context] -> local-context
• update-global-context := [global-context local-context] -> global-context'
• local-context is the context for a given stage of the traversal
• global-context carries over between traversal stages. Examples (def comp-spec { :isa? {:fn (maybe-traverse-link :isa) :doc traverses an isa link, if it exists :local-context {:doc traversing an isa link} :update-global-context (fn [gc lc] (assoc gc :status :followed-isa-link)) } :subClassOf* {:fn (transitive-closure :subClassOf) :doc 'traverses 0 or more subClassof links' :local-context-fn (fn [c] {:doc 'traversing subClassOf*'}) :into #{} :update-global-context (fn [gc lc] (assoc gc :status :followed-subclassof)) } }}) (traversal-comp (merge comp-spec {:path [:isa? :subClassOf*] :doc 'Traverses the chain of subsumption links for an instance or class' }))

(t-comp (merge comp-spec {:path [:isa :label] :doc 'gets class labels')))

Short form example:

(t-comp [:family/parent :family/brother]) ... Equal to (t-comp [(traverse-link :family/parent) (traverse-link :family/brother)] An inferred 'uncle' relation.

transitive-closure clj/s

(transitive-closure p)

Returns traversal for chains of p. Where traversal := (fn [g acc queue]...) -> [context acc' queue'], s.t. queue' conj's all o s.t. (g s p o).
A traversal function argument for the traverse function . p is a predicate, typcially an element of g g is a graph. NOTE: cf the '*' operator in SPARQL property paths

traverse clj/s

(traverse g traversal queue)

(traverse g traversal acc queue)

(traverse g traversal context acc queue)

Returns acc acquired by applying traversal to g starting with queue, informed by context Where

• acc is an arbitrary clojure 'accumulator' object (similar to a reduce function). Default is [].
• traversal := (fn [g context acc queue]...) -> [context' acc' queue']
• g is a graph
• context := {context-key context-value....}, expressing important aspects of the traversal state
• queue := [node ...], nodes to visit
• context-key := #{:history ... maybe :skip? ... :seek ... or other keys specific to traversal, which traversal may use to communicate with future iterations of itself.
• history := #{visited-node ...}, this is conj'd with each visited node on each call to avoid cycles.
• skip? (optional) := (fn [node] -> true if we should skip). This may also be a set of nodes to skip. This allows for overriding the default skipping behavior which simply skips history
• seek (optional) := (fn [context acc] -> acc', a function to be called at the start of each traversal, a truthy, non-empty response to which will be the immediate return value of the traverse function. This would save you the time and trouble of processing the whole queue, or making each traversal function smart enough to stop early. Must return the same type as acc.
• node is typically an element in g, but can be any value the traversal function knows how to handle
• visited-node is a node visited upstream. We filter these out to avoid cycles. This can also be specified in advance by the user.
• target is a node we may be searching for. Note: it is good practice to assign a :transition-fn metadata tag to transition functions, though such data is not referenced anywhere at this point.

traverse-link clj/s

(traverse-link p)

Returns traversal function (fn [g context, acc queue]...) -> [context, acc', queue'], following one p in g Where

• acc is a set
• queue := [node ...], nodes to visit in traversal
• p is a predicate in g
• g is a graph

NOTE: typically used as one component in a traversal path

traverse-or clj/s

(traverse-or & ps)

Returns traversal function (fn [g context, acc queue]...) -> [context, acc', queue'], for ps Where

• acc' includes node and and as many os as are linked from node by p1 | p2 | ... in g
• queue := [node ...], nodes to visit in traversal
• ps := [p1, p2, ...]
• p1, p2, ... are all predicates in g, or traversal functions
• g is a graph

cf the '|' operator in SPARQL property paths

triples-format clj/s

(triples-format triples-spec)

Returns the value of (:triples-format (meta triples-spec)) or one of #{:vector :vector-of-vectors :normal-form type} inferred from the shape of triples-spec Where

• args := [g triples-spec], arguments to a method add or remove from graph
• g is a graph
• triples-spec is a specification of triples typically to add to or remove from g
• :normal-form indicates (normal-form? triples-spec) = true
• :triple indicates triples-spec := [s p o]
• :vector-of-vectors indicates triples-spec := [triple...]
• type = (type triples-spec)

triples-removal-format clj/s

(triples-removal-format triples-spec)

Returns a keyword describing the format of triples-spec for removing a set of triples from a graph.

unique clj/s

(unique coll)

(unique coll on-ambiguity)

Returns the single member of coll, or nil if coll is empty. Calls on-ambiguity if there is more than one member (default is to throw an Exception). Where

• coll is a collection
• on-ambiguity := (fn [coll] ...) -> value, default raises an error. Note: this can be used when you've called (G s p) and you're sure there is only one object.

write-to-file clj

(write-to-file path g)

Side-effect: writes normal form of g to path as edn. Returns: path Where

• path is the output of path-fn
• g implements IGraph
• path-fn a function [g] -> path. NOTE: Anything that would choke the reader on slurp should be removed from g before saving.