direl-ts-tool-kit 0.4.8

A toolbox for time series analysis and visualization.

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

import jupyter_black

jupyter_black.load()

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")

df0 = pd.read_csv("dataset_test_01.csv")

df0.head(2)

<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>

	date	LPUE	common name
0	1993-01-01	0.47	camaron blanco
1	1993-02-01	0.22	camaron blanco

df1 = parse_datetime_index(df0)
df1.head(2)

<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>

	LPUE	common name
date
1993-01-01	0.47	camaron blanco
1993-02-01	0.22	camaron blanco

fig = plot_time_series(df1, "LPUE", "$(kg/dop)$", auto_format_label=False)
fig.show()

save_figure(fig, file_name="LPUE_raw")

df2 = reindex_and_aggregate(df1, column_name="LPUE")
df2.head(2)

<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>

	LPUE
date
1993-01-01	0.47
1993-02-01	0.22

fig = plot_time_series(df2, "LPUE", "$(kg/dop)$", auto_format_label=False)
fig.show()

save_figure(fig, file_name="LPUE")

Example 2

import jupyter_black

jupyter_black.load()

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")

df0 = pd.read_csv("Data_DHT11_4.csv")

df0 = df0.rename(columns={"Date": "date"})

df0.head(2)

<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>

	date	Temperature	Humidity
0	4/07/2025 15:30:46	33.6	62.0
1	4/07/2025 15:40:53	33.4	62.0

df1 = parse_datetime_index(df0, format="%d/%m/%Y %H:%M:%S")
df1.head(2)

<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>

	Temperature	Humidity
date
2025-07-04 15:30:46	33.6	62.0
2025-07-04 15:40:53	33.4	62.0

fig = plot_time_series(
    df1,
    variable="Temperature",
    units="$(^\circ C)$",
    time_unit="Day",
    rot=0,
)
fig.show()

df2 = remove_outliers_by_threshold(
    df1, column_name="Temperature", lower_bound=30, upper_bound=32
)

fig = plot_time_series(
    df2,
    variable="Temperature",
    units="$(^\circ C)$",
    time_unit="Day",
    rot=0,
    auto_format_label=False,
)
fig.show()