fuzzylinguistics 0.2.3

A Python library for generating and simplifying fuzzy linguistic summaries of data.

FuzzyLinguistics

A powerful and flexible Python library for generating and simplifying fuzzy linguistic summaries of data. Turn complex datasets into human-readable, natural language insights.

This library implements a complete system for creating summaries of one or two datasets (e.g., comparing models), evaluating their truth and quality, and simplifying them from thousands of potential statements into a handful of concise, meaningful insights.

Key Features

• Generate Summaries: Create summaries for single datasets or compare two datasets against each other.
• Flexible Configuration: Define your linguistic variables programmatically in Python or through a clean JSON interface.
• Powerful Simplification: A multi-stage graph-based algorithm prunes and combines thousands of raw statements into a coherent, high-level summary.
• Quality Metrics: Evaluates summaries based on truth, focus, simplicity, and relevance.
• Visualization: Includes tools to plot membership functions and export the summary graph for analysis.

Installation

Install fuzzylinguistics directly from PyPI:

pip install fuzzylinguistics

GPU Acceleration

fuzzylinguistics uses compute_backend="auto" by default. If a compatible CuPy/CUDA install is available, large numeric operations can run on the GPU; otherwise the package falls back to NumPy on CPU.

CuPy wheels are CUDA-version-specific, so GPU support is provided through optional install extras:

# CUDA 13
pip install "fuzzylinguistics[gpu-cuda13]"

# CUDA 12
pip install "fuzzylinguistics[gpu-cuda12]"

You can force a backend when generating summaries:

fls.generate_fls_one_model(
    results_dir="./results",
    compute_backend="numpy",  # or "auto" / "cupy"
)

For larger datasets, generation now uses bounded batches internally. You can lower max_working_memory_mb, force statement_batch_size, or opt into graph exports with save_simplification_graph_gexf=True. GEXF graph files are disabled by default because graph export can dominate runtime for wide datasets.

Quick Start

The easiest way to get started is with a JSON configuration file.

1. Create your configuration file (config.json)

This file defines your data, linguistic variables (summarizers, qualifiers), and quantifiers.

{
    "datasets": [
        {
            "category_name": "Cars",
            "model_name": "Car Example",
            "uses_qualifier": true,
            "input_dimension_labels": ["color"],
            "input_dimension_units": [null],
            "input_data": [
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [1]
            ],
            "output_dimension_labels": ["speed"],
            "output_dimension_units": [null],
            "output_data": [
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [0],
                [1]
            ]
        }
    ],
    "summarizers": [
        {
            "dimension_name": "color",
            "predicates": ["Red", "Green", "Blue"],
            "trapezoidal_x_vals": [
                [0, 0, 0, 0],
                [0.5, 0.5, 0.5, 0.5],
                [1, 1, 1, 1]
            ],
            "relevancy_weights": [1, 1, 1]
        }
    ],
    "qualifiers": [
        {
            "dimension_name": "speed",
            "predicates": ["Slow", "Normal", "Fast"],
            "trapezoidal_x_vals": [
                [0, 0, 0, 0],
                [0.5, 0.5, 0.5, 0.5],
                [1, 1, 1, 1]
            ],
            "relevancy_weights": [1, 1, 1]
        }
    ],
    "quantifiers": {
        "dimension_name": "quantifier",
        "predicates": ["None", "None", "A Few", "Some", "Many", "All"],
        "trapezoidal_x_vals": [
            [null, null, null, null],
            [0, 0, 0, 0],
            [0.00001, 0.00001, 0.00001, 0.5],
            [0.0, 0.5, 0.5, 0.99999],
            [0.5, 0.99999, 0.99999, 0.99999],
            [1, 1, 1, 1]
        ],
        "relevancy_weights": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
    }
}

2. Run the summarization in Python

# main.py
from fuzzylinguistics import setup_fls

# 1. Setup the system from the config file
fls = setup_fls(config_json_path="config.json")

# 2. Generate and simplify the summary
# Results will be saved to the specified directory
fls.generate_fls_one_model(results_dir='./car_summary_results')

# 3. Print the final, simplified summary
print("--- Final Simplified Summary ---")
for statement in fls.results["simplified_stage_4_summary"]:
    print(statement)

Example Output:

--- Final Simplified Summary ---
None are green color or normal speed.
Of the cars with blue color none are slow speed, and all are fast speed.
Of the cars with red color none are fast speed, and all are slow speed.

Examples

For more detailed examples, including how to compare two models and how to set up the system programmatically without JSON, please see the /examples directory in the project repository.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.