SizeDistr 模組

粒徑分布數據處理模組。

結構

SizeDistr/
├── __init__.py      # SizeDistr (Writer 入口)
├── _size_dist.py    # SizeDist 核心類
├── prop.py          # 統計計算函數
└── merge/           # SMPS-APS 合併演算法 (v0-v4)

快速開始

from AeroViz.dataProcess.SizeDistr import SizeDist

psd = SizeDist(df_pnsd, state='dlogdp', weighting='n')
surface = psd.to_surface()
volume = psd.to_volume()
props = psd.properties()

SizeDist 類

屬性

屬性	類型	說明
`data`	DataFrame	原始數據
`dp`	ndarray	粒徑陣列 (nm)
`dlogdp`	ndarray	對數間距
`index`	DatetimeIndex	時間索引
`state`	str	'dN', 'ddp', 'dlogdp'
`weighting`	str	'n', 's', 'v', 'ext_in', 'ext_ex'

方法

方法	說明	相關理論
`to_surface()`	轉換為表面積分布	→ 對數常態分布
`to_volume()`	轉換為體積分布	→ 對數常態分布
`to_extinction()`	Mie 消光計算	→ Mie 理論
`to_dry()`	乾燥 PSD (吸濕校正)	→ κ-Köhler
`properties()`	統計屬性 (GMD, GSD)	→ 對數常態分布
`mode_statistics()`	模態統計	→ 對數常態分布
`lung_deposition()`	肺沉積計算	→ ICRP 66

模態定義

模態	粒徑範圍
Nucleation	10-25 nm
Aitken	25-100 nm
Accumulation	100-1000 nm
Coarse	1000-2500 nm

SizeDistr 入口類

from pathlib import Path
from AeroViz.dataProcess import DataProcess

dp = DataProcess('SizeDistr', Path('./output'))

方法

方法	說明
`basic(df)`	基本處理 (number/surface/volume)
`merge_SMPS_APS(df_smps, df_aps)`	SMPS-APS 合併 (v1)
`merge_SMPS_APS_v4(df_smps, df_aps, df_pm25)`	SMPS-APS 合併 (v4, 推薦)
`distributions(df_pnsd)`	分布計算
`dry_psd(df_pnsd, df_gRH)`	乾燥 PSD
`extinction_distribution(df_pnsd, df_RI)`	消光分布

SMPS-APS 合併演算法

版本	特點
v0	原始版本
v0.1	加入索引對齊
v1	加入 shift_mode
v2	簡化輸出
v3	multiprocessing + dN/dS/dV
v4	PM2.5 fitness 校正 (推薦)

輸入格式

# DataFrame 欄位為粒徑值 (nm)
df_pnsd.columns = [11.8, 13.6, 15.7, ..., 523.3]
df_pnsd.index = DatetimeIndex

# 成長因子
df_gRH = DataFrame({'gRH': [1.2, 1.3, ...]}, index=time_index)

API 參考

AeroViz.dataProcess.SizeDistr.SizeDist

SizeDist(data: DataFrame, state: Literal['dN', 'ddp', 'dlogdp'] = 'dlogdp', weighting: Literal['n', 's', 'v', 'ext_in', 'ext_ex'] = 'n')

A class representing particle size distribution data.

This class encapsulates particle size distribution data and provides convenient properties for accessing particle diameters, logarithmic bin widths, and distribution state information.

Attributes:

Name	Type	Description
`_data`	`DataFrame`	The processed PSD data stored as a pandas DataFrame.
`_dp`	`ndarray`	The array of particle diameters from the PSD data.
`_dlogdp`	`ndarray`	The array of logarithmic particle diameter bin widths.
`_index`	`DatetimeIndex`	The index of the DataFrame representing time.
`_state`	`str`	The state of particle size distribution data ('dN', 'ddp', 'dlogdp').
`_weighting`	`str`	The weighting type for distribution calculations.

Methods:

Name	Description
`data`	Returns the size distribution DataFrame.
`dp`	Returns the particle diameter array.
`dlogdp`	Returns the logarithmic bin width array.
`index`	Returns the time index.
`state`	Returns the distribution state.
`weighting`	Returns the weighting type.

Examples:

>>> from pandas import read_csv
>>> df = read_csv('PNSD_dNdlogdp.csv', parse_dates=['Time'], index_col='Time')
>>> psd = SizeDist(df, state='dlogdp', weighting='n')
>>> print(psd.dp)

Initialize a SizeDist object.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	The particle size distribution data with particle diameters as columns. Column names must be numeric diameter values in nm.	required
`state`	`(dN, ddp, dlogdp)`	The state of the distribution data: - 'dN': Raw number concentration - 'ddp': dN/ddp normalized - 'dlogdp': dN/dlogdp normalized	`'dN'`
`weighting`	`(n, s, v, ext_in, ext_ex)`	The weighting type for property calculations: - 'n': Number weighting - 's': Surface weighting - 'v': Volume weighting - 'ext_in': Internal extinction weighting - 'ext_ex': External extinction weighting	`'n'`

Raises:

Type	Description
`ValueError`	If data is None or empty, or column names are not numeric.
`TypeError`	If data is not a DataFrame.

Functions

to_surface

to_surface() -> DataFrame

Convert to surface area distribution.

Formula: dS/dlogDp = π * dp² * dN/dlogDp

Returns:

Type	Description
`DataFrame`	Surface area distribution (nm² / cm³).

Examples:

>>> psd = SizeDist(df)
>>> surface = psd.to_surface()

to_volume

to_volume() -> DataFrame

Convert to volume distribution.

Formula: dV/dlogDp = (π/6) * dp³ * dN/dlogDp

Returns:

Type	Description
`DataFrame`	Volume distribution (nm³ / cm³).

Examples:

>>> psd = SizeDist(df)
>>> volume = psd.to_volume()

to_extinction

to_extinction(RI: DataFrame, method: str = 'internal', result_type: str = 'extinction') -> DataFrame

Calculate extinction distribution using Mie theory.

Parameters:

Name	Type	Description	Default
`RI`	`DataFrame`	Refractive index data with n and k columns.	required
`method`	`(internal, external, core_shell, sensitivity)`	Mixing method for Mie calculation.	`'internal'`
`result_type`	`(extinction, scattering, absorption)`	Type of optical result.	`'extinction'`

Returns:

Type	Description
`DataFrame`	Extinction distribution (Mm⁻¹).

Examples:

>>> psd = SizeDist(df)
>>> ext = psd.to_extinction(df_RI, method='internal')

to_dry

to_dry(df_gRH: DataFrame, uniform: bool = True) -> DataFrame

Convert ambient (wet) PSD to dry PSD.

Shrinks particles according to hygroscopic growth factor and redistributes concentrations to appropriate smaller diameter bins.

Parameters:

Name	Type	Description	Default
`df_gRH`	`DataFrame`	DataFrame with 'gRH' column (growth factor = Dp_wet / Dp_dry).	required
`uniform`	`bool`	If True, apply uniform gRH across all sizes. If False, apply size-dependent gRH based on lognormal distribution.	`True`

Returns:

Type	Description
`DataFrame`	Dry particle size distribution.

Examples:

>>> psd = SizeDist(df_pnsd)
>>> dry_psd = psd.to_dry(df_chem[['gRH']])

properties

properties() -> DataFrame

Calculate statistical properties of the distribution.

Returns:

Type	Description
`DataFrame`	Properties including GMD, GSD, mode, and mode contributions.

Examples:

>>> psd = SizeDist(df)
>>> props = psd.properties()

mode_statistics

mode_statistics(unit: str = 'nm') -> dict

Calculate statistics for different size modes.

Computes number, surface, and volume distributions along with GMD, GSD, total, and mode for each size range.

Parameters:

Name	Type	Description	Default
`unit`	`(nm, um)`	Unit of particle diameter in the data.	`'nm'`

Returns:

Type	Description
`dict`	'number': Number distribution (dN) 'number_norm': Normalized number distribution (dN/dlogDp) 'surface': Surface area distribution 'surface_norm': Normalized surface distribution 'volume': Volume distribution 'volume_norm': Normalized volume distribution 'statistics': DataFrame with GMD, GSD, total, mode per size mode

Examples:

>>> psd = SizeDist(df)
>>> stats = psd.mode_statistics()
>>> stats['statistics']  # GMD, GSD for each mode

lung_deposition

lung_deposition(activity: str = 'light') -> dict

Calculate lung deposition using ICRP 66 model.

Based on the ICRP (International Commission on Radiological Protection) Human Respiratory Tract Model for particle deposition.

Parameters:

Name	Type	Description	Default
`activity`	`(sleep, sitting, light, heavy)`	Activity level affecting breathing pattern: - 'sleep': Sleeping (nasal, 7.5 L/min) - 'sitting': Sitting awake (nasal, 9 L/min) - 'light': Light exercise (nasal+oral, 25 L/min) - 'heavy': Heavy exercise (oral, 50 L/min)	`'sleep'`

Returns:

Type	Description
`dict`	'DF': Deposition fraction DataFrame (HA, TB, AL, Total) 'deposited': Deposited number distribution 'dose': Regional deposited dose (particles/cm³) 'total_dose': Total deposited particles

Notes

Deposition regions: - HA (Head Airways): 頭部氣道 (鼻、咽、喉) - TB (Tracheobronchial): 氣管支氣管區 - AL (Alveolar): 肺泡區

References

ICRP Publication 66 (1994)
Hinds, W.C. (1999) Aerosol Technology

Examples:

>>> psd = SizeDist(df)
>>> lung = psd.lung_deposition(activity='light')
>>> lung['DF']        # Deposition fractions
>>> lung['dose']      # Regional dose

SizeDistr 模組

結構

快速開始

SizeDist 類

屬性

方法

模態定義

SizeDistr 入口類

方法

SMPS-APS 合併演算法

輸入格式

相關資源

API 參考

AeroViz.dataProcess.SizeDistr.SizeDist

Functions

to_surface

to_volume

to_extinction

to_dry

properties

mode_statistics

lung_deposition