AeroViz 0.1.21__py3-none-any.whl

AeroViz/rawDataReader/script/AE33.py

@@ -0,0 +1,173 @@
+from pandas import read_table, to_numeric, concat
+
+from AeroViz.rawDataReader.core import AbstractReader, QCRule, QCFlagBuilder
+from AeroViz.rawDataReader.core.pre_process import _absCoe
+
+
+class Reader(AbstractReader):
+    """AE33 Aethalometer Data Reader.
+
+    A specialized reader for AE33 Aethalometer data files, which measure black carbon
+    concentrations at seven wavelengths.
+
+    See full documentation at docs/source/instruments/AE33.md for detailed information
+    on supported formats and QC procedures.
+    """
+    nam = 'AE33'
+
+    # =========================================================================
+    # Column Definitions
+    # =========================================================================
+    BC_COLUMNS = ['BC1', 'BC2', 'BC3', 'BC4', 'BC5', 'BC6', 'BC7']
+    ABS_COLUMNS = ['abs_370', 'abs_470', 'abs_520', 'abs_590', 'abs_660', 'abs_880', 'abs_950']
+    CAL_COLUMNS = ['abs_550', 'AAE', 'eBC']
+    BB_COLUMN = 'BB(%)'  # Biomass Burning percentage from source apportionment
+
+    # =========================================================================
+    # QC Thresholds
+    # =========================================================================
+    MIN_BC = 0           # Minimum BC concentration (ng/m³)
+    MAX_BC = 20000       # Maximum BC concentration (ng/m³)
+    MIN_AAE = 0.7        # Minimum valid AAE (absolute value)
+    MAX_AAE = 2.0        # Maximum valid AAE (absolute value)
+
+    # =========================================================================
+    # Status Error Codes (bitwise flags)
+    # =========================================================================
+    # Note: 128 and 256 are tape low warnings, not errors - data is still valid
+    # 384 (128+256) removed to avoid flagging tape warnings as errors
+    ERROR_STATES = [
+        1,     # Tape advance (tape advance, fast calibration, warm-up)
+        2,     # First measurement – obtaining ATN0
+        3,     # Stopped
+        4,     # Flow low/high by more than 0.5 LPM
+        16,    # Calibrating LED
+        32,    # Calibration error (at least one channel OK)
+        1024,  # Stability test
+        2048,  # Clean air test
+        4096,  # Optical test
+    ]
+
+    def _raw_reader(self, file):
+        """Read and parse raw AE33 Aethalometer data files."""
+        if file.stat().st_size / 1024 < 550:
+            self.logger.warning(f'{file.name} may not be a whole daily data.')
+
+        _df = read_table(file, parse_dates={'time': [0, 1]}, index_col='time',
+                         delimiter=r'\s+', skiprows=5, usecols=range(67))
+        _df.columns = _df.columns.str.strip(';')
+
+        # Select BC columns, Status, and BB(%) if available
+        cols_to_read = self.BC_COLUMNS + ['Status']
+        if self.BB_COLUMN in _df.columns:
+            cols_to_read.append(self.BB_COLUMN)
+
+        _df = _df[cols_to_read].apply(to_numeric, errors='coerce')
+
+        return _df.loc[~_df.index.duplicated() & _df.index.notna()]
+
+    def _QC(self, _df):
+        """
+        Perform quality control on AE33 Aethalometer raw data.
+
+        QC Rules Applied (raw data only)
+        ---------------------------------
+        1. Status Error    : Invalid instrument status codes
+        2. Invalid BC      : BC concentration outside 0-20000 ng/m³
+        3. Insufficient    : Less than 50% hourly data completeness
+
+        Note: AAE validation is done in _process() after calculation.
+        """
+        _index = _df.index.copy()
+        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, self.ERROR_STATES),
+                description='Invalid instrument status code detected'
+            ),
+            QCRule(
+                name='Invalid BC',
+                condition=lambda df: ((df[self.BC_COLUMNS] <= self.MIN_BC) |
+                                      (df[self.BC_COLUMNS] > self.MAX_BC)).any(axis=1),
+                description=f'BC concentration outside valid range {self.MIN_BC}-{self.MAX_BC} ng/m³'
+            ),
+            QCRule(
+                name='Insufficient',
+                condition=lambda df: self.QC_control().hourly_completeness_QC(
+                    df[self.BC_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)
+
+        # 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 absorption coefficients and validate derived parameters.
+
+        Processing Steps
+        ----------------
+        1. Calculate absorption coefficients at each wavelength
+        2. Calculate AAE (Absorption Ångström Exponent)
+        3. Calculate eBC (equivalent Black Carbon)
+        4. Validate AAE range and update QC_Flag
+
+        Parameters
+        ----------
+        _df : pd.DataFrame
+            Quality-controlled DataFrame with BC columns and QC_Flag
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with absorption coefficients, AAE, eBC, and updated QC_Flag
+        """
+        _index = _df.index.copy()
+
+        # Calculate absorption coefficients, AAE, and eBC
+        _df_cal = _absCoe(_df[self.BC_COLUMNS], instru=self.nam, specified_band=[550])
+
+        # Combine with Status, BB(%), and QC_Flag
+        extra_cols = ['Status', 'QC_Flag']
+        if self.BB_COLUMN in _df.columns:
+            extra_cols.insert(0, self.BB_COLUMN)
+        df_out = concat([_df_cal, _df[extra_cols]], axis=1)
+
+        # Validate AAE and update QC_Flag
+        # AAE is stored as negative value, so we check -AAE
+        invalid_aae = (-df_out['AAE'] < self.MIN_AAE) | (-df_out['AAE'] > self.MAX_AAE)
+        df_out = self.update_qc_flag(df_out, invalid_aae, 'Invalid AAE')
+
+        # Log combined QC summary with calculated info
+        if hasattr(self, '_qc_summary') and self._qc_summary is not None:
+            import pandas as pd
+            # Add Invalid AAE row before Valid row
+            total = len(df_out)
+            invalid_aae_row = pd.DataFrame([{
+                'Rule': 'Invalid AAE',
+                'Count': invalid_aae.sum(),
+                'Percentage': f'{invalid_aae.sum() / total * 100:.1f}%',
+                'Description': f'AAE outside valid range {self.MIN_AAE}-{self.MAX_AAE}'
+            }])
+            # Insert before Valid row (last row)
+            summary = pd.concat([self._qc_summary.iloc[:-1], invalid_aae_row, self._qc_summary.iloc[-1:]], ignore_index=True)
+            self.logger.info(f"{self.nam} QC Summary:")
+            for _, row in summary.iterrows():
+                self.logger.info(f"  {row['Rule']}: {row['Count']} ({row['Percentage']})")
+
+        # Reorder columns
+        all_data_cols = self.BC_COLUMNS + self.ABS_COLUMNS + self.CAL_COLUMNS
+        if self.BB_COLUMN in df_out.columns:
+            all_data_cols.append(self.BB_COLUMN)
+        return df_out[all_data_cols + ['QC_Flag']].reindex(_index)

AeroViz/rawDataReader/script/AE43.py

@@ -0,0 +1,151 @@
+from pandas import read_csv, to_numeric, concat
+
+from AeroViz.rawDataReader.core import AbstractReader, QCRule, QCFlagBuilder
+from AeroViz.rawDataReader.core.pre_process import _absCoe
+
+
+class Reader(AbstractReader):
+    """AE43 Aethalometer Data Reader
+
+    A specialized reader for AE43 Aethalometer data files, which measure black carbon
+    concentrations at seven wavelengths.
+
+    See full documentation at docs/source/instruments/AE43.md for detailed information
+    on supported formats and QC procedures.
+    """
+    nam = 'AE43'
+
+    # =========================================================================
+    # Column Definitions
+    # =========================================================================
+    BC_COLUMNS = ['BC1', 'BC2', 'BC3', 'BC4', 'BC5', 'BC6', 'BC7']
+    ABS_COLUMNS = ['abs_370', 'abs_470', 'abs_520', 'abs_590', 'abs_660', 'abs_880', 'abs_950']
+    CAL_COLUMNS = ['abs_550', 'AAE', 'eBC']
+
+    # =========================================================================
+    # QC Thresholds
+    # =========================================================================
+    MIN_BC = 0           # Minimum BC concentration (ng/m³)
+    MAX_BC = 20000       # Maximum BC concentration (ng/m³)
+    MIN_AAE = 0.7        # Minimum valid AAE (absolute value)
+    MAX_AAE = 2.0        # Maximum valid AAE (absolute value)
+
+    # =========================================================================
+    # Status Error Codes (bitwise flags) - Same as AE33
+    # =========================================================================
+    ERROR_STATES = [
+        1,     # Tape advance (tape advance, fast calibration, warm-up)
+        2,     # First measurement – obtaining ATN0
+        3,     # Stopped
+        4,     # Flow low/high by more than 0.5 LPM
+        16,    # Calibrating LED
+        32,    # Calibration error (at least one channel OK)
+        384,   # Tape error (tape not moving, end of tape)
+        1024,  # Stability test
+        2048,  # Clean air test
+        4096,  # Optical test
+    ]
+
+    def _raw_reader(self, file):
+        """Read and parse raw AE43 Aethalometer data files."""
+        _df = read_csv(file, parse_dates={'time': ['StartTime']}, index_col='time')
+        _df_id = _df['SetupID'].iloc[-1]
+
+        # Get last SetupID data (including Status column)
+        _df = _df.groupby('SetupID').get_group(_df_id)[self.BC_COLUMNS + ['Status']].copy()
+        _df = _df.apply(to_numeric, errors='coerce')
+
+        return _df.loc[~_df.index.duplicated() & _df.index.notna()]
+
+    def _QC(self, _df):
+        """
+        Perform quality control on AE43 Aethalometer raw data.
+
+        QC Rules Applied (raw data only)
+        ---------------------------------
+        1. Status Error   : Invalid instrument status codes
+        2. Invalid BC     : BC concentration outside 0-20000 ng/m³
+        3. Insufficient   : Less than 50% hourly data completeness
+
+        Note: AAE validation is done in _process() after calculation.
+        """
+        _index = _df.index.copy()
+        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, self.ERROR_STATES),
+                description='Invalid instrument status code detected'
+            ),
+            QCRule(
+                name='Invalid BC',
+                condition=lambda df: ((df[self.BC_COLUMNS] <= self.MIN_BC) |
+                                      (df[self.BC_COLUMNS] > self.MAX_BC)).any(axis=1),
+                description=f'BC concentration outside valid range {self.MIN_BC}-{self.MAX_BC} ng/m³'
+            ),
+            QCRule(
+                name='Insufficient',
+                condition=lambda df: self.QC_control().hourly_completeness_QC(
+                    df[self.BC_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)
+
+        # 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 absorption coefficients and validate derived parameters.
+
+        Processing Steps
+        ----------------
+        1. Calculate absorption coefficients at each wavelength
+        2. Calculate AAE (Absorption Ångström Exponent)
+        3. Calculate eBC (equivalent Black Carbon)
+        4. Validate AAE range and update QC_Flag
+
+        Note: AE43 uses AE33 coefficients for absorption calculation.
+        """
+        _index = _df.index.copy()
+
+        # Calculate absorption coefficients, AAE, and eBC
+        # Note: AE43 uses AE33 coefficients
+        _df_cal = _absCoe(_df[self.BC_COLUMNS], instru='AE33', specified_band=[550])
+
+        # Combine with Status and QC_Flag
+        df_out = concat([_df_cal, _df[['Status', 'QC_Flag']]], axis=1)
+
+        # Validate AAE and update QC_Flag
+        invalid_aae = (-df_out['AAE'] < self.MIN_AAE) | (-df_out['AAE'] > self.MAX_AAE)
+        df_out = self.update_qc_flag(df_out, invalid_aae, 'Invalid AAE')
+
+        # Log combined QC summary with calculated info
+        if hasattr(self, '_qc_summary') and self._qc_summary is not None:
+            import pandas as pd
+            # Add Invalid AAE row before Valid row
+            total = len(df_out)
+            invalid_aae_row = pd.DataFrame([{
+                'Rule': 'Invalid AAE',
+                'Count': invalid_aae.sum(),
+                'Percentage': f'{invalid_aae.sum() / total * 100:.1f}%',
+                'Description': f'AAE outside valid range {self.MIN_AAE}-{self.MAX_AAE}'
+            }])
+            # Insert before Valid row (last row)
+            summary = pd.concat([self._qc_summary.iloc[:-1], invalid_aae_row, self._qc_summary.iloc[-1:]], ignore_index=True)
+            self.logger.info(f"{self.nam} QC Summary:")
+            for _, row in summary.iterrows():
+                self.logger.info(f"  {row['Rule']}: {row['Count']} ({row['Percentage']})")
+
+        # Reorder columns
+        all_data_cols = self.BC_COLUMNS + self.ABS_COLUMNS + self.CAL_COLUMNS
+        return df_out[all_data_cols + ['QC_Flag']].reindex(_index)

AeroViz/rawDataReader/script/APS.py

@@ -0,0 +1,339 @@
+import numpy as np
+from pandas import to_datetime, read_table, Series, DataFrame, concat
+
+from AeroViz.rawDataReader.core import AbstractReader, QCRule, QCFlagBuilder
+
+
+class Reader(AbstractReader):
+    """APS (Aerodynamic Particle Sizer) Data Reader
+
+    A specialized reader for APS data files, which measure particle size distributions
+    in the range of 542-1981 nm (aerodynamic diameter).
+
+    See full documentation at docs/source/instruments/APS.md for detailed information
+    on supported formats and QC procedures.
+    """
+    nam = 'APS'
+
+    # =========================================================================
+    # QC Thresholds
+    # =========================================================================
+    MIN_HOURLY_COUNT = 5  # Minimum measurements per hour
+    MIN_TOTAL_CONC = 1  # Minimum total concentration (#/cm³)
+    MAX_TOTAL_CONC = 700  # Maximum total concentration (#/cm³)
+
+    # Status Flags column name
+    STATUS_COLUMN = 'Status Flags'
+    # All zeros status means no error
+    STATUS_OK = '0000 0000 0000 0000'
+
+    # APS Status Flag bit definitions (from TSI RF command)
+    # Format: bit_position: description
+    ERROR_STATES = {
+        0: 'Laser fault',
+        1: 'Total Flow out of range',
+        2: 'Sheath Flow out of range',
+        3: 'Excessive sample concentration',
+        4: 'Accumulator clipped',
+        5: 'Autocal failed',
+        6: 'Internal temperature < 10°C',
+        7: 'Internal temperature > 40°C',
+        8: 'Detector voltage out of range',
+        # 9: Reserved (unused)
+    }
+
+    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 APS 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 APS data files.
+
+        Handles files with multiple concatenated headers (when multiple APS export
+        files are merged into one). Header rows are identified and filtered out.
+        """
+        with open(file, 'r', encoding='utf-8', errors='ignore') as f:
+            try:
+                # Try normal reading first
+                _df_full = read_table(f, skiprows=6, parse_dates={'Time': ['Date', 'Start Time']},
+                                      date_format='%m/%d/%y %H:%M:%S', low_memory=False).set_index('Time')
+            except:
+                # File is transposed, re-read
+                f.seek(0)
+                raw_df = read_table(f, skiprows=6, low_memory=False, index_col='Sample #')
+                _df_full = raw_df.T
+                _df_full.columns.name = None
+
+                if 'Date' in _df_full.columns and 'Start Time' in _df_full.columns:
+                    datetime_str = _df_full['Date'] + ' ' + _df_full['Start Time']
+                    df_idx = to_datetime(datetime_str, format='%m/%d/%y %H:%M:%S', errors='coerce')
+                    _df_full.index = df_idx
+                    _df_full.index.name = 'Time'
+                    _df_full.drop('Date', axis=1, inplace=True)
+
+            # Index is already datetime from try/except block above
+            # Filter out invalid timestamps (NaT from embedded headers)
+            _df_full = _df_full.loc[_df_full.index.notna()]
+            # Remove duplicate indices (keep first occurrence)
+            dup_mask = _df_full.index.duplicated(keep=False)
+            if dup_mask.any():
+                print(f"File: {file.name} - Duplicated indices: {_df_full.index[dup_mask].unique().tolist()}")
+            _df_full = _df_full[~_df_full.index.duplicated(keep='first')]
+
+            # Now extract size bins (542 nm ~ 1981 nm, columns 3 to 54)
+            _df = _df_full.iloc[:, 3:54].rename(columns=lambda x: round(float(x), 4))
+
+            # Include Status Flags column in _df (will be processed by core together)
+            if self.STATUS_COLUMN in _df_full.columns:
+                _df[self.STATUS_COLUMN] = _df_full[self.STATUS_COLUMN].astype(str).str.strip()
+
+        return _df
+
+    def _QC(self, _df):
+        """
+        Perform quality control on APS data.
+
+        QC Rules Applied
+        ----------------
+        1. Status Error   : Non-zero status flags indicate instrument error
+        2. Insufficient   : Less than 5 measurements per hour
+        3. Invalid Number Conc : Total number concentration outside valid range (1-700 #/cm³)
+        """
+        _df = _df.copy()
+        _index = _df.index.copy()
+
+        # Filter to numeric columns only (exclude Status Flags)
+        numeric_cols = [col for col in _df.columns if isinstance(col, (int, float))]
+        df_numeric = _df[numeric_cols]
+
+        # Calculate total concentration
+        dlogDp = np.diff(np.log(df_numeric.columns.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'))
+
+        # 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='binary_string'
+                ),
+                description='Non-zero status flags indicate instrument error'
+            ),
+            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} #/cm³)'
+            ),
+        ])
+
+        # 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 APS 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 totals for size cutoffs: 1μm, 2.5μm, all
+        5. Store distributions for separate file output
+
+        Size Cutoffs (APS range: 0.542-19.81 μm)
+        -----------------------------------------
+        - 1μm: particles smaller than 1 μm
+        - 2.5μm: particles smaller than 2.5 μm
+        - all: full size range
+
+        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)  # in μm
+
+        # 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 (μm²·cm⁻³)
+        dV_dlogDp = dN_dlogDp * np.pi * (dp ** 3) / 6  # Volume distribution (μm³·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])  # Extend to match length
+        dN = dN_dlogDp * dlogDp  # Number concentration
+        dS = dS_dlogDp * dlogDp  # Surface area
+        dV = dV_dlogDp * dlogDp  # Volume
+
+        # Calculate statistics
+        stats = DataFrame(index=_df.index)
+
+        # Size cutoffs in μm (APS bins are in μm)
+        SIZE_CUTOFFS = {
+            '1um': 1.0,  # 1 μm
+            '2.5um': 2.5,  # 2.5 μm
+            'all': np.inf  # All particles
+        }
+
+        # Calculate for each weighting type and size cutoff
+        for weight_name, dist in [('num', dN), ('surf', dS), ('vol', dV)]:
+            for cutoff_name, cutoff_um in SIZE_CUTOFFS.items():
+                # Filter bins for this cutoff
+                mask_bins = dp < cutoff_um
+                if not mask_bins.any():
+                    continue
+
+                dp_cut = dp[mask_bins]
+                dist_cut = dist.iloc[:, mask_bins]
+
+                # Calculate total
+                total = dist_cut.sum(axis=1, min_count=1)
+                stats[f'total_{weight_name}_{cutoff_name}'] = total
+
+                # Calculate GMD and GSD only for 'all' cutoff
+                if cutoff_name == 'all':
+                    total_valid = total.where(total > 0)
+
+                    # GMD calculation (in log space)
+                    log_dp = np.log(dp_cut)
+                    gmd_log = (dist_cut * 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_cut.values).sum(axis=1) / total_valid)
+
+                    stats[f'GMD_{weight_name}'] = np.exp(gmd_log)
+                    stats[f'GSD_{weight_name}'] = np.exp(gsd_log)
+
+                    # Calculate mode (diameter with maximum concentration)
+                    mask = dist_cut.notna().any(axis=1)
+                    stats.loc[mask, f'mode_{weight_name}'] = dist_cut.loc[mask].idxmax(axis=1)
+
+        # 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_aps_dNdlogDp.csv : Number distribution (dN/dlogDp)
+        - output_aps_dSdlogDp.csv : Surface distribution (dS/dlogDp)
+        - output_aps_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}")