;docformat = 'rst'
;+
; This uses the spacecraft offset file to calculate a
;   space craft offset
;
; :Author:
;   Bill Barrett
;
; :Examples:
;   IDL> clock_offset = calculate_or_interpolate_sc_offset(time_in_gps_usec)
;
; :Params:
;   time_in_gps_usec : double (or long64), required
;     The time in gps microseconds to use to generate an offset
;   
; :Returns:
;   The calculated space craft offset for that time period.
;
;-
function calculate_or_interpolate_sc_offset, time_in_gps_usec
  common sc_offset, clock_offset_data

  if n_elements(clock_offset_data) eq 0 then begin
    read_spacecraft_offset_file
  endif

  ; The dates from the spacecraft offset file are in 'yyyyddd' format
  yyyy_ddd = usec2yd(time_in_gps_usec)
  aim_day = yd2ad(yyyy_ddd)
  
  ; The offset is assumed to be zero near the beginning of the mission
  less = where(clock_offset_data.year_day_of_year le yyyy_ddd, less_count)
  if less_count le 0 then begin
    clock_offset=0.0
  endif else begin
    more = where(clock_offset_data.year_day_of_year gt yyyy_ddd, more_count)
    ; If the date is between two known points, then interpolate
    if more_count gt 0 then begin
      clock_offset = linterp( $
        yd2ad(clock_offset_data[less[less_count - 1]].year_day_of_year), $
        clock_offset_data[less[less_count - 1]].clock_offset, $
        yd2ad(clock_offset_data[more[0]].year_day_of_year), $
        clock_offset_data[more[0]].clock_offset, $
        aim_day)
    endif else begin
      ; If the date is past the last date in the file
      max_index = n_elements(clock_offset_data) - 1
      ; If the slope is available, use it to extrapolate
      if  clock_offset_data[max_index].clock_slope ne -9999. then begin
        days_since_last_entry = aim_day - yd2ad(clock_offset_data[max_index].year_day_of_year)
        ; The clock offset slope is in seconds per day
        clock_offset = clock_offset_data[max_index].clock_offset + $
          (days_since_last_entry * clock_offset_data[max_index].clock_slope)
      endif else begin
        ; Otherwise extrapolate using a n-point linear fit from the last known valid points
        n_points = n_elements(clock_offset_data) ge 10 ? 10 : n_elements(clock_offset_data)
        start_index = n_elements(clock_offset_data) - n_points
        x = extrac(yd2ad(clock_offset_data.year_day_of_year), start_index, n_points)
        y = extrac(records_w_valid_offsets.clock_offset, start_index, n_points)
        coefs=no_chi_linfit(x, y)
        clock_offset = coefs[0] + yd2ad(yyyy_ddd) * coefs[1]
      endelse
    endelse
  endelse

  ; Convert the offset from seconds to microseconds
  return, clock_offset * 1e6
end