linkml 1.8.1__py3-none-any.whl → 1.8.3__py3-none-any.whl

linkml/transformers/logical_model_transformer.py

@@ -1,23 +1,67 @@
 """
-A model transformer that transforms a schema into logical form with inheritance remaoved.
+A model transformer that transforms a schema into logical form.
 
 Formally, this transformer generates a logical model of the schema in which inheritance
-of slots/attributes is replaced by boolean conjunctions.
+of slots/attributes is replaced by boolean conjunctions, and the final form is simplified.
+
+For example, given a slot `s`:
+
+```
+slots:
+  s:
+    range: integer
+    minimum_value: 1
+```
+
+Which is reused and refined by C and C (where C is_a D):
+
+```
+classes:
+  D:
+    slots:
+     - s
+    slot_usage:
+      s:
+         minimum_value: 2
+  C:
+    is_a: D
+    slot_usage:
+      s:
+        minimum_value: 3
+```
+
+The hierarchy unrolling step will create an attribute `s` for C that is the conjunction of usages for that
+class, ancestors, and the base slot:
+
+```
+s:
+    range: integer
+    all_of:
+        - minimum_value: 1
+        - minimum_value: 2
+        - minimum_value: 3
+```
+
+This is then simplified using symbolic reasoning to:
+
+```
+s:
+    range: integer
+    minimum_value: 3
+```
+
+See logictools.py for the symbolic reasoning engine.
+
 
-For example, given a slot s and two classes C and D, where C is_a D. If both C and D
-place constraints on s (for example, C may refine the range, or make more restricted
-value constraints), then an attribute is generated for C that for which the conjunction
-of constraints in both classes hold.
 
-These logical constraints are then simplified by translating to disjunctive normal form,
-and applying simplification rules.
 """
 
 import logging
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import Any, Callable, Dict, Iterator, List, Union
+from typing import Any, Callable, Dict, Iterator, List, Optional, Union
 
+from linkml_runtime import SchemaView
 from linkml_runtime.dumpers import json_dumper
 from linkml_runtime.linkml_model import ClassDefinitionName, SchemaDefinition
 from linkml_runtime.linkml_model.meta import (
@@ -37,6 +81,8 @@ HERITABLE_METASLOT = [
     "range_expression",
     "minimum_value",
     "maximum_value",
+    "minimum_cardinality",
+    "maximum_cardinality",
     "pattern",
     "structured_pattern",
     "required",
@@ -64,6 +110,8 @@ DIRECT_ROLL_DOWN = ["multivalued", "key", "identifier", "designates_type"]
 HERITABLE_TYPE_METASLOT = [
     "minimum_value",
     "maximum_value",
+    # "minimum_cardinality",
+    # "maximum_cardinality",
     "pattern",
     "structured_pattern",
     "all_of",
@@ -103,6 +151,7 @@ class LogicalModelTransformer(ModelTransformer):
     >>> _ = sb.add_class("Person", slots={"age": {"range": "integer"}}, is_a="Thing")
     >>> _ = sb.add_class("Organization", slots={"category": {"range": "OrganizationType"}}, is_a="Thing")
     >>> _ = sb.add_enum("OrganizationType", ["commercial", "non-profit"])
+    >>> _ = sb.add_defaults()
     >>> from linkml.transformers.logical_model_transformer import LogicalModelTransformer
     >>> tr = LogicalModelTransformer()
     >>> tr.set_schema(sb.schema)
@@ -113,8 +162,10 @@ class LogicalModelTransformer(ModelTransformer):
     attributes:
       id:
         name: id
+        range: string
       name:
         name: name
+        range: string
       age:
         name: age
         range: integer
@@ -142,6 +193,10 @@ class LogicalModelTransformer(ModelTransformer):
 
     ...
 
+    This has "compiled away" the hierarchy. The type of the values of 'entities' for Container can
+    be checked against the any_of expression, without needing to know the full class hierarchy.
+    This is useful when compiling to a framework that does not support inheritance.
+
     If you are compiling to a framework that does have inheritance, then you can specify that these are
     preserved:
 
@@ -173,6 +228,9 @@ class LogicalModelTransformer(ModelTransformer):
         name: entities2
         multivalued: true
         any_of:
+        - range: Organization
+        - range: Person
+
     ...
 
     Note that defaults are always applied after reasoning. So if you set a default_range to
@@ -211,6 +269,10 @@ class LogicalModelTransformer(ModelTransformer):
     minimum_value: 40
     maximum_value: 60
 
+    Here the slot-level constraints seem to have been "overridden". In fact, LinkML is monotonic, and there
+    is no overriding. In fact the constraints have been combined as a conjunction (And), and then the resulting
+    entailed attribute has been *simplified* (age >= 40 & age >= 0 ==> age >= 40).
+
     The reasoning engine can also detect unsatisfiable constraints:
 
     >>> from linkml.transformers.logical_model_transformer import UnsatisfiableAttribute
@@ -227,6 +289,9 @@ class LogicalModelTransformer(ModelTransformer):
     Let's get rid of the problematic class:
 
     >>> del sb.schema.classes["YoungAdult"]
+
+    And try a different example - we will try and override the range of the age slot with a string:
+
     >>> _ = sb.add_class("Person2", is_a="Person", slot_usage={"age": {"range": "string"}})
     >>> tr.set_schema(sb.schema)
     >>> try:
@@ -237,8 +302,6 @@ class LogicalModelTransformer(ModelTransformer):
     Attribute Person2.age is unsatisfiable
     <BLANKLINE>
 
-
-
     """
 
     preserve_class_is_a: bool = False
@@ -277,16 +340,24 @@ class LogicalModelTransformer(ModelTransformer):
     a lack of range assignment.
     """
 
-    def transform(self, tgt_schema_name: str = None, simplify=True, **kwargs) -> Any:
+    reason_over_metamodel_slots: Optional[List[str]] = None
+    """
+    If set, only reason over the specified metamodel slots.
+    """
+
+    def transform(self, tgt_schema_name: str = None, simplify=True, force_any_of=False, **kwargs) -> Any:
         """
-        Transform the schema to a logical model, translating inheritance to boolean expressions.
+        Transform the schema using logical reasoning, materializing entailed simple attributes.
 
         :param tgt_schema_name:
         :param simplify: If True (default), simplify the schema after transformation
+        :param force_any_of: If True, force the use of any_of expressions for range, even for singletons
         :return:
         """
         sv = self.schemaview
-        target_schema = deepcopy(self.source_schema)
+        target_schemaview = SchemaView(deepcopy(self.source_schema))
+        target_schemaview.merge_imports()
+        target_schema = target_schemaview.schema
         for tn, typ in target_schema.types.items():
             ancs = sv.type_ancestors(tn, reflexive=False)
             logging.debug(f"Unrolling type {tn}, merging {len(ancs)}")
@@ -312,7 +383,7 @@ class LogicalModelTransformer(ModelTransformer):
             self._roll_down(target_schema, cn, ancs)
         self.apply_defaults(target_schema)
         if simplify:
-            self.simplify(target_schema)
+            self.simplify(target_schema, force_any_of=force_any_of)
         if self.tidy_slots:
             target_schema.slots = {}
         if self.tidy_inheritance:
@@ -366,7 +437,8 @@ class LogicalModelTransformer(ModelTransformer):
         :return:
         """
         new_slot_dict = {}
-        for p in HERITABLE_METASLOT:
+        heritable_metaslots = self.reason_over_metamodel_slots or HERITABLE_METASLOT
+        for p in heritable_metaslots:
             pv = getattr(source, p)
             if pv is not None and pv != [] and pv != {} and pv is not False:
                 new_slot_dict[p] = pv
@@ -377,7 +449,7 @@ class LogicalModelTransformer(ModelTransformer):
         sv = self.schemaview
         if source.range in sv.all_types():
             typ = sv.get_type(source.range)
-            for p in set(HERITABLE_TYPE_METASLOT).intersection(HERITABLE_METASLOT):
+            for p in set(HERITABLE_TYPE_METASLOT).intersection(heritable_metaslots):
                 pv = getattr(typ, p)
                 if pv is not None and pv != [] and pv != {} and pv is not False:
                     new_slot_dict[p] = pv
@@ -395,6 +467,9 @@ class LogicalModelTransformer(ModelTransformer):
         """
         new_slot_dict = {}
         for p in HERITABLE_TYPE_METASLOT:
+            if p in ["repr"]:
+                # not on anonymous types
+                continue
             pv = getattr(source, p)
             if pv is not None and pv != [] and pv != {} and pv is not False:
                 new_slot_dict[p] = pv
@@ -431,7 +506,7 @@ class LogicalModelTransformer(ModelTransformer):
         for sx in att.all_of + att.exactly_one_of + att.none_of + att.any_of:
             yield from self._collection_slot_expressions(sx, filter_function)
 
-    def simplify(self, target_schema: SchemaDefinition):
+    def simplify(self, target_schema: SchemaDefinition, force_any_of=False):
         for cls in target_schema.classes.values():
             for att in cls.attributes.values():
                 x = self._as_logical_expression(att)
@@ -441,6 +516,9 @@ class LogicalModelTransformer(ModelTransformer):
                 if logictools.is_contradiction(x):
                     raise UnsatisfiableAttribute(f"Attribute {cls.name}.{att.name} is unsatisfiable")
                 self._simplify_member_ofs(x)
+                if force_any_of:
+                    if not isinstance(x, logictools.Or):
+                        x = logictools.Or(x)
                 logger.debug(f"Simplified member of: {x}")
                 simplified_att = self._from_logical_expression(x)
                 for k, v in simplified_att.__dict__.items():
@@ -524,6 +602,10 @@ class LogicalModelTransformer(ModelTransformer):
     def _value_var(self) -> logictools.Variable:
         return logictools.Variable("value")
 
+    @property
+    def _length_var(self) -> logictools.Variable:
+        return logictools.Variable("length")
+
     @property
     def _type_var(self) -> logictools.Variable:
         return logictools.Variable("type")
@@ -535,10 +617,15 @@ class LogicalModelTransformer(ModelTransformer):
         exprs = []
         value_var = self._value_var
         type_var = self._type_var
+        length_var = self._length_var
         if slot_expression.minimum_value is not None:
             exprs.append(value_var >= slot_expression.minimum_value)
         if slot_expression.maximum_value is not None:
             exprs.append(value_var <= slot_expression.maximum_value)
+        if slot_expression.minimum_cardinality is not None:
+            exprs.append(length_var >= slot_expression.minimum_cardinality)
+        if slot_expression.maximum_cardinality is not None:
+            exprs.append(length_var <= slot_expression.maximum_cardinality)
         if slot_expression.pattern is not None:
             exprs.append(logictools.Term(MATCHES_PREDICATE, value_var, slot_expression.pattern))
         if slot_expression.range:
@@ -576,6 +663,7 @@ class LogicalModelTransformer(ModelTransformer):
                 "none_of",
                 "any_of",
             ]:
+                # already accounted for
                 continue
             v = getattr(slot_expression, p, None)
             if v is not None and v != [] and v != {}:
@@ -624,6 +712,17 @@ class LogicalModelTransformer(ModelTransformer):
                     return AnonymousSlotExpression(maximum_value=val - 1)
                 else:
                     raise ValueError(f"Unknown predicate {expr.predicate} for {var}")
+            elif var == self._length_var:
+                if expr.predicate == ">=":
+                    return AnonymousSlotExpression(minimum_cardinality=val)
+                elif expr.predicate == ">":
+                    return AnonymousSlotExpression(minimum_cardinality=val + 1)
+                elif expr.predicate == "<=":
+                    return AnonymousSlotExpression(maximum_cardinality=val)
+                elif expr.predicate == "<":
+                    return AnonymousSlotExpression(maximum_cardinality=val - 1)
+                else:
+                    raise ValueError(f"Unknown predicate {expr.predicate} for {var}")
             elif var == self._type_var:
                 if expr.predicate == "in":
                     if val == logictools.UniversalSet():

linkml/utils/converter.py

@@ -24,7 +24,7 @@ from linkml.utils.datautils import (
 )
 
 
-@click.command()
+@click.command(name="convert")
 @click.option("--module", "-m", help="Path to python datamodel module")
 @click.option("--output", "-o", help="Path to output file")
 @click.option(

linkml/utils/execute_tutorial.py

@@ -189,6 +189,8 @@ def parse_file_to_blocks(input) -> List[Block]:
 @click.version_option(__version__, "-V", "--version")
 def cli(inputs, directory):
     """
+    Execute a tutorial markdown file (eg. those in the /docs/intro/ directory) and
+    save the outputs in the given directory
 
     Example:
 

linkml/utils/logictools.py

@@ -1,7 +1,7 @@
 import operator
 from copy import deepcopy
 from itertools import product
-from typing import Any, Collection, List, Optional, Tuple
+from typing import Any, Collection, List, Optional, Tuple, Type
 
 
 def member_of(item: Any, collection: Collection[Any]) -> bool:
@@ -25,6 +25,8 @@ OPS = {
 
 
 class Expression:
+    """Base class for logic expressions"""
+
     def __eq__(self, other: "Expression"):
         if isinstance(other, Expression):
             return self._ordered_str() == other._ordered_str()
@@ -60,6 +62,7 @@ class Expression:
 
     def __contains__(self, other: Any):
         return Term("contains", self, other)
+        return Term("contains", self, other)
 
     def _ordered_str(self, **kwargs):
         return str(self)
@@ -69,6 +72,8 @@ class Expression:
 
 
 class Variable(Expression):
+    """A variable in a logic expression"""
+
     def __init__(self, name: str):
         self.name = name
 
@@ -80,6 +85,8 @@ class Variable(Expression):
 
 
 class Top(Expression):
+    """True expression"""
+
     def __str__(self):
         return "T"
 
@@ -88,6 +95,8 @@ class Top(Expression):
 
 
 class Bottom(Expression):
+    """False expression"""
+
     def __str__(self):
         return "F"
 
@@ -96,6 +105,8 @@ class Bottom(Expression):
 
 
 class Not(Expression):
+    """Negation of an expression"""
+
     def __init__(self, operand: Expression):
         self.operand = operand
 
@@ -107,6 +118,8 @@ class Not(Expression):
 
 
 class And(Expression):
+    """Conjunction of expressions"""
+
     def __init__(self, *operands: Expression):
         self.operands: List[Expression] = list(operands)
 
@@ -306,6 +319,45 @@ def distribute_and_over_or(expr: Expression) -> Expression:
 
 
 def is_contradiction(expr: Expression, apply_dnf=False) -> Optional[bool]:
+    """
+    Check if the given expression is a contradiction.
+
+    >>> a = Variable("a")
+    >>> b = Variable("b")
+    >>> c = Variable("c")
+    >>> d = Variable("d")
+    >>> F = Bottom()
+    >>> T = Top()
+    >>> is_contradiction(T)
+    False
+    >>> is_contradiction(F)
+    True
+    >>> is_contradiction(~T)
+    True
+    >>> is_contradiction(~F)
+    False
+    >>> is_contradiction(~~T)
+    False
+    >>> is_contradiction(~~F)
+    True
+    >>> is_contradiction(F & F)
+    True
+    >>> is_contradiction(F & T)
+    True
+    >>> is_contradiction(F | T)
+    False
+    >>> is_contradiction(a & F )
+    True
+    >>> is_contradiction(a & ~a)
+    True
+    >>> assert is_contradiction(a & T) is None
+    >>> assert is_contradiction(a) is None
+    >>> assert is_contradiction(And(a)) is None
+
+    :param expr:
+    :param apply_dnf:
+    :return:
+    """
     if apply_dnf:
         expr = to_dnf(expr)
         expr = simplify(expr)
@@ -354,6 +406,32 @@ def evals_to_true(expr: Expression, apply_dnf=False) -> Optional[bool]:
     """
     Two-valued logic
 
+    >>> a = Variable("a")
+    >>> b = Variable("b")
+    >>> c = Variable("c")
+    >>> d = Variable("d")
+    >>> F = Bottom()
+    >>> T = Top()
+    >>> evals_to_true(T)
+    True
+    >>> evals_to_true(F)
+    False
+    >>> evals_to_true(~T)
+    False
+    >>> evals_to_true(~F)
+    True
+    >>> evals_to_true(a & b)
+    False
+    >>> evals_to_true(a | b)
+    False
+    >>> evals_to_true(a & a)
+    False
+
+    Note that this does not perform unification, so the following does not evaluate to True
+
+    >>> evals_to_true(a & ~a)
+    False
+
     :param expr:
     :param apply_dnf:
     :return:
@@ -363,7 +441,7 @@ def evals_to_true(expr: Expression, apply_dnf=False) -> Optional[bool]:
     if isinstance(expr, And):
         return all([evals_to_true(operand) for operand in expr.operands])
     elif isinstance(expr, Not):
-        if is_contradiction(expr.operand) is False:
+        if is_contradiction(expr.operand) is True:
             return True
         else:
             return False
@@ -378,32 +456,6 @@ def evals_to_true(expr: Expression, apply_dnf=False) -> Optional[bool]:
         return False
 
 
-def is_tautology(expr):
-    """
-    Checks if the given propositional logic formula is a tautology.
-
-    A formula is a tautology if it is true under every possible valuation of its variables.
-
-    Args:
-        expr (Expression): The input formula which is an instance of Expression or its subclasses.
-
-    Returns:
-        bool: True if the formula is a tautology, False otherwise.
-    """
-    if isinstance(expr, Or):
-        for i in range(len(expr.operands)):
-            for j in range(i + 1, len(expr.operands)):
-                if isinstance(expr.operands[i], Not) and expr.operands[i].operand == expr.operands[j]:
-                    return True
-                elif isinstance(expr.operands[j], Not) and expr.operands[j].operand == expr.operands[i]:
-                    return True
-    elif isinstance(expr, And):
-        for operand in expr.operands:
-            if is_tautology(operand):
-                return True
-    return False
-
-
 def eliminate_redundant(expr: Expression) -> Expression:
     if isinstance(expr, And):
         visited = set()
@@ -444,6 +496,23 @@ def simplify(expr: Expression) -> Expression:
     """
     Simplifies the given propositional logic formula.
 
+    >>> a = Variable("a")
+    >>> b = Variable("b")
+    >>> c = Variable("c")
+    >>> d = Variable("d")
+    >>> simplify(a & b)
+    (a & b)
+    >>> simplify(a | b)
+    (a | b)
+    >>> simplify(a & a)
+    a
+    >>> simplify(a | a)
+    a
+    >>> simplify(a & ~a)
+    F
+    >>> simplify(a | ~a)
+    T
+
     :param expr:
     :return:
     """
@@ -521,6 +590,30 @@ COMPOSITIONS = {
 
 
 def _unsat(x: Expression, y: Expression) -> bool:
+    """
+    Check if two terms are unsatisfiable when combined.
+
+    >>> a = Variable("a")
+    >>> b = Variable("b")
+    >>> _unsat( a < b, a > b)
+    True
+    >>> _unsat( a < b, a < b)
+    False
+    >>> _unsat( a <= b, b >= a)
+    False
+    >>> _unsat( a < b, a <= b)
+    False
+    >>> _unsat( a < b, b <= a)
+    False
+    >>> _unsat( IsIn(a, [1, 2]), IsIn(a, [2, 3]))
+    False
+    >>> _unsat( IsIn(a, [1, 2]), IsIn(a, [3, 4]))
+    True
+
+    :param x:
+    :param y:
+    :return:
+    """
     if isinstance(x, Term) and isinstance(y, Term):
         if x.operands[0] == y.operands[0]:
             xp = x.predicate
@@ -547,7 +640,27 @@ def _unsat(x: Expression, y: Expression) -> bool:
     return False
 
 
-def compose_operators(boolean_op, op1, v1, op2, v2) -> Optional[Tuple]:
+def compose_operators(boolean_op: Type[Expression], op1: str, v1: Any, op2: str, v2: Any) -> Optional[Tuple]:
+    """
+    Compose two expressions.
+
+    >>> assert compose_operators(And, '<', 1, '<', 2) == (operator.__lt__, 1)
+    >>> assert compose_operators(Or, '<', 1, '<', 2) == (operator.__lt__, 2)
+    >>> assert compose_operators(Or, '=', 1, '=', 2) is None
+    >>> assert compose_operators(And, '=', 1, '=', 2) is None
+    >>> assert compose_operators(And, "in", [1, 2], "in", [2, 3]) == (member_of, [2])
+    >>> assert compose_operators(Or, "in", [1, 2], "in", [2, 3]) == (member_of, [1, 2, 3])
+    >>> assert compose_operators(And, "in", [1], "in", [3]) == (member_of, [])
+    >>> assert compose_operators(And, "in", [1], "in", UniversalSet()) == (member_of, [1])
+    >>> assert compose_operators(Or, "in", [1], "in", UniversalSet()) == (member_of, UniversalSet())
+
+    :param boolean_op:
+    :param op1:
+    :param v1:
+    :param op2:
+    :param v2:
+    :return: New expression OR None if the expressions cannot be reduced
+    """
     rev_op_map = {v: k for k, v in OPS.items()}
     if not (op1 in rev_op_map and op2 in rev_op_map):
         return None

linkml/utils/schema_builder.py

@@ -101,12 +101,13 @@ class SchemaBuilder:
                     for k, v in slots.items():
                         cls.slots.append(k)
                         self.add_slot(SlotDefinition(k, **v), replace_if_present=replace_if_present)
-                for s in slots:
-                    cls.slots.append(s.name if isinstance(s, SlotDefinition) else s)
-                    if isinstance(s, str) and s in self.schema.slots:
-                        # top-level slot already exists
-                        continue
-                    self.add_slot(s, replace_if_present=replace_if_present)
+                else:
+                    for s in slots:
+                        cls.slots.append(s.name if isinstance(s, SlotDefinition) else s)
+                        if isinstance(s, str) and s in self.schema.slots:
+                            # top-level slot already exists
+                            continue
+                        self.add_slot(s, replace_if_present=replace_if_present)
             if slot_usage:
                 if isinstance(slot_usage, dict):
                     for k, v in slot_usage.items():

linkml/utils/schema_fixer.py

@@ -382,7 +382,7 @@ class SchemaFixer:
         return schema
 
 
-@click.group()
+@click.group(name="fix")
 @click.option("-v", "--verbose", count=True)
 @click.option("-q", "--quiet")
 def main(verbose: int, quiet: bool):

linkml/utils/sqlutils.py

@@ -270,7 +270,7 @@ class SQLStore:
             return obj
 
 
-@click.group()
+@click.group(name="sqldb")
 @click.option("-v", "--verbose", count=True)
 @click.option("-q", "--quiet")
 @click.option(

linkml/validator/cli.py

@@ -64,7 +64,7 @@ def _resolve_loaders(loader_config: Iterable[Union[str, Dict[str, Dict[str, str]
 DEPRECATED = "[DEPRECATED: only used in legacy mode]"
 
 
-@click.command()
+@click.command(name="validate")
 @click.option(
     "-s",
     "--schema",
@@ -132,6 +132,9 @@ def cli(
     include_range_class_descendants: bool,
     include_context: bool,
 ):
+    """
+    Validate data according to a LinkML Schema
+    """
     if legacy_mode:
         from linkml.validators import jsonschemavalidator
 

linkml/validators/jsonschemavalidator.py

@@ -114,7 +114,7 @@ class JsonSchemaDataValidator(DataValidator):
             yield f"{best_error.message} in {best_error.json_path}"
 
 
-@click.command()
+@click.command(name="jsonschema")
 @click.option("--module", "-m", help="Path to python datamodel module")
 @click.option(
     "--input-format",

linkml/validators/sparqlvalidator.py

@@ -85,7 +85,7 @@ class SparqlDataValidator(DataValidator):
         return self.schema
 
 
-@click.command()
+@click.command(name="sparql")
 @click.option("--named-graph", "-G", multiple=True, help="Constrain query to a named graph")
 @click.option("--input", "-i", help="Input file to validate")
 @click.option("--endpoint-url", "-U", help="URL of sparql endpoint")

linkml/workspaces/example_runner.py

@@ -255,7 +255,7 @@ class ExampleRunner:
             return dict_obj
 
 
-@click.command()
+@click.command(name="examples")
 @click.option("--schema", "-s", required=True, help="Path to linkml schema yaml file")
 @click.option("--prefixes", "-P", help="Path to prefixes")
 @click.option("--input-directory", "-e", help="folder containing positive examples that MUST pass validation")