;+
; Project     : SOLAR-B - EIS
;
; Name        : EIS_CPT_EXTRACT_PERIOD
;
; Purpose     : Calculates the data volume generated within a specified period.
;
; Explanation : Calculates the data volume generated  within a specified period.
;
; Use         : < volume = eis_cpt_extract_period(study_details, timeline, start_time, end_time) >
;
; Inputs      : study_details              : STRUCTURE ARRAY of type EIS_study_detail.
;               timeline                   : STRUCTURE ARRAY of type EIS_CPT_timeline updated
;               start_time                 : DOUBLE TAI time of start of period.
;                                            If not defined then uses from first study.
;               end_time                   : DOUBLE TAI time of end of period.
;                                            If not defined then uses until last study.
;
; Opt. Inputs : None.
;
; Outputs     : volume                     : FLOAT volume of data generated in Mbits
;
; Opt. Outputs: None.
;
; Keywords    : None.
;
; Calls       : None.
;
; Common      : None.
;
; Restrictions: None.
;
; Side effects: None.
;
; Category    : EIS_CPT.
;
; Prev. Hist. : None.
;
; Written     : Martin Carter RAL 27/09/05
;
; Modified    : Version 0.0, 27/09/05, MKC
;               Version 0.1, 03/10/06, MKC
;                 Changed output to Mbits.
;
; Version     : 0.1, 03/10/06
;-
;**********************************************************

FUNCTION eis_cpt_extract_period, study_details, timeline, start_time, end_time

  ; initialize data volume generated within period

  volume = 0.0

  ; check timeline exists

  IF KEYWORD_SET(timeline) THEN BEGIN

     ; get study durations

    duration = study_details[timeline.index].duration*study_details[timeline.index].study_repeat_number

   ; set up internal start and end times of period

    IF KEYWORD_SET(start_time) THEN stime = start_time ELSE stime = 0.0d0

    IF KEYWORD_SET(end_time) THEN etime = end_time ELSE etime = last_item(timeline.time+duration)

    ; get list of studies overlapping period

    list = WHERE(timeline.time LT etime AND timeline.time+duration GT stime, count)

    ; workout volume for all studies overlapping period

    FOR k = 0, count-1 DO BEGIN

      ; get proportion of time within period
      ; enforce minimum 1 second denominator

      duration = duration > 1

      proportion = (((timeline[list[k]].time+duration[list[k]]) < etime) - (timeline[list[k]].time > stime))/ $
                         (duration[list[k]] > 1)


      ; add proportion of data generated

      volume = volume + proportion*study_details[timeline[list[k]].index].data* $
                 study_details[timeline[list[k]].index].study_repeat_number

    ENDFOR

  ENDIF

  ; return volume generated in MBits

  RETURN, 8L*volume/(1024L*1024L)

END