direl-ts-tool-kit 0.4.8__py3-none-any.whl → 0.5.0__py3-none-any.whl

direl_ts_tool_kit/plot/plot_style.py

@@ -1,3 +1,4 @@
+import seaborn as sns
 import matplotlib.pyplot as plt
 import matplotlib.dates as mdates
 

direl_ts_tool_kit/plot/plot_ts.py

@@ -1,8 +1,16 @@
+import pandas as pd
 from .plot_style import *
+from scipy.stats import pearsonr
 
 
 def plot_time_series(
-    df_ts, variable, units="", color="BLUE_LINES", time_unit="Year", rot=90, auto_format_label=True
+    df_ts,
+    variable,
+    units="",
+    color="BLUE_LINES",
+    time_unit="Year",
+    rot=90,
+    auto_format_label=True,
 ):
     """
     Plots a time series with custom styling and dual-level grid visibility.
@@ -100,7 +108,7 @@ def plot_time_series(
     if time_unit == "Day":
         ax.xaxis.set_major_locator(mdates.DayLocator())
         ax.xaxis.set_minor_locator(mdates.HourLocator())
-        
+
     if time_unit == "Hour":
         ax.xaxis.set_major_locator(mdates.HourLocator())
         ax.xaxis.set_minor_locator(mdates.MinuteLocator())
@@ -151,3 +159,102 @@ def save_figure(
     fig.savefig(f"{base_name}.png")
     fig.savefig(f"{base_name}.pdf")
     fig.savefig(f"{base_name}.svg")
+
+
+def heat_map(X, y, colors="Blues"):
+    """
+    Generates a correlation heatmap plot for a set of features and a target variable.
+
+    This function concatenates the feature DataFrame (X) and the target Series (y)
+    to compute and visualize the full pairwise correlation matrix using Seaborn.
+
+    Parameters
+    ----------
+    X : pd.DataFrame
+        The DataFrame containing the feature variables.
+    y : pd.Series or pd.DataFrame
+        The target variable (must be concatenable with X).
+    colors : str or matplotlib.colors.Colormap, optional
+        The colormap to use for the heatmap, passed to the 'cmap' argument
+        in seaborn.heatmap. Defaults to "Blues".
+
+        Note: For standard correlation matrices (which include negative values),
+        a diverging colormap (e.g., "coolwarm", "vlag") is usually recommended.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The generated Matplotlib figure object containing the heatmap.
+
+    Notes
+    -----
+    The heatmap displays the Pearson correlation coefficient rounded to two
+    decimal places and includes annotations for improved readability.
+    """
+    fig, ax = plt.subplots()
+    Z = pd.concat([X, y], axis=1)
+
+    ax = sns.heatmap(
+        Z.corr(),
+        cmap=colors,
+        annot=True,
+        linewidths=0.5,
+        fmt=".2f",
+        annot_kws={"size": 10},
+    )
+
+    return fig
+
+
+def corrfunc(x, y, ax=None, **kws):
+    """Plot the correlation coefficient in the top left hand corner of a plot."""
+    r, _ = pearsonr(x, y)
+    ax = ax or plt.gca()
+    ax.annotate(f"R = {r:.2f}", xy=(0.1, 0.9), fontsize=25, xycoords=ax.transAxes)
+
+
+def pair_plot(X, y):
+    """
+    Generates a cornered pair plot (scatterplot matrix) to visualize relationships
+    between features and the target variable.
+
+    The function combines the feature DataFrame (X) and the target Series (y)
+    and uses seaborn.pairplot to create a matrix of scatter plots and histograms.
+    It focuses on the lower triangular part (corner=True) and includes a
+    regression line for trend visualization.
+
+    Parameters
+    ----------
+    X : pd.DataFrame
+        The DataFrame containing the feature variables.
+    y : pd.Series or pd.DataFrame
+        The target variable (must be concatenable with X).
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The generated Matplotlib Figure object containing the cornered pair plot.
+
+    Notes
+    -----
+    1. **Dependency:** This function requires a previously defined custom function
+       `corrfunc` to be available in the local namespace, as it is used via
+       `svm.map_lower()`. This custom function is typically used to display
+       correlation coefficients (e.g., Pearson's r) in the lower panel.
+    2. **Aesthetics:** Uses a regression line (`kind="reg"`) with custom color
+       (RED_LINES) to highlight linear relationships.
+    3. **Output:** The returned Figure object can be manipulated further
+       or saved using methods like `fig.savefig()`.
+    """
+    Z = pd.concat([X, y], axis=1)
+    svm = sns.pairplot(
+        Z,
+        corner=True,
+        kind="reg",
+        plot_kws={"line_kws": {"color": paper_colors["RED_LINES"]}},
+    )
+    svm.map_lower(corrfunc)
+
+    fig = svm.fig
+
+    return fig

direl_ts_tool_kit-0.5.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: direl-ts-tool-kit
+Version: 0.5.0
+Summary: A toolbox for time series analysis and visualization.
+Home-page: https://gitlab.com/direl/direl_tool_kit
+Author: Diego Restrepo-Leal
+Author-email: diegorestrepoleal@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: pandas>=1.0.0
+Requires-Dist: numpy>=1.18.0
+Requires-Dist: matplotlib>=3.0.0
+Requires-Dist: openpyxl
+Requires-Dist: seaborn
+Requires-Dist: scipy
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# direl-ts-tool-kit
+> A Toolbox for Time Series Analysis and Visualization
+
+A lightweight Python library developed to streamline common tasks in time series processing, including data preparation,
+visualization with a consistent aesthetic style, and handling irregular indices.
+
+## Key features and functions
+
+The library provides the following key functionalities, primarily centered around data preparation and plotting.
+
+### Data preparation and index management
+#### parse_datetime_index
+`parse_datetime_index(df_raw, date_column="date", format=None)`
+
+Parses a specified column into datetime objects and sets it as the DataFrame index.
+
+This function prepares raw data for time series analysis by ensuring the
+DataFrame is indexed by the correct datetime type.
+
+#### generate_dates
+`generate_dates(df_ts, freq="MS")`
+
+Generates a continuous DatetimeIndex covering the time span of the input DataFrame.
+
+The function determines the start and end dates from the existing DataFrame index
+and creates a new, regular date sequence based on the specified frequency.
+
+#### reindex_and_aggregate
+`reindex_and_aggregate(df_ts, column_name, freq="MS")`
+
+Re-indexes a time series DataFrame to a regular frequency, aggregates values,
+and introduces NaN for missing time steps.
+
+This function first identifies the time range from the original (potentially irregular)
+index, aggregates data if necessary (e.g., if multiple entries exist per time step),
+and then merges the data onto a complete date range, effectively filling gaps
+with NaN values.
+
+#### remove_outliers_by_threshold
+`remove_outliers_by_threshold(df_ts, column_name, lower_bound, upper_bound)`
+
+Replaces values in a specified column with NaN if they fall outside a defined range (outlier removal).
+
+This function identifies data points that are either below the lower
+bound or above the upper bound and treats them as missing data.
+
+
+### Visualization and styling
+
+#### plot_time_series
+`plot_time_series(df_ts, variable, units="", color="BLUE_LINES", time_unit="Year", rot=90, auto_format_label=True)`
+
+Plots a time series with custom styling and dual-level grid visibility.
+
+This function automatically sets major and minor time-based locators
+on the x-axis based on the specified time unit, and formats the y-axis
+to use scientific notation.
+
+#### save_figure
+`save_figure(fig, file_name, variable_name="", path="./")`
+
+Saves a Matplotlib figure in three common high-quality formats (PNG, PDF, SVG).
+
+The function creates a consistent file name structure:
+{path}/{file_name}_{variable_name}.{extension}.
+
+#### heat_map
+`heat_map(X, y, colors="Blues")`
+
+Generates a correlation heatmap plot for a set of features and a target variable.
+
+This function concatenates the feature DataFrame (X) and the target Series (y)
+to compute and visualize the full pairwise correlation matrix using Seaborn.
+
+#### pair_plot
+`pair_plot(X, y)`
+
+Generates a cornered pair plot (scatterplot matrix) to visualize relationships
+between features and the target variable.
+
+The function combines the feature DataFrame (X) and the target Series (y)
+and uses seaborn.pairplot to create a matrix of scatter plots and histograms.
+It focuses on the lower triangular part (corner=True) and includes a
+regression line for trend visualization.
+
+
+# Examples
+- [Example 1](https://gitlab.com/direl/direl_tool_kit/-/blob/main/example/example_01.md?ref_type=heads)
+- [Example 2](https://gitlab.com/direl/direl_tool_kit/-/blob/main/example/example_02.md?ref_type=heads)
+

direl_ts_tool_kit-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+direl_ts_tool_kit/__init__.py,sha256=W99Wd3BeEFKOxT51TApURElbDJvqIjD8u_-qDoCYSJ0,94
+direl_ts_tool_kit/plot/__init__.py,sha256=CMwyv-kiE74nwr3MJPL7gWIJmcfZ8UQCRu7mBGGQ4rI,49
+direl_ts_tool_kit/plot/plot_style.py,sha256=WVcxr5LK0ht8RmFscUri7HcCB5Vd50UItocYNnlj3sA,1032
+direl_ts_tool_kit/plot/plot_ts.py,sha256=PbqclUAVTbYa7YTf59Q75XW1qqaW_I7qPuuTXMQmmxI,8340
+direl_ts_tool_kit/utilities/__init__.py,sha256=jMtxYZUtwlhgI99sxe_8MMzsDnxtbTP7Ivh9tUOeIwQ,25
+direl_ts_tool_kit/utilities/data_prep.py,sha256=k3eOwQEEd5mxy2DtT_Gdo7BhkzEmSQqvMJ89y8mH5CQ,6024
+direl_ts_tool_kit-0.5.0.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+direl_ts_tool_kit-0.5.0.dist-info/METADATA,sha256=ctS91dCUFsS4i4HI80XFjhHVEaySpNVQw79wyvh_ipM,4509
+direl_ts_tool_kit-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+direl_ts_tool_kit-0.5.0.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
+direl_ts_tool_kit-0.5.0.dist-info/RECORD,,

direl_ts_tool_kit-0.4.8.dist-info/METADATA

@@ -1,487 +0,0 @@
-Metadata-Version: 2.4
-Name: direl-ts-tool-kit
-Version: 0.4.8
-Summary: A toolbox for time series analysis and visualization.
-Home-page: https://gitlab.com/direl/direl_tool_kit
-Author: Diego Restrepo-Leal
-Author-email: diegorestrepoleal@gmail.com
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Intended Audience :: Science/Research
-Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENCE
-Requires-Dist: pandas>=1.0.0
-Requires-Dist: numpy>=1.18.0
-Requires-Dist: matplotlib>=3.0.0
-Requires-Dist: openpyxl
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# direl-ts-tool-kit
-> A Toolbox for Time Series Analysis and Visualization
-
-A lightweight Python library developed to streamline common tasks in time series processing, including data preparation,
-visualization with a consistent aesthetic style, and handling irregular indices.
-
-## Key features and functions
-
-The library provides the following key functionalities, primarily centered around data preparation and plotting.
-
-### Data preparation and index management
-#### parse_datetime_index
-`parse_datetime_index(df_raw, date_column="date", format=None)`
-
-Parses a specified column into datetime objects and sets it as the DataFrame index.
-
-This function prepares raw data for time series analysis by ensuring the
-DataFrame is indexed by the correct datetime type.
-
-#### generate_dates
-`generate_dates(df_ts, freq="MS")`
-
-Generates a continuous DatetimeIndex covering the time span of the input DataFrame.
-
-The function determines the start and end dates from the existing DataFrame index
-and creates a new, regular date sequence based on the specified frequency.
-
-#### reindex_and_aggregate
-`reindex_and_aggregate(df_ts, column_name, freq="MS")`
-
-Re-indexes a time series DataFrame to a regular frequency, aggregates values,
-and introduces NaN for missing time steps.
-
-This function first identifies the time range from the original (potentially irregular)
-index, aggregates data if necessary (e.g., if multiple entries exist per time step),
-and then merges the data onto a complete date range, effectively filling gaps
-with NaN values.
-
-#### remove_outliers_by_threshold
-`remove_outliers_by_threshold(df_ts, column_name, lower_bound, upper_bound)`
-
-Replaces values in a specified column with NaN if they fall outside a defined range (outlier removal).
-
-This function identifies data points that are either below the lower
-bound or above the upper bound and treats them as missing data.
-
-
-### Visualization and styling
-
-#### plot_time_series
-`plot_time_series(df_ts, variable, units="", color="BLUE_LINES", time_unit="Year", rot=90, auto_format_label=True)`
-
-Plots a time series with custom styling and dual-level grid visibility.
-
-This function automatically sets major and minor time-based locators
-on the x-axis based on the specified time unit, and formats the y-axis
-to use scientific notation.
-
-#### save_figure
-`save_figure(fig, file_name, variable_name="", path="./")`
-
-Saves a Matplotlib figure in three common high-quality formats (PNG, PDF, SVG).
-
-The function creates a consistent file name structure:
-{path}/{file_name}_{variable_name}.{extension}.
-
-# Examples
-## Example 1
-```python
-import jupyter_black
-
-jupyter_black.load()
-```
-
-
-```python
-import pandas as pd
-import warnings
-
-from direl_ts_tool_kit import (
-    plot_time_series,
-    save_figure,
-    parse_datetime_index,
-    reindex_and_aggregate,
-)
-
-warnings.filterwarnings("ignore")
-```
-
-
-```python
-df0 = pd.read_csv("dataset_test_01.csv")
-```
-
-
-```python
-df0.head(2)
-```
-
-
-
-
-<div>
-<style scoped>
-    .dataframe tbody tr th:only-of-type {
-        vertical-align: middle;
-    }
-
-    .dataframe tbody tr th {
-        vertical-align: top;
-    }
-
-    .dataframe thead th {
-        text-align: right;
-    }
-</style>
-<table border="1" class="dataframe">
-  <thead>
-    <tr style="text-align: right;">
-      <th></th>
-      <th>date</th>
-      <th>LPUE</th>
-      <th>common name</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th>0</th>
-      <td>1993-01-01</td>
-      <td>0.47</td>
-      <td>camaron blanco</td>
-    </tr>
-    <tr>
-      <th>1</th>
-      <td>1993-02-01</td>
-      <td>0.22</td>
-      <td>camaron blanco</td>
-    </tr>
-  </tbody>
-</table>
-</div>
-
-
-
-
-```python
-df1 = parse_datetime_index(df0)
-df1.head(2)
-```
-
-
-
-
-<div>
-<style scoped>
-    .dataframe tbody tr th:only-of-type {
-        vertical-align: middle;
-    }
-
-    .dataframe tbody tr th {
-        vertical-align: top;
-    }
-
-    .dataframe thead th {
-        text-align: right;
-    }
-</style>
-<table border="1" class="dataframe">
-  <thead>
-    <tr style="text-align: right;">
-      <th></th>
-      <th>LPUE</th>
-      <th>common name</th>
-    </tr>
-    <tr>
-      <th>date</th>
-      <th></th>
-      <th></th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th>1993-01-01</th>
-      <td>0.47</td>
-      <td>camaron blanco</td>
-    </tr>
-    <tr>
-      <th>1993-02-01</th>
-      <td>0.22</td>
-      <td>camaron blanco</td>
-    </tr>
-  </tbody>
-</table>
-</div>
-
-
-
-
-```python
-fig = plot_time_series(df1, "LPUE", "$(kg/dop)$", auto_format_label=False)
-fig.show()
-```
-
-
-    
-![png](example/output_5_0.png)
-    
-
-
-
-```python
-save_figure(fig, file_name="LPUE_raw")
-```
-
-
-```python
-df2 = reindex_and_aggregate(df1, column_name="LPUE")
-df2.head(2)
-```
-
-
-
-
-<div>
-<style scoped>
-    .dataframe tbody tr th:only-of-type {
-        vertical-align: middle;
-    }
-
-    .dataframe tbody tr th {
-        vertical-align: top;
-    }
-
-    .dataframe thead th {
-        text-align: right;
-    }
-</style>
-<table border="1" class="dataframe">
-  <thead>
-    <tr style="text-align: right;">
-      <th></th>
-      <th>LPUE</th>
-    </tr>
-    <tr>
-      <th>date</th>
-      <th></th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th>1993-01-01</th>
-      <td>0.47</td>
-    </tr>
-    <tr>
-      <th>1993-02-01</th>
-      <td>0.22</td>
-    </tr>
-  </tbody>
-</table>
-</div>
-
-
-
-
-```python
-fig = plot_time_series(df2, "LPUE", "$(kg/dop)$", auto_format_label=False)
-fig.show()
-```
-
-
-    
-![png](example/output_8_0.png)
-    
-
-
-
-```python
-save_figure(fig, file_name="LPUE")
-```
-
-## Example 2
-```python
-import jupyter_black
-
-jupyter_black.load()
-```
-
-
-```python
-import pandas as pd
-import warnings
-
-from direl_ts_tool_kit import (
-    plot_time_series,
-    parse_datetime_index,
-    remove_outliers_by_threshold,
-)
-
-warnings.filterwarnings("ignore")
-```
-
-
-```python
-df0 = pd.read_csv("Data_DHT11_4.csv")
-```
-
-
-```python
-df0 = df0.rename(columns={"Date": "date"})
-```
-
-
-```python
-df0.head(2)
-```
-
-
-
-
-<div>
-<style scoped>
-    .dataframe tbody tr th:only-of-type {
-        vertical-align: middle;
-    }
-
-    .dataframe tbody tr th {
-        vertical-align: top;
-    }
-
-    .dataframe thead th {
-        text-align: right;
-    }
-</style>
-<table border="1" class="dataframe">
-  <thead>
-    <tr style="text-align: right;">
-      <th></th>
-      <th>date</th>
-      <th>Temperature</th>
-      <th>Humidity</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th>0</th>
-      <td>4/07/2025 15:30:46</td>
-      <td>33.6</td>
-      <td>62.0</td>
-    </tr>
-    <tr>
-      <th>1</th>
-      <td>4/07/2025 15:40:53</td>
-      <td>33.4</td>
-      <td>62.0</td>
-    </tr>
-  </tbody>
-</table>
-</div>
-
-
-
-
-```python
-df1 = parse_datetime_index(df0, format="%d/%m/%Y %H:%M:%S")
-df1.head(2)
-```
-
-
-
-
-<div>
-<style scoped>
-    .dataframe tbody tr th:only-of-type {
-        vertical-align: middle;
-    }
-
-    .dataframe tbody tr th {
-        vertical-align: top;
-    }
-
-    .dataframe thead th {
-        text-align: right;
-    }
-</style>
-<table border="1" class="dataframe">
-  <thead>
-    <tr style="text-align: right;">
-      <th></th>
-      <th>Temperature</th>
-      <th>Humidity</th>
-    </tr>
-    <tr>
-      <th>date</th>
-      <th></th>
-      <th></th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th>2025-07-04 15:30:46</th>
-      <td>33.6</td>
-      <td>62.0</td>
-    </tr>
-    <tr>
-      <th>2025-07-04 15:40:53</th>
-      <td>33.4</td>
-      <td>62.0</td>
-    </tr>
-  </tbody>
-</table>
-</div>
-
-
-
-
-```python
-fig = plot_time_series(
-    df1,
-    variable="Temperature",
-    units="$(^\circ C)$",
-    time_unit="Day",
-    rot=0,
-)
-fig.show()
-```
-
-
-    
-![png](example/output_6_0.png)
-    
-
-
-
-```python
-df2 = remove_outliers_by_threshold(
-    df1, column_name="Temperature", lower_bound=30, upper_bound=32
-)
-```
-
-
-```python
-fig = plot_time_series(
-    df2,
-    variable="Temperature",
-    units="$(^\circ C)$",
-    time_unit="Day",
-    rot=0,
-    auto_format_label=False,
-)
-fig.show()
-```
-
-
-    
-![png](example/output_9_0.png)
-    

direl_ts_tool_kit-0.4.8.dist-info/RECORD

@@ -1,11 +0,0 @@
-direl_ts_tool_kit/__init__.py,sha256=W99Wd3BeEFKOxT51TApURElbDJvqIjD8u_-qDoCYSJ0,94
-direl_ts_tool_kit/plot/__init__.py,sha256=CMwyv-kiE74nwr3MJPL7gWIJmcfZ8UQCRu7mBGGQ4rI,49
-direl_ts_tool_kit/plot/plot_style.py,sha256=vhzcDa3LzgkHuy-GnliofGZ8TDntkm3_1C5kgl2Gx3E,1010
-direl_ts_tool_kit/plot/plot_ts.py,sha256=Fi_J-5qyDxcR-Z6sRHksn1e5QZcKqITGbpH3-bAX-Jw,5015
-direl_ts_tool_kit/utilities/__init__.py,sha256=jMtxYZUtwlhgI99sxe_8MMzsDnxtbTP7Ivh9tUOeIwQ,25
-direl_ts_tool_kit/utilities/data_prep.py,sha256=k3eOwQEEd5mxy2DtT_Gdo7BhkzEmSQqvMJ89y8mH5CQ,6024
-direl_ts_tool_kit-0.4.8.dist-info/licenses/LICENCE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-direl_ts_tool_kit-0.4.8.dist-info/METADATA,sha256=SKyYobCv0NBNvgDVP-b2q26m9HmTvavKr9LQVECGfEg,8888
-direl_ts_tool_kit-0.4.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-direl_ts_tool_kit-0.4.8.dist-info/top_level.txt,sha256=vMCRudnGnsdRg_6fUftnG8PF2Y1m0bjBDMf3pCAp6bc,18
-direl_ts_tool_kit-0.4.8.dist-info/RECORD,,