Time Series Dashboard¶

The Time Series Dashboard provides a comprehensive web-based interface for time series analysis, visualization, and forecasting. It offers advanced analytical capabilities with an intuitive user interface for exploring temporal data patterns and generating predictions.

Note

This dashboard is currently under active development. Some features may be experimental or subject to change. If you encounter any issues or have suggestions, please open an issue in the GitHub repository.

Features¶

Multi-language Support: Available in English and Spanish
Data Upload: Support for CSV and Excel file formats with custom parsing options
Interactive Visualizations: Multiple plot types including original series, STL decomposition, lag analysis, and seasonality analysis
Automated Forecasting: Integration with StatsForecast for time series predictions
Cross-validation: Built-in model validation and error analysis
Model Comparison: Compare multiple forecasting models with performance metrics
Export Capabilities: Download results and generated code templates
Experimental Features: Advanced analysis tools (toggleable)

Main Application¶

Time Series App¶

mango_dashboard.time_series.dashboards.time_series_app.interface_visualization(project_name: str = None, logo_url: str = None, experimental_features: bool = False)¶

Main interface for the comprehensive time series visualization and forecasting dashboard.

This function creates a complete Streamlit-based dashboard for time series analysis, including data upload, visualization, and forecasting capabilities. It provides a multilingual interface (English/Spanish) with advanced features for time series exploration and model training.

Features:

Multi-language support (English/Spanish)
File upload and management (CSV/Excel)
Interactive time series visualization
Multiple plot types (original, STL, lag analysis, seasonality, periodogram)
Automated forecasting with StatsForecast
Cross-validation and error analysis
Model comparison and performance metrics
Data export capabilities
Experimental features toggle

Parameters:

project_name (str, optional) – Name of the project to display in the dashboard title
logo_url (str, optional) – URL or file path to the project logo (currently disabled)
experimental_features (bool, optional) – Flag to enable experimental visualization features

Returns:

None (creates Streamlit dashboard interface)

Return type:

None

Example:

>>> interface_visualization(
...     project_name="Sales Analysis",
...     experimental_features=True
... )
# Creates interactive time series dashboard

Utility Components¶

Data Loading and Processing¶

mango_dashboard.time_series.dashboards.time_series_utils.data_loader.load_data(files_loaded: Dict, ui_text: Dict)¶

Load and process data from uploaded files for time series visualization.

This function processes multiple data files and determines the appropriate visualization type based on the data structure. It handles both forecast data (with ‘forecast_origin’ and ‘f’ columns) and exploration data. For forecast data, it calculates error metrics including absolute error, percentage error, and their absolute values.

The function concatenates all dataframes and ensures consistency in visualization types across all loaded files.

Parameters:

files_loaded (Dict) – Dictionary mapping file names to their loaded data
ui_text (Dict) – Dictionary containing UI text and visualization options

Returns:

Tuple containing the concatenated dataframe and visualization type

Return type:

tuple[pd.DataFrame, str]

Raises:

ValueError – If files have inconsistent visualization types

Example:

>>> files = {
...     'data1.csv': {'data': df1},
...     'data2.csv': {'data': df2}
... }
>>> ui_text = {
...     'visualization_options': ['Exploration', 'Forecast']
... }
>>> df, viz_type = load_data(files, ui_text)
>>> print(f"Visualization type: {viz_type}")
Visualization type: Exploration

mango_dashboard.time_series.dashboards.time_series_utils.data_processing.aggregate_to_input_cache(data, freq, series_conf)¶

Cache wrapper for aggregate_to_input function.

This function provides caching for the aggregate_to_input operation to improve performance when processing time series data repeatedly.

Parameters:

data (pd.DataFrame) – Time series data to aggregate
freq (str) – Frequency for aggregation
series_conf (dict) – Configuration for series aggregation

Returns:

Aggregated time series data

Return type:

pd.DataFrame

mango_dashboard.time_series.dashboards.time_series_utils.data_processing.convert_df(df: pandas.DataFrame)¶

Convert DataFrame to CSV format with UTF-8 encoding.

This function converts a pandas DataFrame to CSV format and encodes it as UTF-8 bytes. The result is cached to prevent repeated computation on every Streamlit rerun.

Parameters:: df (pd.DataFrame) – DataFrame to convert to CSV
Returns:: CSV data encoded as UTF-8 bytes
Return type:: bytes

mango_dashboard.time_series.dashboards.time_series_utils.data_processing.calculate_horizon(df: pandas.DataFrame, freq: str) → pandas.DataFrame¶

Calculate the forecast horizon based on the selected frequency.

This function calculates the forecast horizon (h) by computing the time difference between the forecast datetime and the forecast origin. The calculation method depends on the frequency: - Hourly (h): Difference in hours - Daily (D): Difference in days - Weekly (W): Difference in weeks - Monthly (MS): Difference in months - Quarterly (QE): Difference in quarters - Yearly (YE): Difference in years

Parameters:

df (pd.DataFrame) – DataFrame with forecast data containing ‘datetime’ and ‘forecast_origin’ columns
freq (str) – Frequency code for horizon calculation

Returns:

DataFrame with added ‘h’ column containing horizon values

Return type:

pd.DataFrame

Raises:

ValueError – If the frequency is not supported

Example:

>>> df = pd.DataFrame({
...     'datetime': ['2023-01-02', '2023-01-03'],
...     'forecast_origin': ['2023-01-01', '2023-01-01']
... })
>>> result = calculate_horizon(df, 'D')
>>> print(result['h'].tolist())
[1, 2]

mango_dashboard.time_series.dashboards.time_series_utils.data_processing.process_data(data: pandas.DataFrame, columns_id: List, select_agr_tmp_dict: Dict, select_agr_tmp: str, ui_text: Dict)¶

Process input data for time series analysis and visualization.

This function processes time series data based on the selected visualization type (exploration or forecast). It handles data aggregation, datetime conversion, and prepares data for both time series analysis and forecast evaluation.

For exploration mode, it returns aggregated time series data. For forecast mode, it additionally processes forecast data with error metrics and calculates forecast horizons.

Parameters:

data (pd.DataFrame) – Input DataFrame containing time series data
columns_id (List[str]) – List of column names to use as identifiers
select_agr_tmp_dict (Dict) – Dictionary mapping aggregation options to frequency codes
select_agr_tmp (str) – Selected aggregation option key
ui_text (Dict) – Dictionary containing UI text and visualization options

Returns:

Tuple containing (time_series_data, forecast_data)

Return type:

tuple[pd.DataFrame, pd.DataFrame | None]

Example:

>>> data = pd.DataFrame({
...     'datetime': ['2023-01-01', '2023-01-02'],
...     'y': [100, 110],
...     'model': ['model1', 'model1']
... })
>>> time_series, forecast = process_data(
...     data, ['model'], {'daily': 'D'}, 'daily', ui_text
... )

mango_dashboard.time_series.dashboards.time_series_utils.data_processing.calculate_min_diff_per_window(df: pandas.DataFrame) → float¶

Calculate the minimum time difference between consecutive timestamps.

This function calculates the minimum time difference between consecutive timestamps in a time series. It handles different time scales automatically: - For differences >= 28 days, it uses day-based calculation - For smaller differences, it uses second-based calculation converted to days

Parameters:: df (pd.DataFrame) – DataFrame containing a ‘datetime’ column with timestamps
Returns:: Minimum time difference in days (or days for large differences)
Return type:: float

Example:

>>> df = pd.DataFrame({
...     'datetime': pd.to_datetime(['2023-01-01', '2023-01-02', '2023-01-05'])
... })
>>> min_diff = calculate_min_diff_per_window(df)
>>> print(min_diff)
1.0

mango_dashboard.time_series.dashboards.time_series_utils.data_processing.render_script(models: List, horizon: int, step_size: int, n_windows: int, freq_code: str)¶

Render a Python script from a Jinja2 template for forecast generation.

This function generates a Python script by rendering a Jinja2 template with the provided parameters. The template is used to create forecast generation scripts with the specified models, horizon, and configuration.

Parameters:

models (List[str]) – List of model names to include in the script
horizon (int) – Forecast horizon (number of periods to forecast)
step_size (int) – Step size for rolling window forecasts
n_windows (int) – Number of forecast windows
freq_code (str) – Frequency code for the time series

Returns:

Rendered Python script as a string

Return type:

str

Example:

>>> script = render_script(
...     models=['ARIMA', 'Prophet'],
...     horizon=30,
...     step_size=7,
...     n_windows=4,
...     freq_code='D'
... )
>>> print(script[:100])
# Generated forecast script...

File Management¶

mango_dashboard.time_series.dashboards.time_series_utils.file_uploader.preview_data(uploaded_file, separator, decimal, thousands, encoding, date_format, ui_text)¶

Preview data from an uploaded file with specified parsing parameters.

This function displays a preview of the uploaded file data using the specified parsing parameters. It handles CSV files with custom separators, decimal/thousands separators, encoding, and date formats. Automatically converts datetime columns if they exist in the data.

Parameters:

uploaded_file (UploadedFile) – The uploaded file object from Streamlit
separator (str) – Field separator used in the CSV file
decimal (str) – Decimal separator for numeric values
thousands (str) – Thousands separator for numeric values
encoding (str) – Text encoding of the file
date_format (str) – Date format for datetime parsing
ui_text (Dict) – Dictionary containing UI text labels

Returns:

None

Return type:

None

Example:

>>> preview_data(
...     uploaded_file, ',', '.', ',', 'utf-8', '%Y-%m-%d', ui_text
... )
# Displays preview of the uploaded data

mango_dashboard.time_series.dashboards.time_series_utils.file_uploader.upload_files(ui_text: Dict)¶

Upload and configure multiple files for time series analysis.

This function provides a file upload interface that allows users to upload CSV and Excel files with custom parsing parameters. It creates a form-based interface for configuring file-specific settings like separators, encoding, and date formats. Automatically handles model column detection and creation.

Features:

Support for CSV and Excel files
Custom parsing parameters per file
Automatic datetime column detection and conversion
Model column auto-creation if missing
Form-based configuration interface

Parameters:: ui_text (Dict) – Dictionary containing UI text labels and messages
Returns:: Tuple containing (files_loaded_dict, no_model_column_flag)
Return type:: tuple[Dict, bool]

Example:

>>> files_loaded, no_model = upload_files(ui_text)
>>> print(f"Loaded {len(files_loaded)} files")
Loaded 3 files

mango_dashboard.time_series.dashboards.time_series_utils.file_uploader.manage_files(files_loaded, ui_text)¶

Manage and update previously uploaded files.

This function provides a management interface in the sidebar for updating or removing previously uploaded files. Users can modify file names, parsing parameters, and remove files from the analysis. Changes are applied immediately and trigger a Streamlit rerun.

Features:

File name editing
Parsing parameter updates (for CSV files)
File removal functionality
Automatic session state updates
Model column synchronization

Parameters:

files_loaded (Dict) – Dictionary of currently loaded files with their configurations
ui_text (Dict) – Dictionary containing UI text labels and messages

Returns:

None (updates session state directly)

Return type:

None

Example:

>>> manage_files(files_loaded, ui_text)
# Updates files in sidebar with management options

User Interface Components¶

mango_dashboard.time_series.dashboards.time_series_utils.ui_components.select_series(data: pandas.DataFrame, columns: List, ui_text: Dict)¶

Create a sidebar interface for selecting time series based on specified columns.

This function creates a cascading selection interface in the sidebar where users can filter time series data by selecting values from specified columns. Each column creates a selectbox that filters the data progressively, allowing for hierarchical selection of specific time series.

Parameters:

data (pd.DataFrame) – DataFrame containing the time series data with filtering columns
columns (List) – List of column names to use for filtering the series
ui_text (Dict) – Dictionary containing UI text labels and messages

Returns:

Dictionary containing the selected values for each column

Return type:

Dict

Example:

>>> selected = select_series(data, ['region', 'product'], ui_text)
>>> print(selected)
{'region': 'North', 'product': 'Widget A'}

mango_dashboard.time_series.dashboards.time_series_utils.ui_components.plot_time_series(time_series: pandas.DataFrame, selected_series: List, select_agr_tmp_dict: Dict, select_agr_tmp: str, ui_text: Dict, columns_id_name: str, experimental_features: bool)¶

Create interactive time series visualizations with multiple plot types.

This function provides a comprehensive plotting interface for time series analysis, offering six different visualization types:

Original Series: Basic line plots with date range selection
Series by Year: Yearly comparisons with multi-year selection
STL Decomposition: Seasonal and Trend decomposition using Loess
Lag Analysis: ACF and PACF plots for autocorrelation analysis
Seasonality Boxplots: Distribution analysis by time periods
Periodogram: Frequency domain analysis for seasonality detection

Features:

Interactive date range selection
Multiple series comparison with scaling options
Automatic seasonality detection
Experimental features toggle
Responsive plot layouts

Parameters:

time_series (pd.DataFrame) – DataFrame containing time series data with datetime and y columns
selected_series (List) – List of selected series dictionaries for plotting
select_agr_tmp_dict (Dict) – Dictionary mapping temporal grouping to pandas frequency strings
select_agr_tmp (str) – Selected temporal aggregation option
ui_text (Dict) – Dictionary containing UI text labels and messages
columns_id_name (str) – Name of the column containing series identifiers
experimental_features (bool) – Flag to enable experimental visualization features

Returns:

None (displays plots in Streamlit interface)

Return type:

None

Example:

>>> plot_time_series(
...     time_series, selected_series, freq_dict, 'daily', ui_text, 'id', True
... )
# Displays interactive time series plots

mango_dashboard.time_series.dashboards.time_series_utils.ui_components.setup_sidebar(time_series: pandas.DataFrame, columns_id: List, ui_text: Dict, columns_id_name: str)¶

Set up the main sidebar interface for time series analysis dashboard.

This function creates the primary navigation and configuration interface in the sidebar, including visualization mode selection, temporal grouping options, and series selection management. It automatically determines available temporal aggregations based on data frequency and manages series selection state.

Features:

Visualization mode selection (time series vs forecast analysis)
Dynamic temporal grouping based on data frequency
Series selection and management interface
Automatic forecast mode detection
Session state management for selections

Parameters:

time_series (pd.DataFrame) – DataFrame containing time series data with datetime column
columns_id (List) – List of column names to use as series identifiers
ui_text (Dict) – Dictionary containing UI text labels and messages
columns_id_name (str) – Name of the primary identifier column

Returns:

Tuple containing (temporal_grouping, visualization_mode, available_options, selected_series)

Return type:

tuple[str, str, List, List]

Example:

>>> grouping, viz_mode, options, series = setup_sidebar(
...     time_series, ['region', 'product'], ui_text, 'id'
... )
>>> print(f"Selected grouping: {grouping}")
Selected grouping: daily

mango_dashboard.time_series.dashboards.time_series_utils.ui_components.plot_forecast(forecast: pandas.DataFrame, selected_series: List, ui_text: Dict, columns_id_name: str)¶

Create interactive forecast visualization plots with error analysis.

This function generates comprehensive forecast plots showing both actual and predicted values with detailed error metrics. It supports multiple models comparison and provides interactive date selection for forecast origin analysis.

Features:

Interactive forecast origin date selection
Multiple model comparison with color coding
Detailed hover information with error metrics
Weekday information display
Automatic legend and label management
Error calculation and display

Parameters:

forecast (pd.DataFrame) – DataFrame containing forecast data with y, f, and error columns
selected_series (List) – List of selected series dictionaries for plotting
ui_text (Dict) – Dictionary containing UI text labels and messages
columns_id_name (str) – Name of the column containing series identifiers

Returns:

None (displays forecast plots in Streamlit interface)

Return type:

None

Example:

>>> plot_forecast(forecast_data, selected_series, ui_text, 'series_id')
# Displays interactive forecast plots with error analysis

mango_dashboard.time_series.dashboards.time_series_utils.ui_components.plot_error_visualization(forecast: pandas.DataFrame, selected_series: List, ui_text: Dict[str, str], freq: str = None, columns_id_name: str = None)¶

Create comprehensive error analysis visualizations for forecast evaluation.

This function provides detailed error analysis through multiple visualization types and statistical summaries. It includes filtering capabilities, model comparison, and various error distribution analyses.

Features:

Dual filtering (datetime and forecast origin ranges)
Top 10 error identification by model
Statistical summaries (mean/median errors and percentiles)
Multiple plot types: box plots, scatter plots, horizon analysis
Model performance ranking
Interactive percentile selection
Temporal aggregation options

Parameters:

forecast (pd.DataFrame) – DataFrame containing forecast data with error metrics
selected_series (List) – List of selected series dictionaries for analysis
ui_text (Dict[str, str]) – Dictionary containing UI text labels and messages
freq (str, optional) – Frequency string for time series (e.g., ‘D’, ‘H’, ‘M’)
columns_id_name (str, optional) – Name of the column containing series identifiers

Returns:

None (displays error analysis in Streamlit interface)

Return type:

None

Example:

>>> plot_error_visualization(
...     forecast_data, selected_series, ui_text, 'D', 'series_id'
... )
# Displays comprehensive error analysis dashboard

mango_dashboard.time_series.dashboards.time_series_utils.ui_components.pad_to_end_of_year(df, year)¶

Pad DataFrame with null values to extend data until the end of the specified year.

This utility function extends a time series DataFrame by adding null values from the last available date to December 31st of the specified year. This is useful for creating consistent yearly visualizations where some series may end before the year’s end.

Parameters:

df (pd.DataFrame) – DataFrame with datetime column to be padded
year (int) – Year to pad until (integer)

Returns:

DataFrame extended with null values until end of year

Return type:

pd.DataFrame

Example:

>>> df_padded = pad_to_end_of_year(df, 2023)
>>> print(df_padded['datetime'].max())
2023-12-31 23:59:59

Configuration¶

Usage¶

The Time Series Dashboard can be launched using Streamlit:

streamlit run mango_dashboard/time_series/dashboards/time_series_app.py

Environment Variables¶

The dashboard can be configured using the following environment variables:

TS_DASHBOARD_PROJECT_NAME: Set the project name displayed in the dashboard
TS_DASHBOARD_EXPERIMENTAL_FEATURES: Enable experimental features (true/false)