ConceptFlow

ConceptFlow is a Python library for Formal Concept Analysis (FCA) that fits into the scientific Python stack. Its machine-learning parts are proper scikit-learn estimators that pass scikit-learn's estimator checks.

pip install conceptflow

Requires Python 3.12 or newer.

Example

import conceptflow as cf
from conceptflow.algorithms import compute_canonical_basis

# Each object has either all three attributes or exactly one.
ctx = cf.FormalContext.from_array(
    [[1, 1, 1], [1, 0, 0], [0, 1, 0], [0, 0, 1]],
    objects=["g1", "g2", "g3", "g4"],
    attributes=["a", "b", "c"],
)

lattice = cf.ConceptLattice.from_context(ctx)
print(lattice.n_concepts)  # 5

for implication in compute_canonical_basis(ctx):
    print(implication.premise_names(ctx), "->", implication.conclusion_names(ctx))
# ('a', 'b') -> ('c',)
# ('a', 'c') -> ('b',)
# ('b', 'c') -> ('a',)

fig = cf.plot_lattice(lattice, backend="matplotlib", layout="layered")
fig.savefig("lattice.png")  # backend="tikz" gives LaTeX code instead

Features

• Formal contexts: building and editing, clarification and reduction, apposition, subposition, direct sum and product; .cxt, JSON (FCART/fcapy) and CSV files; incomplete (yes/no/unknown) contexts.
• Concept lattices: NextClosure and Close-by-One on bitsets, iceberg lattices, navigation (join, meet, up-sets, object and attribute concepts), explicit opt-in limits for very large lattices.
• Implications and rules: canonical (Duquenne-Guigues) basis with LinCbO, proper-premise basis, near-implications with exceptions (Luxenburger basis), minimal generators.
• Measures: stability (exact and bounds), Δ-measure, entropy, information gain; lattice width, height, incomparable pairs, linearity and distributivity indices.
• Scale-measures: coarser views of a context from attribute projections and conjunctions, their verification, and refinement pairs.
• Conceptual scaling of many-valued data with seven scale types and explicit missing-value handling.
• scikit-learn: scaling, concept and implication features, and an outlier detector that explains its decisions with implications.
• Visualization: interactive HTML, DimFlux and layered layouts, matplotlib, Graphviz and TikZ/LaTeX export; Toscana-style nested line diagrams; 14 drawing quality metrics (crossings, layering, slopes, clearance).
• Data quality: rule violations, redundant objects and attributes, explanations of objects and rules.
• Factorization: Boolean matrix factorization (GreConD, ASSO) as scikit-learn transformers; ordinal two-factorization.
• Datasets: the 20 contexts of the FCA repository (bundled), the UCI Mushroom data and random contexts.

Documentation

The documentation is at conceptflow.readthedocs.io:

• Getting started
• User guide: contexts, lattices, implications, measures, scaling, scikit-learn, visualization, nested diagrams, data quality, factorization, datasets
• API reference
• Benchmarks against fcapy and concepts
• Changelog

The sources are in docs/.

To build the documentation site locally (with the API reference):

pip install -e ".[docs]"
mkdocs serve

Runnable examples, including a full case study, are in examples/.

Citing and contributing

If you use ConceptFlow in your research, please cite it; see CITATION.cff (or GitHub's "Cite this repository" button). Questions, bug reports and contributions are welcome; see CONTRIBUTING.md.

License

BSD 3-Clause; see LICENSE. Lattice layouts use DimFlux (the dim-flux package, CC BY 4.0), installed automatically.