API Documentation

helpers

Functions for DMS data processing

Part of the polair package.

title: _helpers.py
author: Laura Köhler
institution: Alfred-Wegener-Institut, Bremerhaven, Germany
contact: laura.koehler@awi.de
date: 2026-04-17

polair._helpers.add2logfile(logfile, text)

Writes text in the logfile.

Parameters:

logfile – .txt file Logfile for the processing, location defined in the config file
text – str Text which should be added to the logfile

polair._helpers.add_attrs_var(ds, v, var_dict)

This function adds all attributes from the variable dictrionary except for the old name which is only necessary to read in the correct file.

It adds the original unit because no unit conversion is done so far.

Parameters:

ds – xarray.Dataset Input dataset
v – str Variable for which attributes are added
var_dict – dict Dictionary with all the information for each parameter

Returns:

Dataset with added attributes.

Return type:

xarray.Dataset

polair._helpers.add_global_attrs(ds, config, flight)

This function adds metadata to the data set as stated in the config file.

Parameters:

ds – xarray.Dataset Input data set
config – dict config file containing campaign information
flight – int research flight which is processed

polair._helpers.add_segment_coordinate(ds, config, flight)

Assigns segment coordinate to a data set.

Parameters:

ds – xarray.Dataset data set which is supposed to get the segment coordinate
config – dict configuration dictionary
flight – int flight number

Returns:

data set with segment coordinate

Return type:

xarray.Dataset

polair._helpers.check_sampling(df, v, var_dict, logfile)

Check if sampling interval in df[‘time’] matches expected_sampling (seconds).

95% of samples should match within tolerance. Identified gaps and sampling issues are written in the logfile.

Parameters:

df – pandas.DataFrame Dataframe with data
v – str Variable name
var_dict – dict Dictionary with varible information
logfile – str Logfile path

polair._helpers.convert_unit(ds, var_dict, v)

This function converts the unit from the original unit to the final (SI) unit specified in the variable information.

Parameters:

ds – xarray.Dataset Input dataset
var_dict – dict Dictionary with variable (unit) information
v – str Variable for which unit should be converted

Returns:

Dataset with converted units

Return type:

xarray.Dataset

polair._helpers.create_logfile(config)

Check if processing log file already exists, if not, create it, print date and time.

The config file needs to contain the path information of the log file.

Parameters:: config – dict Configuration dictionary
Returns:: Path to logfile
Return type:: str

polair._helpers.find_gaps(df, v, var_dict, logfile, gap_factor=2.0)

Find data gaps in a time series based on sampling interval.

Parameters:

df – pandas.DataFrame Must contain a ‘time’ column of datetime64.
v – str Variable of the dataframe.
var_dict – dict Inlcudes raw_sampling_time for each variable.
gap_factor – float, optional Threshold factor (default 2.0).

Returns:

Each row is a gap interval: [start_time, end_time, gap_duration].

Return type:

pandas.DataFrame

polair._helpers.g_welmec(lat, h)

Ratio of gravitational acceleration according to Welmec-Formula devided by 9.81.

Parameters:

lat – xarray.DataArray Latitude in degree
h – xarray.DataArray height above sea level in m

Returns:

Dataarray with latitude and height dependent values of g.

Return type:

xarray.DataArray

polair._helpers.get_global_attributes(ds, config, instrument, flight)

Assigns attributes to the data set according to the config file.

Parameters:

ds – xarray.Dataset data set which should get attributes
config – dict configuration dictionary
instrument – str instrument as called in the condig file
flight – int flight number

Returns:

data set with attributes.

Return type:

xarray.Dataset

polair._helpers.get_timestamps(df)

Repair timestamps to datetime64 datetimes.

Parameters:: df – pandas.DataFrame Dataframe with times and data imported from the DMS download.
Returns:: Dataframe with the same data but datetime64 timestamps.
Return type:: pandas.DataFrame

polair._helpers.get_variable_names(xml_file)

Read a DMS order XML file and extract the variable names created by DMS.

Background:

DMS filenames depend on the device configuration during specific flights or campaigns.
This function reads an XML order file (e.g., ‘RAD_flightname.xml’) and extracts variable names based on <channel> tags that include ‘deviceShortName’ and ‘channelShortName’.

Parameters:: xml_file – str Location of the xml file, should be included in the config
Returns:: List with all variable names in the xml file.
Return type:: list

polair._helpers.import_data(v, config, flight)

Import file for single variable using path and prefix for the specific flight from config file.

Parameters:

v – str Variable name
config – dict Configuration dictionary
flight – int Flight number

Returns:

Dataframe with time and variable data.

Return type:

pandas.DataFrame

polair._helpers.import_device_data(indir, dev, time_offset)

Import data from different devices.

Parameters:

indir – str input directory
dev – str device
time_offset – int offset time in ms between device and noseboom to be defined in config file

Returns:

combined data from files in input directory

Return type:

xarray.Dataset

polair._helpers.import_dictionary(yaml_file)

Import config file for respective campaign and other dictionaries.

The config file contains: - campaign information - Paths to xml-file, data

Parameters:: yaml_file – .yaml file Dictionary containing basic information about the campaign
Returns:: The config file as dictionary
Return type:: dict

polair._helpers.import_radiation_data(fn, name)

Imports the radiation file from the DMS raw data.

Parameters:

fn – str filename
name – str variable name

Returns:

data set with variable data

Return type:

xarray.Dataset

polair._helpers.interpolate_time(df, v, var_dict, steps=0.01)

Linearly interpolate time on common timestamps with 100 Hz (or choose accordingly), convert to xarray dataset.

Parameters:

df – pandas.DataFrame Dataframe containing data.
v – str Variable name
var_dict – dict Dictionary containing variable information. It should be specified in the config file.
steps – float Optional, frequency specification given in s, default is 100 Hz, i.e. 0.01 s

Returns:

Dataset interpolated to step frequency, default is 100 Hz.

Return type:

xarray.Dataset

polair._helpers.resample2sec(ds, resample, freq='1s')

Resample data to 1s (default) temporal resolution.

e.g. if timestamps from DMS. Used method is ‘nearest’. This function is optional and not used per default.

Parameters:

ds – xarray.Dataset data to be resampled
resample – bool resampling is only done if resample is put to True
freq – str resampling frequency. Default is “1s” which corresponds to 1 second

Returns:

resampled dataset if sampling is put to True. Else ds is not changed

Return type:

xarray.Dataset

calibration

Definitions of DMS output calibration functions.

Part of the polair package.

title: _calibration.py
author: Laura Köhler
institution: Alfred-Wegener-Institut, Bremerhaven, Germany
contact: laura.koehler@awi.de
date: 2026-04-17

polair._calibration.cal(v, cal_file, df, fn_prefix, var_dict)

Calibrate DMS data and calculate physical values from analog output when necessary.

Applies different calibration methods based on variable type: - Pressure transducers (psT, psB, psN) - Five-hole probe pressures (qaT, qbT, qcT, etc.) - Temperature and other sensors with quadratic calibration - GPS/INS messages with special parsing - Radiation sensor temperatures with Callendar-Van-Dusen equation

Parameters:

v – str Variable name to be calibrated
cal_file – dict Dictionary with calibration coefficients for the campaign
df – pandas.DataFrame DataFrame with raw data to be calibrated
fn_prefix – str Filename prefix for loading auxiliary data (e.g., temperature files)
var_dict – dict Dictionary with variable metadata and old names

Returns:

DataFrame with calibrated values for variable v

Return type:

pandas.DataFrame

corr_fcts

Definitions needed for aircraft noseboom and tbird processing.

Part of the polair package.

title: _corr_fcts.py
author: Laura Köhler
institution: Alfred-Wegener-Institut, Bremerhaven, Germany
contact: laura.koehler@awi.de
date: 2026-04-17

polair._corr_fcts.alignement_correction(data, fhp_params, platform, twist_angle)

Apply alignment corrections from mounting of the noseboom/t-bird.

Parameters are determined from calibration segments with manual evaluation.

Parameters:

data – xarray.Dataset 100 Hz calibrated data
fhp_params – dict Dictionary with parameters for the five-hole probes
platform – str “noseboom” or “tbird”
twist_angle – float Rotation angle of the sonde (in degrees, from config file)

Returns:

Dataset with corrected values

Return type:

xarray.DataArray

polair._corr_fcts.ampbox2lwr_pyrgeometer(I, T)

Convert pyrgeometer current to longwave radiation.

Includes temperature correction using Stefan-Boltzmann law.

Parameters:

I – xarray.DataArray Raw current in A
T – xarray.DataArray Body temperature in K

Returns:

Longwave radiation in W/m²

Return type:

xarray.DataArray

polair._corr_fcts.ampbox2swr_pyranometer(I)

Convert pyranometer current to shortwave radiation.

Based on ampbox manual: 1 mV input → 1 mA output, so 4-20 mA represents 0-16 mV.

Parameters:: I – xarray.DataArray Raw current in A
Returns:: Radiation in W/m²
Return type:: xarray.DataArray

polair._corr_fcts.angle_diff(a, b)

Calculate the shortest angle difference between two angles to determine peaks.

Parameters:

a – xarray.DataArray Angle a (radians)
b – xarray.DataArray Angle b (radians)

Returns:

Shortest angle difference in degrees [-180, 180)

Return type:

xarray.DataArray

polair._corr_fcts.check_flow(ds, refvar='flow_rate', variance=0.1)

Remove flow anomalies where flow rate varies more than specified percentage from average.

Parameters:

ds – xarray.Dataset Data
refvar – str, optional Variable used to check flow rate (default: “flow_rate”)
variance – float, optional Allowed deviation from mean (default: 0.1 = 10%)

Returns:

Data with flow anomalies removed

Return type:

xarray.Dataset

polair._corr_fcts.correct_ins_with_gps(data, v)

Stabilize INS data using GPS measurements.

Parameters:

data – xarray.Dataset 100 Hz calibrated data
v – str Variable to correct (options: “lon”, “lat”, “gs”, “h_ins”, “w_ins”, “vew”, “vns”)

Returns:

GPS-corrected data

Return type:

xarray.Dataset

polair._corr_fcts.correct_ttrk_inat_with_gps(data, data_corr)

Correct INS true track using GPS with unwrapping.

Parameters:

data – xarray.Dataset 100 Hz calibrated data
data_corr – xarray.Dataset Data including ttrk with switched antenna correction

Returns:

GPS-corrected INAT true track

Return type:

xarray.Dataset

polair._corr_fcts.correct_ttrk_ins_with_gps(data, data_corr, v)

True heading correction from INS by GPS

Parameters:

data – xarray.Dataset 100 Hz calibrated data
data_corr – xarray.Dataset GPS-corrected data (from correct_ins_with_gps)
v – str Variable to correct (only “ttrk” supported)

Returns:

GPS-corrected true track

Return type:

xarray.Dataset

polair._corr_fcts.get_h_ins(w, deltat=0.01)

Calculate aircraft altitude from vertical acceleration and velocity.

Parameters:

w – xarray.Dataset Vertical velocity dataset
deltat – float, optional Sampling rate in seconds (default: 0.01 for 100 Hz data)

Returns:

Aircraft altitude from INS

Return type:

xarray.Dataset

polair._corr_fcts.get_radiation(config, flight, out_vars)

Calculate body temperatures and radiation from DMS raw data.

Parameters:

config – dict Configuration dictionary
flight – int Flight number
out_vars – dict Dictionary with output variables

Returns:

Dataset with longwave and shortwave radiation

Return type:

xarray.Dataset

polair._corr_fcts.get_true_air_speed(data, platform)

Calculate true airspeed from air density.

Parameters:

data – xarray.Dataset Data with corrected variables (adiabatic corrected Te_N_corr and ps)
platform – str “noseboom” or “tbird”

Returns:

True airspeed

Return type:

xarray.DataArray

polair._corr_fcts.get_w_ins(data, start, stop, deltat=0.01)

Calculate vertical velocity from INS vertical acceleration and remove Schuler oscillation.

Parameters:

data – xarray.Dataset Calibrated data
start – numpy.datetime64 Start time of the flight (from config)
stop – numpy.datetime64 End time of the flight (from config)
deltat – float, optional Sampling rate in seconds (default: 0.01 for 100 Hz data)

Returns:

Vertical velocity from INS with Schuler oscillation removed

Return type:

xarray.Dataset

polair._corr_fcts.get_wind_component(data, data_corr, component, platform)

Calculate wind components from calibrated raw data and corrected data.

Parameters:

data – xarray.Dataset Dataset with raw data
data_corr – xarray.Dataset Dataset with corrected data
component – str Wind component (“u”, “v”, or “vertwind”)
platform – str “noseboom” or “tbird”

Returns:

Wind component

Return type:

xarray.DataArray

polair._corr_fcts.humidity_correction(rh, T_sensor, T_amb)

Apply adiabatic correction to relative humidity.

Cuts values larger than 1.0 (limits of adiabatic correction).

Parameters:

rh – xarray.DataArray Relative humidity from humicap
T_sensor – xarray.DataArray Humidity sensor temperature in K
T_amb – xarray.DataArray Ambient temperature in K

Returns:

Corrected relative humidity (capped at 1.0)

Return type:

xarray.DataArray

polair._corr_fcts.mask_out_peaks(ds, refvar='p_amb', threshold=5000, timedelta=1)

Mask out peaks in data based on pressure changes.

Parameters:

ds – xarray.Dataset Data
refvar – str, optional Variable used to check for peaks (default: “p_amb”)
threshold – float, optional Threshold to identify peaks (default: 5000 Pa)
timedelta – int, optional Time window in seconds for peak detection (default: 1 s)

Returns:

Data with peaks removed

Return type:

xarray.Dataset

polair._corr_fcts.mask_ttrk_thdg(ttrk, thdg)

Mask regions where true track and true heading differ significantly.

Also masks 2-second windows around unphysical peaks in curves.

Parameters:

ttrk – xarray.DataArray True track (radians)
thdg – xarray.DataArray True heading (radians)

Returns:

(masked ttrk, masked thdg) in radians

Return type:

tuple

polair._corr_fcts.resistance2temperature(R)

Convert PT-100 resistance in Ohm in radiation sensors to temperature in K using Callendar-Van-Dusen equation ((https://de.wikipedia.org/wiki/Callendar-Van-Dusen-Gleichung), a, b from Datasheet.

Parameters:: R – xarray.DataArray Resistance in Ohm
Returns:: Temperature in K
Return type:: xarray.DataArray

polair._corr_fcts.reverse_antennas(ds, angle, shift)

Apply antenna switching correction.

If shift=True: shifts angle by 180° (possible reason: switched antennas in iNAT).

Parameters:

ds – xarray.Dataset Calibrated data
angle – str Angle variable to be switched (e.g., “roll_inat”, “pitch_inat”, “thdg”)
shift – bool Whether to apply 180° shift (True) or keep original (False)

Returns:

Shifted data if shift=True, else unchanged data

Return type:

xarray.DataArray

polair._corr_fcts.sat_correction(ds, ds_corr, t, recovery=1.0)

Compute static air temperature from TAT using adiabatic correction.

Recovery is a correction for deiced sensor (recovery=1.00025).

Parameters:

ds – xarray.Dataset Dataset with all variables
ds_corr – xarray.Dataset Dataset with corrected variables (not used in docstring but present in code)
t – str Temperature variable name
recovery – float, optional Recovery factor for deiced sensor (default: 1.00025)

Returns:

Corrected temperature

Return type:

xarray.DataArray

polair._corr_fcts.sat_pressure(temp)

Calculate saturation pressure using the Magnus formula.

Parameters:: temp – xarray.DataArray Temperature in Kelvin
Returns:: Saturation pressure in hPa
Return type:: xarray.DataArray

polair._corr_fcts.stp_conditions(ds, temp='t_amb', pres='p_amb')

Add variables reduced to standard temperature and pressure (STP). The dataset needs to have the device internal temperature and pressure

STP conditions: p₀ = 1013 hPa, T₀ = 0°C.

Parameters:

ds – xarray.Dataset Dataset with variables to reduce to STP, ambient temperature and pressure
temp – str, optional Name of temperature variable (default: “t_amb”)
pres – str, optional Name of pressure variable (default: “p_amb”)

Returns:

Dataset with additional STP-corrected variables

Return type:

xarray.Dataset

polair._corr_fcts.true_track_xarray(lat1, lon1, lat2, lon2)

Calculate the true track (bearing) between two geographic points.

Parameters:

lat1 – xarray.DataArray Latitude at start point (degrees)
lon1 – xarray.DataArray Longitude at start point (degrees)
lat2 – xarray.DataArray Latitude at end point (degrees)
lon2 – xarray.DataArray Longitude at end point (degrees)

Returns:

True track (bearing) in degrees [0, 360)

Return type:

xarray.DataArray

polair._corr_fcts.unwrap_with_nans(da, period=360)

Unwrap angle data while preserving NaN positions.

Interpolates over NaNs to enable unwrapping, then restores original NaNs.

Parameters:

da – xarray.DataArray Angle data to be unwrapped (degrees)
period – float, optional Period for unwrapping (default: 360 for degrees)

Returns:

Unwrapped data array with NaNs at original positions

Return type:

xarray.DataArray