pistachioplots 0.1.0__tar.gz

pistachioplots-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel José Aguilar Paniagua
+
+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.

pistachioplots-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: pistachioplots
+Version: 0.1.0
+Summary: Plotting utilities built on pistachiots, polars, and plotnine
+Author-email: Daniel José Aguilar Paniagua <danieljoseaguilar@gmail.com>
+License: MIT
+Keywords: plotting,plotnine,polars,time series,exploratory data analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/plain
+License-File: LICENSE.txt
+Requires-Dist: polars
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: plotnine
+Requires-Dist: mizani
+Requires-Dist: statsmodels
+Requires-Dist: pistachiots
+Dynamic: license-file
+
+pistachioplots
+
+Plotting utilities for exploratory data analysis and time series, built on
+polars, plotnine and pistachiots.
+
+The package installs as 'pistachioplots' and imports as 'PistachioPlots'.
+
+
+INSTALLATION
+
+    pip install pistachioplots
+
+
+USAGE
+
+    import PistachioPlots as pst
+
+Every function returns a plotnine plot, or a dictionary of plots when it is
+asked for several at once. Variables can be given explicitly or left out, in
+which case the function picks the columns whose type fits.
+
+
+DISTRIBUTIONS
+
+    dist_density(df, var)       histogram with a kernel density overlay, and
+                                optional analytic densities on top
+    dist_density_cond(df, var, var_cat)
+                                the same, conditioned on a categorical
+                                variable, overlaid or in facets
+    dist_mass(df, var)          bar chart of a categorical variable, with
+                                percentage and count labels
+    dist_mass_cond(df, var1, var2)
+                                the distribution of var1 conditioned on var2,
+                                in facets or as side-by-side bars
+
+
+TIME SERIES
+
+    ts(df, var, response)       one plot per variable, or a single faceted one
+    ts_multiple(df, var)        several series in one panel or in facets
+    ts_by_keys(df, var)         panel data with one or two keys
+    time_breaks(plt, dates)     x-axis breaks and date format
+
+These take a TSPolars object from pistachiots. 'response' gives one variable
+the first color and the first place in the legend. 'ts_breaks_params' controls
+the breaks: 'jump' (the step between them), 'date_format' and 'plot_minor'.
+
+
+CORRELATIONS
+
+    corrs(df, response)         Pearson, Spearman and Kendall coefficients
+                                against a response, with significance marks
+    corrs_matrix(df)            correlation matrix as a heatmap
+
+Lagged variables named L1x, L2x and so on are grouped and sorted by lag number.
+
+
+SCATTER AND LINES
+
+    scatter(df, var)            scatter matrix across the given variables
+    scatter(df, vary, varx)     a response against one or several covariates
+    line(df, varx, vary)        a simple line, optionally stepped or filled
+
+
+THEME AND COLORS
+
+    theme_params_def            the default theme settings; copy it, change
+                                what you need and pass it as theme_params
+    colors_categ(series)        the palette for a categorical variable
+    set_palette(colors)         override the package palette
+
+    tms = pst.theme_params_def.copy()
+    tms['x_angle'] = 90
+    pst.dist_mass(df, 'region', theme_params = tms)
+
+
+LICENSE
+
+MIT. See the LICENSE.txt file.

pistachioplots-0.1.0/README.txt

@@ -0,0 +1,79 @@
+pistachioplots
+
+Plotting utilities for exploratory data analysis and time series, built on
+polars, plotnine and pistachiots.
+
+The package installs as 'pistachioplots' and imports as 'PistachioPlots'.
+
+
+INSTALLATION
+
+    pip install pistachioplots
+
+
+USAGE
+
+    import PistachioPlots as pst
+
+Every function returns a plotnine plot, or a dictionary of plots when it is
+asked for several at once. Variables can be given explicitly or left out, in
+which case the function picks the columns whose type fits.
+
+
+DISTRIBUTIONS
+
+    dist_density(df, var)       histogram with a kernel density overlay, and
+                                optional analytic densities on top
+    dist_density_cond(df, var, var_cat)
+                                the same, conditioned on a categorical
+                                variable, overlaid or in facets
+    dist_mass(df, var)          bar chart of a categorical variable, with
+                                percentage and count labels
+    dist_mass_cond(df, var1, var2)
+                                the distribution of var1 conditioned on var2,
+                                in facets or as side-by-side bars
+
+
+TIME SERIES
+
+    ts(df, var, response)       one plot per variable, or a single faceted one
+    ts_multiple(df, var)        several series in one panel or in facets
+    ts_by_keys(df, var)         panel data with one or two keys
+    time_breaks(plt, dates)     x-axis breaks and date format
+
+These take a TSPolars object from pistachiots. 'response' gives one variable
+the first color and the first place in the legend. 'ts_breaks_params' controls
+the breaks: 'jump' (the step between them), 'date_format' and 'plot_minor'.
+
+
+CORRELATIONS
+
+    corrs(df, response)         Pearson, Spearman and Kendall coefficients
+                                against a response, with significance marks
+    corrs_matrix(df)            correlation matrix as a heatmap
+
+Lagged variables named L1x, L2x and so on are grouped and sorted by lag number.
+
+
+SCATTER AND LINES
+
+    scatter(df, var)            scatter matrix across the given variables
+    scatter(df, vary, varx)     a response against one or several covariates
+    line(df, varx, vary)        a simple line, optionally stepped or filled
+
+
+THEME AND COLORS
+
+    theme_params_def            the default theme settings; copy it, change
+                                what you need and pass it as theme_params
+    colors_categ(series)        the palette for a categorical variable
+    set_palette(colors)         override the package palette
+
+    tms = pst.theme_params_def.copy()
+    tms['x_angle'] = 90
+    pst.dist_mass(df, 'region', theme_params = tms)
+
+
+LICENSE
+
+MIT. See the LICENSE.txt file.

pistachioplots-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "pistachioplots"
+version = "0.1.0"
+description = "Plotting utilities built on pistachiots, polars, and plotnine"
+readme = {file = "README.txt", content-type = "text/plain"}
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "Daniel José Aguilar Paniagua", email = "danieljoseaguilar@gmail.com"}]
+keywords = ["plotting", "plotnine", "polars", "time series", "exploratory data analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "polars",
+    "pandas",
+    "numpy",
+    "scipy",
+    "matplotlib",
+    "plotnine",
+    "mizani",
+    "statsmodels",
+    "pistachiots",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"

pistachioplots-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pistachioplots-0.1.0/src/PistachioPlots/PstCorrs.py

@@ -0,0 +1,330 @@
+
+
+import numpy as np
+import polars as pl 
+from plotnine import (
+    ggplot, aes, geom_col, geom_text, scale_fill_manual,
+    scale_x_discrete, labs, position_dodge, geom_raster,
+    scale_fill_gradient2, scale_fill_gradientn, coord_equal
+)
+import re
+from scipy import stats
+from typing import Literal
+import warnings
+
+
+
+import pistachiots as cln 
+from pistachiots import TSPolars
+from . import PstUtils as psu
+
+
+def corrs(df, response, covs = None, rem_lags = False, group_lags = True, alpha = 0.05, theme_params = psu.theme_params_def):
+
+    # 1. Valdiacion y limpieza:
+
+    #1.1. Quitar lags
+    if rem_lags:
+        df = df.rem_lags(rem_response = True, response = response)
+
+    #1.2. Extaer covariables. 
+    df = df.select([c for c in df.columns if psu.is_continuous(df[c]) or psu.is_integer(df[c])])
+
+    if not covs:
+        covs = [c for c in df.columns if c!= response] 
+        covs = [c for c in covs if c!=df.ts_col] if isinstance(df, TSPolars) else covs 
+        if not covs:
+            raise ValueError('There are no numeric/ordered covariates.')
+    else:
+        missings_covs = [c for c in  covs if c not in df.columns]
+        if missings_covs:
+            missing_str = ', '.join(missings_covs)
+            raise ValueError(f"Covariate(s) {missing_str} is not numeric/ordered and/or is not in df.")
+
+    if response not in df.columns:
+        raise ValueError('Response is not numeric/ordered and/or is not in df.')
+
+    if isinstance(df, TSPolars):
+        if group_lags and not any(re.match(r"^L[0-9]+", c) for c in covs):
+            warnings.warn("There are no lags but group_lags is True.") 
+            group_lags = False
+
+
+    # 2. Calculate correlations:
+    def calc_corr_df(cov_name):
+        x = df[cov_name].to_numpy()
+        y = df[response].to_numpy()
+
+        nan_mask = np.isnan(x) | np.isnan(y)
+        x = x[~nan_mask]
+        y = y[~nan_mask]
+
+        pearson = stats.pearsonr(x, y, alternative='two-sided', method=None)
+        kendall = stats.kendalltau(x, y, method='auto', alternative='two-sided', variant='b', nan_policy='omit')
+        spearman = stats.spearmanr(x, y, nan_policy='omit', alternative='two-sided')
+
+        df_corr_cov = pl.DataFrame({
+            'variable':[cov_name] * 3, 
+            'method':['Pearson', 'Spearman', 'Kendall'],
+            'corr':[pearson.statistic, spearman.statistic, kendall.statistic],
+            'p_val':[pearson.pvalue, spearman.pvalue, kendall.pvalue],
+        })
+
+        return df_corr_cov
+
+    df_corrs = (
+        pl.concat([calc_corr_df(c) for c in covs])
+        .with_columns(
+            pl.when(pl.col('p_val') <= alpha).then(pl.lit('*')).otherwise(pl.lit('')).alias('signif'),
+            pl.col('method').cast(pl.Enum(['Pearson',  'Kendall','Spearman']))
+        )
+        .with_columns(
+            pl.when(pl.col('corr') > 0).then(pl.col('corr')+0.04).otherwise(pl.col('corr')-0.04).alias('text_y'),
+            #pl.when(pl.col('corr') > 0).then(pl.lit(0)).otherwise(pl.lit(1)).alias('text_vjust')
+        )
+    )
+    
+
+    # 3. Group lags:
+    if group_lags:
+        lag_re = re.compile(r"^L([0-9]+)")
+
+        covs_base = list(dict.fromkeys(lag_re.sub("", c) for c in covs))
+        covs_cont = [c for c in covs if not lag_re.match(c)]
+
+        ord_vars = []
+        for base in covs_base:
+            pattern = re.compile(rf"^L[0-9]+{re.escape(base)}$")
+            lagged = sorted(
+                (c for c in covs if pattern.match(c)),
+                key=lambda c: int(lag_re.match(c).group(1))
+            )
+            if base in covs_cont:
+                ord_vars.extend([base] + lagged)
+            else:
+                ord_vars.extend(lagged)
+
+        df_corrs = df_corrs.with_columns(
+            pl.col('variable').cast(pl.Enum(ord_vars))
+        )
+    
+    # 4. Base plot:
+    palette = psu.colors_categ(df_corrs['method'], is_ord=False)
+   
+    base_plot = (
+        ggplot(df_corrs, aes('variable', 'corr', fill='method'))
+        + geom_col(position=position_dodge(0.9))
+        + geom_text(
+            aes(label='signif', y='text_y'),
+            position=position_dodge(0.9),
+            size=9,
+            family=theme_params.get('font'),
+        )
+        + scale_fill_manual(values={
+            'Pearson': palette[0], 'Kendall': palette[1], 'Spearman': palette[2]
+        })
+        + labs(
+            fill=None,
+            caption=f"*: significancia al {alpha * 100:g}%",
+        )
+        #+ scale_x_discrete(guide=guide_axis(n_dodge=1))
+    )
+
+    # 5. Add theme:
+    theme_params = dict(theme_params)
+    theme_params['title'] = f"Coeficientes de dependencia sobre {response}"
+    final_plot = psu.add_theme(base_plot, **theme_params)
+
+    return final_plot
+
+
+def corrs_matrix(
+    df,
+    statistic: Literal['pearson', 'spearman', 'kendall'] = 'pearson',
+    varsx = None,
+    varsy = None,
+    ratio = 0.75,
+    rem_lags = False,
+    group_lags = True,
+    write_signif = False,
+    write_coef = False, 
+    write_pval = False,
+    label_size = 9, 
+    ndecimals = 4,
+    alpha1 = 0.05,
+    alpha2 = 0.01,
+    alpha3 = 0.0001,
+    theme_params = psu.theme_params_def
+):
+    # 1. Validacion y limpieza:
+
+    if rem_lags:
+        df = df.rem_lags(rem_response=False)
+
+    df = df.select([c for c in df.columns if psu.is_continuous(df[c]) or psu.is_integer(df[c])])
+
+    if isinstance(varsx, str):
+        varsx = [varsx]
+
+    if isinstance(varsy, str):
+        varsy = [varsy]
+
+    if not varsx:
+        varsx = [c for c in df.columns if c != df.ts_col] if isinstance(df, TSPolars) else list(df.columns)
+        if not varsx:
+            raise ValueError('There are no numeric columns.')
+    else:
+        missings_varsx = [c for c in varsx if c not in df.columns]
+        if missings_varsx:
+            missing_str = ', '.join(missings_varsx)
+            raise ValueError(f"Variables {missing_str} are not numeric and/or are not in df.")
+
+    if not varsy:
+        varsy = [c for c in df.columns if c != df.ts_col] if isinstance(df, TSPolars) else list(df.columns)
+        if not varsy:
+            raise ValueError('There are no numeric columns.')
+    else:
+        missings_varsy = [c for c in varsy if c not in df.columns]
+        if missings_varsy:
+            missing_str = ', '.join(missings_varsy)
+            raise ValueError(f"Variables {missing_str} are not numeric and/or are not in df.")
+
+    if statistic not in ('pearson', 'spearman', 'kendall'):
+        raise ValueError("statistic must be one of 'pearson', 'spearman', 'kendall'")
+
+    if isinstance(df, TSPolars):
+        if group_lags and not any(re.match(r"^L[0-9]+", c) for c in varsx+varsy):
+            warnings.warn("There are no lags but group_lags is True.") 
+            group_lags = False
+
+    if isinstance(df, TSPolars):
+        df = df.df
+
+    # 2. Calculate correlations:
+    def calc_corr_df(varx, vary):
+        x = df[varx].to_numpy()
+        y = df[vary].to_numpy()
+
+        nan_mask = np.isnan(x) | np.isnan(y)
+        x = x[~nan_mask]
+        y = y[~nan_mask]
+
+        if statistic == 'pearson':
+            st = stats.pearsonr(x, y, alternative='two-sided')
+        elif statistic == 'spearman':
+            st = stats.spearmanr(x, y, nan_policy='omit', alternative='two-sided')
+        else:
+            st = stats.kendalltau(x, y, method='auto', alternative='two-sided', variant='b', nan_policy='omit')
+
+        return pl.DataFrame({
+            'x': [varx],
+            'y': [vary],
+            'coef': [st.statistic],
+            'p_val': [st.pvalue],
+        })
+
+    df_corrs = (
+        pl.concat([calc_corr_df(varx, vary) for varx in varsx for vary in varsy])
+        .with_columns(
+            (
+                pl.when(pl.col('p_val') <= alpha3)
+                .then(pl.lit('***'))
+                .when(pl.col('p_val') <= alpha2)
+                .then(pl.lit('**'))
+                .when(pl.col('p_val') <= alpha1)
+                .then(pl.lit('*'))
+                .otherwise(pl.lit(''))
+                .alias('signif')
+            ),
+            pl.col('p_val').round(ndecimals).cast(pl.Utf8).alias('p_val_fmt'),
+            pl.col('coef').map_elements(lambda v: f"{v:.{ndecimals}f}", return_dtype=pl.Utf8).alias('coef_fmt'),
+        )
+        .with_columns(
+            pl.when(pl.lit(write_coef) & pl.lit(write_signif))
+            .then(pl.col('coef_fmt') + pl.col('signif'))
+            .when(pl.lit(write_coef))
+            .then(pl.col('coef_fmt'))
+            .when(pl.lit(write_signif))
+            .then(pl.col('signif'))
+            .otherwise(pl.lit(''))
+            .alias('label')
+        )
+        .with_columns(
+            pl.when(pl.lit(write_pval))
+            .then(pl.col('label') + pl.lit('\n(') + pl.col('p_val_fmt') + pl.lit(')'))
+            .otherwise(pl.col('label'))
+            .alias('label')
+        )
+    )
+
+    # 3. Group lags (both axes):
+    if group_lags:
+        lag_re = re.compile(r"^L([0-9]+)")
+
+        def ordered_levels(varlist):
+            covs_base = list(dict.fromkeys(lag_re.sub("", c) for c in varlist))
+            covs_cont = [c for c in varlist if not lag_re.match(c)]
+            ord_vars = []
+            for base in covs_base:
+                pattern = re.compile(rf"^L[0-9]+{re.escape(base)}$")
+                lagged = sorted(
+                    (c for c in varlist if pattern.match(c)),
+                    key=lambda c: int(lag_re.match(c).group(1))
+                )
+                if base in covs_cont:
+                    ord_vars.extend([base] + lagged)
+                else:
+                    ord_vars.extend(lagged)
+            return ord_vars
+
+        df_corrs = (
+            df_corrs
+            .with_columns(
+                pl.col('x').cast(pl.Enum(ordered_levels(varsx))),
+                pl.col('y').cast(pl.Enum(ordered_levels(varsy)))
+            )
+        )
+
+    # 4. Create plot:
+    plt = ggplot(df_corrs, aes(x='x', y='y', fill='coef')) + geom_raster()
+
+    if write_signif or write_coef or write_pval:
+        plt = plt + geom_text(aes(label='label'), color='black', size=label_size)
+
+    plt = plt + labs(
+        x=None,
+        y=None,
+        fill=statistic.capitalize(),
+        caption=(
+            f"*: significancia al {alpha1*100:g}% | "
+            f"**: {alpha2*100:g}% | "
+            f"***: {alpha3*100:g}%"
+            if write_signif else None
+        ),
+    )
+
+    # 5. Add theme:
+    theme_params = dict(theme_params)
+    theme_params['title'] = f"Matriz de correlaciones ({statistic.capitalize()})"
+    plt = psu.add_theme(plt, **theme_params)
+
+    plt = plt + scale_fill_gradientn(
+        colors=['#67001F', '#B2182B', '#D6604D', '#F4A582', '#FDDBC7', '#FFFFFF',
+                '#D1E5F0', '#92C5DE', '#4393C3', '#2166AC', '#053061'],
+        limits=(-1, 1),
+    )
+
+    plt = plt + coord_equal(ratio=ratio)
+
+    return plt
+
+
+
+
+    
+    
+
+    
+
+
+