Locations

In PollyXT-Pipelines, a Location represents a station where PollyXT is, or was, hosted. It contains the station’s coordinates and the related IDs for SCC. Specifically, for each station we know:

Caution

All variables are required.

  • Name: Station Name

  • Profile name (profile_name): The name used by WRF for this location

  • SCC Station ID (scc_code): The station ID registered with SCC, it’s used in measurement IDs (e.g. aky).

  • Latitude/Longitude (lat, code:lon): The station coordinates

  • Altitude (altitude_asl): The station’s altitude

  • System ID (daytime_configuration, nighttime_configuration): The SCC Lidar configuration ID for daytime and nightime

  • Channel ID (Array, channel_id): Value for the channel_ID SCC variable.

  • Background (Array, background_low, background_high): Values for the Background_Low and Background_High SCC variables.

  • LR Input (Array, lr_input): Value for the LR_Input SCC variable.

  • Temperature (temperature): Value for the Temperature_at_Lidar_Station SCC variable

  • Pressure (pressure): Value for the Pressure_at_Lidar_Station SCC variable

  • Zero state for depol_cal_angle (depol_calibration_zero_state): Value that is used to signify a normal measurement in the depol_cal_angle PollyXT variable. This is used to distinguish between normal measurements and measurements that are used to calibrate the depolarization angle. If depol_cal_angle is not equal to zero_state_depol_cal_angle, the corresponding time period is assumed to be a calibration period.

  • Total/Cross channels: Four variables are available for setting the total/cross channel indices in the PollyXT file for 355nm, 532nm and 1064nm:

    1. For 355nm: total_channel_355_nm_idx and cross_channel_355_nm_idx.

    2. For 532nm: total_channel_532_nm_idx and cross_channel_532_nm_idx.

    3. For 1064nm: total_channel_1064_nm_idx and cross_channel_1064_nm_idx.

  • Calibration channels: For both wavelengths, the SCC channel IDs must be provided in the following order in calibration_355nm_total_channel_ids and calibration_355nm_cross_channel_ids (same for 532nm and/or 1064nm) for each wavelength:

    1. plus_45_transmitted

    2. plus_45_reflected

    3. minus_45_transmitted

    4. minus_45_reflected

  • Sounding provider (sounding_provider): Which provider to use for radiosonde files.

  • Sunrise time (sunrise_time): Adjustments for the sunrise time. Can either be a fixed time (HH:MM format) or an offset from the astronomical (calculated) sunrise in either +MM (e.g., +17 for +17 minutes) or -MM.

  • Sunset time (sunset_time): Adjustments for the sunset time. Same format as sunrise time.

For the arrays, you can input values separated by commas (see example below). Currently, the application has a built-in registry containing information about two stations, Antikythera and Finokalia.

For depolarization channels, any channel (e.g., 355nm) that is missing one of the required fields (e.g., total_channel_355_nm_idx) will be ignored. That means, any channel without a complete description will be skipped during the creation of depolarization calibration files. If you find one channel is missing from your generated files, make sure all required variables are present here.

For the variable channel_id and the depolarization total/cross channels, you can either specify the SCC integer channel ID or the channel name. However, only one way of specifying channels can be used (all integers or all strings). If strings are used, the resulting netCDF files will use the channel_string_IDs variable instead of channel_ID.

Printing known locations

To print all locations the application knows about, you can use the locations-show command. Adding the --details option will print all variables for each location, instead of just the names.

pollyxt_pipelines locations-show
pollyxt_pipelines locations-show --detail

Adding new locations

A config file is used to add new locations to the application. It is stored in different locations, depending on the operating system you are on:

  • Linux: /etc/pollyxt_pipelines/locations.ini (system-wide) and ~/.config/pollyxt_pipelines/locations.ini (user)

  • Windows: %APPDATA%/PollyXT_Pipelines/pollyxt_pipelines.ini

To print the path for your system, use the locations-path command:

pollyxt_pipelines locations-path
pollyxt_pipelines locations-path --user # Print only the user's path

The file is ini-formatted, where each section is a station name. For example:

[Antikythera]
scc_code = aky
lat = 23.3100
lon = 35.8600
altitude_asl = 0.1
daytime_configuration = 437
nighttime_configuration = 438
channel_id = 493, 500, 497, 499, 494, 496, 498, 495, 501, 941, 940, 502
background_low = 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
background_high = 249, 249, 249, 249, 249, 249, 249, 249, 249, 249, 249, 249
lr_input = 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
temperature = 20
pressure = 1008
depol_calibration_zero_state = 0
total_channel_355_nm_idx = 0
cross_channel_355_nm_idx = 1
total_channel_532_nm_idx = 4
cross_channel_532_nm_idx = 5
calibration_355nm_total_channel_ids = 1266, 1268
calibration_355nm_cross_channel_ids = 1236, 1267
calibration_532nm_total_channel_ids = 1270, 1272
calibration_532nm_cross_channel_ids = 1269, 1271
profile_name = ANTIKYTHERA
sounding_provider = noa_wrf

You can add more than one location in the same file. Verify that it worked by running pollyxt_pipelines locations-show --detail when you are done.

API

Locations are represented using NamedTuple objects, you can add more in pollyxt_pipelines.locations. All known locations should be added in the LOCATIONS tuple. Some helper functions are also defined to search stations by their name/IDs.

Contains information about locations

Each location (i.e. SCC station) is defined in an .ini file. For some stations, the .ini files are included with the software but custom locations can be defined.

pollyxt_pipelines.locations.LOCATIONS = {'Antikythera': ('Antikythera', 'ANTIKYTHERA', 'noa_wrf', 'aky', 23.31, 35.86, 0.1, 437, 438, 461, 462, None, 0, ['no000', 'no007', 'no004', 'no006', 'no001', 'no003', 'no005', 'no002', 'no008', 'no009', 'no010', 'no011'], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [249, 249, 249, 249, 249, 249, 249, 249, 249, 249, 249, 249], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], 20, 1008, 0, 1, 4, 5, None, None, ['no0024', 'no0026'], ['no0014', 'no0025'], ['no0028', 'no0030'], ['no0027', 'no0029'], None, None, '04:00', '16:00'), 'CVO': ('CVO', 'mindelo', 'cloudnet', 'cvo', 16.87, -24.99, 10.0, 712, 713, 714, 715, 716, 0, [1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2005, 2006, 2007, 2008, 2009, 2004, 2003], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [240, 240, 240, 240, 240, 240, 240, 240, 240, 240, 240, 240, 240, 240, 240], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], 15, 1000, 0, 1, 4, 5, 7, 14, [2010, 2011], [2012, 2013], [2014, 2015], [2016, 2017], [2018, 2019], [2020, 2021], '0', '0'), 'Finokalia': ('Finokalia', 'FINOKALIA', 'noa_wrf', 'fik', 25.6698, 35.3377, 0.1, 186, 302, 461, 462, None, 0, [493, 500, 497, 499, 494, 496, 498, 495, 501, 941, 940, 502], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [249, 249, 249, 249, 249, 249, 249, 249, 249, 249, 249, 249], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], 20, 1008, 0, 1, 4, 5, None, None, [1266, 1268], [1236, 1267], [1270, 1272], [1269, 1271], None, None, '+69', '-15')}

List of all known locations

class pollyxt_pipelines.locations.Location(name: str, profile_name: str, sounding_provider: str, scc_code: str, lat: float, lon: float, altitude_asl: float, daytime_configuration: int, nighttime_configuration: int, calibration_configuration_355nm: int | None, calibration_configuration_532nm: int | None, calibration_configuration_1064nm: int | None, depol_calibration_zero_state: int, channel_id: List[int] | List[str], background_low: List[int], background_high: List[int], lr_input: List[int], temperature: int, pressure: int, total_channel_355_nm_idx: int | None, cross_channel_355_nm_idx: int | None, total_channel_532_nm_idx: int | None, cross_channel_532_nm_idx: int | None, total_channel_1064_nm_idx: int | None, cross_channel_1064_nm_idx: int | None, calibration_355nm_total_channel_ids: List[int] | List[str], calibration_355nm_cross_channel_ids: List[int] | List[str], calibration_532nm_total_channel_ids: List[int] | List[str], calibration_532nm_cross_channel_ids: List[int] | List[str], calibration_1064nm_total_channel_ids: List[int] | List[str], calibration_1064nm_cross_channel_ids: List[int] | List[str], sunrise_time: str, sunset_time: str)[source]

Bases: NamedTuple

Represents a physical location of PollyXT installation.

altitude_asl: float

Altitude of station

background_high: List[int]

Value for the Background_High variable

background_low: List[int]

Value for the Background_Low variable

calibration_1064nm_cross_channel_ids: Union[List[int], List[str]]

Calibration channel SCC IDs for 1064nm. Comma separated list. First value must be the +45° channel, second value must be the -45° channel.

calibration_1064nm_total_channel_ids: Union[List[int], List[str]]

Calibration channel SCC IDs for 1064nm. Comma separated list. First value must be the +45° channel, second value must be the -45° channel.

calibration_355nm_cross_channel_ids: Union[List[int], List[str]]

Calibration channel SCC IDs for 355nm. Comma separated list. First value must be the +45° channel, second value must be the -45° channel.

calibration_355nm_total_channel_ids: Union[List[int], List[str]]

Calibration channel SCC IDs for 355nm. Comma separated list. First value must be the +45° channel, second value must be the -45° channel.

calibration_532nm_cross_channel_ids: Union[List[int], List[str]]

Calibration channel SCC IDs for 532nm. Comma separated list. First value must be the +45° channel, second value must be the -45° channel.

calibration_532nm_total_channel_ids: Union[List[int], List[str]]

Calibration channel SCC IDs for 532nm. Comma separated list. First value must be the +45° channel, second value must be the -45° channel.

calibration_configuration_1064nm: Optional[int]

SCC Lidar Configuration ID - Calibration (532 nm)

calibration_configuration_355nm: Optional[int]

SCC Lidar Configuration ID - Calibration (355 nm)

calibration_configuration_532nm: Optional[int]

SCC Lidar Configuration ID - Calibration (532 nm)

channel_id: Union[List[int], List[str]]

Mapping of PollyXT Channels to SCC Channels Comma-separated list. The order of the list is the order of the channels in the PollyXT netCDF file.

cross_channel_1064_nm_idx: Optional[int]

Index in Polly netCDF file for the cross channel (1064nm)

cross_channel_355_nm_idx: Optional[int]

Index in Polly netCDF file for the cross channel (355nm)

cross_channel_532_nm_idx: Optional[int]

Index in Polly netCDF file for the cross channel (532nm)

daytime_configuration: int

SCC Lidar Configuration ID - Daytime

depol_calibration_zero_state: int

Value of depol_cal_angle when there is no calibration taking place

has_depol_channels()[source]

Returns a dictionary of wavelengths to booleans, true if that corresponding wavelength has depolarization channels.

Return type:

Dict[Wavelength, bool]

lat: float

Latitude of station

lon: float

Longitude of station

lr_input: List[int]

Value for the lr_input variable

name: str

Location friendly name

nighttime_configuration: int

SCC Lidar Configuration ID - Nightime

pressure: int

Pressure at the lidar station (Pressure_at_Lidar_Station variable)

print()[source]

Prints this location as a Table in the terminal

profile_name: str

How are the WRF profile names prefixed

scc_code: str

SCC Station code

sounding_provider: str

Which radiosonde provider to use

sunrise_time: str

MM) or offset (minutes from calculated sunrise in +X or -X format, where X an integer)

Type:

Sunrise time (HH

sunset_time: str

MM) or offset (minutes from calculated sunrise in +X or -X format, where X an integer)

Type:

Sunrise time (HH

temperature: int

Temperature at the lidar station (Temperature_at_Lidar_Station variable)

total_channel_1064_nm_idx: Optional[int]

Index in Polly netCDF file for the total channel (1064nm)

total_channel_355_nm_idx: Optional[int]

Index in Polly netCDF file for the total channel (355nm)

total_channel_532_nm_idx: Optional[int]

Index in Polly netCDF file for the total channel (532nm)

pollyxt_pipelines.locations.get_location_by_scc_code(code)[source]

Returns a location by its SCC code or None if it doesn’t exist.

Return type:

Optional[Location]

pollyxt_pipelines.locations.location_from_section(name, section)[source]

Create a Location from a ConfigParser Section (SectionProxy)

Return type:

Location

pollyxt_pipelines.locations.read_locations()[source]

Reads all built-in and custom locations into a dictionary: name -> Location

Return type:

Dict[str, Location]

pollyxt_pipelines.locations.unknown_location_error(name)[source]

Prints an error message that the given location is not found, along with a list of known locations