Skip to content

Optical 模組

光學特性數據處理模組。

結構

Optical/
├── __init__.py       # Optical (Writer 入口)
├── _IMPROVE.py       # IMPROVE 消光方程
├── _mie.py           # Mie 理論計算
├── _mie_sd.py        # Mie 粒徑分布計算
├── _retrieve_RI.py   # 折射率反演
├── _derived.py       # 衍生光學參數
├── mie_theory.py     # Mie 混合模式
└── coefficient.py    # 散射/吸收係數

快速開始

from pathlib import Path
from AeroViz.dataProcess import DataProcess

dp = DataProcess('Optical', Path('./output'))
result = dp.IMPROVE(df_mass, df_RH, method='revised')

方法列表

方法 說明 相關理論
basic(df_sca, df_abs) 基本消光特性 -
IMPROVE(df_mass, df_RH, method) IMPROVE 消光方程 → IMPROVE
gas_extinction(df_no2, df_temp) 氣體消光貢獻 → IMPROVE
Mie(df_pnsd, df_m, wave_length) Mie 消光計算 → Mie 理論
retrieve_RI(df_optical, df_pnsd) 折射率反演 → Mie 理論
derived(...) 衍生光學參數 -

輸出說明

IMPROVE

輸出 說明
dry 乾燥消光 (欄位：AS, AN, OM, Soil, SS, EC, total；小寫 total = 各成分加總)
wet 濕消光 (同上欄位)
ALWC 液態水貢獻 (wet - dry)
fRH 吸濕成長因子

df_RH 必須是 Series（例如 met['RH']），不可傳單欄 DataFrame。 總消光請用 dry['total'] / wet['total']，勿用 .sum(axis=1)（會把 total 欄重複計入）。

Mie

輸出 說明
extinction 消光係數 (Mm⁻¹)
scattering 散射係數 (Mm⁻¹)
absorption 吸收係數 (Mm⁻¹)

retrieve_RI

輸出 說明
n 實部
k 虛部

derived

輸出 說明
PG 總消光 (Sca + Abs + Gas)
MAC 質量吸收截面 (m²/g)
Ox 氧化劑濃度 (NO₂ + O₃)
Vis_cal 計算能見度 (km)
fRH_IMPR IMPROVE fRH
OCEC_ratio OC/EC 比值
PM1_PM25 PM1/PM2.5 比值

Mie 混合模式

模式 說明
internal 內混合：體積加權平均折射率
external 外混合：分別計算後加總
core_shell 核殼結構：EC 核心 + 其他殼層
sensitivity 敏感度分析

輸入格式

散射係數（NEPH 輸出；欄位小寫）

df_sca.columns = ['sca_550', 'SAE']  # optical_basic 需要這兩欄

吸收係數（AE33 輸出；欄位小寫）

df_abs.columns = ['abs_550', 'AAE', 'eBC']  # optical_basic 需要這三欄
# AE33 也提供多波長 abs_370 ~ abs_950 (Mm⁻¹)

質量濃度（IMPROVE 用）

required = ['AS', 'AN', 'OM', 'Soil', 'SS', 'EC']  # μg/m³

相關資源

API 參考

AeroViz.dataProcess.Optical.Optical 

Optical(path_out=None, excel=True, csv=False)

Bases: Writer

Functions

scaCoe 

scaCoe(df_sca, instru, specified_band)

absCoe 

absCoe(df_ae33, instru, specified_band)

basic 

basic(df_sca, df_abs, df_mass=None, df_no2=None, df_temp=None)

Mie 

Mie(df_psd, df_m, wavelength=550, psd_type='auto')

Calculate optical properties from PSD using Mie theory.

Parameters:

Name Type Description Default
df_psd DataFrame

Particle number size distribution. Columns are particle diameters (nm), rows are time points.

 required
df_m DataFrame or Series

Complex refractive index (n + ik) for each time point.

 required
wavelength float

Wavelength of incident light in nm.

 550
psd_type str

Type of PSD input: - 'dNdlogDp': Number concentration per log bin width (#/cm³) - 'dN': Number concentration per bin (#/cm³/bin) - 'auto': Auto-detect with warning if uncertain

 'auto'

Returns:

Type Description
DataFrame

Optical coefficients with columns: ext, sca, abs (Mm⁻¹)

IMPROVE 

IMPROVE(df_mass, df_RH=None, method='revised', df_nh4_status=None, df_ext=None, oa_oc_ratio=1.8, upper_bounds=None)

Calculate extinction using IMPROVE equation.

Parameters:

Name Type Description Default
df_mass DataFrame

Mass concentrations. - 'revised' / 'modified': columns AS, AN, OM, Soil, SS, EC - 'localized': columns AS, AN, POC, SOC, Soil, SS, EC

 required
df_RH DataFrame

Relative humidity data (%).

 None
method str

IMPROVE version: 'revised', 'modified', or 'localized'.

 'revised'
df_nh4_status DataFrame

NH4 status from reconstruction_basic()['NH4_status']. If provided, rows with 'Deficiency' status will be excluded.

 None
df_ext DataFrame

Measured extinction with 'Scattering' and 'Absorption' columns (Mm⁻¹). Required when method='localized' to fit POA/SOA mass scattering efficiencies via MLR.

 None
oa_oc_ratio float

OA/OC conversion ratio (used only by method='localized').

 1.8
upper_bounds dict

Upper bounds for the MLR coefficients (used only by method='localized'). Defaults to {'S_POA': 10, 'L_POA': 10, 'S_SOA': 10, 'L_SOA': 10}.

 None

Returns:

Type Description
dict

Dictionary with keys: - 'dry': Dry extinction DataFrame - 'wet': Wet extinction DataFrame (if df_RH provided) - 'ALWC': Water contribution (wet - dry) - 'fRH': Hygroscopic growth factor For method='localized' the dict additionally contains: - 'coefficients': fitted MSE/MAE values - 'regression': slope and R² of the closure

gas_extinction 

gas_extinction(df_no2, df_temp)

Calculate gas contribution to extinction.

Parameters:

Name Type Description Default
df_no2 DataFrame

NO2 concentration (ppb)

 required
df_temp DataFrame

Ambient temperature (Celsius)

 required

Returns:

Type Description
DataFrame

Gas extinction with ScatteringByGas, AbsorptionByGas, ExtinctionByGas

retrieve_RI 

retrieve_RI(df_optical, df_pnsd, dlogdp=0.014, wavelength=550)

Retrieve refractive index from optical and PSD measurements.

Parameters:

Name Type Description Default
df_optical DataFrame

Optical data with Extinction, Scattering, Absorption columns

 required
df_pnsd DataFrame

Particle number size distribution data

 required
dlogdp float

Logarithmic bin width

 0.014
wavelength float

Wavelength in nm

 550

Returns:

Type Description
DataFrame

Retrieved refractive index with re_real and re_imaginary columns

derived 

derived(df_sca=None, df_abs=None, df_ext=None, df_no2=None, df_o3=None, df_ec=None, df_oc=None, df_pm1=None, df_pm25=None, df_improve=None)

Calculate derived optical and atmospheric parameters.

Parameters:

Name Type Description Default
df_sca DataFrame

Scattering coefficient (Mm-1)

 None
df_abs DataFrame

Absorption coefficient (Mm-1)

 None
df_ext DataFrame

Extinction coefficient (Mm-1)

 None
df_no2 DataFrame

NO2 concentration (ppb)

 None
df_o3 DataFrame

O3 concentration (ppb)

 None
df_ec DataFrame

Elemental carbon (ug/m3)

 None
df_oc DataFrame

Organic carbon (ug/m3)

 None
df_pm1 DataFrame

PM1 (ug/m3)

 None
df_pm25 DataFrame

PM2.5 (ug/m3)

 None
df_improve DataFrame

IMPROVE extinction data

 None

Returns:

Type Description
DataFrame

Derived parameters (PG, MAC, Ox, Vis_cal, fRH_IMPR, OCEC_ratio, etc.)

BrC 

BrC(df_abs, wavelengths=None, ref_wavelength=880, aae_bc=1.0)

Calculate Brown Carbon (BrC) absorption by separating BC and BrC contributions.

This method uses the AAE-based separation approach: 1. Assume Black Carbon (BC) has AAE = 1.0 (or user-specified value) 2. Absorption at 880nm is entirely from BC (reference wavelength) 3. Calculate BC absorption at shorter wavelengths using power law 4. BrC absorption = Total absorption - BC absorption 5. Calculate BrC AAE from the derived spectrum

Parameters:

Name Type Description Default
df_abs DataFrame

Absorption coefficient data with columns like 'abs_370', 'abs_470', 'abs_520', 'abs_590', 'abs_660', 'abs_880'. Units should be Mm-1.

 required
wavelengths list[int]

Wavelengths to calculate BrC absorption for. Default: [370, 470, 520, 590, 660]

 None
ref_wavelength int

Reference wavelength (nm) assumed to be purely BC absorption.

 880
aae_bc float

Absorption Ångström Exponent for Black Carbon. Typical range: 0.8-1.1 for fresh BC.

 1.0

Returns:

Type Description
DataFrame
  • abs_BC_{wl}: BC absorption at each wavelength (Mm-1)
  • abs_BrC_{wl}: BrC absorption at each wavelength (Mm-1, NaN if invalid)
  • BrC_fraction_{wl}: BrC contribution fraction (0-1, NaN if invalid)
  • AAE_BrC: BrC Absorption Ångström Exponent (NaN if invalid)

Examples:

>>> from AeroViz import RawDataReader, DataProcess
>>> # Read AE33 data (has multi-wavelength absorption)
>>> ae33 = RawDataReader(instrument='AE33', path='/data/AE33',
...                       start='2024-01-01', end='2024-01-31')
>>> # Calculate BrC
>>> optical = DataProcess(method='Optical')
>>> brc_result = optical.BrC(ae33)
>>> # Check valid data (non-NaN)
>>> valid_brc = brc_result['AAE_BrC'].dropna()
>>> print(valid_brc.mean())
Notes

The separation assumes AAE_BC ≈ 1.0 based on Mie theory for graphitic carbon. Real BC may have slightly different AAE depending on mixing state and size distribution.

Validity check: If calculated BC absorption exceeds total absorption at ANY wavelength, the entire row is marked as invalid (NaN for all BrC-related values). This indicates the AAE=1 assumption is not valid.

References
  • Lack & Langridge (2013), ACP 13:8321-8341
  • Kirchstetter et al. (2004), JGR 109:D21208