cbrkit 0.3.2__tar.gz → 0.4.0__tar.gz

{cbrkit-0.3.2 → cbrkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cbrkit
-Version: 0.3.2
+Version: 0.4.0
 Summary: Customizable Case-Based Reasoning (CBR) toolkit for Python with a built-in API and CLI.
 Home-page: https://wi2trier.github.io/cbrkit/
 License: MIT
@@ -135,10 +135,10 @@ queries = cbrkit.loaders.dataframe(pd.read_csv("path/to/queries.csv"))
 queries = cbrkit.loaders.json("path/to/queries.json")
 ```
 
-In case your query collection only contains a single query, you can use the `singleton` function to extract it.
+In case your query collection only contains a single entry, you can use the `singleton` function to extract it.
 
 ```python
-query = cbrkit.singleton(queries)
+query = cbrkit.helpers.singleton(queries)
 ```
 
 Alternatively, you can also create a query directly in Python:

{cbrkit-0.3.2 → cbrkit-0.4.0}/README.md

@@ -86,10 +86,10 @@ queries = cbrkit.loaders.dataframe(pd.read_csv("path/to/queries.csv"))
 queries = cbrkit.loaders.json("path/to/queries.json")
 ```
 
-In case your query collection only contains a single query, you can use the `singleton` function to extract it.
+In case your query collection only contains a single entry, you can use the `singleton` function to extract it.
 
 ```python
-query = cbrkit.singleton(queries)
+query = cbrkit.helpers.singleton(queries)
 ```
 
 Alternatively, you can also create a query directly in Python:

{cbrkit-0.3.2 → cbrkit-0.4.0}/cbrkit/sim/numeric.py

@@ -15,9 +15,11 @@ def linear(max: float, min: float = 0.0) -> SimPairFunc[Number, float]:
         min: Minimum bound of the interval
 
     ![linear](../../assets/numeric/linear.png)
-    >>> sim = linear(100)
-    >>> sim(50, 60)
-    0.9
+
+    Examples:
+        >>> sim = linear(100)
+        >>> sim(50, 60)
+        0.9
     """
 
     def wrapped_func(x: Number, y: Number) -> float:
@@ -40,6 +42,7 @@ def threshold(threshold: float) -> SimPairFunc[Number, float]:
         threshold: If the absolute difference between the two values is less than or equal to this value, the similarity is 1.0, otherwise it is 0.0
 
     ![threshold](../../assets/numeric/threshold.png)
+
     Examples:
         >>> sim = threshold(10)
         >>> sim(50, 60)
@@ -61,6 +64,7 @@ def exponential(alpha: float = 1.0) -> SimPairFunc[Number, float]:
         alpha: Controls the growth of the exponential function for the similarity. The larger alpha is, the faster the similarity decreases.
 
     ![exponential](../../assets/numeric/exponential.png)
+
     Examples:
         >>> sim = exponential(0.1)
         >>> sim(50, 60)
@@ -81,6 +85,7 @@ def sigmoid(alpha: float = 1.0, theta: float = 1.0) -> SimPairFunc[Number, float
         theta: Specifies the point at which the similarity value is 0.5.
 
     ![sigmoid](../../assets/numeric/sigmoid.png)
+
     Examples:
         >>> sim = sigmoid(1, 10)
         >>> sim(50, 60)

cbrkit-0.4.0/cbrkit/sim/taxonomy.py

@@ -0,0 +1,328 @@
+from dataclasses import dataclass, field
+from typing import Literal, Optional, Protocol, TypedDict, cast
+
+from cbrkit.loaders import data as load_data
+from cbrkit.typing import FilePath, SimPairFunc
+
+__all__ = [
+    "Taxonomy",
+    "TaxonomyNode",
+    "TaxonomyFunc",
+    "TaxonomyStrategy",
+    "load",
+    "wu_palmer",
+    "user_weights",
+    "auto_weights",
+    "node_levels",
+    "path_steps",
+]
+
+
+class SerializedNode(TypedDict, total=False):
+    name: str
+    weight: float
+    children: list["SerializedNode | str"]
+
+
+@dataclass(slots=True)
+class TaxonomyNode:
+    name: str
+    weight: float
+    depth: int
+    parent: Optional["TaxonomyNode"]
+    children: dict[str, "TaxonomyNode"] = field(default_factory=dict)
+
+    @property
+    def level(self) -> int:
+        return self.depth + 1
+
+
+class Taxonomy:
+    __slots__ = ("root", "nodes")
+
+    root: TaxonomyNode
+    nodes: dict[str, TaxonomyNode]
+
+    def __init__(self, path: FilePath) -> None:
+        root_data = cast(SerializedNode, load_data(path))
+        self.nodes = {}
+        self.root = self._load(root_data)
+
+    @property
+    def max_depth(self) -> int:
+        return max(node.depth for node in self.nodes.values())
+
+    @property
+    def max_level(self) -> int:
+        return max(node.level for node in self.nodes.values())
+
+    def _load(
+        self,
+        data: SerializedNode | str,
+        parent: TaxonomyNode | None = None,
+        depth: int = 0,
+    ) -> TaxonomyNode:
+        if isinstance(data, str):
+            data = {"name": data}
+
+        assert "name" in data, "Missing name in some node"
+
+        node = TaxonomyNode(
+            name=data["name"],
+            weight=data.get("weight", 1.0),
+            depth=depth,
+            parent=parent,
+        )
+
+        for child in data.get("children", []):
+            child_node = self._load(child, node, depth + 1)
+            node.children[child_node.name] = child_node
+
+        self.nodes[node.name] = node
+
+        return node
+
+    def lca(self, node1: TaxonomyNode, node2: TaxonomyNode) -> TaxonomyNode:
+        while node1 != node2:
+            if node1.parent is None or node2.parent is None:
+                return self.root
+
+            if node1.depth > node2.depth:
+                node1 = node1.parent
+            else:
+                node2 = node2.parent
+
+        return node1
+
+
+class TaxonomyFunc(Protocol):
+    def __call__(self, taxonomy: Taxonomy, x: str, y: str) -> float:
+        ...
+
+
+TaxonomyStrategy = Literal["optimistic", "pessimistic", "average"]
+
+
+def wu_palmer() -> TaxonomyFunc:
+    """Wu & Palmer similarity measure of two nodes in a taxonomy.
+
+    Examples:
+        >>> taxonomy = Taxonomy("./data/cars-taxonomy.yaml")
+        >>> sim = wu_palmer()
+        >>> sim(taxonomy, "audi", "porsche")
+        0.5
+        >>> sim(taxonomy, "audi", "bmw")
+        0.0
+    """
+
+    def wrapped_func(taxonomy: Taxonomy, x: str, y: str) -> float:
+        node1 = taxonomy.nodes[x]
+        node2 = taxonomy.nodes[y]
+        lca = taxonomy.lca(node1, node2)
+
+        return (2 * lca.depth) / (node1.depth + node2.depth)
+
+    return wrapped_func
+
+
+def user_weights(strategy: TaxonomyStrategy) -> TaxonomyFunc:
+    """User-defined weights similarity measure of two nodes in a taxonomy.
+
+    The weights are defined by the user in the taxonomy file.
+
+    Args:
+        strategy: The strategy to use in case one of the node is the lowest common ancestor (lca).
+            One of "optimistic", "pessimistic", or "average".
+
+    ![user weights](../../assets/taxonomy/user-weights.png)
+
+    Examples:
+        >>> taxonomy = Taxonomy("./data/cars-taxonomy.yaml")
+        >>> sim = user_weights("optimistic")
+        >>> sim(taxonomy, "audi", "Volkswagen AG")
+        1.0
+        >>> sim(taxonomy, "audi", "bmw")
+        0.0
+    """
+
+    def wrapped_func(taxonomy: Taxonomy, x: str, y: str) -> float:
+        node1 = taxonomy.nodes[x]
+        node2 = taxonomy.nodes[y]
+        lca = taxonomy.lca(node1, node2)
+        weight = lca.weight
+
+        if lca == node1 or lca == node2:
+            # pessimistic not needed: weight of lca already used
+            if strategy == "optimistic":
+                weight = 1.0
+            elif strategy == "average":
+                weight = (node1.weight + node2.weight) / 2
+
+        return weight
+
+    return wrapped_func
+
+
+def auto_weights(strategy: TaxonomyStrategy) -> TaxonomyFunc:
+    """Automatic weights similarity measure of two nodes in a taxonomy.
+
+    The weights are automatically calculated based on the depth of the nodes.
+
+    Args:
+        strategy: The strategy to use in case one of the node is the lowest common ancestor (lca).
+            One of "optimistic", "pessimistic", or "average".
+
+    ![auto weights](../../assets/taxonomy/auto-weights.png)
+
+    Examples:
+        >>> taxonomy = Taxonomy("./data/cars-taxonomy.yaml")
+        >>> sim = auto_weights("optimistic")
+        >>> sim(taxonomy, "audi", "Volkswagen AG")
+        1.0
+        >>> sim(taxonomy, "audi", "bmw")
+        0.0
+    """
+
+    def wrapped_func(taxonomy: Taxonomy, x: str, y: str) -> float:
+        node1 = taxonomy.nodes[x]
+        node2 = taxonomy.nodes[y]
+        lca = taxonomy.lca(node1, node2)
+        max_depth = taxonomy.max_depth
+
+        weight = lca.depth / max_depth
+
+        if lca == node1 or lca == node2:
+            # pessimistic not needed: weight of lca already used
+            if strategy == "optimistic":
+                weight = 1.0
+            elif strategy == "average":
+                weight1 = node1.depth / max_depth
+                weight2 = node2.depth / max_depth
+                weight = (weight1 + weight2) / 2
+
+        return weight
+
+    return wrapped_func
+
+
+def node_levels(strategy: TaxonomyStrategy) -> TaxonomyFunc:
+    """Node levels similarity measure of two nodes in a taxonomy.
+
+    The similarity is calculated based on the levels of the nodes.
+
+    Args:
+        strategy: The strategy to use in case one of the node is the lowest common ancestor (lca).
+            One of "optimistic", "pessimistic", or "average".
+
+    ![node levels](../../assets/taxonomy/node-levels.png)
+
+    Examples:
+        >>> taxonomy = Taxonomy("./data/cars-taxonomy.yaml")
+        >>> sim = node_levels("optimistic")
+        >>> sim(taxonomy, "audi", "Volkswagen AG")
+        1.0
+        >>> sim(taxonomy, "audi", "bmw")
+        0.3333333333333333
+    """
+
+    def wrapped_func(taxonomy: Taxonomy, x: str, y: str) -> float:
+        node1 = taxonomy.nodes[x]
+        node2 = taxonomy.nodes[y]
+        lca = taxonomy.lca(node1, node2)
+
+        if strategy == "optimistic":
+            return lca.level / min(node1.level, node2.level)
+        elif strategy == "pessimistic":
+            return lca.level / max(node1.level, node2.level)
+        elif strategy == "average":
+            return lca.level / ((node1.level + node2.level) / 2)
+        else:
+            return 0.0
+
+    return wrapped_func
+
+
+def path_steps(weightUp: float = 1.0, weightDown: float = 1.0) -> TaxonomyFunc:
+    """Path steps similarity measure of two nodes in a taxonomy.
+
+    The similarity is calculated based on the steps up and down from the lowest common ancestor (lca).
+
+    Args:
+        weightUp: The weight to use for the steps up.
+        weightDown: The weight to use for the steps down.
+
+    ![path steps](../../assets/taxonomy/path-steps.png)
+
+    Examples:
+        >>> taxonomy = Taxonomy("./data/cars-taxonomy.yaml")
+        >>> sim = path_steps()
+        >>> sim(taxonomy, "audi", "Volkswagen AG")
+        0.8333333333333334
+        >>> sim(taxonomy, "audi", "bmw")
+        0.3333333333333333
+    """
+
+    def wrapped_func(taxonomy: Taxonomy, x: str, y: str) -> float:
+        node1 = taxonomy.nodes[x]
+        node2 = taxonomy.nodes[y]
+        lca = taxonomy.lca(node1, node2)
+
+        stepsUp = node1.depth - lca.depth
+        stepsDown = node2.depth - lca.depth
+
+        weightedSteps = (stepsUp * weightUp) + (stepsDown * weightDown)
+        maxWeightedSteps = (taxonomy.max_depth * weightUp) + (
+            taxonomy.max_depth * weightDown
+        )
+
+        return (maxWeightedSteps - weightedSteps) / maxWeightedSteps
+
+    return wrapped_func
+
+
+_taxonomy_func = wu_palmer()
+
+
+def load(
+    path: FilePath, measure: TaxonomyFunc = _taxonomy_func
+) -> SimPairFunc[str, float]:
+    """Load a taxonomy and return a function that measures the similarity.
+
+    The taxonomy is loaded from the given path and expected to conform to the following structure:
+
+    ```yaml
+    name: ROOT
+    weight: 0.0
+    children:
+      - name: CHILD1
+        weight: 0.4
+        children:
+          - name: GRANDCHILD1
+            weight: 0.8
+            children:
+              - name: GREATGRANDCHILD1
+              - name: GREATGRANDCHILD2
+          - name: GRANDCHILD2
+      - name: CHILD2
+        weight: 0.6
+        children: []
+    ```
+
+    The `name` field is required for each node, and the `children` field is optional.
+    The `weight` field is optional and can be used to assign a weight/similarity value to the node.
+    If not set, the default value is 1.0.
+    The `weight` is only used by the measure `user_weights` and ignored otherwise.
+
+    Examples:
+        >>> sim = load("./data/cars-taxonomy.yaml", measure=wu_palmer())
+        >>> sim("audi", "porsche")
+        0.5
+        >>> sim("audi", "bmw")
+        0.0
+    """
+    taxonomy = Taxonomy(path)
+
+    def wrapped_func(x: str, y: str) -> float:
+        return measure(taxonomy, x, y)
+
+    return wrapped_func

{cbrkit-0.3.2 → cbrkit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cbrkit"
-version = "0.3.2"
+version = "0.4.0"
 description = "Customizable Case-Based Reasoning (CBR) toolkit for Python with a built-in API and CLI."
 authors = ["Mirko Lenz <mirko@mirkolenz.com>"]
 license = "MIT"

cbrkit-0.3.2/cbrkit/sim/taxonomy.py

@@ -1,118 +0,0 @@
-from dataclasses import dataclass, field
-from typing import Optional, Protocol, TypedDict, cast
-
-from cbrkit.loaders import data as load_data
-from cbrkit.typing import FilePath, SimPairFunc
-
-__all__ = ["Taxonomy", "TaxonomyNode", "TaxonomyFunc", "load", "wu_palmer"]
-
-
-class SerializedNode(TypedDict, total=False):
-    key: str
-    sim: float
-    children: list["SerializedNode | str"]
-
-
-@dataclass(slots=True)
-class TaxonomyNode:
-    key: str
-    weight: float | None
-    depth: int
-    parent: Optional["TaxonomyNode"]
-    children: dict[str, "TaxonomyNode"] = field(default_factory=dict)
-
-
-class Taxonomy:
-    __slots__ = ("root", "nodes")
-
-    root: TaxonomyNode
-    nodes: dict[str, TaxonomyNode]
-
-    def __init__(self, path: FilePath) -> None:
-        root_data = cast(SerializedNode, load_data(path))
-        self.nodes = {}
-        self.root = self._load(root_data)
-
-    def _load(
-        self,
-        data: SerializedNode | str,
-        parent: TaxonomyNode | None = None,
-        depth: int = 0,
-    ) -> TaxonomyNode:
-        if isinstance(data, str):
-            data = {"key": data}
-
-        assert "key" in data, "Missing key in some node"
-
-        node = TaxonomyNode(
-            key=data["key"],
-            weight=data.get("weight"),
-            depth=depth,
-            parent=parent,
-        )
-
-        for child in data.get("children", []):
-            child_node = self._load(child, node, depth + 1)
-            node.children[child_node.key] = child_node
-
-        self.nodes[node.key] = node
-
-        return node
-
-    def lca(self, node1: TaxonomyNode, node2: TaxonomyNode) -> TaxonomyNode:
-        while node1 != node2:
-            if node1.parent is None or node2.parent is None:
-                return self.root
-
-            if node1.depth > node2.depth:
-                node1 = node1.parent
-            else:
-                node2 = node2.parent
-
-        return node1
-
-
-class TaxonomyFunc(Protocol):
-    def __call__(self, taxonomy: Taxonomy, x: str, y: str) -> float:
-        ...
-
-
-def wu_palmer() -> TaxonomyFunc:
-    """Wu & Palmer similarity measure of two nodes in a taxonomy.
-    >>> taxonomy = Taxonomy("./data/cars-taxonomy.yaml")
-    >>> sim = wu_palmer()
-    >>> sim(taxonomy, "audi", "porsche")
-    0.5
-    >>> sim(taxonomy, "audi", "bmw")
-    0.0
-    """
-
-    def wrapped_func(taxonomy: Taxonomy, x: str, y: str) -> float:
-        node1 = taxonomy.nodes[x]
-        node2 = taxonomy.nodes[y]
-        lca = taxonomy.lca(node1, node2)
-
-        return (2 * lca.depth) / (node1.depth + node2.depth)
-
-    return wrapped_func
-
-
-_taxonomy_func = wu_palmer()
-
-
-def load(
-    path: FilePath, measure: TaxonomyFunc = _taxonomy_func
-) -> SimPairFunc[str, float]:
-    """Load a taxonomy and return a function that measures the similarity.
-    >>> sim = load("./data/cars-taxonomy.yaml", measure=wu_palmer())
-    >>> sim("audi", "porsche")
-    0.5
-    >>> sim("audi", "bmw")
-    0.0
-    """
-    taxonomy = Taxonomy(path)
-
-    def wrapped_func(x: str, y: str) -> float:
-        return measure(taxonomy, x, y)
-
-    return wrapped_func