AeroViz 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

AeroViz/dataProcess/Chemistry/_ocec.py

@@ -1,6 +1,8 @@
+import warnings
+
 import numpy as np
 from pandas import concat, DataFrame
-from scipy.optimize import curve_fit
+from scipy.optimize import curve_fit, least_squares, OptimizeWarning
 
 from AeroViz.dataProcess.core import union_index
 
@@ -22,15 +24,26 @@ def _min_Rsq(_oc, _ec, _rng):
     for _ocec, _out in _out_table.items():
         _df = DataFrame([_out.values, _ec.values]).T.dropna()
 
-        _x, _y = _df[0], _df[1]
-        _opt, _ = curve_fit(_func, _x, _y)
+        _x, _y = _df[0].values, _df[1].values
+
+        # 初始參數估計
+        slope_guess = (_y[-1] - _y[0]) / (_x[-1] - _x[0])
+        intercept_guess = _y[0] - slope_guess * _x[0]
+
+        try:
+            with warnings.catch_warnings():
+                warnings.filterwarnings('error')
+                _opt, _ = curve_fit(_func, _x, _y, p0=[slope_guess, intercept_guess], maxfev=5000)
+        except (RuntimeWarning, OptimizeWarning):
+            # 如果 curve_fit 失敗，嘗試使用 least_squares
+            residuals = lambda p: _func(_x, *p) - _y
+            _opt = least_squares(residuals, [slope_guess, intercept_guess]).x
 
-        _tss = np.sum((_y - _y.mean()) ** 2.)
-        _rss = np.sum((_y - _func(_x, *_opt)) ** 2.)
+        _tss = np.sum((_y - np.mean(_y)) ** 2)
+        _rss = np.sum((_y - _func(_x, *_opt)) ** 2)
 
-        _r2_dic[round(_ocec, 3)] = 1. - _rss / _tss
+        _r2_dic[round(_ocec, 3)] = 1 - _rss / _tss
 
-    # get the min R2
     _ratio = DataFrame(_r2_dic, index=[0]).idxmin(axis=1).values[0]
 
     return _ratio, _out_table[_ratio]

AeroViz/plot/__init__.py

@@ -4,6 +4,7 @@ from . import optical
 from .bar import bar
 from .box import box
 from .pie import pie, donuts
+from .radar import radar
 from .regression import linear_regression, multiple_linear_regression
 from .scatter import scatter
 from .templates import *

AeroViz/plot/meteorology/meteorology.py

@@ -70,6 +70,7 @@ def wind_rose(df: DataFrame,
             rlabel_position=rlabel_pos,
             theta_direction=-1,
             theta_zero_location='N',
+            title=kwargs.get('title', None)
         )
         ax.set_thetagrids(angles=[0, 45, 90, 135, 180, 225, 270, 315],
                           labels=["N", "NE", "E", "SE", "S", "SW", "W", "NW"])
@@ -81,6 +82,7 @@ def wind_rose(df: DataFrame,
     return fig, ax
 
 
+# TODO: fix the bug of the CBPF function
 @set_figure(figsize=(4.3, 4))
 def CBPF(df: DataFrame,
          WS: Series | str,

AeroViz/plot/optical/optical.py

@@ -7,7 +7,7 @@ import numpy as np
 from matplotlib.pyplot import Figure, Axes
 
 from AeroViz.plot.utils import *
-from AeroViz.process.method.mie_theory import Mie_Q, Mie_MEE, Mie_PESD
+from temp.process.method.mie_theory import Mie_Q, Mie_MEE, Mie_PESD
 
 __all__ = ['Q_plot',
            'RI_couple',

AeroViz/plot/pie.py

@@ -81,7 +81,9 @@ def pie(data_set: DataFrame | dict,
     radius = 4
     width = 4 if style == 'pie' else 1
 
-    text = [''] * pies if style == 'pie' else [Unit(unit) + '\n\n' + '{:.2f}'.format(x) for x in data.sum(axis=1)]
+    text = [''] * pies if style == 'pie' else [Unit(unit) + '\n\n' +
+                                               '{:.2f} ± {:.2f}'.format(x, s)
+                                               for x, s in zip(data.sum(axis=1), data.std(axis=1))]
     pct_distance = 0.6 if style == 'pie' else 0.88
 
     fig, ax = plt.subplots(1, pies, figsize=((pies * 2) + 1, 2)) if ax is None else (ax.get_figure(), ax)
@@ -99,7 +101,17 @@ def pie(data_set: DataFrame | dict,
                   pctdistance=1.3, radius=radius, wedgeprops=dict(width=width, edgecolor='w'))
         ax[i].axis('equal')
         ax[i].text(0, 0, text[i], ha='center', va='center')
-        ax[i].set_title(category_names[i])
+
+        if kwargs.get('title') is None:
+            ax[i].set_title(category_names[i])
+
+        else:
+            if len(kwargs.get('title')) == pies:
+                title = kwargs.get('title')
+            else:
+                raise ValueError('The length of the title list must match the number of pies.')
+
+            ax[i].set_title(title[i])
 
     ax[-1].legend(labels, loc='center left', prop={'size': 8, 'weight': 'normal'}, bbox_to_anchor=(1, 0, 1.15, 1))
 

AeroViz/plot/radar.py

@@ -0,0 +1,184 @@
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.patches import Circle, RegularPolygon
+from matplotlib.path import Path
+from matplotlib.projections import register_projection
+from matplotlib.projections.polar import PolarAxes
+from matplotlib.spines import Spine
+from matplotlib.transforms import Affine2D
+
+from AeroViz.plot.utils import *
+
+__all__ = ['radar']
+
+
+def radar_factory(num_vars, frame='circle'):
+    """
+    Create a radar chart with `num_vars` axes.
+
+    This function creates a RadarAxes projection and registers it.
+
+    Parameters
+    ----------
+    num_vars : int
+        Number of variables for radar chart.
+    frame : {'circle', 'polygon'}
+        Shape of frame surrounding axes.
+
+    """
+    # calculate evenly-spaced axis angles
+    theta = np.linspace(0, 2 * np.pi, num_vars, endpoint=False)
+
+    class RadarTransform(PolarAxes.PolarTransform):
+
+        def transform_path_non_affine(self, path):
+            # Paths with non-unit interpolation steps correspond to gridlines,
+            # in which case we force interpolation (to defeat PolarTransform's
+            # autoconversion to circular arcs).
+            if path._interpolation_steps > 1:
+                path = path.interpolated(num_vars)
+            return Path(self.transform(path.vertices), path.codes)
+
+    class RadarAxes(PolarAxes):
+
+        name = 'radar'
+        PolarTransform = RadarTransform
+
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+            # rotate plot such that the first axis is at the top
+            self.set_theta_zero_location('N')
+
+        def fill(self, *args, closed=True, **kwargs):
+            """Override fill so that line is closed by default"""
+            return super().fill(closed=closed, *args, **kwargs)
+
+        def plot(self, *args, **kwargs):
+            """Override plot so that line is closed by default"""
+            lines = super().plot(*args, **kwargs)
+            for line in lines:
+                self._close_line(line)
+
+        def _close_line(self, line):
+            x, y = line.get_data()
+            if x[0] != x[-1]:
+                x = np.append(x, x[0])
+                y = np.append(y, y[0])
+                line.set_data(x, y)
+
+        def set_varlabels(self, labels):
+            self.set_thetagrids(np.degrees(theta), labels)
+
+        @staticmethod
+        def _gen_axes_patch():
+            # The Axes patch must be centered at (0.5, 0.5) and of radius 0.5
+            # in axes coordinates.
+            if frame == 'circle':
+                return Circle((0.5, 0.5), 0.5)
+            elif frame == 'polygon':
+                return RegularPolygon((0.5, 0.5), num_vars,
+                                      radius=.5, edgecolor="k")
+            else:
+                raise ValueError("Unknown value for 'frame': %s" % frame)
+
+        def _gen_axes_spines(self):
+            if frame == 'circle':
+                return super()._gen_axes_spines()
+            elif frame == 'polygon':
+                # spine_type must be 'left'/'right'/'top'/'bottom'/'circle'.
+                spine = Spine(axes=self,
+                              spine_type='circle',
+                              path=Path.unit_regular_polygon(num_vars))
+                # unit_regular_polygon gives a polygon of radius 1 centered at
+                # (0, 0) but we want a polygon of radius 0.5 centered at (0.5,
+                # 0.5) in axes coordinates.
+                spine.set_transform(Affine2D().scale(.5).translate(.5, .5)
+                                    + self.transAxes)
+                return {'polar': spine}
+            else:
+                raise ValueError("Unknown value for 'frame': %s" % frame)
+
+    register_projection(RadarAxes)
+    return theta
+
+
+@set_figure(figsize=(3, 3))
+def radar(data, labels=None, legend_labels=None, **kwargs) -> tuple[plt.Figure, plt.Axes]:
+    """
+    Creates a radar chart based on the provided data.
+
+    Parameters
+    ----------
+    data : list of list
+        A 2D list where each inner list represents a factor, and each element
+        within the inner lists represents a value for a species.
+        Shape: (n_factors, n_species)
+        Example: [[0.88, 0.01, 0.03, ...], [0.07, 0.95, 0.04, ...], ...]
+
+    labels : list, optional
+        A list of strings representing the names of species (variables).
+        If provided, it should have the same length as the number of elements
+        in each inner list of `data`.
+        Example: ['Sulfate', 'Nitrate', 'EC', 'OC1', 'OC2', 'OP', 'CO', 'O3']
+
+    legend_labels : list, optional
+        A list of strings for labeling each factor in the legend.
+        If provided, it should have the same length as the number of inner lists in `data`.
+
+    **kwargs : dict
+        Additional keyword arguments to be passed to the plotting function.
+        This may include 'title' for setting the chart title.
+
+    Returns
+    -------
+    tuple[plt.Figure, plt.Axes]
+        A tuple containing the Figure and Axes objects of the created plot.
+
+    Example
+    -------
+    >>> data = [[0.88, 0.01, 0.03, 0.03, 0.00, 0.06, 0.01, 0.00],
+    >>>         [0.07, 0.95, 0.04, 0.05, 0.00, 0.02, 0.01, 0.00],
+    >>>         [0.01, 0.02, 0.85, 0.19, 0.05, 0.10, 0.00, 0.00],
+    >>>         [0.02, 0.01, 0.07, 0.01, 0.21, 0.12, 0.98, 0.00],
+    >>>         [0.01, 0.01, 0.02, 0.71, 0.74, 0.70, 0.30, 0.20]]
+    >>> labels = ['Sulfate', 'Nitrate', 'EC', 'OC1', 'OC2', 'OP', 'CO', 'O3']
+    >>> fig, ax = radar(data, labels=labels, title='Basecase')
+
+    Note
+    ----
+    The first dimension of `data` represents each factor, while the second
+    dimension represents each species.
+    """
+    theta = radar_factory(np.array(data).shape[1], frame='polygon')
+
+    fig, ax = plt.subplots(subplot_kw=dict(projection='radar'))
+    fig.subplots_adjust(wspace=0.25, hspace=0.20, top=0.80, bottom=0.05, right=0.80)
+
+    colors = ['b', 'r', 'g', 'm', 'y']
+
+    # Plot the four cases from the example data on separate axes
+    for d, color in zip(data, colors):
+        ax.plot(theta, d, color=color)
+        ax.fill(theta, d, facecolor=color, alpha=0.25, label='_nolegend_')
+
+    ax.set_varlabels(labels)
+    ax.set_rgrids([0.2, 0.4, 0.6, 0.8])
+    ax.set(title=kwargs.get('title', ''))
+
+    # add legend relative to top-left plot
+    legend_labels = legend_labels or ('Factor 1', 'Factor 2', 'Factor 3', 'Factor 4', 'Factor 5')
+    legend = ax.legend(legend_labels, loc=(0.95, 0.95), labelspacing=0.1)
+
+    plt.show()
+
+    return fig, ax
+
+
+if __name__ == '__main__':
+    data = [[0.88, 0.01, 0.03, 0.03, 0.00, 0.06, 0.01, 0.00],
+            [0.07, 0.95, 0.04, 0.05, 0.00, 0.02, 0.01, 0.00],
+            [0.01, 0.02, 0.85, 0.19, 0.05, 0.10, 0.00, 0.00],
+            [0.02, 0.01, 0.07, 0.01, 0.21, 0.12, 0.98, 0.00],
+            [0.01, 0.01, 0.02, 0.71, 0.74, 0.70, 0.30, 0.20]]
+
+    fig, ax = radar(data=data, labels=['Sulfate', 'Nitrate', 'EC', 'OC1', 'OC2', 'OP', 'CO', 'O3'], title='Basecase')

AeroViz/plot/scatter.py

@@ -22,9 +22,11 @@ def scatter(df: pd.DataFrame,
             x: str,
             y: str,
             c: str | None = None,
+            color: str | None = '#7a97c9',
             s: str | None = None,
             cmap='jet',
             regression=False,
+            regression_line_color: str | None = sns.xkcd_rgb["denim blue"],
             diagonal=False,
             ax: Axes | None = None,
             **kwargs
@@ -41,6 +43,8 @@ def scatter(df: pd.DataFrame,
     y : str
         The column name for the y-axis values.
     c : str, optional
+        The column name for c encoding. Default is None.
+    color : str, optional
         The column name for color encoding. Default is None.
     s : str, optional
         The column name for size encoding. Default is None.
@@ -48,6 +52,8 @@ def scatter(df: pd.DataFrame,
         The colormap to use for the color encoding. Default is 'jet'.
     regression : bool, optional
         If True, fits and plots a linear regression line. Default is False.
+    regression_line_color : str, optional
+        The color of the regression line. Default is 'sns.xkcd_rgb["denim blue"]'.
     diagonal : bool, optional
         If True, plots a 1:1 diagonal line. Default is False.
     ax : Axes, optional
@@ -118,7 +124,7 @@ def scatter(df: pd.DataFrame,
         x_data, y_data, s_data = df_[x].to_numpy(), df_[y].to_numpy(), df_[s].to_numpy()
         check_empty(x_data, y_data, s_data)
 
-        scatter = ax.scatter(x_data, y_data, s=50 * (s_data / s_data.max()) ** 1.5, color='#7a97c9', alpha=0.7,
+        scatter = ax.scatter(x_data, y_data, s=50 * (s_data / s_data.max()) ** 1.5, color=color, alpha=0.5,
                              edgecolors='white')
         colorbar = False
 
@@ -135,7 +141,7 @@ def scatter(df: pd.DataFrame,
         x_data, y_data = df_[x].to_numpy(), df_[y].to_numpy()
         check_empty(x_data, y_data)
 
-        scatter = ax.scatter(x_data, y_data, s=30, color='#7a97c9', alpha=0.7, edgecolors='white')
+        scatter = ax.scatter(x_data, y_data, s=30, color=color, alpha=0.5, edgecolors='white')
         colorbar = False
 
     ax.set(xlim=kwargs.get('xlim', (x_data.min(), x_data.max())),
@@ -144,21 +150,24 @@ def scatter(df: pd.DataFrame,
            ylabel=kwargs.get('ylabel', Unit(y)),
            title=kwargs.get('title', ''))
 
+    ax.xaxis.set_major_formatter(ScalarFormatter())
+    ax.yaxis.set_major_formatter(ScalarFormatter())
+
     if colorbar:
         plt.colorbar(scatter, extend='both', label=Unit(c))
 
     if regression:
         text, y_predict, slope = linear_regression_base(x_data, y_data)
-        ax.plot(x_data, y_predict, linewidth=3, color=sns.xkcd_rgb["denim blue"], alpha=1, zorder=3)
-        plt.text(0.05, 0.95, text, fontdict={'weight': 'bold'}, color=sns.xkcd_rgb["denim blue"],
+        ax.plot(x_data, y_predict, linewidth=3, color=regression_line_color, alpha=1, zorder=3)
+        plt.text(0.05, 0.95, text, fontdict={'weight': 'bold'}, color=regression_line_color,
                  ha='left', va='top', transform=ax.transAxes)
 
     if diagonal:
         ax.axline((0, 0), slope=1., color='k', lw=2, ls='--', alpha=0.5, label='1:1')
-        plt.text(0.91, 0.97, r'$\bf 1:1\ Line$', color='k', ha='right', va='top', transform=ax.transAxes)
 
-    ax.xaxis.set_major_formatter(ScalarFormatter())
-    ax.yaxis.set_major_formatter(ScalarFormatter())
+        data_range = min(ax.get_xlim()[1] - ax.get_xlim()[0], ax.get_ylim()[1] - ax.get_ylim()[0])
+        plt.text(0.9 * data_range, 0.9 * data_range, r'$\bf 1:1\ Line$', color='k', ha='left', va='bottom',
+                 bbox=dict(facecolor='white', edgecolor='none', alpha=0.1, pad=3))
 
     plt.show()
 

AeroViz/plot/templates/koschmieder.py

@@ -10,7 +10,7 @@ from AeroViz.plot.utils import *
 __all__ = ['koschmieder']
 
 
-@set_figure
+@set_figure(figsize=(2.4, 3))
 def koschmieder(df: pd.DataFrame,
                 vis: str,
                 ext: list[str],
@@ -30,8 +30,8 @@ def koschmieder(df: pd.DataFrame,
 
     fig, ax = plt.subplots(**kwargs.get('fig_kws', {})) if ax is None else (ax.get_figure(), ax)
 
-    boxcolors = ['#3f83bf', '#a5bf6b']
-    scattercolor = ['blue', 'green']
+    boxcolors = ['#a5bf6b', '#3f83bf']
+    scattercolor = ['green', 'blue']
     arts = []
     labels = []
 
@@ -74,15 +74,18 @@ def koschmieder(df: pd.DataFrame,
                         label=f'Vis (km) = {round(coeff)} / Ext')
 
         arts.append(line)
-        labels.append(f'Vis (km) = {round(coeff)} / Ext')
+        if 'dry' in ext_col:
+            labels.append(f'Vis (km) = {round(coeff)} / Ext (dry)')
+        else:
+            labels.append(f'Vis (km) = {round(coeff)} / Ext (amb)')
 
     ax.legend(handles=arts, labels=labels, loc='upper right', prop=dict(weight='bold'), bbox_to_anchor=(0.99, 0.99))
 
-    ax.set(xlabel=kwargs.get('xlim', 'Visibility (km)'),
-           ylabel=kwargs.get('xlim', 'Extinction (1/Mm)'),
-           title=kwargs.get('ylim', 'Koschmieder relationship'),
+    ax.set(xlabel=kwargs.get('xlabel', 'Visibility (km)'),
+           ylabel=kwargs.get('ylabel', 'Extinction (1/Mm)'),
+           title=kwargs.get('title', 'Koschmieder relationship'),
            xlim=kwargs.get('xlim', (0, 30)),
-           ylim=kwargs.get('ylim', (0, 500))
+           ylim=kwargs.get('ylim', (0, 800))
            )
 
     plt.xticks(ticks=np.array(range(0, 31, 5)), labels=np.array(range(0, 31, 5)))

AeroViz/plot/timeseries/timeseries.py

@@ -348,7 +348,6 @@ def timeseries_stacked(df,
             ylabel=kwargs.get('ylabel', 'Percentage (%)'),
             xlim=kwargs.get('xlim', (st_tm, fn_tm)),
             ylim=(0, 100),
-            title=kwargs.get('title', '')
             )
 
     xticks = kwargs.get('xticks', date_range(start=st_tm, end=fn_tm, freq=major_freq))

AeroViz/rawDataReader/__init__.py

@@ -1,104 +1,111 @@
 from datetime import datetime
 from pathlib import Path
 
+from pandas import Grouper, Timedelta
+
 from AeroViz.rawDataReader.config.supported_instruments import meta
 from AeroViz.rawDataReader.script import *
 
 __all__ = ['RawDataReader']
 
+SUPPORTED_INSTRUMENTS = [
+    NEPH, Aurora, SMPS, GRIMM, APS_3321, AE33, AE43, BC1054,
+    MA350, TEOM, OCEC, IGAC, VOC, EPA, Minion
+]
+
 
 def RawDataReader(instrument_name: str,
                   path: Path,
-                  qc: bool = True,
-                  csv_raw: bool = True,
                   reset: bool = False,
+                  qc: bool | str = True,
+                  qc_freq: str | None = None,
                   rate: bool = True,
                   append_data: bool = False,
-                  start: datetime | None = None,
-                  end: datetime | None = None,
-                  mean_freq='1h',
-                  csv_out=True,
+                  start: datetime = None,
+                  end: datetime = None,
+                  mean_freq: str = '1h',
+                  csv_out: bool = True,
                   ):
     """
     Factory function to instantiate the appropriate reader module for a given instrument and
     return the processed data over the specified time range.
 
-    Parameters
-    ----------
-    instrument_name : str
-        The name of the instrument for which to read data. Must be a valid key in the `meta` dictionary.
-    path : Path
-        The directory where raw data files for the instrument are stored.
-    qc : bool, optional (default=True)
-        If True, apply quality control (QC) to the raw data.
-    csv_raw : bool, optional (default=True)
-        If True, read raw data from CSV files.
-    reset : bool, optional (default=False)
-        If True, reset the state and reprocess the data from scratch.
-    rate : bool, optional (default=False)
-        If True, calculate rates from the data.
-    append_data : bool, optional (default=False)
-        If True, append new data to the existing dataset instead of overwriting it.
-    start : datetime, optional
-        Start time for filtering the data. If None, no start time filtering will be applied.
-    end : datetime, optional
-        End time for filtering the data. If None, no end time filtering will be applied.
-    mean_freq : str, optional (default='1h')
-        Resampling frequency for averaging the data. Example: '1h' for hourly mean.
-    csv_out : bool, optional (default=True)
-        If True, output the processed data as a CSV file.
-
-    Return
-    ------
-    reader_module : Reader
-        An instance of the reader module corresponding to the specified instrument, which processes
-        the data and returns it in a usable format.
-
-    Raises
-    ------
-    ValueError
-        If the `instrument_name` provided is not a valid key in the `meta` dictionary.
-
-    Example
-    -------
+    :param instrument_name: The name of the instrument for which to read data. Must be a valid key in the `meta` dictionary.
+    :param path: The directory where raw data files for the instrument are stored.
+    :param reset: If True, reset the state and reprocess the data from scratch.
+    :param qc: If True, apply quality control (QC) to the raw data.
+    :param qc_freq: Frequency at which to perform QC. Must be one of 'W', 'M', 'Q', 'Y' for weekly, monthly, quarterly, or yearly.
+    :param rate: If True, calculate rates from the data.
+    :param append_data: If True, append new data to the existing dataset instead of overwriting it.
+    :param start: Start time for filtering the data. If None, no start time filtering will be applied.
+    :param end: End time for filtering the data. If None, no end time filtering will be applied.
+    :param mean_freq: Resampling frequency for averaging the data. Example: '1h' for hourly mean.
+    :param csv_out: If True, output the processed data as a CSV file.
+
+    :return: An instance of the reader module corresponding to the specified instrument, which processes the data and returns it in a usable format.
+
+    :raises ValueError: If the `instrument_name` provided is not a valid key in the `meta` dictionary.
+    :raises ValueError: If the specified path does not exist or is not a directory.
+    :raises ValueError: If the QC frequency is invalid.
+    :raises ValueError: If start and end times are not both provided or are invalid.
+    :raises ValueError: If the mean_freq is not a valid frequency string.
+
+    :Example:
+
     To read and process data for the BC1054 instrument:
 
     >>> from pathlib import Path
     >>> from datetime import datetime
-    >>> data = RawDataReader(instrument_name='BC1054', path=Path('/path/to/data'),
-    >>>                      start=datetime(2024, 1, 1), end=datetime(2024, 2, 1))
+    >>>
+    >>> data = RawDataReader(
+    ...     instrument_name='BC1054',
+    ...     path=Path('/path/to/data'),
+    ...     start=datetime(2024, 2, 1),
+    ...     end=datetime(2024, 7, 31, 23))
     """
     # Mapping of instrument names to their respective classes
-    instrument_class_map = {
-        'NEPH': NEPH,
-        'Aurora': Aurora,
-        'SMPS': SMPS,
-        'GRIMM': GRIMM,
-        'APS_3321': APS_3321,
-        'AE33': AE33,
-        'AE43': AE43,
-        'BC1054': BC1054,
-        'MA350': MA350,
-        'TEOM': TEOM,
-        'OCEC': OCEC,
-        'IGAC': IGAC,
-        'VOC': VOC,
-        'Table': Table,
-        'EPA_vertical': EPA_vertical,
-        'Minion': Minion
-        # Add other instruments and their corresponding classes here
-    }
+    instrument_class_map = {cls.__name__.split('.')[-1]: cls for cls in SUPPORTED_INSTRUMENTS}
 
     # Check if the instrument name is in the map
     if instrument_name not in meta.keys():
         raise ValueError(f"Instrument name '{instrument_name}' is not valid. \nMust be one of: {list(meta.keys())}")
 
+    # 檢查 path 是否存在且是一個目錄
+    if not isinstance(path, Path):
+        path = Path(path)
+    if not path.exists() or not path.is_dir():
+        raise ValueError(f"The specified path '{path}' does not exist or is not a directory.")
+
+    # Validate the QC frequency
+    if qc_freq is not None:
+        try:
+            Grouper(freq=qc_freq)
+        except ValueError as e:
+            raise ValueError(f"Invalid frequency: {qc_freq}. Error: {str(e)}")
+        except TypeError as e:
+            raise ValueError(f"Invalid frequency type: {qc_freq}. Frequency should be a string.")
+
+    if start and end:
+        if end.hour == 0 and end.minute == 0 and end.second == 0:
+            end = end.replace(hour=23)
+    else:
+        raise ValueError("Both start and end times must be provided.")
+    if end <= start:
+        raise ValueError(f"Invalid time range: start {start} is after end {end}")
+
+    # 驗證 mean_freq 的格式是否正確
+    try:
+        Timedelta(mean_freq)
+    except ValueError:
+        raise ValueError(
+            f"Invalid mean_freq: '{mean_freq}'. It should be a valid frequency string (e.g., '1H', '30min', '1D').")
+
     # Instantiate the class and return the instance
     reader_module = instrument_class_map[instrument_name].Reader(
         path=path,
-        qc=qc,
-        csv_raw=csv_raw,
         reset=reset,
+        qc=qc,
+        qc_freq=qc_freq,
         rate=rate,
         append_data=append_data
     )