`AeroViz.chemistry`

Mass reconstruction, component volumes and refractive index, hygroscopic growth and kappa, gas–particle partitioning, OC/EC splitting and ISORROPIA II. Worked examples: Chemical Analysis; call-by-call summary: Post-Processing Functions. Theory: Mass Reconstruction, κ-Köhler.

Input

# reconstruct_mass — species columns in µg/m³; extra ions (K+, Mg2+, Ca2+)
# may be present and are carried through, but the reconstruction itself uses:
df_chem.columns ⊇ ['SO42-', 'NO3-', 'NH4+', 'OC', 'EC', 'Na+', 'Cl-', 'Al', 'Fe', 'Ti', 'PM25']

# partition_ratios — the chemistry frame plus gases and temperature:
gas_columns = ['SO2', 'NO2', 'HNO3', 'NH3']      # ppb or µg/m³

Functions

AeroViz.chemistry

Top-level functions for chemistry analysis.

These are convenience wrappers — see AeroViz.dataProcess.Chemistry.* for full algorithm details. Each function here is a thin re-export of an underlying implementation, with the DataProcess / Writer boilerplate (path_out, excel, csv, on-disk side effects) stripped away so results are returned directly.

Example

from AeroViz.chemistry import reconstruct_mass result = reconstruct_mass(df_chem, df_ref=df_pm25) result['mass']

Attributes

all `module-attribute`

__all__ = ['reconstruct_mass', 'split_oc_ec', 'partition_ratios', 'isoropia', 'volume_ri', 'kappa', 'growth_factor']

Functions:

reconstruct_mass

reconstruct_mass(*df_chem: DataFrame, df_ref: Optional[DataFrame] = None, df_water: Optional[DataFrame] = None, df_density: Optional[DataFrame] = None, nam_lst: Optional[list] = None, split_om: bool = False, oa_oc_ratio: float = 1.8) -> dict

Reconstruct aerosol mass and volume from chemical composition.

Converts ionic species (NH4+, SO42-, NO3-, etc.) to reconstructed species (AS, AN, OM, Soil, SS, EC) considering the ammonium neutralization status. Also computes volumes, density, refractive index, and (optionally) the POA/SOA split via the EC-tracer method.

Parameters:

Name	Type	Description	Default
`*df_chem`	`DataFrame`	Chemical composition data. Multiple DataFrames are concatenated along axis=1 and renamed to `nam_lst`.	`()`
`df_ref`	`DataFrame or Series`	Reference mass (e.g., PM2.5) for quality control.	`None`
`df_water`	`DataFrame`	Aerosol liquid water content (ALWC).	`None`
`df_density`	`DataFrame`	Measured density data (requires `Cl-` column).	`None`
`nam_lst`	`list`	Column names for `df_chem` after concatenation. Default: `['NH4+', 'SO42-', 'NO3-', 'Fe', 'Na+', 'OC', 'EC']`.	`None`
`split_om`	`bool`	If True, split OM into POA and SOA using the EC-tracer method.	`False`
`oa_oc_ratio`	`float`	OA/OC conversion ratio for POA/SOA calculation.	`1.8`

Returns:

Type	Description
`dict`	Keys: `mass`, `volume`, `vol_cal`, `eq`, `NH4_status`, `density_mat`, `density_rec`, `RI_550`, `RI_450`. See :func:`AeroViz.dataProcess.Chemistry._mass_volume.reconstruction_basic` for details.

split_oc_ec

split_oc_ec(df_lcres: DataFrame, df_mass: Optional[DataFrame] = None, ocec_ratio: Optional[float] = None, ocec_ratio_month: int = 1, hr_lim: int = 200, least_square_range: tuple = (0.1, 2.5, 0.1), WISOC_OC_range: tuple = (0.2, 0.7, 0.01)) -> dict

Split OC into primary (POC) and secondary (SOC) using EC-tracer / MRS.

Computes OC/EC, POC, SOC, WSOC, WISOC for both Thermal and Optical analyses, plus ratio-based status flags (Normal / Warning).

Parameters:

Name	Type	Description	Default
`df_lcres`	`DataFrame`	OC/EC analyzer level results — must include columns `OC1`, `OC2`, `OC3`, `OC4`, `PC`, `Thermal_OC`, `Thermal_EC`, `Optical_OC`, `Optical_EC`, `Sample_Volume`.	required
`df_mass`	`DataFrame`	Reference PM mass; used to compute species/PM ratios.	`None`
`ocec_ratio`	`float`	Override the primary OC/EC ratio. If None, the MRS method searches a monthly grid.	`None`
`ocec_ratio_month`	`int`	Resampling window (in months) for the MRS ratio search.	`1`
`hr_lim`	`int`	Minimum number of valid hours per window for an MRS fit.	`200`
`least_square_range`	`tuple`	`(start, stop, step)` candidate OC/EC ratios.	`(0.1, 2.5, 0.1)`
`WISOC_OC_range`	`tuple`	`(start, stop, step)` candidate WISOC/OC ratios.	`(0.2, 0.7, 0.01)`

Returns:

Type	Description
`dict`	Keys `basic` (concatenated OC/EC data + status flags) and `ratio` (per-species PM / OC ratios).

partition_ratios

partition_ratios(df_data: DataFrame) -> DataFrame

Calculate gas-particle partitioning ratios (SOR, NOR, NTR, epsilon).

Parameters:

Name	Type	Description	Default
`df_data`	`DataFrame`	Particle and gas concentrations (μg/m³). Required: `temp` column (Celsius). Optional species (at least one pair): - `SO42-` + `SO2` → SOR - `NO3-` + `NO2` → NOR (and with `HNO3` → NOR_2) - `NH4+` + `NH3` → NTR - `Cl-` + `HCl` → chloride partitioning	required

Returns:

Type	Description
`DataFrame`	Partitioning ratios — columns include `SOR`, `NOR`, `NOR_2`, `NTR`, `epls_SO42-`, `epls_NO3-`, `epls_NH4+`, `epls_Cl-`.

Notes

SOR > 0.1 typically indicates secondary sulfate formation.
Values near 1.0: particle phase dominant; near 0.0: gas phase dominant.

isoropia

isoropia(*df_chem: DataFrame, path_out: Optional[Path] = None, nam_lst: Optional[list] = None) -> dict

Run ISORROPIA II to compute aerosol pH, ALWC, and gas-particle partitioning.

Calls the ISORROPIA II Fortran library via a native f2py extension, so this works on macOS, Linux, and Windows. Replaces the legacy Windows-only isrpia2.exe path; outputs match the old binary to machine precision.

Parameters:

Name	Type	Description	Default
`*df_chem`	`DataFrame`	Chemical species + meteorology DataFrames; concatenated and renamed to `nam_lst`.	`()`
`path_out`	`Path`	Retained for backward compatibility with code written for the legacy subprocess path; no longer used (the extension has no temp-file I/O). Will be removed in a future release.	`None`
`nam_lst`	`list`	Column names for the concatenated input. Default: `['Na+', 'SO42-', 'NH4+', 'NO3-', 'Cl-', 'Ca2+', 'K+', 'Mg2+', 'NH3', 'HNO3', 'HCl', 'RH', 'temp']`.	`None`

Returns:

Type	Description
`dict`	`input` (preprocessed ISORROPIA input) and `output` (pH, ALWC, gas/aerosol-phase NH3/HNO3/HCl/NH4+/NO3-/Cl-).

volume_ri

volume_ri(df_volume: DataFrame, df_alwc: Optional[DataFrame] = None) -> DataFrame

Calculate volume-average refractive index (dry & ambient) and gRH.

Uses the volume-mixing rule: RI_mix = Σ(Vi · RIi) / V_total at 550 nm.

Parameters:

Name	Type	Description	Default
`df_volume`	`DataFrame`	Volume concentrations (μm³/m³). Required: `total_dry`; plus at least one of `AS_volume`, `AN_volume`, `OM_volume`, `Soil_volume`, `SS_volume`, `EC_volume`.	required
`df_alwc`	`DataFrame`	Aerosol liquid water content (`ALWC` column).	`None`

Returns:

Type	Description
`DataFrame`	Columns `n_dry`, `k_dry`, `n_amb`, `k_amb`, `gRH` (ambient values NaN if `df_alwc` not provided).

kappa

kappa(df_data: DataFrame, diameter: float = 0.5) -> DataFrame

Calculate the hygroscopicity parameter kappa.

Parameters:

Name	Type	Description	Default
`df_data`	`DataFrame`	Must contain `gRH`, `AT` (temperature in °C), `RH` (%).	required
`diameter`	`float`	Particle dry diameter in micrometers.	`0.5`

Returns:

Type	Description
`DataFrame`	Single column `kappa_chem`.

growth_factor

growth_factor(df_volume: DataFrame, df_alwc: DataFrame) -> DataFrame

Calculate the hygroscopic growth factor gRH = (V_wet / V_dry)^(1/3).

Parameters:

Name	Type	Description	Default
`df_volume`	`DataFrame`	Must contain `total_dry`.	required
`df_alwc`	`DataFrame`	Must contain `ALWC`.	required

Returns:

Type	Description
`DataFrame`	Single column `gRH`.

AeroViz.chemistry

Input

Functions

AeroViz.chemistry

Attributes

__all__ module-attribute

Functions:

reconstruct_mass

split_oc_ec

partition_ratios

isoropia

volume_ri

kappa

growth_factor

`AeroViz.chemistry`

all `module-attribute`