AeroViz 0.1.21__py3-none-any.whl

AeroViz/rawDataReader/script/SMPS.py

@@ -0,0 +1,389 @@
+import csv
+
+import numpy as np
+from pandas import to_datetime, to_numeric, read_csv, Series, concat, DataFrame
+
+from AeroViz.rawDataReader.core import AbstractReader, QCRule, QCFlagBuilder
+
+
+class Reader(AbstractReader):
+    """SMPS (Scanning Mobility Particle Sizer) Data Reader
+
+    A specialized reader for SMPS data files, which measure particle size distributions
+    in the range of 11.8-593.5 nm.
+
+    See full documentation at docs/source/instruments/SMPS.md for detailed information
+    on supported formats and QC procedures.
+    """
+    nam = 'SMPS'
+
+    # =========================================================================
+    # QC Thresholds
+    # =========================================================================
+    MIN_HOURLY_COUNT = 5           # Minimum measurements per hour
+    MIN_TOTAL_CONC = 2000          # Minimum total concentration (#/cm³)
+    MAX_TOTAL_CONC = 1e7           # Maximum total concentration (#/cm³)
+    MAX_LARGE_BIN_CONC = 4000      # Maximum concentration for >400nm bins (DMA water ingress indicator)
+    LARGE_BIN_THRESHOLD = 400      # Size threshold for large bin filter (nm)
+
+    # Status Flag column name
+    STATUS_COLUMN = 'Status Flag'
+    STATUS_OK = 'Normal Scan'  # Normal status text
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._distributions = None  # Store distributions for separate file output
+
+    def __call__(self, start, end, mean_freq='1h'):
+        """
+        Process SMPS data and save size distributions to separate files.
+
+        Overrides AbstractReader.__call__ to add distribution file saving
+        and filter out size bins from main output.
+
+        Parameters
+        ----------
+        start : datetime
+            Start time for data processing
+        end : datetime
+            End time for data processing
+        mean_freq : str, default='1h'
+            Frequency for resampling the data
+
+        Returns
+        -------
+        pd.DataFrame
+            Processed and resampled data (statistics only, no size bins)
+        """
+        # Call parent __call__ for standard processing
+        result = super().__call__(start, end, mean_freq)
+
+        # Save distributions to separate files
+        self._save_distributions(mean_freq)
+
+        # Filter out size bins from main output, keep only statistics
+        stat_cols = [col for col in result.columns if not isinstance(col, (int, float))]
+        result_stats = result[stat_cols]
+
+        # Re-save filtered output to CSV
+        result_stats.to_csv(self.csv_out)
+
+        return result_stats
+
+    def _raw_reader(self, file):
+        """Read and parse raw SMPS data files."""
+
+        def find_header_row(file_obj, delimiter):
+            csv_reader = csv.reader(file_obj, delimiter=delimiter)
+            for skip, row in enumerate(csv_reader):
+                if row and (row[0] in ['Sample #', 'Scan Number']):
+                    return skip
+            raise ValueError("Header row not found")
+
+        def parse_date(df, date_format):
+            if 'Date' in df.columns and 'Start Time' in df.columns:
+                return to_datetime(df['Date'] + ' ' + df['Start Time'], format=date_format, errors='coerce')
+            elif 'DateTime Sample Start' in df.columns:
+                return to_datetime(df['DateTime Sample Start'], format=date_format, errors='coerce')
+            else:
+                raise ValueError("Expected date columns not found")
+
+        with open(file, 'r', encoding='utf-8', errors='ignore') as f:
+            if file.suffix.lower() == '.txt':
+                delimiter, date_formats = '\t', ['%m/%d/%y %X', '%m/%d/%Y %X']
+            else:  # csv
+                delimiter, date_formats = ',', ['%d/%m/%Y %X']
+
+            skip = find_header_row(f, delimiter)
+            f.seek(0)
+
+            _df = read_csv(f, sep=delimiter, skiprows=skip, low_memory=False)
+            if 'Date' not in _df.columns and 'DateTime Sample Start' not in _df.columns:
+                try:
+                    _df = _df.T
+                    _df.columns = _df.iloc[0]
+                    _df = _df.iloc[1:]
+                    _df = _df.reset_index(drop=True)
+                except:
+                    raise NotImplementedError('Not supported date format')
+
+            for date_format in date_formats:
+                _time_index = parse_date(_df, date_format)
+                if not _time_index.isna().all():
+                    break
+            else:
+                raise ValueError("Unable to parse dates with given formats")
+
+            # Check for comma decimal separator
+            comma_decimal_cols = [col for col in _df.columns if ',' in col.strip()]
+            if comma_decimal_cols:
+                self.logger.warning(f"Detected {len(comma_decimal_cols)} columns using comma as decimal separator")
+                _df.columns = _df.columns.str.replace(',', '.')
+
+            # Filter numeric columns
+            numeric_cols = [col for col in _df.columns if col.strip().replace('.', '').isdigit()]
+            numeric_cols.sort(key=lambda x: float(x.strip()))
+
+            _df.index = _time_index
+            _df.index.name = 'time'
+
+            _df_smps = _df[numeric_cols]
+            _df_smps = _df_smps.loc[_df_smps.index.dropna().copy()]
+
+            # Rename columns to float values (strip spaces)
+            _df_smps.columns = [float(col.strip()) for col in _df_smps.columns]
+
+            size_range = self.kwargs.get('size_range') or (11.8, 593.5)
+
+            if _df_smps.columns[0] != size_range[0] or _df_smps.columns[-1] != size_range[1]:
+                self.logger.warning(f'SMPS file: {file.name} size range mismatch. '
+                                    f'Expected {size_range}, got ({_df_smps.columns[0]}, {_df_smps.columns[-1]})')
+                return None
+
+            _df_smps = _df_smps.apply(to_numeric, errors='coerce')
+
+            # Include Status Flag column in _df (will be processed by core together)
+            if self.STATUS_COLUMN in _df.columns:
+                _df_smps[self.STATUS_COLUMN] = _df.loc[_df_smps.index, self.STATUS_COLUMN].astype(str).str.strip()
+
+            return _df_smps
+
+    def _QC(self, _df):
+        """
+        Perform quality control on SMPS particle size distribution data.
+
+        QC Rules Applied
+        ----------------
+        1. Status Error        : Non-empty status flag indicates instrument error
+        2. Insufficient        : Less than 5 measurements per hour
+        3. Invalid Number Conc : Total number concentration outside valid range (2000-1e7 #/cm³)
+        4. DMA Water Ingress   : Bins >400nm with concentration > 4000 dN/dlogDp (indicates water in DMA)
+        """
+        _df = _df.copy()
+        _index = _df.index.copy()
+
+        # Apply size range filter
+        size_range = self.kwargs.get('size_range') or (11.8, 593.5)
+        numeric_cols = [col for col in _df.columns if isinstance(col, (int, float))]
+        df_numeric = _df[numeric_cols]
+        size_mask = (df_numeric.columns.astype(float) >= size_range[0]) & (df_numeric.columns.astype(float) <= size_range[1])
+        df_numeric = df_numeric.loc[:, size_mask]
+
+        # Calculate total concentration for QC checks
+        dlogDp = np.diff(np.log(df_numeric.columns[:-1].to_numpy(float))).mean()
+        total_conc = df_numeric.sum(axis=1, min_count=1) * dlogDp
+
+        # Calculate hourly data counts
+        hourly_counts = (total_conc
+                         .dropna()
+                         .resample('h')
+                         .size()
+                         .resample('6min')
+                         .ffill()
+                         .reindex(df_numeric.index, method='ffill', tolerance='6min'))
+
+        # Get large bins (>400nm)
+        large_bins = df_numeric.columns[df_numeric.columns.astype(float) >= self.LARGE_BIN_THRESHOLD]
+
+        # Build QC rules declaratively
+        qc = QCFlagBuilder()
+
+        qc.add_rules([
+            QCRule(
+                name='Status Error',
+                condition=lambda df: self.QC_control().filter_error_status(
+                    _df, status_column=self.STATUS_COLUMN, status_type='text', ok_value=self.STATUS_OK
+                ),
+                description=f'Status flag is not "{self.STATUS_OK}"'
+            ),
+            QCRule(
+                name='Insufficient',
+                condition=lambda df: Series(hourly_counts < self.MIN_HOURLY_COUNT, index=df.index).fillna(True),
+                description=f'Less than {self.MIN_HOURLY_COUNT} measurements per hour'
+            ),
+            QCRule(
+                name='Invalid Number Conc',
+                condition=lambda df, tc=total_conc: Series(
+                    (tc < self.MIN_TOTAL_CONC) | (tc > self.MAX_TOTAL_CONC),
+                    index=df.index
+                ).fillna(True),
+                description=f'Total number concentration outside valid range ({self.MIN_TOTAL_CONC}-{self.MAX_TOTAL_CONC:.0e} #/cm³)'
+            ),
+            QCRule(
+                name='DMA Water Ingress',
+                condition=lambda df: (df[large_bins] > self.MAX_LARGE_BIN_CONC).any(axis=1) if len(large_bins) > 0 else Series(False, index=df.index),
+                description=f'Bins >{self.LARGE_BIN_THRESHOLD}nm with concentration > {self.MAX_LARGE_BIN_CONC} dN/dlogDp (water in DMA)'
+            ),
+        ])
+
+        # Apply all QC rules
+        df_qc = qc.apply(_df)
+
+        # Store QC summary for combined output in _process()
+        self._qc_summary = qc.get_summary(df_qc)
+
+        return df_qc.reindex(_index)
+
+    def _process(self, _df):
+        """
+        Calculate size distribution statistics from QC'd SMPS data.
+
+        Processing Steps
+        ----------------
+        1. Calculate dlogDp from bin diameters
+        2. Calculate number, surface, volume distributions (all in dX/dlogDp)
+        3. Calculate total, GMD, GSD, mode for each weighting
+        4. Calculate mode contributions (ultra, accum, coarse fractions)
+        5. Store distributions for separate file output
+
+        Parameters
+        ----------
+        _df : pd.DataFrame
+            Quality-controlled DataFrame with size bin columns and QC_Flag
+
+        Returns
+        -------
+        pd.DataFrame
+            Original size bins (dN/dlogDp) + calculated statistics + QC_Flag
+        """
+        _index = _df.index.copy()
+
+        # Separate QC_Flag from size bins
+        qc_flag = _df['QC_Flag'].copy() if 'QC_Flag' in _df.columns else Series('Valid', index=_df.index)
+
+        # Get numeric columns (size bins)
+        bin_cols = [col for col in _df.columns if isinstance(col, (int, float))]
+        df_bins = _df[bin_cols].copy()  # This is dN/dlogDp
+        dp = np.array(bin_cols, dtype=float)
+
+        # Input is already dN/dlogDp, calculate dS/dlogDp and dV/dlogDp
+        dN_dlogDp = df_bins.copy()
+        dS_dlogDp = dN_dlogDp * np.pi * dp ** 2  # Surface area distribution (nm²·cm⁻³)
+        dV_dlogDp = dN_dlogDp * np.pi * (dp ** 3) / 6  # Volume distribution (nm³·cm⁻³)
+
+        # Store distributions for separate file output (with QC_Flag)
+        self._distributions = {
+            'dNdlogDp': concat([dN_dlogDp, qc_flag], axis=1),
+            'dSdlogDp': concat([dS_dlogDp, qc_flag], axis=1),
+            'dVdlogDp': concat([dV_dlogDp, qc_flag], axis=1),
+        }
+
+        # For statistics calculation, convert to absolute values (dX = dX/dlogDp * dlogDp)
+        dlogDp = np.diff(np.log10(dp))
+        dlogDp = np.append(dlogDp, dlogDp[-1])
+        dN = dN_dlogDp * dlogDp
+        dS = dS_dlogDp * dlogDp
+        dV = dV_dlogDp * dlogDp
+
+        # Calculate statistics for all particles
+        stats = DataFrame(index=_df.index)
+
+        # Calculate for each weighting type
+        for weight_name, dist in [('num', dN), ('surf', dS), ('vol', dV)]:
+            total, gmd, gsd = self._geometric_prop(dp, dist)
+            stats[f'total_{weight_name}'] = total
+            stats[f'GMD_{weight_name}'] = gmd
+            stats[f'GSD_{weight_name}'] = gsd
+
+            # Calculate mode (diameter with maximum concentration)
+            mask = dist.notna().any(axis=1)
+            stats.loc[mask, f'mode_{weight_name}'] = dist.loc[mask].idxmax(axis=1)
+
+            # Calculate mode contributions
+            if weight_name == 'num':
+                total_sum = dist.sum(axis=1)
+                total_sum = total_sum.where(total_sum > 0)
+
+                # Ultrafine: < 100 nm
+                ultra_bins = [c for c in dist.columns if c < 100]
+                if ultra_bins:
+                    stats[f'ultra_{weight_name}'] = dist[ultra_bins].sum(axis=1) / total_sum
+
+                # Accumulation: 100-1000 nm
+                accum_bins = [c for c in dist.columns if 100 <= c < 1000]
+                if accum_bins:
+                    stats[f'accum_{weight_name}'] = dist[accum_bins].sum(axis=1) / total_sum
+
+                # Coarse: >= 1000 nm (if available in SMPS range)
+                coarse_bins = [c for c in dist.columns if c >= 1000]
+                if coarse_bins:
+                    stats[f'coarse_{weight_name}'] = dist[coarse_bins].sum(axis=1) / total_sum
+
+        # Combine: size bins + statistics + QC_Flag
+        # (bins are kept for rate calculation, filtered out when saving to CSV)
+        df_out = concat([df_bins, stats, qc_flag], axis=1)
+
+        # Log QC summary
+        if hasattr(self, '_qc_summary') and self._qc_summary is not None:
+            self.logger.info(f"{self.nam} QC Summary:")
+            for _, row in self._qc_summary.iterrows():
+                self.logger.info(f"  {row['Rule']}: {row['Count']} ({row['Percentage']})")
+
+        return df_out.reindex(_index)
+
+    def _save_distributions(self, mean_freq: str = '1h') -> None:
+        """
+        Save size distributions to separate CSV files.
+
+        Output Files
+        ------------
+        - output_smps_dNdlogDp.csv : Number distribution (dN/dlogDp)
+        - output_smps_dSdlogDp.csv : Surface distribution (dS/dlogDp)
+        - output_smps_dVdlogDp.csv : Volume distribution (dV/dlogDp)
+
+        Parameters
+        ----------
+        mean_freq : str, default='1h'
+            Frequency for resampling the data
+        """
+        if not hasattr(self, '_distributions') or self._distributions is None:
+            self.logger.warning("No distributions to save. Run _process() first.")
+            return
+
+        output_folder = self.csv_out.parent
+        self.logger.info("")
+
+        for dist_name, dist_df in self._distributions.items():
+            # Process QC_Flag: set invalid rows to NaN
+            if 'QC_Flag' in dist_df.columns:
+                invalid_mask = dist_df['QC_Flag'] != 'Valid'
+                numeric_cols = [c for c in dist_df.columns if c != 'QC_Flag']
+                dist_df.loc[invalid_mask, numeric_cols] = np.nan
+                dist_df = dist_df.drop(columns=['QC_Flag'])
+
+            # Resample and save
+            dist_resampled = dist_df.resample(mean_freq).mean().round(4)
+            output_path = output_folder / f'output_{self.nam.lower()}_{dist_name}.csv'
+            dist_resampled.to_csv(output_path)
+            self.logger.info(f"Saved: {output_path.name}")
+
+    @staticmethod
+    def _geometric_prop(dp, dist):
+        """
+        Calculate geometric mean diameter and geometric standard deviation.
+
+        Parameters
+        ----------
+        dp : np.ndarray
+            Particle diameters (nm)
+        dist : pd.DataFrame
+            Distribution data (dN, dS, or dV)
+
+        Returns
+        -------
+        tuple
+            (total, GMD, GSD) as pandas Series
+        """
+        # Total concentration
+        total = dist.sum(axis=1, min_count=1)
+        total_valid = total.where(total > 0)
+
+        # GMD calculation (in log space)
+        log_dp = np.log(dp)
+        gmd_log = (dist * log_dp).sum(axis=1) / total_valid
+
+        # GSD calculation
+        dp_mesh, gmd_mesh = np.meshgrid(log_dp, gmd_log)
+        gsd_log = np.sqrt(((dp_mesh - gmd_mesh) ** 2 * dist.values).sum(axis=1) / total_valid)
+
+        return total, np.exp(gmd_log), np.exp(gsd_log)

AeroViz/rawDataReader/script/TEOM.py

@@ -0,0 +1,181 @@
+from pandas import to_datetime, read_csv, to_numeric, Series, concat
+
+from AeroViz.rawDataReader.core import AbstractReader, QCRule, QCFlagBuilder
+
+
+class Reader(AbstractReader):
+    """TEOM Output Data Formats Reader
+
+    A specialized reader for TEOM (Tapered Element Oscillating Microbalance)
+    particulate matter data files with support for multiple file formats and
+    comprehensive quality control.
+
+    See full documentation at docs/source/instruments/TEOM.md for detailed information
+    on supported formats and QC procedures.
+    """
+    nam = 'TEOM'
+
+    # =========================================================================
+    # Column Definitions
+    # =========================================================================
+    PM_COLUMNS = ['PM_NV', 'PM_Total']
+    OUTPUT_COLUMNS = ['PM_NV', 'PM_Total', 'Volatile_Fraction']
+
+    # =========================================================================
+    # QC Thresholds
+    # =========================================================================
+    MAX_NOISE = 0.01    # Maximum acceptable noise level
+
+    # Status Flag
+    STATUS_COLUMN = 'status'
+    STATUS_OK = 0  # Status code 0 means normal operation
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def _raw_reader(self, file):
+        """
+        Read and parse raw TEOM data files in various formats.
+
+        Handles multiple TEOM data formats and standardizes them to a consistent
+        structure with uniform column names and datetime index.
+
+        Parameters
+        ----------
+        file : Path or str
+            Path to the TEOM data file.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Processed raw TEOM data with datetime index and standardized columns.
+
+        Raises
+        ------
+        NotImplementedError
+            If the file format is not recognized as a supported TEOM data format.
+        """
+        _df = read_csv(file, skiprows=3, index_col=False)
+
+        # Chinese month name conversion dictionary
+        _time_replace = {'十一月': '11', '十二月': '12', '一月': '01', '二月': '02', '三月': '03', '四月': '04',
+                         '五月': '05', '六月': '06', '七月': '07', '八月': '08', '九月': '09', '十月': '10'}
+
+        # Try both naming conventions (will ignore columns that don't exist)
+        _df = _df.rename(columns={
+            # Remote download format
+            'Time Stamp': 'time',
+            'System status': 'status',
+            'PM-2.5 base MC': 'PM_NV',
+            'PM-2.5 MC': 'PM_Total',
+            'PM-2.5 TEOM noise': 'noise',
+            # USB/auto export format
+            'time_stamp': 'time',
+            'tmoStatusCondition_0': 'status',
+            'tmoTEOMABaseMC_0': 'PM_NV',
+            'tmoTEOMAMC_0': 'PM_Total',
+            'tmoTEOMANoise_0': 'noise'
+        })
+
+        # Handle different time formats
+        if 'time' in _df.columns:  # Remote download or auto export with time column
+            _tm_idx = _df.time
+            # Convert Chinese month names if present
+            for _ori, _rpl in _time_replace.items():
+                _tm_idx = _tm_idx.str.replace(_ori, _rpl)
+
+            _df = _df.set_index(to_datetime(_tm_idx, errors='coerce', format='%d - %m - %Y %X'))
+
+        elif 'Date' in _df.columns and 'Time' in _df.columns:  # USB download format
+            _df['time'] = to_datetime(_df['Date'] + ' ' + _df['Time'],
+                                      errors='coerce', format='%Y-%m-%d %H:%M:%S')
+            _df.drop(columns=['Date', 'Time'], inplace=True)
+            _df.set_index('time', inplace=True)
+
+        else:
+            raise NotImplementedError("Unsupported TEOM data format")
+
+        _df = _df[['PM_NV', 'PM_Total', 'noise', 'status']].apply(to_numeric, errors='coerce')
+
+        # Remove duplicates and NaN indices
+        _df = _df.loc[~_df.index.duplicated() & _df.index.notna()]
+
+        return _df
+
+    def _QC(self, _df):
+        """
+        Perform quality control on TEOM particulate matter data.
+
+        QC Rules Applied
+        ----------------
+        1. Status Error         : Non-zero status code indicates instrument error
+        2. High Noise           : noise >= 0.01
+        3. Non-positive         : PM_NV <= 0 OR PM_Total <= 0
+        4. NV > Total           : PM_NV > PM_Total (physically impossible)
+        5. Invalid Vol Frac     : Volatile_Fraction outside valid range (0-1)
+        6. Spike                : Sudden value change (vectorized spike detection)
+        7. Insufficient         : Less than 50% hourly data completeness
+        """
+        _index = _df.index.copy()
+
+        # Pre-process: calculate Volatile_Fraction
+        _df['Volatile_Fraction'] = ((_df['PM_Total'] - _df['PM_NV']) / _df['PM_Total']).__round__(4)
+        df_qc = _df.copy()
+
+        # Build QC rules declaratively
+        qc = QCFlagBuilder()
+
+        qc.add_rules([
+            QCRule(
+                name='Status Error',
+                condition=lambda df: self.QC_control().filter_error_status(
+                    _df, status_column=self.STATUS_COLUMN, status_type='numeric', ok_value=self.STATUS_OK
+                ),
+                description=f'Status code is not {self.STATUS_OK} (non-zero indicates error)'
+            ),
+            QCRule(
+                name='High Noise',
+                condition=lambda df: df['noise'] >= self.MAX_NOISE,
+                description=f'Noise level >= {self.MAX_NOISE}'
+            ),
+            QCRule(
+                name='Non-positive',
+                condition=lambda df: (df[self.PM_COLUMNS] <= 0).any(axis=1),
+                description='PM_NV or PM_Total <= 0 (non-positive value)'
+            ),
+            QCRule(
+                name='NV > Total',
+                condition=lambda df: df['PM_NV'] > df['PM_Total'],
+                description='PM_NV exceeds PM_Total (physically impossible)'
+            ),
+            QCRule(
+                name='Invalid Vol Frac',
+                condition=lambda df: (df['Volatile_Fraction'] < 0) | (df['Volatile_Fraction'] > 1),
+                description='Volatile_Fraction outside 0-1 range'
+            ),
+            QCRule(
+                name='Spike',
+                condition=lambda df: self.QC_control().spike_detection(
+                    df[self.PM_COLUMNS], max_change_rate=3.0
+                ),
+                description='Sudden unreasonable value change detected'
+            ),
+            QCRule(
+                name='Insufficient',
+                condition=lambda df: self.QC_control().hourly_completeness_QC(
+                    df[self.PM_COLUMNS], freq=self.meta['freq']
+                ),
+                description='Less than 50% hourly data completeness'
+            ),
+        ])
+
+        # Apply all QC rules and get flagged DataFrame
+        df_qc = qc.apply(df_qc)
+
+        # Log QC summary
+        summary = qc.get_summary(df_qc)
+        self.logger.info(f"{self.nam} QC Summary:")
+        for _, row in summary.iterrows():
+            self.logger.info(f"  {row['Rule']}: {row['Count']} ({row['Percentage']})")
+
+        return df_qc[self.OUTPUT_COLUMNS + ['QC_Flag']].reindex(_index)

AeroViz/rawDataReader/script/VOC.py

@@ -0,0 +1,106 @@
+from pandas import read_csv
+
+from AeroViz.rawDataReader.core import AbstractReader
+
+
+class Reader(AbstractReader):
+    """ Volatile Organic Compounds (VOC) Data Reader
+
+    This class handles the reading and parsing of VOC measurement data files,
+    which provide concentrations of various volatile organic compounds in air.
+
+    File structure handling:
+    - Processes CSV formatted data files with datetime index
+    - Handles special values like '-' and 'N.D.' (Not Detected) as NA
+    - Standardizes column names by stripping whitespace
+
+    Data processing:
+    - Filters VOC species based on a predefined list of supported compounds
+    - Warns about unsupported VOC species in the data file
+    - Handles duplicate timestamps and invalid indices
+
+    Quality Control procedures:
+    - Basic file validation
+    - No additional QC is applied in the current implementation
+
+    Returns:
+    -------
+    DataFrame
+        Processed VOC data with datetime index and supported VOC species as columns.
+        If no supported species are found, returns the original dataframe.
+
+    Notes:
+    -----
+    VOC measurements are important for understanding air quality, photochemical
+    reactions, and sources of secondary organic aerosols. This reader requires
+    a predefined list of supported VOC species to be provided in the meta attribute.
+    """
+    nam = 'VOC'
+
+    def _raw_reader(self, file):
+        """
+        Read and parse raw VOC measurement data files.
+
+        Parameters
+        ----------
+        file : Path or str
+            Path to the VOC data file.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Processed VOC data with datetime index and supported VOC species as columns.
+
+        Notes
+        -----
+        Requires self.meta["key"] to contain a list of supported VOC species names.
+        If no supported species are found, returns the original dataframe with a warning.
+        """
+        with file.open('r', encoding='utf-8-sig', errors='ignore') as f:
+            _df = read_csv(f, parse_dates=True, index_col=0, na_values=('-', 'N.D.'))
+
+            _df.columns = _df.keys().str.strip(' ')
+            _df.index.name = 'time'
+
+            support_voc = set(self.meta["key"])
+
+            valid_keys = [key for key in _df.keys() if key in support_voc]
+            invalid_keys = [key for key in _df.keys() if key not in support_voc]
+
+            if invalid_keys:
+                self.logger.warning(f'{invalid_keys} are not supported keys.')
+                print(f'\n\t{invalid_keys} are not supported keys.'
+                      f'\n\tPlease check the\033[91m support_voc.md\033[0m file to use the correct name.')
+
+            if valid_keys:
+                return _df[valid_keys].loc[~_df.index.duplicated() & _df.index.notna()]
+            else:
+                self.logger.warning("沒有找到匹配的鍵。返回原始DataFrame。")
+                return _df.loc[~_df.index.duplicated() & _df.index.notna()]
+
+    def _QC(self, _df):
+        """
+        Perform quality control on VOC measurement data.
+
+        This method is a placeholder for future QC implementation. Currently,
+        it returns the data unchanged.
+
+        Parameters
+        ----------
+        _df : pandas.DataFrame
+            Raw VOC data with datetime index and concentration columns.
+
+        Returns
+        -------
+        pandas.DataFrame
+            The input data unchanged.
+
+        Notes
+        -----
+        No QC filters are currently applied. Future implementations could include:
+        1. Minimum detection limit filtering
+        2. Value range checks for each VOC species
+        3. Time-based outlier detection
+        4. Correlation checks between related VOC species
+        """
+        return _df