Sequential report functions

The New Track Check QC module provides the functions needed to perform the track check.

The main routine is mds_full_track_check which takes a list of class`.MarineReport` from a single ship and runs the track check on them. This is an update of the MDS system track check in that it assumes the Earth is a sphere. In practice, it gives similar results to the cylindrical earth formerly assumed.

marine_qc.track_check_utils.backward_discrepancy(lat, lon, date, vsi, dsi)[source]

Calculate the distance between the projected position and the actual position.

The projected position is based on the reported speed and heading at the current and previous time steps. The calculation proceeds from the final, later observation to the first (in contrast to distr1 which runs in time order)

This takes the speed and direction reported by the ship and projects it forwards half a time step, it then projects it forwards another half-time step using the speed and direction for the next report, to which the projected location is then compared. The distances between the projected and actual locations is returned

Parameters:

  • lat (SequenceNumberType) – One-dimensional latitude array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • lon (SequenceNumberType) – One-dimensional longitude array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • date (SequenceDatetimeType) – One-dimensional date array. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • vsi (SequenceNumberType) – One-dimensional reported speed array in km/h. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • dsi (SequenceNumberType) – One-dimensional reported heading array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

Return type:

SequenceFloatType

Returns:

SequenceFloatType – Same type as input, but with float values, shape (n,)

One-dimensional array, sequence, or pandas Series containing distances from estimated positions.

Raises:

  • ValueError – If either input is not 1-dimensional or if their lengths do not match.

  • TypeError – If decorator inspect_arrays does not return np.ndarrays.

marine_qc.track_check_utils.calculate_course_parameters(lat_later, lat_earlier, lon_later, lon_earlier, date_later, date_earlier)[source]

Calculate course parameters.

Parameters:

  • lat_later (float) – Latitude in degrees of later timestamp.

  • lat_earlier (float) – Latitude in degrees of earlier timestamp.

  • lon_later (float) – Longitude in degrees of later timestamp.

  • lon_earlier (float) – Longitude in degrees of earlier timestamp.

  • date_later (datetime) – Date of later timestamp.

  • date_earlier (datetime) – Date of earlier timestamp.

Return type:

tuple[float, float, float, float]

Returns:

tuple of float – A tuple of four floats representing the speed, distance, course and time difference.

marine_qc.track_check_utils.calculate_midpoint(lat, lon, timediff)[source]

Interpolate between alternate reports and compare the interpolated location to the actual location.

E.g. take difference between reports 2 and 4 and interpolate to get an estimate for the position at the time of report 3. Then compare the estimated and actual positions at the time of report 3.

The calculation linearly interpolates the latitudes and longitudes (allowing for wrapping around the dateline and so on).

Parameters:
Return type:

ndarray

Returns:

1D np.ndarray of float – One-dimensional array of distances from estimated positions in kilometers.

Raises:

ValueError – If either input is not 1-dimensional or if their lengths do not match.

marine_qc.track_check_utils.calculate_speed_course_distance_time_difference(lat, lon, date, alternating=False)[source]

Calculate speeds, courses, distances and time differences using consecutive reports.

Parameters:

  • lat (SequenceNumberType) – One-dimensional latitude array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • lon (SequenceNumberType) – One-dimensional longitude array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • date (SequenceDatetimeType) – One-dimensional date array. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • alternating (bool, default: False) – Whether to use alternating reports for calculation.

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

tuple of np.ndarray, each with float values, shape (n,) – A tuple containing four one-dimensional arrays representing: speed, distance, course, and time difference.

marine_qc.track_check_utils.check_distance_from_estimate(vsi, time_differences, fwd_diff_from_estimated, rev_diff_from_estimated, vsi_previous=None)[source]

Check that distances from estimated positions are less than calculated distance.

The estimated positions are calculated forward and backwards in time. The calculated distance is the time difference multiplied by the average reported speeds.

Parameters:

  • vsi (SequenceNumberType) – Reported speed in km/h at current time step.

  • time_differences (SequenceNumberType) – Calculated time differences between reports in hours.

  • fwd_diff_from_estimated (SequenceNumberType) – Distance in km from estimated position, estimates made forward in time.

  • rev_diff_from_estimated (SequenceNumberType) – Distance in km from estimated position, estimates made backward in time.

  • vsi_previous (SequenceNumberType, optional) – One-dimensional array of reported speed in km/h at previous time step. If None, get vsi_previous from vsi.

Return type:

ndarray

Returns:

np.ndarray – Returned array elements set to 10 if estimated and reported positions differ by more than the reported speed multiplied by the calculated time difference, 0 otherwise.

Raises:

TypeError – If inspect_arrays does not return np.ndarrays.

marine_qc.track_check_utils.direction_continuity(dsi, directions, dsi_previous=None, max_direction_change=60.0)[source]

Check if reported and calculated directions are within the allowed change.

This function compares the heading at the previous time step with the calculated ship direction from reported positions, flagging differences that exceed the maximum allowed direction change.

Parameters:

  • dsi (SequenceNumberType) – Heading at current time step in degrees.

  • directions (SequenceNumberType) – Calculated ship direction from reported positions in degrees.

  • dsi_previous (SequenceNumberType, optional) – Heading at previous time step in degrees. If None, get dsi_previous from dsi.

  • max_direction_change (float) – Largest deviations that will not be flagged in degrees.

Return type:

ndarray

Returns:

np.ndarray – Returned array elements are 10.0 if the difference between reported and calculated direction is greater than the max_direction_change (default, 60 degrees), 0.0 otherwise.

marine_qc.track_check_utils.forward_discrepancy(lat, lon, date, vsi, dsi)[source]

Calculate the distance between the projected position and the actual position.

The projected position is based on the reported speed and heading at the current and previous time steps. The observations are taken in time order.

This takes the speed and direction reported by the ship and projects it forwards half a time step, it then projects it forwards another half time-step using the speed and direction for the next report, to which the projected location is then compared. The distances between the projected and actual locations is returned

Parameters:

  • lat (SequenceNumberType) – One-dimensional latitude array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • lon (SequenceNumberType) – One-dimensional longitude array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • date (SequenceDatetimeType) – One-dimensional date array. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • vsi (SequenceNumberType) – One-dimensional reported speed array in km/h. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

  • dsi (SequenceNumberType) – One-dimensional reported heading array in degrees. Can be a sequence (e.g., list or tuple), a one-dimensional NumPy array, or a pandas Series.

Return type:

SequenceFloatType

Returns:

SequenceFloatType – Same type as input, but with float values, shape (n,)

One-dimensional array, sequence, or pandas Series containing distances from estimated positions.

Raises:

  • ValueError – If either input is not 1-dimensional or if their lengths do not match.

  • TypeError – If decorator inspect_arrays does not return np.ndarrays.

marine_qc.track_check_utils.increment_position(alat1, alon1, avs, ads, timediff)[source]

Compute latitude and longitude increments over half a time interval.

This function takes latitudes and longitude, a speed, a direction and a time difference and returns increments of latitude and longitude which correspond to half the time difference.

Parameters:

  • alat1 (SequenceNumberType) – One-dimensional array of Latitude at starting point in degrees.

  • alon1 (SequenceNumberType) – One-dimensional array of Longitude at starting point in degrees.

  • avs (SequenceNumberType) – One-dimensional array of speed of ship in km/h.

  • ads (SequenceNumberType) – One-dimensional array of heading of ship in degrees.

  • timediff (SequenceNumberType) – One-dimensional array of time difference between the points in hours.

Return type:

tuple[ndarray, ndarray]

Returns:

1D np.ndarray of float – Returns latitude and longitude increment or None and None if timediff is None.

marine_qc.track_check_utils.modal_speed(speeds)[source]

Calculate the modal speed from the input array in 3 knot bins.

Returns thebin-centre for the modal group.

The data are binned into 3-knot bins with the first from 0-3 knots having a bin centre of 1.5 and the highest containing all speed in excess of 33 knots with a bin centre of 34.5. The bin with the most speeds in it is found. The higher of the modal speed or 8.5 is returned:

Bins- 0-3, 3-6, 6-9, 9-12, 12-15, 15-18, 18-21, 21-24, 24-27, 27-30, 30-33, 33-36 Centres-1.5, 4.5, 7.5, 10.5, 13.5, 16.5, 19.5, 22.5, 25.5, 28.5, 31.5, 34.5

Parameters:

speeds (list) – Input speeds in km/h.

Return type:

float

Returns:

float – Bin-centre speed (expressed in km/h) for the 3 knot bin which contains most speeds in input array, or 8.5, whichever is higher.

marine_qc.track_check_utils.set_speed_limits(amode)[source]

Take a modal speed and calculate speed limits for the track checker.

Parameters:

amode (float) – Modal speed in km/h.

Return type:

tuple[float, float, float]

Returns:

(float, float, float) – Max speed, maximum max speed and min speed.

marine_qc.track_check_utils.speed_continuity(vsi, speeds, vsi_previous=None, max_speed_change=10.0)[source]

Check if reported speeds are within the allowed change from calculated speeds.

This function compares the reported speed at the current and previous time steps with the speed calculated from positions. Flags positions where the change exceeds the maximum allowed speed change.

Parameters:

  • vsi (SequenceNumberType) – One-dimensional array of reported speed in km/h at current time step.

  • speeds (SequenceNumberType) – One-dimensional array of speed of ship calculated from locations at current and previous time steps in km/h.

  • vsi_previous (SequenceNumberType, optional) – One-dimensional array of reported speed in km/h at previous time step. If None, get vsi_previous from vsi.

  • max_speed_change (float, optional) – Largest change of speed that will not raise flag in km/h, default 10 (km/h).

Return type:

ndarray

Returns:

np.ndarray – Returned array elements are 10 if the reported and calculated speeds differ by more than 10 knots, 0 otherwise.