Instruments

This module implements UATAQ instruments as classes.

Each instrument class is a subclass of the Instrument abstract base class and implements methods for reading and parsing data files.

The Instrument class provides a common interface for all instrument classes and defines abstract methods that must be implemented by each subclass.

class uataq.instruments.Instrument(SID, name, loggers, config)

Bases: object

Abstract base class for instrument objects.

model

Model of the instrument.

Type:

str

SID

Site ID where the instrument is installed.

Type:

str

name

Name of the instrument.

Type:

str

groups

Research groups that operate the instrument.

Type:

list[str]

loggers

Loggers used by the research groups to record data.

Type:

set[str]

config

Configuration settings for the instrument.

Type:

dict

get_files(group: str, lvl: str) → list[str]

Get list of file paths for a given level.

read_data(group: str, lvl: str, time_range: TimeRange, num_processes: int, file_pattern: str) → pd.DataFrame

Read and parse group data files for the given level and time range using multiple processes.

model: str

__init__(SID, name, loggers, config)

Initialize the Instrument object.

Parameters:

• SID (str) – Site ID where the instrument is installed.

• name (str) – Name of the instrument.

• loggers (dict) – Dictionary of loggers used by different research groups.

• config (dict) – Configuration settings for the instrument.

get_highest_lvl(group)

Get the highest data level for the instrument.

Parameters:

group (str) – The research group whose data to retrieve.

Returns:

The highest data level.

Return type:

str

get_files(group, lvl)

Get list of file paths for a given level.

Parameters:

• group (str) – The research group whose data to retrieve.

• lvl (str) – The level of the data to retrieve.

Returns:

A list of file paths.

Return type:

list[str]

get_datafiles(group, lvl, time_range, pattern=None)

Get data files for the given level and time range from the groupspace.

Parameters:

• group (str) – The research group whose data to retrieve.

• lvl (str) – The level of the data to retrieve.

• time_range (TimeRange | TimeRangeTypes) – The time range of the data to retrieve.

• pattern (str) – A string pattern to filter the file paths.

Returns:

A list of data files.

Return type:

list[DataFile]

standardize_data(group, data)

Manipulate the data to a standard format between research groups, renaming columns, converting units, mapping values, etc. as needed.

Parameters:

• group (str) – The research group whose data to standardize.

• data (pandas.DataFrame) – The data to standardize.

Returns:

The standardized data.

Return type:

pandas.DataFrame

read_data(group, lvl=None, time_range=None, num_processes=1, file_pattern=None)

Read and parse data files for the given level and time range, using multiple processes if specified.

Parameters:

• group (str) – The research group whose data to read.

• lvl (str) – The level of the data to read.

• time_range (TimeRange | TimeRangeTypes) – The time range to read data. Default is None which reads all available data.

• num_processes (int | 'max') – The number of processes to use for parallelization.

• file_pattern (str) – A string pattern to filter the file paths.

Returns:

A concatenated DataFrame containing the parsed data from files.

Return type:

pandas.DataFrame

uataq.instruments.configure_instrument(SID, name, config, loggers=None)

Configure an instrument object based on the given configuration settings.

Parameters:

• SID (str) – Site ID where the instrument is installed.

• name (str) – Name of the instrument.

• config (dict) – Configuration settings for the instrument.

• loggers (dict, optional) – Dictionary of loggers used by different research groups.

Returns:

An instrument object configured with the given settings.

Return type:

Instrument

Raises:

• ValueError – If the instrument model is not found in the catalog.

• ValueError – If no loggers are found for the instrument at the site.

class uataq.instruments.InstrumentEnsemble(SID, configs, loggers=None)

Bases: object

Container for an ensemble of instruments at a site.

SID

Site ID of the ensemble.

Type:

str

configs

Dictionary of configuration settings for each instrument.

Type:

dict[str, dict]

names

List of instrument names in the ensemble.

Type:

list[str]

loggers

Set of loggers used by the research groups.

Type:

set[str]

groups

Set of research groups that operate the instruments.

Type:

set[str]

pollutants

Set of pollutants measured by the instruments.

Type:

set[str]

__init__(SID, configs, loggers=None)

Initialize the InstrumentEnsemble object.

Parameters:

• SID (str) – Site ID of the ensemble.

• configs (dict[instrument, config]) – Dictionary of configuration settings for each instrument.

• loggers (dict[group, logger], optional) – Dictionary of loggers used by different research groups.

class uataq.instruments.SensorMixin

Bases: object

Mixin for instrument objects that measure a pollutant.

Attributes:

pollutants (tuple): Tuple of pollutants measured by the instrument.

pollutants: tuple[str, ...]

class uataq.instruments.BB_205(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = '2b_205'

pollutants: tuple[str, ...] = ('O3',)

class uataq.instruments.BB_405(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = '2b_405'

pollutants: tuple[str, ...] = ('NO', 'NO2', 'NOx')

class uataq.instruments.CR1000(SID, name, loggers, config)

Bases: Instrument

model: str = 'cr1000'

class uataq.instruments.GPS(SID, name, loggers, config)

Bases: Instrument

model: str = 'gps'

read_data(group, lvl=None, time_range=None, num_processes=1, file_pattern=None)

Read and parse data files for the given level and time range, using multiple processes if specified.

Parameters:

• group (str) – The research group whose data to read.

• lvl (str) – The level of the data to read.

• time_range (TimeRange | TimeRangeTypes) – The time range to read data. Default is None which reads all available data.

• num_processes (int | 'max') – The number of processes to use for parallelization.

• file_pattern (str) – A string pattern to filter the file paths.

Returns:

A concatenated DataFrame containing the parsed data from files.

Return type:

pandas.DataFrame

class uataq.instruments.LGR_NO2(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'lgr_no2'

pollutants: tuple[str, ...] = ('NO2',)

class uataq.instruments.LGR_UGGA(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'lgr_ugga'

pollutants: tuple[str, ...] = ('CO2', 'CH4')

class uataq.instruments.Licor_6262(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'licor_6262'

pollutants: tuple[str, ...] = ('CO2',)

class uataq.instruments.Licor_7000(SID, name, loggers, config)

Bases: Licor_6262

model: str = 'licor_7000'

class uataq.instruments.Magee_AE33(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'magee_ae33'

pollutants: tuple[str, ...] = ('BC',)

class uataq.instruments.MetOne_ES405(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'metone_es405'

pollutants: tuple[str, ...] = ('PM1', 'PM2.5', 'PM4', 'PM10')

class uataq.instruments.MetOne_ES642(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'metone_es642'

pollutants: tuple[str, ...] = ('PM2.5',)

class uataq.instruments.Teledyne_T200(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'teledyne_t200'

pollutants: tuple[str, ...] = ('NO', 'NO2', 'NOx')

class uataq.instruments.Teledyne_T300(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'teledyne_t300'

pollutants: tuple[str, ...] = ('CO',)

class uataq.instruments.Teledyne_T400(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'teledyne_t400'

pollutants: tuple[str, ...] = ('O3',)

class uataq.instruments.Teledyne_T500u(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'teledyne_t500u'

pollutants: tuple[str, ...] = ('NO2',)

class uataq.instruments.Teom_1400ab(SID, name, loggers, config)

Bases: Instrument, SensorMixin

model: str = 'teom_1400ab'

pollutants: tuple[str, ...] = ('PM2.5',)

uataq.instruments.catalog: dict[str, type[Instrument]] = {'2b_205': <class 'uataq.instruments.BB_205'>, '2b_405': <class 'uataq.instruments.BB_405'>, 'cr1000': <class 'uataq.instruments.CR1000'>, 'gps': <class 'uataq.instruments.GPS'>, 'lgr_no2': <class 'uataq.instruments.LGR_NO2'>, 'lgr_ugga': <class 'uataq.instruments.LGR_UGGA'>, 'licor_6262': <class 'uataq.instruments.Licor_6262'>, 'licor_7000': <class 'uataq.instruments.Licor_7000'>, 'magee_ae33': <class 'uataq.instruments.Magee_AE33'>, 'metone_es405': <class 'uataq.instruments.MetOne_ES405'>, 'metone_es642': <class 'uataq.instruments.MetOne_ES642'>, 'teledyne_t200': <class 'uataq.instruments.Teledyne_T200'>, 'teledyne_t300': <class 'uataq.instruments.Teledyne_T300'>, 'teledyne_t400': <class 'uataq.instruments.Teledyne_T400'>, 'teledyne_t500u': <class 'uataq.instruments.Teledyne_T500u'>, 'teom_1400ab': <class 'uataq.instruments.Teom_1400ab'>}

Instrument catalog