Skip to content

Organic Carbon/Elemental Carbon Analyzer (OC/EC)

The OC/EC analyzer measures carbonaceous aerosol components using thermal and optical methods.

AeroViz.rawDataReader.script.OCEC.Reader 

Reader(path: Path | str, reset: bool | str = False, qc: bool | str = True, **kwargs)

Bases: AbstractReader

OC/EC (Organic Carbon/Elemental Carbon) Analyzer Data Reader

A specialized reader for OC/EC analyzer data files, which measure carbonaceous aerosol composition using thermal and optical methods.

See docs/api/instruments/chemical/OCEC.md for usage and docs/guide/reader-reference.md for the file layout, status codes and QC rules.

Attributes

nam class-attribute instance-attribute 

nam = 'OCEC'

OUTPUT_COLUMNS class-attribute instance-attribute 

OUTPUT_COLUMNS = ['Thermal_OC', 'Thermal_EC', 'Optical_OC', 'Optical_EC', 'TC', 'OC1', 'OC2', 'OC3', 'OC4', 'PC']

MIN_VALUE class-attribute instance-attribute 

MIN_VALUE = -5

MAX_VALUE class-attribute instance-attribute 

MAX_VALUE = 100

MDL class-attribute instance-attribute 

MDL = {'Thermal_OC': 0.3, 'Optical_OC': 0.3, 'Thermal_EC': 0.015, 'Optical_EC': 0.015}

METADATA_ALIASES_RTCALC705 class-attribute instance-attribute 

METADATA_ALIASES_RTCALC705 = {'Thermal/Optical OC (ugC/LCm^3)': 'Thermal_OC', 'Thermal/Optical EC (ugC/LCm^3)': 'Thermal_EC', 'OC=TC-BC (ugC/LCm^3)': 'Optical_OC', 'BC (ugC/LCm^3)': 'Optical_EC', 'TC (ugC/LCm^3)': 'TC'}

METADATA_ALIASES_RTCALC802 class-attribute instance-attribute 

METADATA_ALIASES_RTCALC802 = {'OC ugC/m^3 (Thermal/Optical)': 'Thermal_OC', 'EC ugC/m^3 (Thermal/Optical)': 'Thermal_EC', 'OC by diff ugC (TC-OptEC)': 'Optical_OC', 'OptEC ugC/m^3': 'Optical_EC', 'TC ugC/m^3': 'TC'}

METADATA_ALIASES_SHARED class-attribute instance-attribute 

METADATA_ALIASES_SHARED = {'Sample Volume Local Condition Actual m^3': 'Sample_Volume', 'OCPk1-ug C': 'OC1_raw', 'OCPk2-ug C': 'OC2_raw', 'OCPk3-ug C': 'OC3_raw', 'OCPk4-ug C': 'OC4_raw', 'Pyrolized C ug': 'PC_raw', 'ECPk1-ug C': 'EC1_raw', 'ECPk2-ug C': 'EC2_raw', 'ECPk3-ug C': 'EC3_raw', 'ECPk4-ug C': 'EC4_raw', 'ECPk5-ug C': 'EC5_raw'}

DATE_FORMATS class-attribute instance-attribute 

DATE_FORMATS = ['%m/%d/%Y %I:%M:%S %p', '%m/%d/%Y %H:%M:%S']

Methods:

_raw_reader 

_raw_reader(file)

Read and parse raw OC/EC data files.

Parameters:

Name Type Description Default
file Path or str

Path to the OC/EC data file.

 required

Returns:

Type Description
DataFrame

Processed OC/EC data with datetime index and carbon fraction columns.

_QC 

_QC(_df)

Perform quality control on OC/EC data.

QC Rules Applied
  1. Invalid Carbon : Carbon value outside valid range (-5-100 ugC/m3)
  2. Below MDL : Value below method detection limit
  3. Spike : Sudden value change (vectorized spike detection)
  4. Missing OC : Thermal_OC or Optical_OC is missing

Raw format

  • File pattern: *LCRes.csv
  • Native frequency: 1h
  • Encoding: read as UTF-8 with undecodable bytes ignored
  • Header layout: 3 rows of metadata, then the column header (read_csv(skiprows=3, on_bad_lines='skip'))
  • Data structure:
    • Time column: Start Date/Time
    • Carbon fraction measurements (thermal/optical OC, EC, TC; per-peak fractions on newer firmware)
    • Sample volume information

Parse recipe

  1. Start Date/Time is stripped and parsed with the first format that matches any row, tried in order: %m/%d/%Y %I:%M:%S %p (12-hour AM/PM, the RTCalc705 default) then %m/%d/%Y %H:%M:%S (24-hour). The format used is logged; if neither matches, a warning names the file and the sample value and the file yields an empty frame.
  2. Duplicate and NaT indices are removed, then the index is rounded to 1h.

  3. Three alias maps are applied unconditionally (only keys present in the file rename; the rest are inert):

    Firmware Raw column Canonical
    RTCalc705 Thermal/Optical OC (ugC/LCm^3) Thermal_OC
    RTCalc705 Thermal/Optical EC (ugC/LCm^3) Thermal_EC
    RTCalc705 OC=TC-BC (ugC/LCm^3) Optical_OC
    RTCalc705 BC (ugC/LCm^3) Optical_EC
    RTCalc705 TC (ugC/LCm^3) TC
    RTCalc802 OC ugC/m^3 (Thermal/Optical) Thermal_OC
    RTCalc802 EC ugC/m^3 (Thermal/Optical) Thermal_EC
    RTCalc802 OC by diff ugC (TC-OptEC) Optical_OC
    RTCalc802 OptEC ugC/m^3 Optical_EC
    RTCalc802 TC ugC/m^3 TC
    shared Sample Volume Local Condition Actual m^3 Sample_Volume
    shared OCPk1-ug C … OCPk4-ug C OC1_raw … OC4_raw
    shared Pyrolized C ug PC_raw
    shared ECPk1-ug C … ECPk5-ug C EC1_raw … EC5_raw

  4. Firmware is inferred post-rename from the presence of per-peak columns (OC{i}_raw) and logged, so a mixed-firmware batch shows up in the log.

  5. Every column that converts cleanly is coerced to numeric; genuinely textual columns (sample ID, firmware version, laser-correction string) survive.
  6. Derived at L1:
    • OC{i} = OC{i}_raw / Sample_Volume for i = 1–4. NaN on RTCalc705, which has no per-peak columns, or when Sample_Volume is missing (a warning names the file).
    • PC = Thermal_OC − OC1 − OC2 − OC3 − OC4 when all four exist, else NaN.
  7. The ~45-column Sunset export is kept whole — laser/temperature correction, oven pressures, calibration peak area. It used to be narrowed to 11 columns at L1, which put the instrument's own diagnostics out of reach.

Measurement Parameters

The OC/EC analyzer provides measurements of:

Parameter Unit Description
Thermal_OC μgC/m³ Thermal organic carbon
Thermal_EC μgC/m³ Thermal elemental carbon
Optical_OC μgC/m³ Optical organic carbon
Optical_EC μgC/m³ Optical elemental carbon
OC1-4 μgC/m³ Carbon fractions by temperature
PC μgC/m³ Pyrolyzed carbon
TC μgC/m³ Total carbon

Status & error codes

None. The Sunset export carries no status register; see status modes for the readers that do evaluate one.

QC rules

Rule Condition Severity
Invalid Carbon any of Thermal_OC, Thermal_EC, Optical_OC, Optical_EC, TC, OC1–OC4, PC is <= -5 (MIN_VALUE) or > 100 µgC/m³ (MAX_VALUE) error
Below MDL any of the four MDL columns is <= its detection limit advisory
Spike sudden change in Thermal_OC, Thermal_EC, Optical_OC or Optical_EC (spike_detection, max_change_rate=3.0) error
Missing OC Thermal_OC or Optical_OC is NaN error

Below MDL is advisory because a sub-MDL carbon fraction is a real measurement of clean air, not a broken row: invalidating it deleted whole clean-air periods along with the other fractions in the row. Promote it per run with flag_severity={'Below MDL': 'error'} (see severity).

Minimum Detection Limits

Class constants on the reader (Reader.MDL), not the config meta:

Parameter MDL (μgC/m³)
Thermal_OC 0.3
Optical_OC 0.3
Thermal_EC 0.015
Optical_EC 0.015

Output

L2 carries the carbon fractions plus the remaining source columns — the fractions are the product, but the metadata beside them is what explains a bad one.

Column Unit Description
Thermal_OC μgC/m³ Thermal organic carbon
Thermal_EC μgC/m³ Thermal elemental carbon
Optical_OC μgC/m³ Optical organic carbon
Optical_EC μgC/m³ Optical elemental carbon
TC μgC/m³ Total carbon
OC1, OC2, OC3, OC4 μgC/m³ Per-peak OC fractions, OC{i}_raw / Sample_Volume (NaN on RTCalc705)
PC μgC/m³ Pyrolyzed carbon, Thermal_OC − OC1 − OC2 − OC3 − OC4
remaining source columns as exported Sample_Volume, *_raw peaks, laser/temperature corrections, oven pressures, …

Files written per read are listed in RawDataReader Reference §1.

Notes

  • Provides critical information about combustion sources
  • Helps identify secondary organic aerosol formation
  • Combines thermal and optical analysis methods
  • Standardizes output across different instrument formats