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:

_inventory_sniff classmethod 

_inventory_sniff(file)

Sample count: a results file with only the four header lines has none.

_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. A results file with the header lines but no sample rows (RTCalc writes one for a run that produced nothing) is skipped with a debug line — it is not a read error.
  3. Duplicate and NaT indices are removed, then the index is rounded to 1h.

  4. 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

  5. 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.

  6. Every column that converts cleanly is coerced to numeric; genuinely textual columns (sample ID, firmware version, laser-correction string) survive.
  7. 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.
  8. 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