cbrkit 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cbrkit
-Version: 0.3.1
+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
@@ -104,7 +104,7 @@ The following modules are part of CBRkit:
 CBRkit is fully typed, so IDEs like VSCode and PyCharm can provide autocompletion and type checking.
 We will explain all modules and their basic usage in the following sections.
 
-### Loading Cases
+### Loading Cases and Queries
 
 The first step is to load cases and queries.
 We provide predefined functions for the most common formats like CSV, JSON, and XML.
@@ -119,9 +119,36 @@ df = pd.read_csv("path/to/cases.csv")
 cases = cbrkit.loaders.dataframe(df)
 ```
 
-Queries can either be loaded using the same loader functions or constructed manually.
+When dealing with formats like JSON, the files can be loaded directly:
 
 ```python
+cases = cbrkit.loaders.json("path/to/cases.json")
+```
+
+Queries can either be loaded using the same loader functions.
+CBRkit expects the type of the queries to match the type of the cases.
+
+```python
+ # for pandas
 queries = cbrkit.loaders.dataframe(pd.read_csv("path/to/queries.csv"))
+# for json
+queries = cbrkit.loaders.json("path/to/queries.json")
 ```
 
+In case your query collection only contains a single entry, you can use the `singleton` function to extract it.
+
+```python
+query = cbrkit.helpers.singleton(queries)
+```
+
+Alternatively, you can also create a query directly in Python:
+
+```python
+# for pandas
+query = pd.Series({"name": "John", "age": 25})
+# for json
+query = {"name": "John", "age": 25}
+```
+
+### Similarity Measures and Aggregation
+

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

@@ -55,7 +55,7 @@ The following modules are part of CBRkit:
 CBRkit is fully typed, so IDEs like VSCode and PyCharm can provide autocompletion and type checking.
 We will explain all modules and their basic usage in the following sections.
 
-### Loading Cases
+### Loading Cases and Queries
 
 The first step is to load cases and queries.
 We provide predefined functions for the most common formats like CSV, JSON, and XML.
@@ -70,8 +70,35 @@ df = pd.read_csv("path/to/cases.csv")
 cases = cbrkit.loaders.dataframe(df)
 ```
 
-Queries can either be loaded using the same loader functions or constructed manually.
+When dealing with formats like JSON, the files can be loaded directly:
 
 ```python
+cases = cbrkit.loaders.json("path/to/cases.json")
+```
+
+Queries can either be loaded using the same loader functions.
+CBRkit expects the type of the queries to match the type of the cases.
+
+```python
+ # for pandas
 queries = cbrkit.loaders.dataframe(pd.read_csv("path/to/queries.csv"))
+# for json
+queries = cbrkit.loaders.json("path/to/queries.json")
 ```
+
+In case your query collection only contains a single entry, you can use the `singleton` function to extract it.
+
+```python
+query = cbrkit.helpers.singleton(queries)
+```
+
+Alternatively, you can also create a query directly in Python:
+
+```python
+# for pandas
+query = pd.Series({"name": "John", "age": 25})
+# for json
+query = {"name": "John", "age": 25}
+```
+
+### Similarity Measures and Aggregation

{cbrkit-0.3.1 → cbrkit-0.4.0}/cbrkit/__init__.py

@@ -5,12 +5,14 @@
 
 """
 
-from . import global_sim, loaders, retrieval, sim, typing
 
-__all__ = (
+from . import global_sim, helpers, loaders, retrieval, sim, typing
+
+__all__ = [
     "loaders",
     "sim",
     "global_sim",
     "typing",
     "retrieval",
-)
+    "helpers",
+]

{cbrkit-0.3.1 → cbrkit-0.4.0}/cbrkit/global_sim/_aggregate.py

@@ -2,7 +2,7 @@ import statistics
 from collections.abc import Mapping, Sequence
 from typing import Literal
 
-from cbrkit.sim._helpers import unpack_sim
+from cbrkit.helpers import unpack_sim
 from cbrkit.typing import (
     AggregatorFunc,
     AnyFloat,

{cbrkit-0.3.1 → cbrkit-0.4.0}/cbrkit/global_sim/_attribute_value.py

@@ -5,7 +5,7 @@ from typing import Any, Generic
 
 import pandas as pd
 
-from cbrkit.sim import sim2map
+from cbrkit.helpers import sim2map
 from cbrkit.typing import (
     AggregatorFunc,
     AnySimFunc,

{cbrkit-0.3.1 → cbrkit-0.4.0}/cbrkit/global_sim/graph/_astar.py

@@ -16,7 +16,7 @@ from cbrkit.global_sim.graph._model import (
     NodeData,
     NodeKey,
 )
-from cbrkit.sim._helpers import unpack_sims
+from cbrkit.helpers import unpack_sims
 from cbrkit.typing import Casebase, FloatProtocol, KeyType, SimPairFunc, SimType
 
 logger = logging.getLogger(__name__)

cbrkit-0.3.1/cbrkit/sim/_helpers.py → cbrkit-0.4.0/cbrkit/helpers.py

@@ -1,5 +1,5 @@
 from abc import ABC
-from collections.abc import Iterable, Mapping, Sequence
+from collections.abc import Collection, Iterable, Mapping, Sequence
 from inspect import signature as inspect_signature
 from typing import Any, cast
 
@@ -22,9 +22,41 @@ __all__ = [
     "unpack_sim",
     "unpack_sims",
     "AbstractFloat",
+    "singleton",
 ]
 
 
+def singleton(x: Mapping[Any, ValueType] | Collection[ValueType]) -> ValueType:
+    """
+    Return the only element of the input, or raise an error if there are multiple elements.
+
+    Args:
+        x: The input collection or mapping.
+
+    Returns:
+        The only element of the input.
+
+    Examples:
+        >>> singleton([1])
+        1
+        >>> singleton({1: "a"})
+        'a'
+
+    Raises:
+        ValueError: If the input has more than one element.
+        TypeError: If the input is not a collection or mapping.
+    """
+    if len(x) != 1:
+        raise ValueError(f"Expected exactly one element, but got {len(x)}")
+
+    if isinstance(x, Mapping):
+        return next(iter(x.values()))
+    elif isinstance(x, Collection):
+        return next(iter(x))
+    else:
+        raise TypeError(f"Expected a Mapping or Collection, but got {type(x)}")
+
+
 def dist2sim(distance: float) -> float:
     """Convert a distance to a similarity.
 

{cbrkit-0.3.1 → cbrkit-0.4.0}/cbrkit/retrieval.py

@@ -2,8 +2,8 @@ from collections.abc import Callable, Collection, Mapping, Sequence
 from dataclasses import dataclass
 from typing import Any, Generic
 
+from cbrkit.helpers import sim2map, unpack_sim
 from cbrkit.loaders import python as load_python
-from cbrkit.sim._helpers import sim2map, unpack_sim
 from cbrkit.typing import (
     AnySimFunc,
     Casebase,

cbrkit-0.4.0/cbrkit/sim/__init__.py

@@ -0,0 +1,9 @@
+from . import collections, generic, numeric, strings, taxonomy
+
+__all__ = [
+    "collections",
+    "generic",
+    "numeric",
+    "strings",
+    "taxonomy",
+]

{cbrkit-0.3.1 → cbrkit-0.4.0}/cbrkit/sim/collections.py

@@ -1,7 +1,7 @@
 from collections.abc import Collection, Set
 from typing import Any
 
-from cbrkit.sim._helpers import dist2sim
+from cbrkit.helpers import dist2sim
 from cbrkit.typing import SimPairFunc
 
 __all__ = ["jaccard"]

{cbrkit-0.3.1 → 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.1 → cbrkit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cbrkit"
-version = "0.3.1"
+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.1/cbrkit/sim/__init__.py

@@ -1,16 +0,0 @@
-from . import collections, generic, numeric, strings, taxonomy
-from ._helpers import AbstractFloat, dist2sim, sim2map, sim2seq, unpack_sim, unpack_sims
-
-__all__ = [
-    "collections",
-    "generic",
-    "numeric",
-    "strings",
-    "taxonomy",
-    "dist2sim",
-    "sim2map",
-    "sim2seq",
-    "unpack_sim",
-    "unpack_sims",
-    "AbstractFloat",
-]

cbrkit-0.3.1/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