uataq.sites.Site.get_obs

Site.get_obs(pollutants='all', format='wide', group=None, time_range=None, num_processes=1, **kwargs)

Get observations for each pollutant, combining instruments by pollutants.

Parameters:

• pollutants (Literal['all'] | str | list[str] | tuple[str, ...] | set[str]) – pollutants to read. If ‘all’, read all pollutants. Default is ‘all’.

• format (Literal['wide'] | Literal['long']) – Format of the data to return. Default is ‘wide’.

• group (str | Mapping[str, str] | None) – The research group to read data from. A name applies to every instrument; a mapping of instrument name to group name sets it per instrument. Default None selects each instrument’s group automatically (see resolve_group()).

• time_range (TimeRange | str | tuple[str | datetime | datetime64 | None, str | datetime | datetime64 | None] | list[str | datetime | datetime64 | None] | slice | None) – The time range to read data, in UTC (see Time range). Default is None which reads all available data.

• num_processes (int | Literal['max']) – Number of processes to use for reading data. Default is 1.

Returns:

One dataframe indexed by Time_UTC, with the final-level rows of every instrument that measures the requested pollutants, sorted by time. The wide format has a column for each concentration column of the pollutants asked for (CO2d_ppm_cal and CO2d_ppm_raw, O3_ppb and so on: those concentration_columns() picks with raw=True, so 'NO' gives NO_ppb and not NO2_ppb); the long format has a pollutant column (those names) and a value column. An instrument column after them names the instrument each row came from (the name get_network_obs uses), so obs.resample("h").mean(numeric_only=True) leaves it out. The wide columns come instrument by instrument, in the order the pollutants were asked for (a set is sorted; 'all' follows the site’s config), and the same on every call. Rows on one timestamp come in that order too.

Return type:

DataFrame

Raises:

• ValueError – If a pollutant is not measured at the site. The message says which pollutants the site does measure, and tells a pollutant uataq reads at other sites (Not measured at ...) from a name it does not know (Invalid pollutant(s)).

• TypeError – If you pass lvl or level: get_obs always reads the final level. Use uataq.read_data() to read another.

Warns:

• EmptyResultWarning – If the instruments have files for the range but no data in it, so the table has no rows. A range with no files raises ReaderError instead.

• DroppedPollutantWarning – If you name several pollutants and none of the instruments that measure one of them gave data (no files for the range, or not installed then), so the table leaves it out. It names the pollutants and the instruments. pollutants='all' does not warn, and when none of the pollutants has data the read raises ReaderError instead.