AeroViz 0.1.14__py3-none-any.whl → 0.1.15__py3-none-any.whl

AeroViz/dataProcess/Optical/_absorption.py

@@ -5,9 +5,11 @@ def _absCoe(df, instru, specified_band: list):
 
     band_AE33 = np.array([370, 470, 520, 590, 660, 880, 950])
     band_BC1054 = np.array([370, 430, 470, 525, 565, 590, 660, 700, 880, 950])
+    band_MA350 = np.array([375, 470, 528, 625, 880])
 
     MAE_AE33 = np.array([18.47, 14.54, 13.14, 11.58, 10.35, 7.77, 7.19]) * 1e-3
     MAE_BC1054 = np.array([18.48, 15.90, 14.55, 13.02, 12.10, 11.59, 10.36, 9.77, 7.77, 7.20]) * 1e-3
+    MAE_MA350 = np.array([24.069, 19.070, 17.028, 14.091, 10.120]) * 1e-3
 
     band = band_AE33 if instru == 'AE33' else band_BC1054
     MAE = MAE_AE33 if instru == 'AE33' else MAE_BC1054

AeroViz/plot/templates/__init__.py

@@ -1,6 +1,6 @@
 from .ammonium_rich import ammonium_rich
 from .contour import *
-from .corr_matrix import corr_matrix
+from .corr_matrix import corr_matrix, cross_corr_matrix
 from .diurnal_pattern import *
 from .koschmieder import *
 from .metal_heatmap import metal_heatmaps, process_data_with_two_df

AeroViz/plot/templates/corr_matrix.py

@@ -9,18 +9,20 @@ from scipy.stats import pearsonr
 
 from AeroViz.plot.utils import *
 
-__all__ = ['corr_matrix']
+__all__ = ['corr_matrix', 'cross_corr_matrix']
 
 
 @set_figure
 def corr_matrix(data: pd.DataFrame,
                 cmap: str = "RdBu",
                 ax: Axes | None = None,
+                items_order: list = None,  # 新增參數用於指定順序
                 **kwargs
                 ) -> tuple[Figure, Axes]:
     fig, ax = plt.subplots(**kwargs.get('fig_kws', {})) if ax is None else (ax.get_figure(), ax)
 
     _corr = data.corr()
+    breakpoint()
     corr = pd.melt(_corr.reset_index(), id_vars='index')
     corr.columns = ['x', 'y', 'value']
 
@@ -94,8 +96,172 @@ def corr_matrix(data: pd.DataFrame,
         label='p < 0.05'
     )
 
-    ax.legend(handles=[point2], labels=['p < 0.05'], bbox_to_anchor=(0.05, 1, 0.1, 0.05))
+    ax.legend(handles=[point2], labels=['p < 0.05'], bbox_to_anchor=(0.02, 1, 0.05, 0.05))
 
     plt.show()
 
     return fig, ax
+
+
+@set_figure(figsize=(6, 6))
+def cross_corr_matrix(data1: pd.DataFrame,
+                      data2: pd.DataFrame,
+                      cmap: str = "RdBu",
+                      ax: Axes | None = None,
+                      items_order: list = None,  # 新增參數用於指定順序
+                      **kwargs
+                      ) -> tuple[Figure, Axes]:
+    """
+    Create a correlation matrix between two different DataFrames.
+
+    Parameters:
+    -----------
+    data1 : pd.DataFrame
+        First DataFrame
+    data2 : pd.DataFrame
+        Second DataFrame
+    cmap : str, optional
+        Color map for the correlation matrix
+    ax : Axes, optional
+        Matplotlib axes to plot on
+    items_order : list, optional
+        List specifying the order of items to display
+    **kwargs : dict
+        Additional keyword arguments
+    """
+    if ax is None:
+        fig_kws = kwargs.get('fig_kws', {})
+        default_figsize = fig_kws.get('figsize', (8, 8))
+        fig = plt.figure(figsize=default_figsize)
+        ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
+    else:
+        fig = ax.get_figure()
+
+    # 如果沒有指定順序，使用原始列名順序
+    if items_order is None:
+        x_labels = list(data1.columns)
+        y_labels = list(data2.columns)
+    else:
+        # 使用指定順序，但只包含實際存在於數據中的列
+        x_labels = [item for item in items_order if item in data1.columns]
+        y_labels = [item for item in items_order if item in data2.columns]
+
+    # Calculate cross-correlation between the two DataFrames
+    correlations = []
+    p_values_list = []
+
+    for col1 in x_labels:  # 使用指定順序的列名
+        for col2 in y_labels:
+            try:
+                mask = ~(np.isnan(data1[col1]) | np.isnan(data2[col2]))
+                if mask.sum() > 2:
+                    corr, p_val = pearsonr(data1[col1][mask], data2[col2][mask])
+                else:
+                    corr, p_val = np.nan, np.nan
+            except Exception as e:
+                print(f"Error calculating correlation for {col1} and {col2}: {str(e)}")
+                corr, p_val = np.nan, np.nan
+
+            correlations.append({
+                'x': col1,
+                'y': col2,
+                'value': corr
+            })
+            if p_val is not None and p_val < 0.05:
+                p_values_list.append({
+                    'x': col1,
+                    'y': col2,
+                    'value': p_val
+                })
+
+    corr = pd.DataFrame(correlations)
+    p_values = pd.DataFrame(p_values_list)
+
+    # Create mapping using the specified order
+    x_to_num = {label: i for i, label in enumerate(x_labels)}
+    y_to_num = {label: i for i, label in enumerate(y_labels)}
+
+    # 調整標籤顯示
+    ax.set_xticks([x_to_num[v] for v in x_labels])
+    ax.set_xticklabels(x_labels, rotation=45, ha='right')
+    ax.set_yticks([y_to_num[v] for v in y_labels])
+    ax.set_yticklabels(y_labels)
+
+    ax.grid(False, 'major')
+    ax.grid(True, 'minor')
+    ax.set_xticks([t + 0.5 for t in ax.get_xticks()], minor=True)
+    ax.set_yticks([t + 0.5 for t in ax.get_yticks()], minor=True)
+
+    ax.set_xlim([-0.5, max([v for v in x_to_num.values()]) + 0.5])
+    ax.set_ylim([-0.5, max([v for v in y_to_num.values()]) + 0.5])
+
+    # Color mapping
+    n_colors = 256
+    palette = sns.color_palette(cmap, n_colors=n_colors)
+    color_min, color_max = [-1, 1]
+
+    def value_to_color(val):
+        if pd.isna(val):
+            return (1, 1, 1)
+        val_position = float((val - color_min)) / (color_max - color_min)
+        val_position = np.clip(val_position, 0, 1)
+        ind = int(val_position * (n_colors - 1))
+        return palette[ind]
+
+    # Plot correlation squares
+    x_coords = corr['x'].map(x_to_num)
+    y_coords = corr['y'].map(y_to_num)
+    sizes = corr['value'].abs().fillna(0) * 70
+    colors = [value_to_color(val) for val in corr['value']]
+
+    point = ax.scatter(
+        x=x_coords,
+        y=y_coords,
+        s=sizes,
+        c=colors,
+        marker='s',
+        label='$R^{2}$'
+    )
+
+    # 調整顏色軸的位置和大小
+    cax = fig.add_axes([0.91, 0.1, 0.02, 0.8])
+    axes_image = plt.cm.ScalarMappable(cmap=colormaps[cmap])
+    cbar = plt.colorbar(mappable=axes_image, cax=cax, label=r'$R^{2}$')
+    cbar.set_ticks([0, 0.25, 0.5, 0.75, 1])
+    cbar.set_ticklabels(np.linspace(-1, 1, 5))
+
+    # Plot significance markers
+    if not p_values.empty:
+        point2 = ax.scatter(
+            x=p_values['x'].map(x_to_num),
+            y=p_values['y'].map(y_to_num),
+            s=10,
+            marker='*',
+            color='k',
+            label='p < 0.05'
+        )
+        ax.legend(handles=[point2], labels=['p < 0.05'],
+                  bbox_to_anchor=(0.005, 1.04), loc='upper left')
+
+    # Add labels
+    ax.set_xlabel('NZ', labelpad=10)
+    ax.set_ylabel('FS', labelpad=10)
+
+    plt.show()
+
+    return fig, ax
+
+
+if __name__ == '__main__':
+    import pandas as pd
+    from pandas import to_numeric
+
+    df_NZ = pd.read_csv('/Users/chanchihyu/Desktop/NZ_minion_202402-202411.csv', parse_dates=True, index_col=0)
+    df_FS = pd.read_csv('/Users/chanchihyu/Desktop/FS_minion_202402-202411.csv', parse_dates=True, index_col=0)
+
+    items = ['Ext', 'Sca', 'Abs', 'PNC', 'PSC', 'PVC', 'SO2', 'NO', 'NOx', 'NO2', 'CO', 'O3', 'THC', 'NMHC', 'CH4',
+             'PM10', 'PM2.5', 'WS', 'AT', 'RH',
+             'OC', 'EC', 'Na+', 'NH4+', 'NO3-', 'SO42-', 'Al', 'Si', 'Ca', 'Ti', 'V', 'Cr', 'Mn', 'Fe', 'Cu', 'Zn']
+    df_NZ = df_NZ.apply(to_numeric, errors='coerce')
+
+    corr_matrix(df_NZ[items], items_order=items)

AeroViz/plot/templates/metal_heatmap.py

@@ -117,11 +117,11 @@ def normalize_and_split(df, df2):
     return df, df2
 
 
-@set_figure(figsize=(12, 3), fs=6)
+@set_figure(figsize=(6, 3), fs=8, fw='normal')
 def metal_heatmaps(df,
                    process=True,
-                   major_freq='24h',
-                   minor_freq='12h',
+                   major_freq='10d',
+                   minor_freq='1d',
                    cmap='jet',
                    ax: Axes | None = None,
                    **kwargs
@@ -131,7 +131,7 @@ def metal_heatmaps(df,
 
     fig, ax = plt.subplots(**kwargs.get('fig_kws', {})) if ax is None else (ax.get_figure(), ax)
 
-    sns.heatmap(df.T, vmin=None, vmax=3, cmap=cmap, xticklabels=False, yticklabels=True,
+    sns.heatmap(df.T, vmin=None, vmax=3, cmap=cmap, xticklabels=True, yticklabels=True,
                 cbar_kws={'label': 'Z score', "pad": 0.02})
     ax.grid(color='gray', linestyle='-', linewidth=0.3)
 
@@ -142,14 +142,23 @@ def metal_heatmaps(df,
     # Set the major and minor ticks
     ax.set_xticks(ticks=[df.index.get_loc(t) for t in major_tick])
     ax.set_xticks(ticks=[df.index.get_loc(t) for t in minor_tick], minor=True)
-    ax.set_xticklabels(major_tick.strftime('%F'))
+    ax.set_xticklabels(major_tick.strftime('%F'), rotation=0)
     ax.tick_params(axis='y', rotation=0)
 
     ax.set(xlabel='',
-           ylabel='',
+           ylabel='Trace metals',
            title=kwargs.get('title', None)
            )
 
+    if kwargs.get('savefig'):
+        plt.savefig(kwargs.get('savefig'), dpi=600)
+
     plt.show()
 
     return fig, ax
+
+
+if __name__ == '__main__':
+    fig, ax = plt.subplots(1, 1, figsize=(6, 6))
+    plt.title('text', font={'weight': 'bold'})
+    plt.show()

AeroViz/plot/timeseries/timeseries.py

@@ -2,6 +2,7 @@ from typing import Literal
 
 import matplotlib.pyplot as plt
 import numpy as np
+import pandas as pd
 from matplotlib.cm import ScalarMappable
 from matplotlib.pyplot import Figure, Axes
 from mpl_toolkits.axes_grid1 import make_axes_locatable
@@ -12,7 +13,6 @@ from AeroViz.plot.utils import *
 
 __all__ = ['timeseries', 'timeseries_stacked']
 
-
 default_bar_kws = dict(
     width=0.0417,
     edgecolor=None,
@@ -105,12 +105,20 @@ def _wind_arrow(ax, df, y, c, scatter_kws, cbar_kws, inset_kws):
     # ax.set_xlim(df.index.min() - datetime.timedelta(days=1), df.index.max())
 
 
-def process_timeseries_data(df, rolling=None, interpolate_limit=None):
-    # apply rolling window if specified
-    df = df.rolling(window=rolling, min_periods=1).mean(numeric_only=True) if rolling is not None else df
+def process_timeseries_data(df, rolling=None, interpolate_limit=None, full_time_index=None):
+    # 1. 先建立完整的時間索引
+    if full_time_index is None:
+        full_time_index = pd.date_range(start=df.index.min(), end=df.index.max(), freq='h')  # 或其他適合的頻率
+
+    # 2. 重新索引，這會產生缺失值而不是丟棄時間點
+    df = df.reindex(full_time_index)
 
     # apply interpolation if specified
     df = df.interpolate(method='time', limit=interpolate_limit) if interpolate_limit is not None else df
+
+    # apply rolling window if specified
+    df = df.rolling(window=rolling, min_periods=1).mean(numeric_only=True) if rolling is not None else df
+
     return df
 
 
@@ -313,17 +321,18 @@ def timeseries(df: DataFrame,
     return fig, ax
 
 
-@set_figure(autolayout=False)
+@set_figure(figsize=(6, 3), fs=6, autolayout=False)
 def timeseries_stacked(df,
                        y: list[str] | str,
                        yi: list[str] | str,
                        label: list[str] | str,
-                       rolling: int | str | None = 6,
-                       interpolate_limit: int | None = 6,
-                       major_freq: str = '1MS',
-                       minor_freq: str = '10d',
+                       plot_type: Literal["absolute", "percentage", "both"] | str = 'both',
+                       rolling: int | str | None = 4,
+                       interpolate_limit: int | None = 4,
+                       major_freq: str = '10d',
+                       minor_freq: str = '1d',
+                       support_df: DataFrame | None = None,
                        ax: Axes | None = None,
-                       legend_ncol: int = 1,
                        **kwargs
                        ) -> tuple[Figure, Axes]:
     try:
@@ -331,17 +340,30 @@ def timeseries_stacked(df,
     except IndexError:
         raise IndexError("The DataFrame is empty. Please provide a valid DataFrame.")
 
+    if plot_type not in ['absolute', 'percentage', 'both']:
+        raise ValueError("plot_type must be one of 'absolute', 'percentage', or 'both'")
+
     # calculate the percentage of each component
+    df = df.dropna()
     df_pct = df[yi].div(df[yi].sum(axis=1), axis=0) * 100
+
     mean = [f"{_label} : {df[comp].mean():.2f}" for _label, comp in zip(label, yi)]
     pct = [f"{_label} : {df_pct[comp].mean():.2f}%" for _label, comp in zip(label, yi)]
 
+    full_time_index = pd.date_range(start=st_tm, end=fn_tm, freq='h')
+
     # process data
-    df = process_timeseries_data(df, rolling, interpolate_limit)
-    df_pct = process_timeseries_data(df_pct, rolling, interpolate_limit)
+    df = process_timeseries_data(df, rolling, interpolate_limit, full_time_index)
+    df_pct = process_timeseries_data(df_pct, rolling, interpolate_limit, full_time_index)
 
-    fig, (ax1, ax2) = plt.subplots(2, 1, **{**{'figsize': (12, 3)}, **kwargs.get('fig_kws', {})})
+    # Set figure size based on plot_type
+    figsize = (7, 6) if plot_type == 'both' else (7, 3)
+    if plot_type == 'both':
+        fig, (ax1, ax2) = plt.subplots(2, 1, **{**{'figsize': figsize, 'dpi': 600}, **kwargs.get('fig_kws', {})})
+    else:
+        fig, ax1 = plt.subplots(1, 1, **{**{'figsize': figsize, 'dpi': 600}, **kwargs.get('fig_kws', {})})
 
+    plt.subplots_adjust(right=0.95)
     width = 0.0417
     color = Color.colors1
 
@@ -349,54 +371,76 @@ def timeseries_stacked(df,
         if len(lst) != len(yi):
             raise ValueError(f"The length of {name} must match the combined length of y and y2")
 
-    bottom = None  # 初始化堆疊位置
-    for i, (_column, _color, _label) in enumerate(zip(yi, color, mean)):
-        if i == 0:
-            bottom = df[_column] * 0  # 第一個堆疊底部為零
-        ax1.bar(df.index, df[_column], color=_color, width=width, bottom=bottom, label=_label)
-        bottom += df[_column]  # 更新堆疊底部位置
+    def plot_stacked_bars(ax, data, labels, is_percentage=False):
+        bottom = None
+        for i, (_column, _color, _label) in enumerate(zip(yi, color, labels)):
+            if i == 0:
+                bottom = data[_column] * 0
+            ax.bar(data.index, data[_column], color=_color, width=width, bottom=bottom, label=_label)
+            bottom += data[_column]
 
-    ax1.legend(loc='upper left', ncol=legend_ncol, prop={'weight': 'bold'}, bbox_to_anchor=(1, 0, 1.2, 1))
+        # Set axis properties
+        if kwargs.get('legend', True):
+            ax.legend(loc='upper left', ncol=2, prop={'weight': 'bold'}, bbox_to_anchor=(0.75, 0, 0.2, 1))
 
-    ax1.axes.xaxis.set_visible(False)
+        ylim = (0, 100) if is_percentage else kwargs.get('ylim', (None, None))
+        ylabel = 'Percentage (%)' if is_percentage else (
+            kwargs.get('ylabel', Unit(y) if isinstance(y, str) else Unit(y[0])))
 
-    ax1.set(xlabel=kwargs.get('xlabel', ''),
-            ylabel=kwargs.get('ylabel', Unit(y) if isinstance(y, str) else Unit(y[0])),
-            xlim=kwargs.get('xlim', (st_tm, fn_tm)),
-            ylim=kwargs.get('ylim', (None, None)),
-            title=kwargs.get('title', ''),
-            )
+        ax.set(xlabel=kwargs.get('xlabel', ''),
+               xlim=kwargs.get('xlim', (st_tm, fn_tm)),
+               ylim=ylim,
+               title=kwargs.get('title', ''))
 
-    xticks = kwargs.get('xticks', date_range(start=st_tm, end=fn_tm, freq=major_freq))
-    yticks = kwargs.get('yticks', np.linspace(*ax1.get_ylim(), num=6))
-    minor_xticks = kwargs.get('minor_xticks', date_range(start=st_tm, end=fn_tm, freq=minor_freq))
+        ax.set_ylabel(ylabel, fontsize=12)
 
-    ax1.set_xticks(ticks=xticks, labels=xticks.strftime("%F"))
-    ax1.set_yticks(ticks=yticks, labels=[f'{tick:.0f}' for tick in yticks])
-    ax1.set_xticks(minor_xticks, minor=True)
+        # Set ticks
+        xticks = kwargs.get('xticks', date_range(start=st_tm, end=fn_tm, freq=major_freq))
+        yticks = kwargs.get('yticks', np.linspace(*ax.get_ylim(), num=6))
+        minor_xticks = kwargs.get('minor_xticks', date_range(start=st_tm, end=fn_tm, freq=minor_freq))
 
-    # ax2
-    bottom = None  # 初始化堆疊位置
-    for i, (_column, _color, _label) in enumerate(zip(yi, color, pct)):
-        if i == 0:
-            bottom = df_pct[_column] * 0  # 第一個堆疊底部為零
-        ax2.bar(df_pct.index, df_pct[_column], color=_color, width=width, bottom=bottom, label=_label)
-        bottom += df_pct[_column]  # 更新堆疊底部位置
+        ax.set_xticks(ticks=xticks, labels=xticks.strftime("%F"))
+        ax.set_yticks(ticks=yticks, labels=[f'{tick:.0f}' for tick in yticks])
+        ax.set_xticks(minor_xticks, minor=True)
 
-    ax2.legend(loc='upper left', ncol=legend_ncol, prop={'weight': 'bold'}, bbox_to_anchor=(1, 0, 1.2, 1))
+    # Plot based on plot_type
+    if plot_type in ['absolute', 'both']:
+        plot_stacked_bars(ax1, df, mean, is_percentage=False)
+        if plot_type == 'absolute':
+            ax1.axes.xaxis.set_visible(True)
 
-    ax2.set(xlabel=kwargs.get('xlabel', ''),
-            ylabel=kwargs.get('ylabel', 'Percentage (%)'),
-            xlim=kwargs.get('xlim', (st_tm, fn_tm)),
-            ylim=(0, 100),
-            )
+        if support_df is not None:  # 確保support_df存在
+            # 創建次要Y軸
+            ax_right = ax1.twinx()
 
-    xticks = kwargs.get('xticks', date_range(start=st_tm, end=fn_tm, freq=major_freq))
-    yticks = kwargs.get('yticks', np.linspace(*ax2.get_ylim(), num=6))
-    minor_xticks = kwargs.get('minor_xticks', date_range(start=st_tm, end=fn_tm, freq=minor_freq))
+            support_df = process_timeseries_data(support_df, rolling, interpolate_limit, full_time_index)
+
+            # 繪製線圖在次要Y軸上
+            ax_right.plot(support_df.index, support_df['PM2.5'],
+                          color='black', linewidth=1.5,
+                          label=f'Measured $PM_{{2.5}}$')
 
-    ax2.set_xticks(ticks=xticks, labels=xticks.strftime("%F"))
-    ax2.set_yticks(ticks=yticks, labels=[f'{tick:.0f}' for tick in yticks])
-    ax2.set_xticks(minor_xticks, minor=True)
+            # ax_right.plot(support_df.index, support_df['PM10'],
+            #               color='gray', linewidth=1.5,
+            #               label=f'Measured $PM_{{10}}$')
 
+            # 設置次要Y軸的標籤和格式
+            # ax_right.set_ylabel(Unit('PM2.5'), fontsize=12)
+            ax_right.set_ylim(0, 120)
+            ax_right.axes.yaxis.set_visible(False)
+
+            # ax_right.tick_params(axis='y', colors='black')
+            # ax_right.legend(loc='upper right', prop={'size': 12})
+
+    if plot_type in ['percentage', 'both']:
+        ax_pct = ax2 if plot_type == 'both' else ax1
+        plot_stacked_bars(ax_pct, df_pct, pct, is_percentage=True)
+
+    if plot_type == 'both':
+        pass
+        # ax1.axes.xaxis.set_visible(False)
+
+    plt.savefig('/Users/chanchihyu/Desktop/times_stacked.png', transparent=True)
+
+    plt.show()
     return fig, ax1

AeroViz/rawDataReader/__init__.py

@@ -19,10 +19,10 @@ SIZE_RANGE_INSTRUMENTS = ['SMPS', 'APS', 'GRIMM']
 
 def RawDataReader(instrument: str,
                   path: Path | str,
-                  reset: bool = False,
+                  reset: bool | str = False,
                   qc: bool | str = True,
-                  start: datetime = None,
-                  end: datetime = None,
+                  start: datetime | str = None,
+                  end: datetime | str = None,
                   mean_freq: str = '1h',
                   size_range: tuple[float, float] | None = None,
                   suppress_warnings: bool = False,
@@ -94,9 +94,22 @@ def RawDataReader(instrument: str,
 
     Examples
     --------
+    >>> from AeroViz import RawDataReader
+    >>>
+    >>> # Using string inputs
+    >>> df_ae33 = RawDataReader(
+    ...     instrument='AE33',
+    ...     path='/path/to/your/data/folder',
+    ...     reset=True,
+    ...     qc='1MS',
+    ...     start='2024-01-01',
+    ...     end='2024-06-30',
+    ...     mean_freq='1h',
+    ... )
+
+    >>> # Using Path and datetime objects
     >>> from pathlib import Path
     >>> from datetime import datetime
-    >>> from AeroViz import RawDataReader
     >>>
     >>> df_ae33 = RawDataReader(
     ...     instrument='AE33',
@@ -130,9 +143,26 @@ def RawDataReader(instrument: str,
             raise ValueError(f"Invalid frequency: {qc}. Must be one of: "
                              f"W (week), MS (month start), QS (quarter start), YS (year start)")
 
-    # Verify input times
+    # Convert and verify input times
     if not (start and end):
         raise ValueError("Both start and end times must be provided.")
+
+    # Convert start time if it's a string
+    if isinstance(start, str):
+        try:
+            start = datetime.fromisoformat(start.replace('Z', '+00:00'))
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid start time format. Please use ISO format (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS): {e}")
+
+    # Convert end time if it's a string
+    if isinstance(end, str):
+        try:
+            end = datetime.fromisoformat(end.replace('Z', '+00:00'))
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid end time format. Please use ISO format (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS): {e}")
+
     if end <= start:
         raise ValueError(f"Invalid time range: start {start} is after end {end}")