direl-ts-tool-kit 0.4.4__tar.gz → 0.4.8__tar.gz

direl_ts_tool_kit-0.4.8/PKG-INFO

@@ -0,0 +1,487 @@
+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)
+