tigerdatalab 3.0.4__py3-none-any.whl

tigerdatalab/__init__.py

@@ -0,0 +1,17 @@
+"""TigerDataLab — an automated Data Analytics + Data Quality + Visualization
++ BI + DataOps layer on top of pandas, numpy, duckdb and plotly.
+
+    import tigerdatalab as tdl
+    result = tdl.analyze("sales.xlsx")
+    print(result.summary())
+    result.report("analysis")
+"""
+from .config import __version__
+from .core import AnalysisResult, analyze, open, large, profile, quality_check, clean_file
+from .exceptions import TigerDataLabError, UnsupportedFileTypeError, NoTrendDataError, NoCustomerIdentifierError
+
+__all__ = [
+    "__version__", "AnalysisResult", "analyze", "open", "large",
+    "profile", "quality_check", "clean_file",
+    "TigerDataLabError", "UnsupportedFileTypeError", "NoTrendDataError", "NoCustomerIdentifierError",
+]

tigerdatalab/analytics/category.py

@@ -0,0 +1,38 @@
+"""Category-level analytics + Pareto data for chart engine."""
+from __future__ import annotations
+
+import pandas as pd
+
+
+def analyze_categories(df: pd.DataFrame, semantics: dict) -> dict:
+    category_col = semantics.get("category")
+    if not category_col or category_col not in df.columns:
+        return {"available": False, "reason": "No category/segment column was detected."}
+
+    revenue_col = semantics.get("revenue")
+    profit_col = semantics.get("profit")
+
+    grouped = df.groupby(category_col)
+    result: dict = {"available": True, "category_column": category_col, "unique_categories": int(df[category_col].nunique())}
+
+    if revenue_col and revenue_col in df.columns:
+        rev = grouped[revenue_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum()).sort_values(ascending=False)
+        total = rev.sum()
+        result["revenue_by_category"] = [{"category": str(k), "revenue": float(v),
+                                           "share_pct": round(float(100 * v / total), 2) if total else 0}
+                                          for k, v in rev.items()]
+        if total:
+            result["top_category_revenue_share_pct"] = round(float(100 * rev.iloc[0] / total), 2)
+            result["top_category"] = str(rev.index[0])
+
+    if profit_col and profit_col in df.columns:
+        profit = grouped[profit_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum()).sort_values(ascending=False)
+        result["profit_by_category"] = [{"category": str(k), "profit": float(v)} for k, v in profit.items()]
+        if revenue_col and revenue_col in df.columns:
+            rev_by_cat = grouped[revenue_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum())
+            margin = (profit / rev_by_cat.reindex(profit.index) * 100).round(2)
+            margin_sorted = margin.sort_values()
+            result["worst_margin_category"] = str(margin_sorted.index[0]) if len(margin_sorted) else None
+            result["margin_by_category"] = [{"category": str(k), "margin_pct": float(v)} for k, v in margin.items() if pd.notna(v)]
+
+    return result

tigerdatalab/analytics/customer.py

@@ -0,0 +1,51 @@
+"""Customer-level analytics. Raises NoCustomerIdentifierError when no
+customer identifier column was detected, rather than inventing numbers."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ..exceptions import NoCustomerIdentifierError
+
+
+def analyze_customers(df: pd.DataFrame, semantics: dict) -> dict:
+    customer_col = semantics.get("customer")
+    if not customer_col or customer_col not in df.columns:
+        raise NoCustomerIdentifierError()
+
+    revenue_col = semantics.get("revenue")
+    profit_col = semantics.get("profit")
+    order_col = semantics.get("order")
+
+    grouped = df.groupby(customer_col)
+    n_customers = int(df[customer_col].nunique())
+
+    result: dict = {"customer_column": customer_col, "unique_customers": n_customers}
+
+    if order_col and order_col in df.columns:
+        orders_per_customer = grouped[order_col].nunique()
+        result["avg_orders_per_customer"] = round(float(orders_per_customer.mean()), 2)
+        result["repeat_customers"] = int((orders_per_customer > 1).sum())
+        result["one_time_customers"] = int((orders_per_customer == 1).sum())
+    else:
+        orders_per_customer = grouped.size()
+        result["avg_orders_per_customer"] = round(float(orders_per_customer.mean()), 2)
+        result["repeat_customers"] = int((orders_per_customer > 1).sum())
+        result["one_time_customers"] = int((orders_per_customer == 1).sum())
+
+    if revenue_col and revenue_col in df.columns:
+        rev_by_customer = grouped[revenue_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum())
+        total_rev = rev_by_customer.sum()
+        result["avg_revenue_per_customer"] = round(float(rev_by_customer.mean()), 2)
+        top = rev_by_customer.sort_values(ascending=False).head(10)
+        result["top_customers"] = [{"customer": str(k), "revenue": float(v)} for k, v in top.items()]
+        bottom = rev_by_customer.sort_values(ascending=True).head(10)
+        result["bottom_customers"] = [{"customer": str(k), "revenue": float(v)} for k, v in bottom.items()]
+        if total_rev:
+            top5_share = top.head(5).sum() / total_rev * 100
+            result["top5_revenue_concentration_pct"] = round(float(top5_share), 2)
+
+    if profit_col and profit_col in df.columns:
+        profit_by_customer = grouped[profit_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum())
+        result["avg_profit_per_customer"] = round(float(profit_by_customer.mean()), 2)
+
+    return result

tigerdatalab/analytics/growth.py

@@ -0,0 +1,86 @@
+"""Growth/decline detection per product and per category.
+
+Splits the dataset's date range into an earlier half and a later half,
+compares the chosen metric (revenue by default) per group, and tags each
+group as growing / declining / flat. Requires a date column; degrades to
+`{"available": False, ...}` when one isn't present rather than crashing.
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from ..quality.types import parse_date_column
+
+FLAT_BAND_PCT = 5.0
+
+
+def _growth_by_group(df: pd.DataFrame, group_col: str, date_col: str, metric_col: str) -> dict:
+    dates = parse_date_column(df[date_col])
+    metric = pd.to_numeric(df[metric_col], errors="coerce")
+    work = pd.DataFrame({"group": df[group_col], "date": dates, "value": metric}).dropna()
+    if work.empty or work["date"].nunique() < 2:
+        return {"available": False, "reason": "Not enough valid date-tagged rows to compute growth."}
+
+    midpoint = work["date"].min() + (work["date"].max() - work["date"].min()) / 2
+    first_half = work[work["date"] <= midpoint].groupby("group")["value"].sum()
+    second_half = work[work["date"] > midpoint].groupby("group")["value"].sum()
+
+    all_groups = set(first_half.index) | set(second_half.index)
+    rows = []
+    for g in all_groups:
+        f = float(first_half.get(g, 0.0))
+        s = float(second_half.get(g, 0.0))
+        if f == 0 and s == 0:
+            continue
+        if f == 0:
+            change_pct = 100.0 if s > 0 else 0.0
+        else:
+            change_pct = round(100 * (s - f) / abs(f), 2)
+        if change_pct > FLAT_BAND_PCT:
+            status = "growing"
+        elif change_pct < -FLAT_BAND_PCT:
+            status = "declining"
+        else:
+            status = "flat"
+        rows.append({"group": str(g), "first_half": round(f, 2), "second_half": round(s, 2),
+                      "change_pct": change_pct, "status": status})
+
+    rows.sort(key=lambda r: r["change_pct"])
+    growing = [r for r in rows if r["status"] == "growing"]
+    declining = [r for r in rows if r["status"] == "declining"]
+
+    return {
+        "available": True,
+        "group_column": group_col,
+        "metric_column": metric_col,
+        "split_date": midpoint.strftime("%Y-%m-%d"),
+        "growing": sorted(growing, key=lambda r: -r["change_pct"])[:10],
+        "declining": declining[:10],
+        "all": rows,
+    }
+
+
+def analyze_growth(df: pd.DataFrame, semantics: dict) -> dict:
+    date_col = semantics.get("date")
+    metric_col = semantics.get("revenue") or semantics.get("profit") or semantics.get("quantity")
+    result = {"product": {"available": False}, "category": {"available": False}}
+
+    if not date_col or not metric_col:
+        result["product"] = {"available": False, "reason": "No date + numeric metric available for growth analysis."}
+        result["category"] = result["product"]
+        return result
+
+    product_col = semantics.get("product")
+    category_col = semantics.get("category")
+
+    if product_col and product_col in df.columns:
+        result["product"] = _growth_by_group(df, product_col, date_col, metric_col)
+    else:
+        result["product"] = {"available": False, "reason": "No product column detected."}
+
+    if category_col and category_col in df.columns:
+        result["category"] = _growth_by_group(df, category_col, date_col, metric_col)
+    else:
+        result["category"] = {"available": False, "reason": "No category column detected."}
+
+    return result

tigerdatalab/analytics/kpi.py

@@ -0,0 +1,66 @@
+"""Business KPI calculation from detected semantic columns."""
+from __future__ import annotations
+
+import pandas as pd
+
+
+def calculate_kpis(df: pd.DataFrame, semantics: dict) -> dict:
+    kpis: dict = {}
+
+    def col(concept):
+        c = semantics.get(concept)
+        return pd.to_numeric(df[c], errors="coerce") if c and c in df.columns else None
+
+    revenue = col("revenue")
+    cost = col("cost")
+    profit = col("profit")
+    quantity = col("quantity")
+    discount = col("discount")
+
+    if revenue is not None:
+        kpis["total_revenue"] = float(revenue.sum())
+        kpis["average_selling_price"] = float(revenue.mean())
+
+    if cost is not None:
+        kpis["total_cost"] = float(cost.sum())
+
+    if profit is None and revenue is not None and cost is not None:
+        profit = revenue - cost
+        kpis["profit_derived"] = True
+
+    if profit is not None:
+        kpis["total_profit"] = float(profit.sum())
+        if revenue is not None and revenue.sum() != 0:
+            kpis["profit_margin_pct"] = round(100 * profit.sum() / revenue.sum(), 2)
+
+    if quantity is not None:
+        kpis["total_quantity"] = float(quantity.sum())
+        if revenue is not None and quantity.sum() != 0:
+            kpis["average_selling_price"] = round(float(revenue.sum() / quantity.sum()), 2)
+
+    order_col = semantics.get("order")
+    if order_col and order_col in df.columns:
+        n_orders = int(df[order_col].nunique())
+        kpis["orders"] = n_orders
+        if revenue is not None and n_orders:
+            kpis["average_order_value"] = round(float(revenue.sum() / n_orders), 2)
+    else:
+        kpis["orders"] = int(len(df))
+        if revenue is not None and len(df):
+            kpis["average_order_value"] = round(float(revenue.sum() / len(df)), 2)
+
+    customer_col = semantics.get("customer")
+    if customer_col and customer_col in df.columns:
+        kpis["customers"] = int(df[customer_col].nunique())
+
+    product_col = semantics.get("product")
+    if product_col and product_col in df.columns:
+        kpis["products"] = int(df[product_col].nunique())
+
+    if discount is not None:
+        kpis["average_discount_pct"] = round(float(discount.mean()), 2)
+        if revenue is not None and revenue.sum() != 0:
+            kpis["total_discount_value"] = round(float((revenue * discount / 100).sum()), 2) \
+                if discount.max() <= 1.5 * 100 and discount.max() > 1 else None
+
+    return kpis

tigerdatalab/analytics/product.py

@@ -0,0 +1,40 @@
+"""Product-level analytics."""
+from __future__ import annotations
+
+import pandas as pd
+
+
+def analyze_products(df: pd.DataFrame, semantics: dict) -> dict:
+    product_col = semantics.get("product")
+    if not product_col or product_col not in df.columns:
+        return {"available": False, "reason": "No product identifier/name column was detected."}
+
+    revenue_col = semantics.get("revenue")
+    profit_col = semantics.get("profit")
+    quantity_col = semantics.get("quantity")
+    discount_col = semantics.get("discount")
+
+    grouped = df.groupby(product_col)
+    result: dict = {"available": True, "product_column": product_col, "unique_products": int(df[product_col].nunique())}
+
+    if revenue_col and revenue_col in df.columns:
+        rev = grouped[revenue_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum()).sort_values(ascending=False)
+        result["top_products_by_revenue"] = [{"product": str(k), "revenue": float(v)} for k, v in rev.head(10).items()]
+
+    if quantity_col and quantity_col in df.columns:
+        qty = grouped[quantity_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum()).sort_values(ascending=False)
+        result["top_products_by_quantity"] = [{"product": str(k), "quantity": float(v)} for k, v in qty.head(10).items()]
+
+    if profit_col and profit_col in df.columns:
+        profit = grouped[profit_col].apply(lambda s: pd.to_numeric(s, errors="coerce").sum()).sort_values(ascending=False)
+        result["top_products_by_profit"] = [{"product": str(k), "profit": float(v)} for k, v in profit.head(10).items()]
+        result["worst_products_by_profit"] = [{"product": str(k), "profit": float(v)} for k, v in profit.tail(10).items()]
+        negative = profit[profit < 0]
+        result["loss_making_products"] = [{"product": str(k), "profit": float(v)} for k, v in negative.items()]
+        result["loss_making_product_count"] = int(len(negative))
+
+    if discount_col and discount_col in df.columns:
+        disc = grouped[discount_col].apply(lambda s: pd.to_numeric(s, errors="coerce").mean()).sort_values(ascending=False)
+        result["highest_discount_products"] = [{"product": str(k), "avg_discount": float(v)} for k, v in disc.head(10).items()]
+
+    return result

tigerdatalab/analytics/profitability.py

@@ -0,0 +1,24 @@
+"""Profitability derivation: profit = revenue - cost when profit is absent."""
+from __future__ import annotations
+
+import pandas as pd
+
+
+def ensure_profit_column(df: pd.DataFrame, semantics: dict) -> tuple[pd.DataFrame, dict, bool]:
+    """Return (df, semantics, derived) - adds a `_tdl_profit` column and
+    registers it under semantics['profit'] only if profit is not already
+    present but revenue and cost both are. Never overwrites an existing
+    business column."""
+    if semantics.get("profit"):
+        return df, semantics, False
+
+    revenue_col = semantics.get("revenue")
+    cost_col = semantics.get("cost")
+    if revenue_col and cost_col and revenue_col in df.columns and cost_col in df.columns:
+        out = df.copy()
+        out["_tdl_profit"] = pd.to_numeric(out[revenue_col], errors="coerce") - pd.to_numeric(out[cost_col], errors="coerce")
+        new_semantics = dict(semantics)
+        new_semantics["profit"] = "_tdl_profit"
+        return out, new_semantics, True
+
+    return df, semantics, False

tigerdatalab/analytics/trends.py

@@ -0,0 +1,79 @@
+"""Time-trend analysis: monthly/daily aggregation, MoM, YoY, rolling avg."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ..exceptions import NoTrendDataError
+from ..quality.types import parse_date_column, numeric_columns, detect_all_dtypes
+
+
+def _pick_metric(df: pd.DataFrame, semantics: dict) -> str | None:
+    for concept in ("revenue", "profit", "cost", "quantity"):
+        col = semantics.get(concept)
+        if col and col in df.columns:
+            return col
+    numeric = numeric_columns(df)
+    return numeric[0] if numeric else None
+
+
+def compute_trend(df: pd.DataFrame, semantics: dict) -> dict:
+    date_col = semantics.get("date")
+    if not date_col or date_col not in df.columns:
+        raise NoTrendDataError(candidates=[])
+
+    metric_col = _pick_metric(df, semantics)
+    if not metric_col:
+        raise NoTrendDataError(candidates=[date_col])
+
+    dates = parse_date_column(df[date_col])
+    metric = pd.to_numeric(df[metric_col], errors="coerce")
+    work = pd.DataFrame({"date": dates, "value": metric}).dropna()
+
+    if work.empty or work["date"].nunique() < 2:
+        raise NoTrendDataError(candidates=[date_col])
+
+    span_days = (work["date"].max() - work["date"].min()).days
+    freq = "D" if span_days <= 62 else "M"
+
+    work = work.set_index("date").sort_index()
+    if freq == "D":
+        agg = work["value"].resample("D").sum()
+        granularity = "daily"
+    else:
+        agg = work["value"].resample("ME").sum()
+        granularity = "monthly"
+
+    agg = agg[agg.index.notna()]
+    result_df = agg.reset_index()
+    result_df.columns = ["period", "value"]
+
+    growth_pct = None
+    if len(agg) >= 2 and agg.iloc[0] != 0:
+        growth_pct = round(100 * (agg.iloc[-1] - agg.iloc[0]) / abs(agg.iloc[0]), 2)
+
+    mom_pct = None
+    if len(agg) >= 2 and agg.iloc[-2] != 0:
+        mom_pct = round(100 * (agg.iloc[-1] - agg.iloc[-2]) / abs(agg.iloc[-2]), 2)
+
+    yoy_pct = None
+    if granularity == "monthly" and len(agg) >= 13 and agg.iloc[-13] != 0:
+        yoy_pct = round(100 * (agg.iloc[-1] - agg.iloc[-13]) / abs(agg.iloc[-13]), 2)
+
+    rolling = agg.rolling(window=3, min_periods=1).mean()
+
+    label = {"revenue": "Revenue", "profit": "Profit", "cost": "Cost", "quantity": "Quantity"}
+    metric_label = next((v for k, v in label.items() if semantics.get(k) == metric_col), metric_col)
+
+    return {
+        "date_column": date_col,
+        "metric_column": metric_col,
+        "metric_label": metric_label,
+        "granularity": granularity,
+        "title": f"{granularity.capitalize()} {metric_label} Trend",
+        "periods": [p.strftime("%Y-%m-%d") for p in result_df["period"]],
+        "values": [float(v) for v in result_df["value"]],
+        "rolling_average": [float(v) for v in rolling.values],
+        "growth_pct": growth_pct,
+        "mom_pct": mom_pct,
+        "yoy_pct": yoy_pct,
+    }

tigerdatalab/cli/main.py

@@ -0,0 +1,77 @@
+"""TigerDataLab command-line interface.
+
+    tigerdatalab analyze sales.csv
+    tigerdatalab dashboard sales.csv
+    tigerdatalab profile sales.csv
+    tigerdatalab quality sales.csv
+    tigerdatalab clean sales.csv
+    tigerdatalab report sales.csv
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .. import core
+from ..exceptions import TigerDataLabError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="tigerdatalab", description="TigerDataLab CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_analyze = sub.add_parser("analyze", help="Run full analysis and print summary")
+    p_analyze.add_argument("path")
+
+    p_dash = sub.add_parser("dashboard", help="Generate the interactive dashboard")
+    p_dash.add_argument("path")
+    p_dash.add_argument("-o", "--output", default="analysis/dashboard.html")
+
+    p_profile = sub.add_parser("profile", help="Print a data profile")
+    p_profile.add_argument("path")
+
+    p_quality = sub.add_parser("quality", help="Print a data quality report")
+    p_quality.add_argument("path")
+
+    p_clean = sub.add_parser("clean", help="Clean and export the dataset")
+    p_clean.add_argument("path")
+    p_clean.add_argument("-o", "--output", default="cleaned_data.xlsx")
+
+    p_report = sub.add_parser("report", help="Generate the full report bundle")
+    p_report.add_argument("path")
+    p_report.add_argument("-o", "--output", default="analysis")
+
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "analyze":
+            core.analyze(args.path, verbose=True)
+        elif args.command == "dashboard":
+            result = core.analyze(args.path, verbose=False)
+            out = result.dashboard(args.output)
+            print(f"Dashboard written to: {out}")
+        elif args.command == "profile":
+            import json
+            print(json.dumps(core.profile(args.path), indent=2, default=str))
+        elif args.command == "quality":
+            import json
+            print(json.dumps(core.quality_check(args.path), indent=2, default=str))
+        elif args.command == "clean":
+            from ..reporting.exporters import save_cleaned_excel
+            df = core.clean_file(args.path)
+            out = save_cleaned_excel(args.output, df)
+            print(f"Cleaned data written to: {out}")
+        elif args.command == "report":
+            result = core.analyze(args.path, verbose=True)
+            outputs = result.report(args.output)
+            print("\nGenerated files:")
+            for k, v in outputs.items():
+                print(f"  {k}: {v}")
+        return 0
+    except TigerDataLabError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tigerdatalab/config.py

@@ -0,0 +1,47 @@
+"""Global configuration and constants for TigerDataLab."""
+from __future__ import annotations
+
+__version__ = "3.0.4"
+
+SUPPORTED_EXTENSIONS = [".csv", ".xlsx", ".xlsm", ".json", ".parquet", ".sql", ".db", ".sqlite", ".duckdb"]
+
+# Row-count thresholds used to decide small / medium / large execution strategy.
+SMALL_DATA_ROW_LIMIT = 100_000
+MEDIUM_DATA_ROW_LIMIT = 5_000_000
+
+# SQL keywords that TigerDataLab will never auto-execute.
+DESTRUCTIVE_SQL_KEYWORDS = ["DROP", "TRUNCATE", "DELETE", "ALTER"]
+
+# Semantic keyword dictionaries used by the column-semantics detector.
+# Each business concept maps to a list of substrings matched against
+# lower-cased, underscore/space-normalized column names.
+SEMANTIC_KEYWORDS: dict[str, list[str]] = {
+    "revenue": ["revenue", "sales_amount", "sales", "amount", "gmv", "turnover",
+                "net_sales", "total_sales", "grand_total", "line_total",
+                "sale_amount", "total_amount", "order_value", "order_total",
+                "net_amount", "gross_sales", "sales_value"],
+    "profit": ["profit", "net_profit", "gross_profit", "profit_amount", "margin_amount",
+               "net_income", "earnings", "profit_value"],
+    "cost": ["cost", "cogs", "cost_price", "purchase_cost", "unit_cost",
+             "cost_amount", "buying_price", "purchase_price", "cogs_amount"],
+    "quantity": ["quantity", "qty", "units", "units_sold", "unit_count",
+                 "qty_sold", "no_of_units", "units_purchased", "order_qty"],
+    "customer": ["customer_id", "customer", "buyer_id", "buyer", "client_id", "user_id",
+                 "cust_id", "member_id", "account_id", "customer_name", "client_name"],
+    "product": ["product_id", "product_name", "product", "item", "sku", "item_name", "name",
+                "product_title", "item_code", "product_code"],
+    "category": ["category", "segment", "department", "product_category", "product_type",
+                 "sub_category", "subcategory", "product_group"],
+    "date": ["date", "order_date", "transaction_date", "created_at", "timestamp", "order_time",
+             "invoice_date", "order_dt", "txn_date", "purchase_date", "created_date", "datetime"],
+    "discount": ["discount_pct", "discount_percent", "discount", "disc_pct", "disc_percent"],
+    "order": ["order_id", "transaction_id", "invoice_id", "invoice_no", "order_no",
+              "order_number", "txn_id", "receipt_no", "receipt_id", "bill_no", "bill_id"],
+    "price": ["unit_price", "selling_price", "price", "rate", "mrp", "list_price",
+              "retail_price", "sale_price"],
+}
+
+# Keys checked in priority order (more specific first) to avoid, e.g.,
+# "cost_price" being tagged as "price" instead of "cost".
+SEMANTIC_PRIORITY = ["order", "customer", "product", "category", "date",
+                      "discount", "cost", "profit", "revenue", "quantity", "price"]