Migrating to 0.3.0

0.3.0 changes the output: reconvert your missions. Nothing on this page needs a code change unless you read PHASE, PHASE_QC, PROFILE_NUMBER, DIVE_NUMBER (now dive_number), SA/CT, uri, a passed-through variable in cm/s, a data point by its index around a GPS fix, or the SENSOR_* serial numbers and dates, or still import a pre-0.1.0 name.

PHASE

PHASE is assigned from what the glider recorded it did (see How the phase is assigned). On the same dive, 0.2.0 and 0.3.0 differ like this:

0.2.0

0.3.0

values used

1 ascent, 2 descent, 3 at the first two GPS fixes

1 ascent, 2 descent, 3 surfacing, 4 parking (a loiter), 5 inflection, 0 unknown

descent / ascent split

at the pressure maximum

at the glider’s apogee (state table, or the G&C event that moves the VBD to zero)

bottom of the dive

descent to the pressure maximum, then ascent

inflection (the apogee); the deepest sample can fall in the first ascent data points

end of the climb

ascent

ascent through the surface coast (the OG1 table does not name it), then surfacing from begin surface

GPS fixes

the first two 3, the last one ascent

every fix 3

data type

byte, _FillValue 127

byte, _FillValue 0

attributes

phase_vocabulary

also flag_values, flag_meanings, phase_calculation_method, phase_calculation_method_vocabulary

Code that selects profiles with PHASE == 2 / PHASE == 1 still works, but the apogee samples (5) are no longer in either. To keep every sample, split each dive at its inflection, or at its deepest sample as 0.2.0 did.

xarray reads PHASE with its _FillValue 0 as missing, so PHASE 0 (unknown) comes back as NaN; xr.open_dataset(..., mask_and_scale=False) or ds.PHASE.fillna(0) keeps the 0.

PROFILE_NUMBER

Now from PHASE, as OG1 defines it: one number per run of descent or ascent, -9999 on every other data point (surfacing, inflection). 0.2.0 split each dive at the pressure maximum, numbered the halves 2n-1 and 2n from the dive number, and gave every data point a number. tools.add_profile_number (and its old name assign_profile_number), which did that, is removed: call tools.add_phase, then tools.add_profiles.

PROFILE_DIRECTION, SEGMENT_NUMBER

New (OG1): 1/-1/0 for descent/ascent/other, and +1 each time the glider enters surfacing.

dive_number

Renamed from DIVE_NUMBER: it is the Seaglider’s dive number, not an OG1 variable, so it is written in lower case like the other non-OG1 variables.

PHASE_QC

0 (no QC performed) on every data point, with the OG1 flag scale 0–4 as flag_values and flag_meanings. 0.2.0 wrote 0 with no flag attributes.

Salinity: no SA or CT

Files carry practical salinity (PSAL) only, as TEOS-10 recommends archiving. 0.2.0 renamed a basestation file’s absolute_salinity and conservative_temperature to SA and CT; they now pass through under those names, with the basestation’s own attributes (for example units = "g/kg", no standard_name). POTDENS0 is still written (computed with TEOS-10). Compute SA and CT when you need them:

import gsw

SA = gsw.SA_from_SP(ds.PSAL, ds.PRES, ds.LONGITUDE, ds.LATITUDE)
CT = gsw.CT_from_t(SA, ds.TEMP, ds.PRES)

Variable attributes

  • uri is renamed vocabulary (OG1’s name); read vocabulary. See Variable vocabulary.

  • Every variable on N_MEASUREMENTS carries coordinates = "TIME LONGITUDE LATITUDE DEPTH".

  • Units are written in one canonical spelling on every variable, including those that keep their basestation names (g kg-1, kg m-3, degree_Celsius, m, degree). A passed-through variable in cm/s is converted to m s-1, with original_units and a conversion_units entry. Spellings the converter does not recognise are left as written.

GPS fixes: one data point each

Each GPS fix is now one data point, so TIME normally has no duplicate at a fix and sel(TIME=...), swap_dims and resampling work on it. 0.2.0 wrote each fix twice (the merged gps_info record and an appended copy carrying LATITUDE_GPS/LONGITUDE_GPS/TIME_GPS); the *_GPS variables and the fix’s surface LATITUDE/LONGITUDE and DEPTH (0 m) now sit on the one gps_info data point. A fix logged twice within a dive is written once. The same fix re-logged at a dive boundary is written once when the later copy carries nothing but the fix (the dropped copy is recorded in the conversion_dropped_gps_fixes global); if it carries other data, both are kept, TIME keeps the duplicate there, and the conversion logs a WARNING. N_MEASUREMENTS is shorter by the removed fixes; TIME_GPS is the fix time as the GPS recorded it (log_gps_time).

Basestation 2.10 files

Files whose gc_state_secs are seconds from the dive start (basestation 2.10) no longer put data points in January 1970. Their output name and time_coverage_start change from sg033_19700101T000012_R to the dive’s real start, for example sg033_20100903T181710_R.

Sensor serial numbers and calibration dates

Serial numbers and calibration dates are read from the calibration comments by named rules (see How calibration comments are read); files differ from 0.2.0 wherever the old parser was wrong.

sample

0.2.0 wrote

0.3.0

sg005 CTD (SBE 24520-1 calibration 04FEB08)

SENSOR_CTD_245201

SENSOR_CTD_24520-1

sg005 WET Labs (no comment)

SENSOR_FLUOROMETER_0000, date 00-00-0000

SENSOR_FLUOROMETER_UNK, date UNK

  • A serial or date that cannot be read is UNK; 0000, 00-00-0000, 0000-00-00, Format Error and None Found are no longer written.

  • Two-number dates are read by separator: slashes month-first (9/10/08 → 10 September), dots and dashes day-first (12.05.2012 → 12 May). 0.2.0 read every such date day-first.

  • New on each SENSOR_*: original_calibcomm (the comment as written) and, for multi-channel instruments, sensor_calibration_dates. New global: conversion_sensor_calibration.

  • sensors.<key>.calibration_date in mission.yaml must be an ISO date (YYYY-MM-DD).

Removed names

The pre-0.1.0 names that warned or raised through 0.1.x and 0.2.x are removed. Using one gives Python’s ordinary AttributeError (ImportError for from ... import); Migrating to 0.1.0 gives each one’s replacement:

  • readers: load_basestation_files, load_first_basestation_file, scan_and_repair_files, repair_netcdf_time_metadata_inplace, profnum_from_filename, glider_sn_from_filename, load_sample_dataset;

  • writers: save_dataset;

  • tools: calc_Z, assign_phase, reformat_units_str, reformat_units_var, convert_units_var, OG1_name_mapping, print_OG1_mapping_summary and the pipeline internals (og1_name_mapping, gather_sensor_info, add_sensor_to_dataset, merge_datasets_along_time, extract_scalar_parameters, add_scalar_parameters, set_best_dtype);

  • contributors: registry_institutions, normalize_orcid, normalize_role;

  • vocabularies: load_default_contributors, contrib_to_append, unit_str_format, unit1_to_unit2, preferred_units;

  • the convertOG1 module;

  • plotters.show_* no longer accept a file path: pass an open dataset.

tools.add_profile_number (and its old name assign_profile_number) is also removed; see PROFILE_NUMBER above.