conceptflow 0.1.0__py3-none-any.whl

conceptflow/__init__.py

@@ -0,0 +1,40 @@
+"""
+ConceptFlow.
+
+A scikit-learn compatible Formal Concept Analysis framework.
+"""
+
+from conceptflow._version import __version__
+from conceptflow.core import (
+    Concept,
+    ConceptLattice,
+    FormalContext,
+    ManyValuedContext,
+)
+from conceptflow.visualization import (
+    GraphData,
+    GraphEdge,
+    GraphNode,
+    lattice_to_graph_data,
+    plot_lattice,
+)
+
+from conceptflow.exploration import (
+    ExplorationBuilder,
+    ExplorationView,
+)
+
+__all__ = [
+    "__version__",
+    "Concept",
+    "FormalContext",
+    "ManyValuedContext",
+    "ConceptLattice",
+    "GraphData",
+    "GraphEdge",
+    "GraphNode",
+    "lattice_to_graph_data",
+    "plot_lattice",
+    "ExplorationBuilder",
+    "ExplorationView",
+]

conceptflow/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

conceptflow/algorithms/__init__.py

@@ -0,0 +1,47 @@
+from conceptflow.algorithms.derivation import (
+    attribute_closure,
+    attribute_derivation,
+    object_derivation,
+)
+from conceptflow.algorithms.enumeration import (
+    enumerate_concepts,
+    enumerate_concepts_bruteforce,
+    enumerate_concepts_nextclosure,
+    enumerate_concepts_closebyone,
+)
+
+from conceptflow.algorithms._registry import (
+    SUPPORTED_ENUMERATION_ALGORITHMS,
+    normalize_enumeration_algorithm,
+)
+
+from conceptflow.algorithms.hasse import compute_hasse_edges, is_cover
+from conceptflow.algorithms.implications import Implication, compute_canonical_basis
+from conceptflow.algorithms.order import strict_subconcept_of, subconcept_of
+
+from conceptflow.algorithms.reduction import (
+    ClarificationResult,
+    clarified_context,
+    clarify_context,
+)
+
+__all__ = [
+    "object_derivation",
+    "attribute_derivation",
+    "attribute_closure",
+    "enumerate_concepts",
+    "enumerate_concepts_bruteforce",
+    "enumerate_concepts_nextclosure",
+    "enumerate_concepts_closebyone",
+    "subconcept_of",
+    "strict_subconcept_of",
+    "is_cover",
+    "compute_hasse_edges",
+    "Implication",
+    "compute_canonical_basis",
+    "SUPPORTED_ENUMERATION_ALGORITHMS",
+    "normalize_enumeration_algorithm",
+    "ClarificationResult",
+    "clarified_context",
+    "clarify_context",
+]

conceptflow/algorithms/_registry.py

@@ -0,0 +1,58 @@
+"""
+Algorithm registry utilities.
+
+This module centralizes algorithm name handling so that public APIs can
+support clean canonical names and optional aliases without duplicating
+string logic across the codebase.
+"""
+
+from __future__ import annotations
+
+
+ENUMERATION_ALGORITHM_ALIASES = {
+    "bruteforce": "bruteforce",
+    "brute_force": "bruteforce",
+    "brute-force": "bruteforce",
+    "nextclosure": "nextclosure",
+    "next_closure": "nextclosure",
+    "next-closure": "nextclosure",
+    "closebyone": "closebyone",
+    "close_by_one": "closebyone",
+    "close-by-one": "closebyone",
+    "cbo": "closebyone",
+}
+
+SUPPORTED_ENUMERATION_ALGORITHMS = frozenset(
+    ENUMERATION_ALGORITHM_ALIASES.values()
+)
+
+
+def normalize_enumeration_algorithm(name: str) -> str:
+    """
+    Normalize a concept enumeration algorithm name.
+
+    Parameters
+    ----------
+    name:
+        User-provided algorithm name.
+
+    Returns
+    -------
+    str
+        Canonical algorithm name.
+
+    Raises
+    ------
+    ValueError
+        If the algorithm is unknown.
+    """
+    normalized = name.lower().strip().replace(" ", "_")
+
+    if normalized not in ENUMERATION_ALGORITHM_ALIASES:
+        supported = ", ".join(sorted(SUPPORTED_ENUMERATION_ALGORITHMS))
+        raise ValueError(
+            f'Unknown concept enumeration algorithm "{name}". '
+            f"Supported algorithms are: {supported}."
+        )
+
+    return ENUMERATION_ALGORITHM_ALIASES[normalized]

conceptflow/algorithms/derivation.py

@@ -0,0 +1,80 @@
+"""
+Derivation and closure operators for Formal Concept Analysis.
+
+This module contains the basic FCA derivation operations.
+
+For a formal context (G, M, I):
+
+- A' is the set of attributes common to all objects in A.
+- B' is the set of objects having all attributes in B.
+- B'' is the closure of B.
+
+The functions in this module operate on FormalContext objects but are kept
+outside the FormalContext class so that algorithms remain reusable and easier
+to optimize later.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+
+from conceptflow.core.context import FormalContext
+
+
+def object_derivation(
+    context: FormalContext,
+    object_indices: Iterable[int],
+) -> frozenset[int]:
+    """
+    Compute A' for a set of object indices A.
+    """
+    object_indices = frozenset(object_indices)
+
+    if not object_indices:
+        return frozenset(range(context.n_attributes))
+
+    for index in object_indices:
+        if index < 0 or index >= context.n_objects:
+            raise IndexError(
+                f"Object index {index} is out of range for a context with "
+                f"{context.n_objects} objects."
+            )
+
+    mask = context.incidence[list(object_indices), :].all(axis=0)
+    return frozenset(np.flatnonzero(mask).tolist())
+
+
+def attribute_derivation(
+    context: FormalContext,
+    attribute_indices: Iterable[int],
+) -> frozenset[int]:
+    """
+    Compute B' for a set of attribute indices B.
+    """
+    attribute_indices = frozenset(attribute_indices)
+
+    if not attribute_indices:
+        return frozenset(range(context.n_objects))
+
+    for index in attribute_indices:
+        if index < 0 or index >= context.n_attributes:
+            raise IndexError(
+                f"Attribute index {index} is out of range for a context with "
+                f"{context.n_attributes} attributes."
+            )
+
+    mask = context.incidence[:, list(attribute_indices)].all(axis=1)
+    return frozenset(np.flatnonzero(mask).tolist())
+
+
+def attribute_closure(
+    context: FormalContext,
+    attribute_indices: Iterable[int],
+) -> frozenset[int]:
+    """
+    Compute B'' for a set of attribute indices B.
+    """
+    extent = attribute_derivation(context, attribute_indices)
+    return object_derivation(context, extent)

conceptflow/algorithms/enumeration.py

@@ -0,0 +1,208 @@
+"""
+Concept enumeration algorithms for ConceptFlow.
+
+This module contains algorithms for enumerating formal concepts from a
+formal context.
+
+Implemented methods:
+
+- brute-force enumeration
+- NextClosure enumeration
+- CloseByOne-style recursive enumeration
+
+The brute-force algorithm is kept as a correctness baseline. NextClosure is
+the first FCA-native enumeration algorithm used by ConceptFlow.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from itertools import chain, combinations
+
+from conceptflow.algorithms._registry import normalize_enumeration_algorithm
+from conceptflow.algorithms.derivation import (
+    attribute_closure,
+    attribute_derivation,
+)
+from conceptflow.core.concept import Concept
+from conceptflow.core.context import FormalContext
+
+
+def powerset(items: Iterable[int]) -> Iterable[tuple[int, ...]]:
+    """
+    Yield all subsets of the given iterable.
+    """
+    items = list(items)
+    return chain.from_iterable(
+        combinations(items, r) for r in range(len(items) + 1)
+    )
+
+
+def enumerate_concepts_bruteforce(context: FormalContext) -> list[Concept]:
+    """
+    Enumerate all formal concepts using brute force.
+
+    This tries every subset of attributes, closes it, and constructs the
+    corresponding concept.
+    """
+    concepts: set[Concept] = set()
+
+    attribute_indices = range(context.n_attributes)
+
+    for subset in powerset(attribute_indices):
+        intent = attribute_closure(context, subset)
+        extent = attribute_derivation(context, intent)
+        concepts.add(Concept(extent=extent, intent=intent))
+
+    return sorted(
+        concepts,
+        key=lambda c: (
+            len(c.extent),
+            sorted(c.extent),
+            sorted(c.intent),
+        ),
+    )
+
+
+def _next_closure_candidate(
+    context: FormalContext,
+    current_intent: frozenset[int],
+    attribute_order: list[int],
+) -> frozenset[int] | None:
+    """
+    Compute the next closed intent after current_intent in lectic order.
+    """
+    index_of = {attribute: i for i, attribute in enumerate(attribute_order)}
+
+    for i in range(len(attribute_order) - 1, -1, -1):
+        attribute = attribute_order[i]
+
+        if attribute in current_intent:
+            continue
+
+        prefix = {a for a in current_intent if index_of[a] < i}
+        candidate_seed = prefix | {attribute}
+        candidate_closure = attribute_closure(context, candidate_seed)
+
+        is_valid = True
+
+        for j in range(i):
+            earlier_attribute = attribute_order[j]
+
+            if (
+                earlier_attribute in candidate_closure
+            ) != (
+                earlier_attribute in current_intent
+            ):
+                is_valid = False
+                break
+
+        if is_valid:
+            return candidate_closure
+
+    return None
+
+
+def enumerate_concepts_nextclosure(context: FormalContext) -> list[Concept]:
+    """
+    Enumerate all formal concepts using the NextClosure algorithm.
+    """
+    concepts: list[Concept] = []
+
+    attribute_order = list(range(context.n_attributes))
+    current_intent: frozenset[int] | None = attribute_closure(context, [])
+
+    while current_intent is not None:
+        extent = attribute_derivation(context, current_intent)
+        concepts.append(Concept(extent=extent, intent=current_intent))
+
+        current_intent = _next_closure_candidate(
+            context=context,
+            current_intent=current_intent,
+            attribute_order=attribute_order,
+        )
+
+    return concepts
+
+def enumerate_concepts_closebyone(context: FormalContext) -> list[Concept]:
+    """
+    Enumerate formal concepts using a simple CloseByOne-style recursion.
+
+    This implementation is intended as a clear baseline implementation of
+    the CloseByOne idea: recursively generate closures and use a canonicity
+    condition to avoid duplicates.
+    """
+    concepts: set[Concept] = set()
+    n_attributes = context.n_attributes
+
+    def is_canonical(
+        current_intent: frozenset[int],
+        candidate_intent: frozenset[int],
+        attribute_index: int,
+    ) -> bool:
+        """
+        Check the CloseByOne canonicity condition.
+
+        A candidate is canonical if no earlier attribute was introduced by
+        the closure unless it was already present in the current intent.
+        """
+        for earlier in range(attribute_index):
+            if earlier in candidate_intent and earlier not in current_intent:
+                return False
+
+        return True
+
+    def recurse(intent: frozenset[int], start_attribute: int) -> None:
+        extent = attribute_derivation(context, intent)
+        concepts.add(Concept(extent=extent, intent=intent))
+
+        for attribute_index in range(start_attribute, n_attributes):
+            if attribute_index in intent:
+                continue
+
+            candidate_seed = intent | {attribute_index}
+            candidate_intent = attribute_closure(context, candidate_seed)
+
+            if is_canonical(
+                current_intent=intent,
+                candidate_intent=candidate_intent,
+                attribute_index=attribute_index,
+            ):
+                recurse(
+                    intent=candidate_intent,
+                    start_attribute=attribute_index + 1,
+                )
+
+    initial_intent = attribute_closure(context, [])
+    recurse(initial_intent, 0)
+
+    return sorted(
+        concepts,
+        key=lambda c: (
+            len(c.extent),
+            sorted(c.extent),
+            sorted(c.intent),
+        ),
+    )
+
+def enumerate_concepts(
+    context: FormalContext,
+    method: str = "nextclosure",
+) -> list[Concept]:
+    """
+    Enumerate concepts using the selected method.
+    """
+    method = normalize_enumeration_algorithm(method)
+
+    if method == "bruteforce":
+        return enumerate_concepts_bruteforce(context)
+
+    if method == "nextclosure":
+        return enumerate_concepts_nextclosure(context)
+
+    if method == "closebyone":
+        return enumerate_concepts_closebyone(context)
+
+    raise RuntimeError(
+        f'Algorithm "{method}" was normalized but has no implementation.'
+    )

conceptflow/algorithms/hasse.py

@@ -0,0 +1,83 @@
+"""
+Hasse diagram / cover relation utilities for concept lattices.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable
+
+from conceptflow.algorithms.order import strict_subconcept_of
+from conceptflow.core.concept import Concept
+
+_HASSE_LARGE_LATTICE_THRESHOLD = 500
+
+
+def is_cover(
+    lower: Concept,
+    upper: Concept,
+    concepts: Iterable[Concept],
+) -> bool:
+    """
+    Return whether ``upper`` covers ``lower``.
+    """
+    concepts = tuple(concepts)
+
+    if not strict_subconcept_of(lower, upper):
+        return False
+
+    for middle in concepts:
+        if middle == lower or middle == upper:
+            continue
+
+        if (
+            strict_subconcept_of(lower, middle)
+            and strict_subconcept_of(middle, upper)
+        ):
+            return False
+
+    return True
+
+
+def compute_hasse_edges(
+    concepts: Iterable[Concept],
+) -> tuple[tuple[Concept, Concept], ...]:
+    """
+    Compute cover edges of a concept lattice.
+
+    Returns
+    -------
+    tuple of tuple
+        Edges as ``(lower, upper)`` pairs.
+    """
+    concepts = tuple(concepts)
+    n = len(concepts)
+
+    if n > _HASSE_LARGE_LATTICE_THRESHOLD:
+        warnings.warn(
+            f"Computing Hasse edges for {n} concepts. "
+            "This may be slow for large lattices.",
+            stacklevel=2,
+        )
+
+    # Precompute strict order as index sets: above[i] holds all j where
+    # concepts[i] < concepts[j]. This avoids O(n) tuple conversion on every
+    # is_cover() call and enables set-difference to find direct covers.
+    above: list[frozenset[int]] = [
+        frozenset(
+            j for j in range(n)
+            if i != j and strict_subconcept_of(concepts[i], concepts[j])
+        )
+        for i in range(n)
+    ]
+
+    edges: list[tuple[Concept, Concept]] = []
+
+    for i in range(n):
+        # Elements above i that are reachable via an intermediate step are
+        # not direct covers. Their union is: ⋃_{j ∈ above[i]} above[j].
+        reachable_via_intermediate = frozenset(k for j in above[i] for k in above[j])
+        for j in above[i] - reachable_via_intermediate:
+            edges.append((concepts[i], concepts[j]))
+
+    return tuple(edges)

conceptflow/algorithms/implications.py

@@ -0,0 +1,150 @@
+"""
+Duquenne-Guigues (stem) basis computation for ConceptFlow.
+
+The canonical basis is the smallest set of implications (attribute-set
+"premise forces conclusion" rules) that is logically equivalent to every
+implication that holds in a formal context. It is built from the context's
+*pseudo-intents*.
+
+Definition (Ganter & Wille, "Formal Concept Analysis", Prop. 2.15)
+-------------------------------------------------------------------
+For a formal context K = (G, M, I) with derivation/closure operator
+``''`` (``attribute_closure``), a set P subseteq M is a **pseudo-intent** if:
+
+1. P'' != P              (P is not itself a concept intent), and
+2. for every pseudo-intent Q that is a *proper subset* of P: Q'' subseteq P.
+
+Condition 2 is recursive, but well-founded: since Q must be strictly
+smaller than P, processing candidate sets in increasing size order (ties
+broken by any fixed rule, here lectic/lexicographic) guarantees every
+pseudo-intent smaller than the current candidate has already been decided
+before it is needed.
+
+The canonical basis is then exactly:
+
+    { P -> (P'' \\ P) : P is a pseudo-intent }
+
+This is the same style of "clear, correct, exponential-worst-case"
+algorithm as ``enumerate_concepts_bruteforce``: it tries every subset of
+attributes (there is no way around this in general -- deciding whether a
+given set is a pseudo-intent is already as hard as the underlying concept
+lattice can be large), but it is straightforward to verify against the
+definition above.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import chain, combinations
+
+from conceptflow.algorithms.derivation import attribute_closure
+from conceptflow.core.context import FormalContext
+
+
+@dataclass(frozen=True)
+class Implication:
+    """
+    A single exact implication premise -> conclusion.
+
+    Parameters
+    ----------
+    premise:
+        Attribute indices forming the "if" side.
+
+    conclusion:
+        Attribute indices forced by the premise, *beyond* the premise
+        itself (i.e. ``conclusion`` and ``premise`` are disjoint).
+    """
+
+    premise: frozenset[int]
+    conclusion: frozenset[int]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "premise", frozenset(self.premise))
+        object.__setattr__(self, "conclusion", frozenset(self.conclusion))
+
+    def premise_names(self, context: FormalContext) -> tuple[str, ...]:
+        """Return the premise as attribute names, in a fixed order."""
+        return tuple(context.attributes[i] for i in sorted(self.premise))
+
+    def conclusion_names(self, context: FormalContext) -> tuple[str, ...]:
+        """Return the conclusion as attribute names, in a fixed order."""
+        return tuple(context.attributes[i] for i in sorted(self.conclusion))
+
+    def __repr__(self) -> str:
+        return (
+            f"Implication(premise={sorted(self.premise)}, "
+            f"conclusion={sorted(self.conclusion)})"
+        )
+
+
+def _powerset(n_attributes: int):
+    """Yield every subset of range(n_attributes), smallest first."""
+    attributes = range(n_attributes)
+    return chain.from_iterable(
+        combinations(attributes, size) for size in range(n_attributes + 1)
+    )
+
+
+def compute_canonical_basis(context: FormalContext) -> list[Implication]:
+    """
+    Compute the Duquenne-Guigues (stem) basis of a formal context.
+
+    Step by step
+    ------------
+    1. Generate every candidate attribute subset, sorted by
+       ``(size, sorted(subset))`` -- smallest first. This order is what
+       makes step 3 well-defined: any pseudo-intent that could matter for
+       a minimality check on the current candidate is strictly smaller,
+       so it was already visited earlier in this same loop.
+    2. Close the candidate with the context's own derivation operator
+       (``attribute_closure``, i.e. B''). If the candidate is already
+       equal to its own closure, it is a genuine concept intent, not a
+       pseudo-intent -- skip it.
+    3. Otherwise, check the minimality condition against every
+       already-found pseudo-intent Q that is a proper subset of this
+       candidate: all of their closures must already fit inside the
+       candidate. If so, the candidate is itself a new pseudo-intent;
+       record it together with its closure.
+    4. Once every candidate has been classified, turn each pseudo-intent
+       P (with closure P'') into one implication P -> (P'' \\ P) -- the
+       attributes P forces *beyond itself*.
+
+    Parameters
+    ----------
+    context:
+        The formal context to compute the basis for.
+
+    Returns
+    -------
+    list[Implication]
+        The canonical basis, ordered by ``(premise size, premise)``.
+    """
+    pseudo_intents: dict[frozenset[int], frozenset[int]] = {}
+
+    for subset in _powerset(context.n_attributes):
+        candidate = frozenset(subset)
+        closure = attribute_closure(context, candidate)
+
+        if closure == candidate:
+            # Already a concept intent -- nothing new to force.
+            continue
+
+        is_minimal = all(
+            known_closure <= candidate
+            for known_premise, known_closure in pseudo_intents.items()
+            if known_premise < candidate
+        )
+
+        if is_minimal:
+            pseudo_intents[candidate] = closure
+
+    ordered_premises = sorted(
+        pseudo_intents,
+        key=lambda premise: (len(premise), sorted(premise)),
+    )
+
+    return [
+        Implication(premise=premise, conclusion=pseudo_intents[premise] - premise)
+        for premise in ordered_premises
+    ]

conceptflow/algorithms/order.py

@@ -0,0 +1,27 @@
+"""
+Order relations for formal concepts.
+"""
+
+from __future__ import annotations
+
+from conceptflow.core.concept import Concept
+
+
+def subconcept_of(lower: Concept, upper: Concept) -> bool:
+    """
+    Return whether ``lower <= upper`` in the concept lattice.
+
+    In FCA:
+
+        lower <= upper iff extent(lower) subseteq extent(upper)
+
+    Equivalently, this is reverse inclusion on intents.
+    """
+    return lower.extent.issubset(upper.extent)
+
+
+def strict_subconcept_of(lower: Concept, upper: Concept) -> bool:
+    """
+    Return whether ``lower < upper`` in the concept lattice.
+    """
+    return lower != upper and subconcept_of(lower, upper)