showstats 0.0.1__py3-none-any.whl

showstats/__init__.py

@@ -0,0 +1,3 @@
+from .showstats import show_stats
+
+__all__ = ["show_stats"]

showstats/showstats.py

@@ -0,0 +1,208 @@
+# Central functions for table making
+from typing import TYPE_CHECKING, Dict, Union
+
+import polars as pl
+
+from showstats.utils import _format_num_rows
+
+if TYPE_CHECKING:
+    import pandas
+
+
+def _make_tables(
+    df: Union[pl.DataFrame, "pandas.DataFrame"],
+) -> Dict[str, pl.DataFrame]:
+    """
+    Calculate summary statistics for a DataFrame.
+
+    Args:
+        df (pl.DataFrame): The input DataFrame. If not a polars.DataFrame, will try
+        to cast
+
+    Returns:
+        Dict[str, pl.DataFrame]: A dictionary of summary statistics DataFrames for each data type.
+    """
+    from polars import selectors as cs
+
+    functions = {}
+    functions_all = ["null_count", "min", "max"]
+
+    # Map vars to functions
+    vars = {}
+    cols_num = df.select(
+        pl.col(
+            pl.Decimal,
+            pl.Float32,
+            pl.Float64,
+            pl.Int16,
+            pl.Int32,
+            pl.Int64,
+            pl.Int8,
+            pl.UInt16,
+            pl.UInt32,
+            pl.UInt64,
+            pl.UInt8,
+            pl.Boolean,
+        )
+    ).columns
+    if len(cols_num) > 0:
+        vars["num"] = cols_num
+        functions["num"] = functions_all + ["mean", "median", "std"]
+
+    vars_cat = df.select(
+        pl.col(pl.String), pl.col(pl.Enum), pl.col(pl.Categorical)
+    ).columns
+    if len(vars_cat) > 0:
+        vars["cat"] = vars_cat
+        functions["cat"] = functions_all + ["n_unique"]
+
+    vars_datetime = df.select(cs.datetime()).columns
+    if len(vars_datetime) > 0:
+        vars["datetime"] = vars_datetime
+        functions["datetime"] = functions_all + ["mean", "median"]
+
+    vars_date = df.select(cs.date()).columns
+    if len(vars_date) > 0:
+        vars["date"] = vars_date
+        functions["date"] = functions_all
+
+    vars_null = df.select(pl.col(pl.Null)).columns
+    if len(vars_null) > 0:
+        vars["null"] = vars_null
+        functions["null"] = ["null_count"]
+
+    exprs = []
+    for var_type in vars:
+        functions_var_type = functions[var_type]
+        vars_var_type = vars[var_type]
+        for var in vars_var_type:
+            for fun in functions_var_type:
+                varname = f"{fun}_{var}"
+                expr = getattr(pl.col(var), fun)().alias(varname)
+                exprs.append(expr)
+
+    # Compute summary statistics in one go, leveraging Polars' query planner
+    stats = df.select(exprs).row(0, named=True)
+
+    # Make split summary tables
+    dfs = {}
+    for var_type in vars:
+        functions_var_type = functions[var_type]
+        vars_var_type = vars[var_type]
+        rows = []
+        for var in vars_var_type:
+            row = {"Variable": var}
+            for fun in functions_var_type:
+                row[fun] = stats[f"{fun}_{var}"]
+            rows.append(row)
+        dfs[var_type] = pl.DataFrame(rows)
+
+    return dfs
+
+
+def make_stats_df(df: Union[pl.DataFrame, "pandas.DataFrame"]) -> pl.DataFrame:
+    """
+    Create a summary table for the given DataFrame.
+
+    Args:
+        df (pl.DataFrame): The input DataFrame.
+
+    Returns:
+        pl.DataFrame: A summary table with statistics for each variable.
+    """
+
+    if isinstance(df, pl.DataFrame) is False:
+        print("Attempting to convert input to polars.DataFrame")
+        try:
+            df = pl.DataFrame(df)
+        except Exception as e:
+            print(f"Error occurred during attempted conversion: {e}")
+
+    dfs = _make_tables(df)
+    num_rows = df.height
+    varnames = [
+        "Variable",
+        "null_count",
+        "mean",
+        "median",
+        "std",
+        "min",
+        "max",
+    ]
+    var_types = [x for x in ["num", "datetime", "date", "cat", "null"] if x in dfs]
+
+    # Order
+    for var_type in var_types:
+        df_var_type = dfs[var_type].lazy()
+        df_var_type = (
+            df_var_type.with_columns(pl.selectors.float().round(2))
+            .with_columns(
+                pl.col("null_count")
+                .truediv(num_rows)
+                .alias("perc_missing")
+                .mul(100)
+                .round(1)
+            )
+            .with_columns(
+                pl.format("{} ({}%)", pl.col("null_count"), pl.col("perc_missing"))
+            )
+        )
+        # Special conversion for datetimes
+        if var_type == "datetime":
+            df_var_type = df_var_type.with_columns(
+                pl.col("mean", "median", "min", "max").dt.to_string("%Y-%m-%d %H:%M:%S")
+            )
+        else:
+            df_var_type = df_var_type.with_columns(pl.col("*").cast(pl.String))
+        # Add missing values as ""
+        for col_name in varnames:
+            if col_name not in dfs[var_type].columns:
+                df_var_type = df_var_type.with_columns(pl.lit("").alias(col_name))
+        dfs[var_type] = df_var_type.select(varnames)
+
+    thr = 100_000
+    if num_rows < thr:
+        name_var = f"Var; N = {_format_num_rows(num_rows, thr)}"
+    else:
+        name_var = f"Var; N \u2248 {_format_num_rows(num_rows, thr)}"
+    return (
+        pl.concat([dfs[key] for key in var_types])
+        .rename(
+            {
+                "Variable": name_var,
+                "null_count": "Missing",
+                "mean": "Mean",
+                "median": "Median",
+                "std": "Std.",
+                "min": "Min",
+                "max": "Max",
+            }
+        )
+        .collect()
+    )
+
+
+def show_stats(df: Union[pl.DataFrame, "pandas.DataFrame"]) -> None:
+    """
+    Print a summary table for the given DataF‚rame.
+
+    Args:
+        df (pl.DataFrame): The input DataFrame.
+    """
+    from polars import Config
+
+    if df.height == 0 or df.width == 0:
+        raise ValueError("Input data frame must have rows and columns")
+
+    stats_df = make_stats_df(df)
+    cfg = Config(
+        tbl_hide_dataframe_shape=True,
+        tbl_formatting="ASCII_MARKDOWN",
+        tbl_hide_column_data_types=True,
+        float_precision=2,
+        fmt_str_lengths=100,
+        set_tbl_rows=stats_df.height,
+    )
+
+    with cfg:
+        print(stats_df)

showstats/utils.py

@@ -0,0 +1,37 @@
+# Utility functions
+
+
+def _format_num_rows(num: int, thr: float) -> str:
+    """
+    Formats a number nicely, using scientific notation for large numbers.
+
+    Args:
+        num (int): The number to format.
+        thr (int): The threshold above which to use scientific notation.
+
+    Returns:
+        str: The formatted number as a string.
+    """
+    import math
+
+    if num < thr:
+        return f"{num:,.0f}"
+
+    exponent = int(math.floor(math.log10(abs(num))))
+    coefficient = num / 10**exponent
+
+    # Unicode superscript digits
+    superscripts = "⁰¹²³⁴⁵⁶⁷⁸⁹"
+
+    # Convert exponent to superscript
+    exp_superscript = "".join(superscripts[int(d)] for d in str(abs(exponent)))
+    if exponent < 0:
+        exp_superscript = "⁻" + exp_superscript
+
+    return f"{coefficient:.2f}×10{exp_superscript}"
+
+
+def _is_pkg_available(pkg: str) -> None:
+    import importlib
+
+    return importlib.util.find_spec(pkg) is not None

showstats-0.0.1.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.3
+Name: showstats
+Version: 0.0.1
+Summary: Vertical summary statistics for data frames
+Project-URL: Homepage, https://github.com/matthiaskaeding/showstats
+Project-URL: Issues, https://github.com/matthiaskaeding/showstats/issues
+Author: Matthias Kaeding
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: polars>=0.20.21
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5.3; extra == 'pandas'
+Requires-Dist: pyarrow>=10.0.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# showstats: quick and compact summary statistics
+
+
+**showstats** produces summary statistic tables with vertical
+orientation.
+
+``` python
+from showstats import show_stats
+
+show_stats(df)
+```
+
+    | Var; N = 100  | Missing      | Mean         | Median       | Std.  | Min          | Max          |
+    |---------------|--------------|--------------|--------------|-------|--------------|--------------|
+    | int_col       | 0 (0.0%)     | 49.5         | 49.5         | 29.01 | 0.0          | 99.0         |
+    | int_with_miss | 20 (20.0%)   | 57.0         | 59.5         | 27.6  | 0.0          | 99.0         |
+    | ing           |              |              |              |       |              |              |
+    | float_col     | 0 (0.0%)     | 0.5          | 0.5          | 0.29  | 0.0          | 0.99         |
+    | float_col_wit | 0 (0.0%)     | 2.0          | 2.06         | 0.94  | -0.79        | 4.44         |
+    | h_mean_2      |              |              |              |       |              |              |
+    | float_col_wit | 0 (0.0%)     | -0.11        | 0.02         | 2.0   | -6.01        | 5.06         |
+    | h_std_2       |              |              |              |       |              |              |
+    | float_col_wit | 0 (0.0%)     | 9.79         | 9.85         | 0.94  | 7.0          | 12.22        |
+    | h_min_7       |              |              |              |       |              |              |
+    | float_col_wit | 0 (0.0%)     | 14.56        | 14.62        | 0.94  | 11.78        | 17.0         |
+    | h_max_17      |              |              |              |       |              |              |
+    | bool_col      | 0 (0.0%)     | 0.5          | 0.5          | 0.5   | 0.0          | 1.0          |
+    | datetime_col  | 0 (0.0%)     | 2022-01-01   | 2022-01-01   |       | 2022-01-01   | 2022-01-01   |
+    |               |              | 00:00:49     | 00:00:49     |       | 00:00:00     | 00:01:39     |
+    | datetime_col_ | 0 (0.0%)     | 1995-01-01   | 1995-01-01   |       | 1995-01-01   | 1995-01-01   |
+    | 2             |              | 00:00:49     | 00:00:49     |       | 00:00:00     | 00:01:39     |
+    | date_col      | 0 (0.0%)     |              |              |       | 2022-01-01   | 2022-04-10   |
+    | date_col_2    | 0 (0.0%)     |              |              |       | 1500-01-01   | 1500-04-10   |
+    | str_col       | 0 (0.0%)     |              |              |       | ABC          | foo          |
+    | enum_col      | 0 (0.0%)     |              |              |       | low          | high         |
+    | categorical_c | 0 (0.0%)     |              |              |       | low          | medium       |
+    | ol            |              |              |              |       |              |              |
+    | null_col      | 100 (100.0%) |              |              |       |              |              |
+
+Primarily built for polars data frames. **showstats** converts other
+inputs, for compatibility with pandas.DataFrames install as
+`pip install showstats[pandas]`

showstats-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+showstats/__init__.py,sha256=OWa_lNYDUR_q_socZ9lO86SMrtGOvVlPP6BaqySs9ng,60
+showstats/showstats.py,sha256=LnhwYAJM9tmqwENp7tg3KekX2_rDipbGVxIQKWpccrc,5978
+showstats/utils.py,sha256=yCNdxuD_sGobCwkFdsTy50kOax5mU07RJkYmTIKtliY,949
+showstats-0.0.1.dist-info/METADATA,sha256=_KwudXoOTmxppDfrHsL3sDvWSJ0IdrsHI0UJaZcgg7U,3741
+showstats-0.0.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+showstats-0.0.1.dist-info/licenses/LICENSE,sha256=eFm_5oC7njV7uQ08GSk6w0n-y6sCH2N6US5NsyLj8E8,1072
+showstats-0.0.1.dist-info/RECORD,,

showstats-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

showstats-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Matthias Kaeding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.