AeroViz 0.1.21__py3-none-any.whl

AeroViz/dataProcess/Optical/_retrieve_RI.py

@@ -0,0 +1,243 @@
+"""
+Refractive index retrieval from optical measurements.
+
+This module provides functions for retrieving the complex refractive
+index of aerosol particles using a grid search minimization approach
+based on Mie theory calculations.
+
+Required Columns
+----------------
+For retrieve_RI:
+    - Extinction : Extinction coefficient (Mm-1)
+    - Scattering : Scattering coefficient (Mm-1)
+    - Absorption : Absorption coefficient (Mm-1)
+    - PNSD columns : Particle number size distribution (dN/dlogDp)
+"""
+
+import numpy as np
+from pandas import DataFrame
+
+from AeroViz.dataProcess.core import validate_inputs
+
+__all__ = ['retrieve_RI', 'grid_search_RI', 'get_required_columns']
+
+# Required columns for optical data
+REQUIRED_OPTICAL_COLUMNS = ['Extinction', 'Scattering', 'Absorption']
+
+COLUMN_DESCRIPTIONS = {
+    'Extinction': 'Extinction coefficient 消光係數 (Mm-1)',
+    'Scattering': 'Scattering coefficient 散射係數 (Mm-1)',
+    'Absorption': 'Absorption coefficient 吸收係數 (Mm-1)',
+}
+
+
+def grid_search_RI(bext_mea: float,
+                   bsca_mea: float,
+                   babs_mea: float,
+                   dp: np.ndarray,
+                   ndp: np.ndarray,
+                   dlogdp: float = 0.014,
+                   wavelength: float = 550,
+                   n_range: tuple = (1.33, 1.60),
+                   k_range: tuple = (0.00, 0.60),
+                   space_size: int = 31
+                   ) -> tuple:
+    """
+    Retrieve the complex refractive index using grid search minimization.
+
+    This function performs a two-stage grid search to find the refractive
+    index that best matches the measured optical properties.
+
+    Parameters
+    ----------
+    bext_mea : float
+        Measured extinction coefficient (Mm-1).
+    bsca_mea : float
+        Measured scattering coefficient (Mm-1).
+    babs_mea : float
+        Measured absorption coefficient (Mm-1).
+    dp : np.ndarray
+        Particle diameter array (nm).
+    ndp : np.ndarray
+        Number concentration for each diameter (dN/dlogDp).
+    dlogdp : float, default=0.014
+        Logarithmic bin width.
+    wavelength : float, default=550
+        Wavelength for Mie calculation (nm).
+    n_range : tuple, default=(1.33, 1.60)
+        Range of real refractive index (n) to search.
+    k_range : tuple, default=(0.00, 0.60)
+        Range of imaginary refractive index (k) to search.
+    space_size : int, default=31
+        Number of grid points in each dimension.
+
+    Returns
+    -------
+    tuple
+        (n_retrieved, k_retrieved) - The retrieved refractive index components.
+    """
+    from .mie_theory import Mie_PESD
+
+    n_array = np.linspace(n_range[0], n_range[1], num=space_size)
+    k_array = np.linspace(k_range[0], k_range[1], space_size)
+    delta_array = np.zeros((space_size, space_size))
+
+    # First pass: coarse grid search
+    for ki, k in enumerate(k_array):
+        for ni, n in enumerate(n_array):
+            m = n + (1j * k)
+
+            ext_dist, sca_dist, abs_dist = Mie_PESD(m, wavelength, dp, ndp)
+
+            bext_cal = sum(ext_dist) * dlogdp
+            bsca_cal = sum(sca_dist) * dlogdp
+            babs_cal = sum(abs_dist) * dlogdp
+
+            # Normalized chi-squared
+            delta_array[ni][ki] = ((babs_mea - babs_cal) / 18.23) ** 2 + \
+                                  ((bsca_mea - bsca_cal) / 83.67) ** 2
+
+    # Find minimum and refine
+    min_delta = delta_array.argmin()
+    next_n = n_array[(min_delta // space_size)]
+    next_k = k_array[(min_delta % space_size)]
+
+    # Second pass: fine grid search around the minimum
+    n_min = max(next_n - 0.02, 1.33)
+    n_max = next_n + 0.02
+    k_min = max(next_k - 0.04, 0)
+    k_max = next_k + 0.04
+    fine_size = 41
+
+    n_fine = np.linspace(n_min, n_max, fine_size)
+    k_fine = np.linspace(k_min, k_max, fine_size)
+    delta_fine = np.zeros((fine_size, fine_size))
+
+    for ki, k in enumerate(k_fine):
+        for ni, n in enumerate(n_fine):
+            m = n + (1j * k)
+
+            ext_dist, sca_dist, abs_dist = Mie_PESD(m, wavelength, dp, ndp)
+
+            bext_cal = sum(ext_dist) * dlogdp
+            bsca_cal = sum(sca_dist) * dlogdp
+            babs_cal = sum(abs_dist) * dlogdp
+
+            delta_fine[ni][ki] = ((bext_mea - bext_cal) / 18.23) ** 2 + \
+                                 ((bsca_mea - bsca_cal) / 83.67) ** 2
+
+    min_delta_fine = delta_fine.argmin()
+    n_retrieved = n_fine[(min_delta_fine // fine_size)]
+    k_retrieved = k_fine[(min_delta_fine % fine_size)]
+
+    return n_retrieved, k_retrieved
+
+
+def retrieve_RI(df_optical: DataFrame,
+                df_pnsd: DataFrame,
+                dlogdp: float = 0.014,
+                wavelength: float = 550,
+                n_range: tuple = (1.33, 1.60),
+                k_range: tuple = (0.00, 0.60),
+                space_size: int = 31
+                ) -> DataFrame:
+    """
+    Retrieve refractive index for a time series of measurements.
+
+    Parameters
+    ----------
+    df_optical : DataFrame
+        Optical measurements with required columns:
+        - Extinction : Extinction coefficient (Mm-1)
+        - Scattering : Scattering coefficient (Mm-1)
+        - Absorption : Absorption coefficient (Mm-1)
+    df_pnsd : DataFrame
+        Particle number size distribution with diameter columns (nm).
+        Column names should be diameter values (e.g., 10.0, 20.0, ...).
+    dlogdp : float, default=0.014
+        Logarithmic bin width.
+    wavelength : float, default=550
+        Wavelength for Mie calculation (nm).
+    n_range : tuple, default=(1.33, 1.60)
+        Range of real refractive index to search.
+    k_range : tuple, default=(0.00, 0.60)
+        Range of imaginary refractive index to search.
+    space_size : int, default=31
+        Number of grid points for initial search.
+
+    Returns
+    -------
+    DataFrame
+        Retrieved refractive index with columns: re_real, re_imaginary.
+
+    Raises
+    ------
+    ValueError
+        If required columns are missing from df_optical or df_pnsd is empty.
+
+    Examples
+    --------
+    >>> cols = get_required_columns()
+    >>> print(cols['retrieve_RI'])
+    """
+    from pandas import concat
+
+    # Validate optical data
+    validate_inputs(df_optical, REQUIRED_OPTICAL_COLUMNS, 'retrieve_RI', COLUMN_DESCRIPTIONS)
+
+    # Validate PNSD data
+    if df_pnsd is None or df_pnsd.empty:
+        raise ValueError(
+            "\nretrieve_RI() 需要粒徑分布資料！\n"
+            "  必要輸入: df_pnsd (Particle Number Size Distribution)\n"
+            "  欄位格式: 粒徑值作為欄位名稱 (nm)"
+        )
+
+    combined = concat([df_optical, df_pnsd], axis=1).dropna()
+    dp = np.array(df_pnsd.columns, dtype=float)
+
+    results = []
+
+    for idx, row in combined.iterrows():
+        bext_mea = row['Extinction']
+        bsca_mea = row['Scattering']
+        babs_mea = row['Absorption']
+        ndp = np.array(row[df_pnsd.columns])
+
+        n_ret, k_ret = grid_search_RI(
+            bext_mea, bsca_mea, babs_mea,
+            dp, ndp, dlogdp, wavelength,
+            n_range, k_range, space_size
+        )
+
+        results.append({'re_real': n_ret, 're_imaginary': k_ret})
+
+    result_df = DataFrame(results, index=combined.index)
+
+    return result_df.reindex(df_optical.index)
+
+
+def get_required_columns():
+    """
+    Get required column names for refractive index retrieval.
+
+    Returns
+    -------
+    dict
+        Dictionary with function names as keys and required columns as values.
+
+    Examples
+    --------
+    >>> cols = get_required_columns()
+    >>> print(cols['retrieve_RI'])
+    """
+    return {
+        'retrieve_RI': {
+            'df_optical': REQUIRED_OPTICAL_COLUMNS.copy(),
+            'df_pnsd': 'Diameter values as column names (nm)'
+        },
+        'grid_search_RI': {
+            'description': '單點反演，需提供標量值',
+            'inputs': ['bext_mea', 'bsca_mea', 'babs_mea', 'dp (array)', 'ndp (array)']
+        }
+    }

AeroViz/dataProcess/Optical/coefficient.py

@@ -0,0 +1,72 @@
+import numpy as np
+import pandas as pd
+from scipy.optimize import curve_fit
+
+
+def _scaCoe(df, instru, specified_band: list):
+    band_Neph = np.array([450, 550, 700])
+    band_Aurora = np.array([450, 525, 635])
+
+    band = band_Neph if instru == 'Neph' else band_Aurora
+
+    df_sca = df.copy().dropna()
+
+    if instru == 'Neph':
+        df_out = df_sca[['G']].copy()
+        df_out.columns = [f'sca_{_band}' for _band in specified_band]
+    else:
+        df_out = df_sca.apply(get_species_wavelength, axis=1, result_type='expand', args=(specified_band,))
+        df_out.columns = [f'sca_{_band}' for _band in specified_band]
+
+    # calculate
+    df_SAE = df[['B', 'G', 'R']].dropna().apply(get_Angstrom_exponent, axis=1, result_type='expand', args=(band,))
+    df_SAE.columns = ['SAE', 'SAE_intercept']
+
+    _df = pd.concat([df_out, df_SAE['SAE']], axis=1)
+
+    return _df.reindex(df.index)
+
+
+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
+    eBC = 'BC6' if instru == 'AE33' else 'BC9'
+
+    # calculate
+    df_abs = (df.copy().dropna() * MAE).copy()
+
+    df_out = df_abs.apply(get_species_wavelength, axis=1, result_type='expand', args=(specified_band,))
+    df_out.columns = [f'abs_{_band}' for _band in specified_band]
+    df_out['eBC'] = df[eBC]
+
+    df_AAE = df_abs.apply(get_Angstrom_exponent, axis=1, result_type='expand', args=(band,))
+    df_AAE.columns = ['AAE', 'AAE_intercept']
+    df_AAE = df_AAE.mask((-df_AAE['AAE'] < 0.8) | (-df_AAE['AAE'] > 2.)).copy()
+
+    _df = pd.concat([df_out, df_AAE['AAE']], axis=1)
+    return _df.reindex(df.index)
+
+
+def get_species_wavelength(df, specified_band):
+    func = lambda wavelength, _sl, _int: _sl * wavelength + _int
+    popt, pcov = curve_fit(func, specified_band, df.values)
+
+    return func(np.array(specified_band), *popt)
+
+
+def get_Angstrom_exponent(df, band):
+    if (df <= 0).any():
+        return pd.Series([np.nan, np.nan], index=['slope', 'intercept'])  # 返回包含 NaN 的 Series，保持 DataFrame 结构
+
+    func = lambda wavelength, _sl, _int: _sl * wavelength + _int
+    popt, _ = curve_fit(func, np.log(band), np.log(df))
+
+    return pd.Series(popt, index=['slope', 'intercept'])  # 返回带有索引的 Series

AeroViz/dataProcess/Optical/mie_theory.py

@@ -0,0 +1,260 @@
+from typing import Sequence, Literal
+
+import numpy as np
+import pandas as pd
+from numpy import exp, log, log10, sqrt, pi
+
+from .PyMieScatt_update import AutoMieQ
+
+
+def Mie_Q(m: complex,
+          wavelength: float,
+          dp: float | Sequence[float]
+          ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Calculate Mie scattering efficiency (Q) for given spherical particle diameter(s).
+
+    Parameters
+    ----------
+    m : complex
+        The complex refractive index of the particles.
+    wavelength : float
+        The wavelength of the incident light (in nm).
+    dp : float | Sequence[float]
+        Particle diameters (in nm), can be a single value or Sequence object.
+
+    Returns
+    -------
+    Q_ext : ndarray
+        The Mie extinction efficiency for each particle diameter.
+    Q_sca : ndarray
+        The Mie scattering efficiency for each particle diameter.
+    Q_abs : ndarray
+        The Mie absorption efficiency for each particle diameter.
+
+    Examples
+    --------
+    >>> Q_ext, Q_sca, Q_abs = Mie_Q(m=complex(1.5, 0.02), wavelength=550, dp=[100, 200, 300, 400])
+    """
+    # Ensure dp is a numpy array
+    dp = np.atleast_1d(dp)
+
+    # Transpose for proper unpacking
+    Q_ext, Q_sca, Q_abs, g, Q_pr, Q_back, Q_ratio = np.array([AutoMieQ(m, wavelength, _dp) for _dp in dp]).T
+
+    return Q_ext, Q_sca, Q_abs
+
+
+def Mie_MEE(m: complex,
+            wavelength: float,
+            dp: float | Sequence[float],
+            density: float
+            ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Calculate mass extinction efficiency and other parameters.
+
+    Parameters
+    ----------
+    m : complex
+        The complex refractive index of the particles.
+    wavelength : float
+        The wavelength of the incident light.
+    dp : float | Sequence[float]
+        List of particle sizes or a single value.
+    density : float
+        The density of particles.
+
+    Returns
+    -------
+    MEE : ndarray
+        The mass extinction efficiency for each particle diameter.
+    MSE : ndarray
+        The mass scattering efficiency for each particle diameter.
+    MAE : ndarray
+        The mass absorption efficiency for each particle diameter.
+
+    Examples
+    --------
+    >>> MEE, MSE, MAE = Mie_MEE(m=complex(1.5, 0.02), wavelength=550, dp=[100, 200, 300, 400], density=1.2)
+    """
+    Q_ext, Q_sca, Q_abs = Mie_Q(m, wavelength, dp)
+
+    MEE = (3 * Q_ext) / (2 * density * dp) * 1000
+    MSE = (3 * Q_sca) / (2 * density * dp) * 1000
+    MAE = (3 * Q_abs) / (2 * density * dp) * 1000
+
+    return MEE, MSE, MAE
+
+
+def Mie_PESD(m: complex,
+             wavelength: float = 550,
+             dp: float | Sequence[float] = None,
+             ndp: float | Sequence[float] = None,
+             lognormal: bool = False,
+             dp_range: tuple = (1, 2500),
+             geoMean: float = 200,
+             geoStdDev: float = 2,
+             numberOfParticles: float = 1e6,
+             numberOfBins: int = 167,
+             ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Simultaneously calculate "extinction distribution" and "integrated results" using the Mie_Q method.
+
+    Parameters
+    ----------
+    m : complex
+        The complex refractive index of the particles.
+    wavelength : float
+        The wavelength of the incident light.
+    dp : float | Sequence[float]
+        Particle sizes.
+    ndp : float | Sequence[float]
+        Number concentration from SMPS or APS in the units of dN/dlogdp.
+    lognormal : bool, optional
+        Whether to use lognormal distribution for ndp. Default is False.
+    dp_range : tuple, optional
+        Range of particle sizes. Default is (1, 2500) nm.
+    geoMean : float, optional
+        Geometric mean of the particle size distribution. Default is 200 nm.
+    geoStdDev : float, optional
+        Geometric standard deviation of the particle size distribution. Default is 2.
+    numberOfParticles : float, optional
+        Number of particles. Default is 1e6.
+    numberOfBins : int, optional
+        Number of bins for the lognormal distribution. Default is 167.
+
+    Returns
+    -------
+    ext_dist : ndarray
+        The extinction distribution for the given data.
+    sca_dist : ndarray
+        The scattering distribution for the given data.
+    abs_dist : ndarray
+        The absorption distribution for the given data.
+
+    Notes
+    -----
+    return in "dext/dlogdp", please make sure input the dNdlogdp data.
+
+    Examples
+    --------
+    >>> Ext, Sca, Abs = Mie_PESD(m=complex(1.5, 0.02), wavelength=550, dp=[100, 200, 500, 1000], ndp=[100, 50, 30, 20])
+    """
+    if lognormal:
+        dp = np.logspace(log10(dp_range[0]), log10(dp_range[1]), numberOfBins)
+
+        ndp = numberOfParticles * (1 / (log(geoStdDev) * sqrt(2 * pi)) *
+                                   exp(-(log(dp) - log(geoMean)) ** 2 / (2 * log(geoStdDev) ** 2)))
+
+    # dN / dlogdp
+    ndp = np.atleast_1d(ndp)
+
+    Q_ext, Q_sca, Q_abs = Mie_Q(m, wavelength, dp)
+
+    # The 1e-6 here is so that the final value is the same as the unit 1/10^6m.
+    Ext = Q_ext * (pi / 4 * dp ** 2) * ndp * 1e-6
+    Sca = Q_sca * (pi / 4 * dp ** 2) * ndp * 1e-6
+    Abs = Q_abs * (pi / 4 * dp ** 2) * ndp * 1e-6
+
+    return Ext, Sca, Abs
+
+
+def internal(dist: pd.Series,
+             dp: float | Sequence[float],
+             wavelength: float = 550,
+             result_type: Literal['extinction', 'scattering', 'absorption'] = 'extinction'
+             ) -> np.ndarray:
+    """
+    Calculate the extinction distribution by internal mixing model.
+
+    Parameters
+    ----------
+    dist : pd.Series
+        Particle size distribution data.
+    dp : float | Sequence[float]
+        Diameter(s) of the particles, either a single value or a sequence.
+    wavelength : float, optional
+        Wavelength of the incident light, default is 550 nm.
+    result_type : {'extinction', 'scattering', 'absorption'}, optional
+        Type of result to calculate, defaults to 'extinction'.
+
+    Returns
+    -------
+    np.ndarray
+        Extinction distribution calculated based on the internal mixing model.
+    """
+    ext_dist, sca_dist, abs_dist = Mie_PESD(m=complex(dist['n_amb'], dist['k_amb']),
+                                            wavelength=wavelength,
+                                            dp=dp,
+                                            ndp=np.array(dist[:np.size(dp)]))
+
+    if result_type == 'extinction':
+        return ext_dist
+    elif result_type == 'scattering':
+        return sca_dist
+    else:
+        return abs_dist
+
+
+# return dict(ext=ext_dist, sca=sca_dist, abs=abs_dist)
+
+
+def external(dist: pd.Series,
+             dp: float | Sequence[float],
+             wavelength: float = 550,
+             result_type: Literal['extinction', 'scattering', 'absorption'] = 'extinction'
+             ) -> np.ndarray:
+    """
+    Calculate the extinction distribution by external mixing model.
+
+    Parameters
+    ----------
+    dist : pd.Series
+        Particle size distribution data.
+    dp : float | Sequence[float]
+        Diameter(s) of the particles, either a single value or a sequence.
+    wavelength : float, optional
+        Wavelength of the incident light, default is 550 nm.
+    result_type : {'extinction', 'scattering', 'absorption'}, optional
+        Type of result to calculate, defaults to 'extinction'.
+
+    Returns
+    -------
+    np.ndarray
+        Extinction distribution calculated based on the external mixing model.
+    """
+    refractive_dic = {'AS_volume_ratio': complex(1.53, 0.00),
+                      'AN_volume_ratio': complex(1.55, 0.00),
+                      'OM_volume_ratio': complex(1.54, 0.00),
+                      'Soil_volume_ratio': complex(1.56, 0.01),
+                      'SS_volume_ratio': complex(1.54, 0.00),
+                      'EC_volume_ratio': complex(1.80, 0.54),
+                      'ALWC_volume_ratio': complex(1.33, 0.00)}
+
+    ndp = np.array(dist[:np.size(dp)])
+    mie_results = (
+        Mie_PESD(refractive_dic[_specie], wavelength, dp, dist[_specie] / (1 + dist['ALWC_volume_ratio']) * ndp) for
+        _specie in refractive_dic)
+
+    ext_dist, sca_dist, abs_dist = (np.sum([res[0] for res in mie_results], axis=0),
+                                    np.sum([res[1] for res in mie_results], axis=0),
+                                    np.sum([res[2] for res in mie_results], axis=0))
+
+    if result_type == 'extinction':
+        return ext_dist
+    elif result_type == 'scattering':
+        return sca_dist
+    else:
+        return abs_dist
+
+
+def core_shell():
+    pass
+
+
+def sensitivity():
+    pass
+
+
+if __name__ == '__main__':
+    result = Mie_Q(m=complex(1.5, 0.02), wavelength=550, dp=[100., 200.])