plotlibs 0.3.0__py3-none-any.whl

plotlibs/colors.py

@@ -0,0 +1,107 @@
+"""plotlibs.colors — fast matplotlib-compatible color parsing."""
+from __future__ import annotations
+
+TABLEAU = {
+    "C0": (31, 119, 180),
+    "C1": (255, 127, 14),
+    "C2": (44, 160, 44),
+    "C3": (214, 39, 40),
+    "C4": (148, 103, 189),
+    "C5": (140, 86, 75),
+    "C6": (227, 119, 194),
+    "C7": (127, 127, 127),
+    "C8": (188, 189, 34),
+    "C9": (23, 190, 207),
+}
+
+NAMED = {
+    "b": (0, 0, 255), "g": (0, 128, 0), "r": (255, 0, 0),
+    "c": (0, 191, 191), "m": (191, 0, 191), "y": (191, 191, 0),
+    "k": (0, 0, 0), "w": (255, 255, 255),
+    "blue": (0, 0, 255), "green": (0, 128, 0), "red": (255, 0, 0),
+    "cyan": (0, 191, 191), "magenta": (191, 0, 191), "yellow": (255, 255, 0),
+    "black": (0, 0, 0), "white": (255, 255, 255),
+    "gray": (128, 128, 128), "grey": (128, 128, 128),
+    "orange": (255, 165, 0), "purple": (128, 0, 128),
+    "brown": (165, 42, 42), "pink": (255, 192, 203),
+    "lime": (0, 255, 0), "navy": (0, 0, 128), "teal": (0, 128, 128),
+    "lightgray": (211, 211, 211), "lightgrey": (211, 211, 211),
+}
+
+BRAND = {
+    # plotlibs visual identity v1 (see assets/logo.svg)
+    "primary": (79, 70, 229),      # #4F46E5 indigo
+    "accent": (6, 182, 212),       # #06B6D4 cyan
+    "ink": (15, 23, 42),           # #0F172A
+    "paper": (248, 250, 252),      # #F8FAFC
+    "lime": (163, 230, 53),        # #A3E635
+    "amber": (250, 204, 21),       # #FACC15
+    "coral": (251, 113, 133),      # #FB7185
+    "violet": (167, 139, 250),     # #A78BFA
+    "sky": (56, 189, 248),         # #38BDF8
+    "slate": (100, 116, 139),      # #64748B
+}
+
+CYCLE = [
+    BRAND["primary"],
+    BRAND["accent"],
+    BRAND["coral"],
+    (34, 197, 94),
+    BRAND["amber"],
+    BRAND["violet"],
+    BRAND["sky"],
+    BRAND["slate"],
+    (244, 114, 182),
+    (45, 212, 191),
+]
+
+
+def to_rgb(color) -> tuple[int, int, int]:
+    """Parse any matplotlib-like color spec to (r, g, b) 0-255."""
+    if color is None:
+        return BRAND["primary"]
+    if isinstance(color, (tuple, list)):
+        vals = list(color)
+        if len(vals) in (3, 4):
+            # float 0-1 or int 0-255 ?
+            if all(isinstance(v, float) or (isinstance(v, int) and False) for v in vals):
+                pass
+            mx = max(vals[:3])
+            if mx <= 1.0 and any(isinstance(v, float) for v in vals):
+                return tuple(int(max(0, min(1, v)) * 255) for v in vals[:3])
+            return tuple(int(max(0, min(255, v))) for v in vals[:3])
+        raise ValueError(f"Bad color tuple {color!r}")
+    if not isinstance(color, str):
+        raise ValueError(f"Bad color {color!r}")
+    c = color.strip()
+    if c in TABLEAU:
+        return TABLEAU[c]
+    if c in NAMED:
+        return NAMED[c]
+    if c.startswith("#"):
+        h = c[1:]
+        if len(h) == 3:
+            h = "".join(ch * 2 for ch in h)
+        if len(h) == 6:
+            return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+        if len(h) == 8:  # #rrggbbaa -> ignore alpha
+            return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+    # gray string like "0.5"
+    try:
+        f = float(c)
+        v = int(max(0.0, min(1.0, f)) * 255)
+        return (v, v, v)
+    except ValueError:
+        pass
+    raise ValueError(f"Unknown color {color!r}")
+
+
+def to_rgba(color, alpha: float | None = None) -> tuple[int, int, int, int]:
+    r, g, b = to_rgb(color)
+    a = 255
+    if isinstance(color, (tuple, list)) and len(color) == 4:
+        v = color[3]
+        a = int(v * 255) if isinstance(v, float) and v <= 1.0 else int(v)
+    if alpha is not None:
+        a = int(max(0.0, min(1.0, float(alpha))) * 255)
+    return (r, g, b, a)

plotlibs/data.py

@@ -0,0 +1,208 @@
+"""plotlibs.data — جسر البيانات: pandas / numpy / csv بدون اعتماديات إجبارية.
+
+الهدف: محلل البيانات يكتب سطرين فقط:
+    import plotlibs as pl
+    df = pl.load_csv("sales.csv")
+    pl.quick_eda(df)
+
+كل الدوال تعمل مع:
+- pandas.DataFrame (إن وُجدت pandas)
+- dict of columns
+- numpy 2D array
+- list of dicts (rows)
+"""
+from __future__ import annotations
+
+import csv
+import math
+
+import numpy as np
+
+
+def _has_pandas() -> bool:
+    try:
+        import pandas  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def to_frame(data):
+    """حوّل أي مصدر شائع إلى pandas.DataFrame إن أمكن، وإلا dict."""
+    if data is None:
+        raise ValueError("data is None")
+    if _has_pandas():
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            return data
+        if isinstance(data, pd.Series):
+            return data.to_frame()
+        if isinstance(data, dict):
+            return pd.DataFrame(data)
+        if isinstance(data, (list, tuple)) and data and isinstance(data[0], dict):
+            return pd.DataFrame(data)
+        arr = np.asarray(data)
+        if arr.ndim == 2:
+            return pd.DataFrame(arr, columns=[f"c{i}" for i in range(arr.shape[1])])
+        return pd.DataFrame({"value": np.asarray(data).ravel()})
+    # بدون pandas: أعد dict من الأعمدة
+    if isinstance(data, dict):
+        return {k: np.asarray(v) for k, v in data.items()}
+    arr = np.asarray(data)
+    if arr.ndim == 2:
+        return {f"c{i}": arr[:, i] for i in range(arr.shape[1])}
+    return {"value": np.asarray(arr).ravel()}
+
+
+def columns_of(data) -> list[str]:
+    if _has_pandas():
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            return list(data.columns.astype(str))
+    if isinstance(data, dict):
+        return list(data.keys())
+    return []
+
+
+def column_values(data, col):
+    """أعد عموداً كـ numpy array نظيف."""
+    if _has_pandas():
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            return pd.to_numeric(data[col], errors="coerce").to_numpy(dtype=float)
+    if isinstance(data, dict):
+        return np.asarray(data[col], dtype=float).ravel()
+    raise KeyError(f"unknown column {col!r}")
+
+
+def numeric_columns(data) -> list[str]:
+    if isinstance(data, dict):
+        out = []
+        for k, v in data.items():
+            try:
+                arr = np.asarray(v)
+                if arr.dtype.kind in "iufb":
+                    out.append(k)
+                    continue
+                # حاول تحويل عينة
+                np.asarray(v, dtype=float)
+                out.append(k)
+            except Exception:
+                pass
+        return out
+    if _has_pandas():
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            return [str(c) for c in data.select_dtypes(include=[np.number]).columns]
+        return []
+    return []
+
+
+def load_csv(path, **kw):
+    """قراءة CSV سريعة — pandas إن وُجدت وإلا csv stdlib."""
+    if _has_pandas():
+        import pandas as pd
+        return pd.read_csv(path, **kw)
+    with open(path, newline="", encoding=kw.get("encoding", "utf-8")) as f:
+        reader = csv.DictReader(f)
+        cols: dict[str, list] = {}
+        for row in reader:
+            for k, v in row.items():
+                cols.setdefault(k, []).append(v)
+        # حاول التحويل لرقمي
+        out: dict[str, np.ndarray] = {}
+        for k, vals in cols.items():
+            try:
+                out[k] = np.array(vals, dtype=float)
+            except Exception:
+                out[k] = np.array(vals)
+        return out
+
+
+def save_csv(data, path, **kw):
+    if _has_pandas():
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            data.to_csv(path, index=kw.get("index", False))
+            return path
+    if isinstance(data, dict):
+        keys = list(data.keys())
+        n = max(len(np.asarray(data[k]).ravel()) for k in keys)
+        with open(path, "w", newline="", encoding="utf-8") as f:
+            w = csv.writer(f)
+            w.writerow(keys)
+            for i in range(n):
+                row = []
+                for k in keys:
+                    col = np.asarray(data[k]).ravel()
+                    row.append(col[i] if i < len(col) else "")
+                w.writerow(row)
+        return path
+    raise ValueError("unsupported data type for save_csv")
+
+
+def describe(data) -> dict:
+    """إحصاءات وصفية سريعة (count/mean/std/min/25/50/75/max) لكل عمود رقمي."""
+    result: dict[str, dict[str, float]] = {}
+    for col in numeric_columns(data):
+        try:
+            v = column_values(data, col)
+        except Exception:
+            continue
+        v = v[np.isfinite(v)]
+        if v.size == 0:
+            continue
+        q = np.quantile(v, [0.0, 0.25, 0.5, 0.75, 1.0])
+        result[col] = {
+            "count": float(v.size),
+            "mean": float(v.mean()),
+            "std": float(v.std()),
+            "min": float(q[0]),
+            "25%": float(q[1]),
+            "50%": float(q[2]),
+            "75%": float(q[3]),
+            "max": float(q[4]),
+        }
+    return result
+
+
+def corr_matrix(data, cols=None) -> tuple[np.ndarray, list[str]]:
+    """مصفوفة ارتباط Pearson بـ numpy فقط."""
+    cols = cols or numeric_columns(data)
+    if len(cols) < 2:
+        raise ValueError("need >= 2 numeric columns for correlation")
+    mat = np.column_stack([column_values(data, c) for c in cols])
+    # احذف الصفوف التي فيها NaN
+    mask = np.all(np.isfinite(mat), axis=1)
+    mat = mat[mask]
+    if mat.shape[0] < 2:
+        return np.eye(len(cols)), cols
+    c = np.corrcoef(mat, rowvar=False)
+    c = np.nan_to_num(c, nan=0.0)
+    return c, cols
+
+
+def sample_rows(data, n: int = 5):
+    if _has_pandas():
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            return data.head(n)
+    if isinstance(data, dict):
+        keys = list(data.keys())
+        return {k: np.asarray(data[k]).ravel()[:n] for k in keys}
+    return data
+
+
+def train_test_split_simple(*arrays, test_size=0.2, seed=0):
+    """تقسيم سريع بدون sklearn (للمبتدئين)."""
+    rng = np.random.default_rng(seed)
+    n = len(np.asarray(arrays[0]))
+    idx = np.arange(n)
+    rng.shuffle(idx)
+    k = int(math.ceil(n * test_size))
+    te, tr = idx[:k], idx[k:]
+    out = []
+    for a in arrays:
+        a = np.asarray(a)
+        out += [a[tr], a[te]]
+    return out

plotlibs/db.py

@@ -0,0 +1,204 @@
+"""plotlibs.db — مهام قواعد البيانات في سطرين.
+
+    import plotlibs as pl
+    conn = pl.db_connect("sales.db")
+    df = pl.read_sql("SELECT * FROM sales LIMIT 1000", conn)
+    pl.quick_eda(df)
+
+يدعم:
+- sqlite3 من المكتبة القياسية (بدون أي تنصيب)
+- sqlalchemy / duckdb إن وُجدت (URLs مثل sqlite:///x.db أو duckdb:///x.ddb)
+- كتابة DataFrame إلى جدول + إنشاء جداول تجريبية + رسم مباشر من SQL
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+def _is_duckdb_url(url: str) -> bool:
+    return url.startswith("duckdb:")
+
+
+def _is_sqla_url(url: str) -> bool:
+    return "://" in url and not _is_duckdb_url(url) and url.split("://")[0] not in ("sqlite",)
+
+
+def connect(url_or_path: str = ":memory:"):
+    """اتصال ذكي: مسار sqlite أو :memory: أو URL.
+
+    يعيد كائن اتصال sqlite3، أو sqlalchemy Connection، أو duckdb connection.
+    """
+    s = str(url_or_path)
+    if _is_duckdb_url(s):
+        try:
+            import duckdb  # type: ignore
+        except ImportError as e:
+            raise ImportError("duckdb not installed: pip install duckdb") from e
+        path = s.replace("duckdb://", "").replace("duckdb:", "") or ":memory:"
+        return duckdb.connect(path if path else ":memory:")
+    if s.startswith("sqlite:///"):
+        return sqlite3.connect(s.replace("sqlite:///", ""))
+    if "://" in s:
+        # sqlalchemy generic (postgres/mysql/...)
+        try:
+            from sqlalchemy import create_engine  # type: ignore
+        except ImportError as e:
+            raise ImportError("sqlalchemy not installed: pip install sqlalchemy") from e
+        eng = create_engine(s)
+        return eng.connect()
+    # مسار ملف أو :memory:
+    return sqlite3.connect(s)
+
+
+db_connect = connect
+
+
+def read_sql(query: str, conn):
+    """نفّذ SELECT وأعد DataFrame (أو dict إن لم توجد pandas)."""
+    # duckdb
+    try:
+        import duckdb  # type: ignore
+        if isinstance(conn, duckdb.DuckDBPyConnection):
+            return conn.execute(query).fetchdf()
+    except Exception:
+        pass
+    # sqlalchemy
+    try:
+        from sqlalchemy.engine import Connection as _SAConn  # type: ignore
+        if isinstance(conn, _SAConn):
+            import pandas as pd
+            return pd.read_sql(query, conn)
+    except Exception:
+        pass
+    # sqlite3
+    try:
+        import pandas as pd
+        return pd.read_sql_query(query, conn)
+    except ImportError:
+        cur = conn.execute(query)
+        cols = [d[0] for d in cur.description]
+        rows = cur.fetchall()
+        import numpy as np
+        out: dict = {}
+        for i, c in enumerate(cols):
+            col = [r[i] for r in rows]
+            try:
+                out[c] = np.array(col, dtype=float)
+            except Exception:
+                out[c] = np.array(col)
+        return out
+
+
+def to_sql(data, table: str, conn, if_exists: str = "replace"):
+    """اكتب DataFrame/dict إلى جدول SQL."""
+    try:
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            # sqlalchemy conn أم sqlite3؟
+            try:
+                from sqlalchemy.engine import Connection as _SAConn  # type: ignore
+                if isinstance(conn, _SAConn):
+                    data.to_sql(table, conn, if_exists=if_exists, index=False)
+                    return table
+            except Exception:
+                pass
+            data.to_sql(table, conn, if_exists=if_exists, index=False)
+            return table
+    except ImportError:
+        pass
+    # dict fallback عبر sqlite3
+    import numpy as np
+    if isinstance(data, dict) and hasattr(conn, "execute"):
+        keys = list(data.keys())
+        n = max(len(np.asarray(data[k]).ravel()) for k in keys)
+        if if_exists == "replace":
+            try:
+                conn.execute(f'DROP TABLE IF EXISTS "{table}"')
+            except Exception:
+                pass
+        coldefs = ", ".join(f'"{k}" TEXT' for k in keys)
+        conn.execute(f'CREATE TABLE IF NOT EXISTS "{table}" ({coldefs})')
+        for i in range(n):
+            vals = []
+            for k in keys:
+                col = np.asarray(data[k]).ravel()
+                vals.append(str(col[i]) if i < len(col) else None)
+            conn.execute(
+                f'INSERT INTO "{table}" VALUES ({",".join("?" for _ in vals)})', vals
+            )
+        conn.commit()
+        return table
+    raise ValueError("unsupported to_sql input")
+
+
+def list_tables(conn) -> list[str]:
+    try:
+        import duckdb  # type: ignore
+        if isinstance(conn, duckdb.DuckDBPyConnection):
+            rows = conn.execute("SHOW TABLES").fetchall()
+            return [r[0] for r in rows]
+    except Exception:
+        pass
+    try:
+        cur = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+        )
+        return [r[0] for r in cur.fetchall()]
+    except Exception:
+        pass
+    try:
+        rows = conn.execute(
+            "SELECT tablename FROM pg_tables WHERE schemaname='public'"
+        ).fetchall()
+        return [r[0] for r in rows]
+    except Exception:
+        return []
+
+
+def demo_db(path: str = ":memory:"):
+    """أنشئ قاعدة تجريبية sales(region, amount, qty) للتعليم والعروض."""
+    import numpy as np
+    conn = connect(path)
+    rng = np.random.default_rng(7)
+    regions = rng.choice(["Cairo", "Oran", "Riyadh", "Dubai"], size=300)
+    amounts = rng.gamma(2.0, 150.0, size=300).round(2)
+    qty = rng.integers(1, 20, size=300)
+    try:
+        import pandas as pd
+        df = pd.DataFrame({"region": regions, "amount": amounts, "qty": qty})
+    except ImportError:
+        df = {"region": regions, "amount": amounts, "qty": qty}
+    to_sql(df, "sales", conn, if_exists="replace")
+    return conn
+
+
+def plot_from_sql(query: str, conn, kind: str = "line", **kw):
+    """ارسم مباشرة من استعلام SQL: SELECT x, y FROM t."""
+    from . import pyplot as plt
+    from .data import numeric_columns, column_values, columns_of
+
+    df = read_sql(query, conn)
+    cols = columns_of(df)
+    nums = numeric_columns(df)
+    if len(nums) >= 2:
+        x = column_values(df, nums[0])
+        y = column_values(df, nums[1])
+        if kind == "bar":
+            plt.bar(x, y, **kw)
+        elif kind == "scatter":
+            plt.scatter(x, y, **kw)
+        else:
+            plt.plot(x, y, **kw)
+        plt.xlabel(nums[0])
+        plt.ylabel(nums[1])
+        plt.title(query[:60])
+    elif cols:
+        # تجميع فئوي: SELECT region, SUM(amount)
+        try:
+            import pandas as _pd  # noqa
+            vals = df
+        except Exception:
+            vals = df
+        _ = vals
+    return df

plotlibs/eda.py

@@ -0,0 +1,157 @@
+"""plotlibs.eda — تحليل استكشافي بسطر واحد للمحللين و Data Science.
+
+    import plotlibs as pl
+    pl.quick_eda(df)            # شكل 2x2: توزيع + box + ارتباط + قيم مفقودة
+    pl.scatter_matrix(df)       # مصفوفة انتشار
+    pl.plot_missing(df)         # خريطة القيم المفقودة
+    pl.plot_trend(df, "date", "sales")  # خط + متوسط متحرك
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def _get_pyplot():
+    from . import pyplot as plt
+    return plt
+
+
+def quick_eda(data, max_cols: int = 6, savefig=None, title: str = "Quick EDA"):
+    """تقرير بصري سريع 2x2. يعيد Figure."""
+    from .data import numeric_columns, column_values, describe
+    plt = _get_pyplot()
+    nums = numeric_columns(data)[:max_cols]
+    if not nums:
+        raise ValueError("quick_eda needs at least 1 numeric column")
+    fig, axs = plt.subplots(2, 2, figsize=(10, 7))
+    fig.suptitle(title)
+    # 1) توزيع أول عمود
+    v0 = column_values(data, nums[0])
+    v0 = v0[np.isfinite(v0)]
+    axs[0, 0].hist(v0, bins=30)
+    axs[0, 0].kde(v0, label="KDE")
+    axs[0, 0].set_title(f"dist: {nums[0]}")
+    # 2) boxplot كل الأعمدة
+    cols = [column_values(data, c) for c in nums]
+    axs[0, 1].boxplot(cols, labels=nums)
+    axs[0, 1].set_title("boxplot")
+    # 3) ارتباط
+    try:
+        axs[1, 0].corr(data, cols=nums, annot=len(nums) <= 8)
+        axs[1, 0].set_title("correlation")
+    except Exception as e:
+        axs[1, 0].set_title(f"corr N/A: {e}")
+    # 4) نص إحصاءات وصفية
+    desc = describe(data)
+    lines = []
+    for c in nums[:4]:
+        d = desc.get(c, {})
+        if d:
+            lines.append(f"{c}: μ={d['mean']:.2f} σ={d['std']:.2f} med={d['50%']:.2f}")
+    axs[1, 1].plot([0, 1], [0, 0], label="baseline")
+    axs[1, 1].set_title("summary")
+    axs[1, 1].text(0.02, 0.9, "\n".join(lines) or "no stats", fontsize=9, color="black")
+    # حفظ اختياري
+    if savefig:
+        fig.savefig(savefig)
+    _ = desc
+    return fig
+
+
+def scatter_matrix(data, cols=None, figsize=(9, 9), **kw):
+    """مصفوفة انتشار n×n (بديل pandas.plotting.scatter_matrix) — سريعة."""
+    from .data import numeric_columns, column_values
+    plt = _get_pyplot()
+    cols = cols or numeric_columns(data)[:5]
+    n = len(cols)
+    if n < 2:
+        raise ValueError("need >= 2 numeric columns")
+    fig, axs = plt.subplots(n, n, figsize=figsize)
+    if n == 1:
+        axs = np.array([[axs]])
+    for i, ci in enumerate(cols):
+        for j, cj in enumerate(cols):
+            ax = axs[i, j]
+            x = column_values(data, cj)
+            y = column_values(data, ci)
+            m = np.isfinite(x) & np.isfinite(y)
+            x, y = x[m], y[m]
+            if i == j:
+                ax.hist(x, bins=20)
+            else:
+                ax.scatter(x[:5000], y[:5000])
+            if j == 0:
+                ax.set_ylabel(ci)
+            if i == n - 1:
+                ax.set_xlabel(cj)
+    fig.suptitle("scatter matrix")
+    return fig
+
+
+def plot_missing(data, **kw):
+    """شريط القيم المفقودة لكل عمود (بديل missingno)."""
+    plt = _get_pyplot()
+    try:
+        import pandas as pd
+        if isinstance(data, pd.DataFrame):
+            miss = data.isna().mean().sort_values(ascending=False)
+            cols = list(miss.index.astype(str))
+            vals = miss.to_numpy()
+            plt.bar(cols, vals)
+            plt.ylabel("missing ratio")
+            plt.title("missing values")
+            return vals
+    except ImportError:
+        pass
+    # fallback: dict
+    from .data import columns_of
+    ratios = []
+    labels = []
+    for c in columns_of(data):
+        v = np.asarray(data[c]).ravel()
+        try:
+            vf = v.astype(float)
+            r = float(np.isnan(vf).mean())
+        except Exception:
+            r = 0.0
+        labels.append(str(c))
+        ratios.append(r)
+    plt.bar(labels, np.array(ratios))
+    plt.ylabel("missing ratio")
+    plt.title("missing values")
+    return np.array(ratios)
+
+
+def plot_trend(data, x_col, y_col, window: int = 7, **kw):
+    """خط زمني + متوسط متحرك (للمحللين الماليين ومحللي المبيعات)."""
+    from .data import column_values
+    plt = _get_pyplot()
+    x = column_values(data, x_col) if x_col else None
+    y = column_values(data, y_col)
+    n = y.size
+    if x is None or x.size != n:
+        x = np.arange(n, dtype=float)
+    plt.plot(x, y, label=y_col)
+    if n >= window:
+        ma = np.convolve(y, np.ones(window) / window, mode="same")
+        plt.plot(x, ma, label=f"MA({window})")
+    plt.xlabel(x_col or "t")
+    plt.ylabel(y_col)
+    plt.title(f"trend: {y_col}")
+    plt.legend()
+    return ma if n >= window else y
+
+
+def value_counts_plot(values, top: int = 15, horizontal: bool = False, **kw):
+    """رسم تكرار الفئات الأعلى (لمحللي البيانات الفئوية)."""
+    plt = _get_pyplot()
+    vals = np.asarray(values).ravel()
+    uniq, counts = np.unique(vals, return_counts=True)
+    order = np.argsort(-counts, kind="stable")[:top]
+    uniq, counts = uniq[order], counts[order]
+    if horizontal:
+        plt.barh(uniq, counts, **kw)
+    else:
+        plt.bar(uniq, counts, **kw)
+    plt.title("value counts")
+    return uniq, counts