This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# projects/dscovr/mission_compare

- DSC_MISSION_COMPARE__DEFINE[1]
  Defines an object that represents a comparison between data of two missions
- DSC_MISSION_COMPARE__DEFINE[2]
- DSC_MISSION_COMPARE__DEFINE[2]
- DSC_MISSION_COMPARE__DEFINE[3]
- DSC_MISSION_COMPARE__DEFINE[4]
- DSC_MISSION_COMPARE__DEFINE[5]
- DSC_MISSION_COMPARE__DEFINE[6]
- DSC_MISSION_COMPARE__DEFINE[7]
- DSC_MISSION_COMPARE__DEFINE[8]
- DSC_MISSION_COMPARE__DEFINE[9]
- DSC_MISSION_COMPARE__DEFINE[10]
- DSC_MISSION_COMPARE__DEFINE[11]
- DSC_MISSION_COMPARE__DEFINE[12]
- DSC_MISSION_COMPARE__DEFINE[13]
- DSC_MISSION_COMPARE__DEFINE[14]
- DSC_MISSION_COMPARE__DEFINE[15]
- DSC_MISSION_COMPARE__DEFINE[16]
- DSC_MISSION_COMPARE__PLOT
- DSC_SHIFTLINE
- DSC_TIME_ABSOLUTE__DEFINE[1]
  Defines an object to represent an absolute amount of time, not in reference
- DSC_TIME_ABSOLUTE__DEFINE[2]
- DSC_TIME_ABSOLUTE__DEFINE[2]
- DSC_TIME_ABSOLUTE__DEFINE[3]
- DSC_TIME_ABSOLUTE__DEFINE[4]
- DSC_TIME_ABSOLUTE__DEFINE[5]
- DSC_TIME_ABSOLUTE__DEFINE[6]
- DSC_TIME_ABSOLUTE__DEFINE[7]
- DSC_TIME_ABSOLUTE__DEFINE[8]
- DSC_TIME_ABSOLUTE__DEFINE[9]
- DSC_TIME_ABSOLUTE__DEFINE[10]
- DSC_TIME_ABSOLUTE__DEFINE[11]
- DSC_TIME_ABSOLUTE__DEFINE[12]
- DSC_TIME_ABSOLUTE__DEFINE[13]
- DSC_TIME_ABSOLUTE__DEFINE[14]
- DSC_TIME_ABSOLUTE__DEFINE[15]
- DSC_TIME_ABSOLUTE__DEFINE[16]
- DSC_TIME_ABSOLUTE__DEFINE[17]
- DSC_TIME_ABSOLUTE__DEFINE[18]
- DSC_TIME_ABSOLUTE__DEFINE[19]
- DSC_TIME_ABSOLUTE__DEFINE[20]
- DSC_TIME_ABSOLUTE__DEFINE[21]
- DSC_TIME_ABSOLUTE__DEFINE[22]
- DSC_TIME_ABSOLUTE__DEFINE[23]
- DSC_TIME_ABSOLUTE__DEFINE[24]
- DSC_TIME_ABSOLUTE__DEFINE[25]
- DSC_TIME_ABSOLUTE__DEFINE[26]

# Routine Descriptions

## DSC_MISSION_COMPARE__DEFINE[10]

[Next Routine] [List of Routines]

    DESCRIPTION:
      De-selects one variable from the comparison, leaving other
      variable settings intact. OR unset all with keyword \all

    KEYWORDS:
      All:  Mark all variables as unselected with keyword \all.

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      mco.clearVar,'by'       ;; Now only NP,BX
      mco.clearVar,/all

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[11]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Reorders the comparison variables.
      If passed no arguments it will enter an interactive session.

      Order positions are described by 1-indexed positions.
      (I.e.- the top panel is in position 1, the next panel down in
       position 2, etc.)

    INPUT:
      TARGET:
         if SCALAR - An identifier of the item in the variable list
                     that you want moved.  STRING or INTEGER.
                     A STRING must match one of the selected variables.
                     An INTEGER must index a valid position. (I.e.- if
                     there are 4 selected variables, then a 1,2,3,and 4 are
                     valid positions.
         if ARRAY -  A description of the desired ordering. STRING or INTEGER.
                     A STRING array must be a permutation of the existing
                     selected values.
                     AN INTEGER array must be a permuation of the existing positions.
                     (I.e.- if there are 4 selected elements, then the existing positions
                     can be described as [1,2,3,4].  Passing [4,1,2,3] as TARGET requests
                     that the last item be moved to the first position, the first item
                     moved to the second position, etc.)
      DESTINATION:  The desired end position for target element. (INTEGER)
                    Default is 1.
                    This argument only has meaning if TARGET is SCALAR; it is
                    ignored otherwise.

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[12]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns a structure of type {DSC_MISSION_COMPARE}
      containing this object's values

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      mc_str =  mco.getall()

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[13]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the object title (string)

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      defaultTitle = mco.getTitle()

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[14]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the object color settings as a structure

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      panelcolors = mco.getColor()

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[15]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns a string array of shortcut names for all variables
      to be compared in the order the panels will be shown in a
      plot.

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      vars = mco.getVars()

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[16]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Find the standardized mission tag given a passed string.
      Returns !NULL if string does not match a tag.

      Note, this is a static method and can be called on an instance
      of the class or on the class itself.

    KEYWORDS:
      All:  Return all supported mission tags with the \all keyword

    CALLING SEQUENCE:
      tagMatch = dsc_mission_compare.findMTags('d')
      allTags = dsc_mission_compare.findMTags(/all)

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     DSC_MISSION_COMPARE__DEFINE

    PURPOSE:
     Defines an object that represents a comparison between data of two missions
     and enables simplified plotting of matching parameters between the two.
     Currently supports the DSCOVR, WIND, and ACE default loaded datatypes.

    CALLING SEQUENCE:
     mco = Obj_New("DSC_MISSION_COMPARE")
     mco = Obj_New("DSC_MISSION_COMPARE",m1='wi',m2='d',vars=['np','bx','by'])
     mco = dsc_mission_compare()
     mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])

     REQUIRED INPUT:
     none - it will query for required information if none is passed.

    KEYWORDS (Optional):
     C1=:     Mission 1 color (array/scalar) (int/string)
     C2=:     Mission 2 color (array/scalar) (int/string)
              Color arrays must match size to number of variables selected
              IDL single char color strings supported. [k,m,b,c,g,y,r,w]
     M1=:     Mission 1 shortcut string (string)
     M2=:     Mission 2 shortcut string (string)
     SET=:    A DSC_MISSION_COMPARE structure to use to initialize this object.
                This keyword supercedes the other keywords.
     TITLE=:  Title to use for comparison plot.  If not set, will create a
                default based on the missions set (string)
     VARS=:   Shortcut string(s) describing which variable(s) to compare between
                the two missions.  If scalar, will describe a plot with one panel.
                If array, the comparison plot will have one panel for each array
                element. (string)

    OUTPUT:
     dsc_mission_compare object reference

    METHODS:
     SetAll      - modify this object by passing a DSC_MISSION_COMPARE structure
     SetTitle    - modify the comparison plot title
     SetMissions - modify which missions to compare. Pass arguments or set interactively.
     SetVars     - sets all comparison variables based on passed string array OR interactive prompt
     SetVar      - set one variable to be compared, leaving other variable settings intact. OR set all with keyword \all.
     SetColor    - set the plotted line colors for the selected variables
     Plot        - create a plot based on this comparison object
     ClearVar    - de-selects one variable from the comparison, leaving other variable settings intact. OR unset all with keyword \all
     Reorder     - reorders the comparison variables
     GetAll      - returns a structure of type {dsc_mission_compare} containing this object's values
     GetTitle    - returns the object title (string)
     GetColor    - returns the object color settings
     GetVars     - returns a string array of shortcut names for all variables to be compared.
     FindMTag    - (Static Method) find a mission tag based on a passed string
                      OR return all supported mission tags with the \all keyword

    NOTES:
     print/implied print are overloaded for this class.

    CREATED BY: Ayris Narock (ADNET/GSFC) 2018

     $LastChangedBy: nikos $
     $LastChangedDate: 2018-03-12 09:55:28 -0700 (Mon, 12 Mar 2018) $
     $LastChangedRevision: 24869 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/dscovr/mission_compare/dsc_mission_compare__define.pro $

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[2]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Set new values of this object by passing a DSC_MISSION_COMPARE structure

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      c = mco.getall()
      c.btheta=1
      c.vx = 1
      c.np = 0
      c.m1='ace'
      mco.setall,c

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[2]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Modify the comparison plot title.
      Called with no argument will set the default title based on selected missions

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      mco.setTitle,'Comparing WIND and DSCOVR'

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[3]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Set which missions to compare.
      Pass as string arguments or set interactively if no arguments passed.
      If only one argument is passed, it updates Mission 1

      If missions are changed and it is already using a default title,
      it will update the default title.  Otherwise, it will prompt the
      user whether or not to update the current title to a new default
      title.

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      mco.setMissions,'ace','dsc'

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[4]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the title generated by default.

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[5]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Sets all comparison variables.

      If passed a string (scalar or array) will set these variables
      as those to be compared and will de-select all others.

      If no strings, or bad strings, are passed the routine will provide
      an interactive prompt.

      Array order implies the panel order in the plotted comparison.
      If supplying variables interactively, the panel order is the
      order in which the variables are entered at the prompt.

      If passed a {DSC_MISSION_COMPARE} structure it will set the variables
      based on the fields set in the structure, preserving any valid
      ordering and colors if they are set in the structure.  Title and
      mission fields in the structure are ignored.  May update the default title.

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      mco.setVars
      mco.setVars,'bx'              ;; Now only BX is set
      mco.setVars,['v','np','bz']   ;; Now only V,NP,BZ are set. BX is cleared

      g = mco.getAll()
      g.by = 1
      g.v = 0
      mco.setVars,g                 ;; Now NP,BZ, and BY are set.

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[6]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Set one variable to be compared, leaving other variable
      settings intact. The newly added variable will be placed
      at the end of the ordering.

    KEYWORDS:
      All:  Set all variables as selected with keyword \all.

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      mco.setVar,'bz'       ;; Now NP,BX,BY and BZ are all set
      mco.setVar,/all

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[7]

[Previous Routine] [Next Routine] [List of Routines]

    Description:
      Set the color of lines to be plotted by DSC_MISSION_COMPARE::Plot

    KEYWORDS:
      HELP:	Print usage instructions

    CALLING SEQUENCE:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'],c1=120,c2='g')
      mco.setColor				; Set all lines to default colors
      mco.setColor,1  		; Set all mission1 lines to default color
      mco.setColor,2,'r'	; Set all mission2 lines red
      mco.setColor,1,250,'np'	; Set mission1 NP variable line to colortable valued 250

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[8]

[Previous Routine] [Next Routine] [List of Routines]

     DESCRIPTION
    	  Determine whether all selected variables are set
    	  to the same color within each mission.

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__DEFINE[9]

[Previous Routine] [Next Routine] [List of Routines]

     DESCRIPTION
    	  Clean duplicates from Order array

(See projects/dscovr/mission_compare/dsc_mission_compare__define.pro)

## DSC_MISSION_COMPARE__PLOT

[Previous Routine] [Next Routine] [List of Routines]

    dsc_mission_compare method: Plot

    Creates a plot to visualize the comparison described in the associated
    DSC_MISSION_COMPARE object.  Loads data as needed.

    Calling Sequence:
      mco = dsc_mission_compare(m1='wi',m2='d',vars=['np','bx','by'])
      mco.plot

    Inputs:
      (none)

    CREATED BY: Ayris Narock (ADNET/GSFC) 2018

     $LastChangedBy: nikos $
     $LastChangedDate: 2018-03-12 09:55:28 -0700 (Mon, 12 Mar 2018) $
     $LastChangedRevision: 24869 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/dscovr/mission_compare/dsc_mission_compare__plot.pro $

(See projects/dscovr/mission_compare/dsc_mission_compare__plot.pro)

## DSC_SHIFTLINE

[Previous Routine] [Next Routine] [List of Routines]

    NAME: DSC_SHIFTLINE

    DESCRIPTION:
    	Time shift one or more lines of a given TPLOT plot and display
    	shift amount on right side label.

    KEYWORDS: (Optional)
     DYINFO=:      Structure holding dsc_dyplot parameters, as returned in the OLD_DYINFO
                     keyword to that routine.  Use this to call dsc_dyplot with these parameters.
     DSCDY:        Set this to draw DSCOVR confidence intervals for relevant data in all panels.
                     dsc_dyplot options are based on tags in each variable's options structure.
                     i.e., it calls dsc_dyplot with no keywords.
                     Supercedes the DYINFO= keyword.
     NEWVARS=:     Returns the names of any new tplot variable names created during this call.
     PANEL=:       Scalar or Array of indices describing which panels will be targets for
                     time shifting. (1-indexed like TPLOT). Default is all panels. (Int)
     RESET:        Set this to return selected lines to initial, un-shifted, state.
     SHIFTSTRING=: A string representing the desired time shift, formatted to comply with the
                     'dsc_time_absolute' class:
                       Format: '#d#h#m#s#ms'
                       You may leave out unit id strings, but not repeat them:
                          OK     '3h2m'
                          NOT OK '3h45m13m'
                       Numbers must all be positive integers, with the execption of the leading negative.
                          OK     '3d4h23m16s400ms'
                          OK '-23h'
                          NOT OK '15h-4m'
                          NOT OK '15.4m'

                     If value passed in SHIFTSTRING is scalar, this shift will be used for all panels
                     affected by the DSC_SHIFTLINE call.  If value is an array, it must be the same size
                     as the number of panels in this call.  In that case, each shift corresponds to the
                     associated panel. (String)

                     For Example:

                       dsc_shiftline,varpattern='dsc',shiftstring='30m'
                       	-- will shift all DSCOVR lines forward by 30 minutes for all the panels.

                       dsc_shiftline,varpattern='dsc',shiftstring=['30m','-4h'],panel=[1,2]
                         -- will shift the DSCOVR line in the first panel 30 minutes forward
                            and the DSCOVR line in the second panel backward by 4 hours.

     TVINFO=:      Structure containing TPLOT variables information - as returned
                     from the 'new_tvar' keyword to tplot.
                     If not set uses that found in common 'tplot_vars'
     VARPATTERN=:  A regex pattern used to match the tplot variable name to shift.
                     If value is scalar, this pattern will be used for all panels affected by
                     this call.  If value is array, it must be the same size as the number of
                     panels in this call.  In that case, each pattern corresponds to the associated
                     panel. (String)

                     For Example: Given a multi-panel plot, each panel holding both DSCOVR and WIND data

                       dsc_shiftline,varpattern='dsc',shiftstring='30m'
                       	-- will shift all DSCOVR lines forward by 30 minutes for all the panels.

                       dsc_shiftline,varpattern=['dsc','wi'],shiftstring='30m',panel=[1,2]
                         -- will shift the DSCOVR line in the first panel and the WIND line in the second panel.

     VERBOSE=:     Integer indicating the desired verbosity level.  Defaults to !dsc.verbose

    CREATED BY: Ayris Narock (ADNET/GSFC) 2018

     $LastChangedBy: nikos $
     $LastChangedDate: 2018-03-12 09:55:28 -0700 (Mon, 12 Mar 2018) $
     $LastChangedRevision: 24869 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/dscovr/mission_compare/dsc_shiftline.pro $

(See projects/dscovr/mission_compare/dsc_shiftline.pro)

## DSC_TIME_ABSOLUTE__DEFINE[10]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      (Private Method)

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[11]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      (Private Method)

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[12]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      (Private Method)

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[13]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Return a structure of type {DSC_TIME_ABSOLUTE} that containins
      this object's values

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute('-15m36s300ms')
      IDL> mtall = mt.GetAll()
      IDL> print,mtall,/implied
      {
    			"IDL_OBJECT_TOP": 0,
    			"__OBJ__": <NullObject>,
    			"IDL_OBJECT_BOTTOM": 0,
    			"NEG": true,
    			"MS": 300,
    			"S": 36,
    			"M": 15,
    			"H": 0,
    			"D": 0
    		}

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[14]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Return this object's Milliseconds field (long)
      Note: Time is always stored in reduced form
    	   I.e., 5000 milliseconds is stored as 5 seconds

    	 Unit fields are always positive.  The sign of the DSC_TIME_ABSOLUTE object
    	 is stored in the NEG field.

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute('12h2m35ms')
      IDL> mt.getMilli()
      				35

      IDL> mt.set,'3m2s5050ms'
      IDL> mt.getMilli()
    					50

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[15]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Return this object's Seconds field (long)
      Note: Time is always stored in reduced form
    	   I.e., 75 seconds is stored at 1 minute, 15 seconds

    	 Unit fields are always positive.  The sign of the DSC_TIME_ABSOLUTE object
    	 is stored in the NEG field.

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute('12h2s35ms')
      IDL> mt.getSeconds()
      				2

      IDL> mt.set,'3m2s5050ms'
      IDL> mt.getMilli()
    					7

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[16]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Return this object's Minutes field (long)
      Note: Time is always stored in reduced form
    	   I.e., 90 minutes is stored as 1 hour, 30 minutes

    	 Unit fields are always positive.  The sign of the DSC_TIME_ABSOLUTE object
    	 is stored in the NEG field.

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute('3h90m')
      IDL> mt.getMinutes()
      				30

      IDL> mt.set,'30m200s'
      IDL> mt.getMinutes()
    					33

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[17]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Return this object's Hours field (long)
      Note: Time is always stored in reduced form
    	   I.e., 90 minutes is stored as 1 hour, 30 minutes

    	 Unit fields are always positive.  The sign of the DSC_TIME_ABSOLUTE object
    	 is stored in the NEG field.

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute('-3h90m')
      IDL> mt.getHours()
      				4

      IDL> mt.set,'66m'
      IDL> mt.getHours()
    					1

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[18]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Return this object's Days field (long)
      Note: Time is always stored in reduced form
    	   I.e., 25 hours is stored as 1 day, 1 hour

    	 Unit fields are always positive.  The sign of the DSC_TIME_ABSOLUTE object
    	 is stored in the NEG field.

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute('2d15h')
      IDL> mt.getDays()
      				2

      IDL> mt.set,'-30h'
      IDL> mt.getDays()
    					1

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[19]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns TRUE if time object is negative, FALSE otherwise (boolean)

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute('-30h')
      IDL> mt.IsNeg()
      true

      IDL> mt.set,'15s2h'
      IDL> mt.IsNeg()
      false

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     dsc_time_absolute__define

    PURPOSE:
     Defines an object to represent an absolute amount of time, not in reference
     to any date.  e.g., "10 minutes."  Used to enable time amount conversion and
     string representations.

     Designates all times as a combination of days(d), hours(h), minutes(m),
     seconds(s), and milliseconds(ms) and can be both positive and negative.
     The time representation is always kept in a reduced form.  So, for example,
     you can define a time of 1 hour and 65 minutes
       IDL> t1 = dsc_time_absolute('1h65m')
     In this case it will be stored as 2 hours and 5 minutes.
       IDL> print,t1
       02h 05m

    CALLING SEQUENCE:
     abstime = Obj_New("DSC_TIME_ABSOLUTE")
     abstime = Obj_New("DSC_TIME_ABSOLUTE",h=1,mn=30)
     abstime = Obj_New("DSC_TIME_ABSOLUTE",'1h30m')
     abstime = dsc_time_absolute()
     abstime = dsc_time_absolute(h=1,mn=30)
     abstime = dsc_time_absolute('1h30m')

    INPUT:
     TIMESTRING (Optional) If this argument is supplied, all other keywords are ignored.
                 A string representing the desired time amount in the format: '#d#h#m#s#ms'
                 with d,h,m,s,ms signifying respectively days,hours,minutes,seconds, and milliseconds.
                   You may leave out unit id strings, but not repeat them:
                      OK     '3h2m'
                      NOT OK '3h45m13m'
                   Numbers must all be positive integers, with the execption of the leading negative.
                      OK     '3d4h23m16s400ms'
                      OK '-23h'
                      NOT OK '15h-4m'
                      NOT OK '15.4m'

    KEYWORDS (Optional):
     NEG:    Set this to negate the total time value set by the other keywords
     D=:     Days
     H=:     Hours
     MN=:    Minutes
     S=:     Seconds
     MS=:    Milliseconds

    OUTPUT:
     dsc_time_absolute object reference

    METHODS:
     Set     - pass a timestring argument or keywords to set the class values
     SetAll	- pass a structure to set class values.
     Negate  - switch the sign of the time value stored
     Copy    - create a copy of this object
     Add     - add an amount of time (as specified in a timestring) to this object
     Sub     - subtranct an amount of time (as specified in a timestring) from this object
     GetAll  - returns a structure of type {dsc_time_absolute} containing this object's values
     GetMilli   - returns this object's millisecond field (long)
     GetSeconds - returns this object's seconds field (long)
     GetMinutes - returns this object's minutes field (long)
     GetHours   - returns this object's hours field (long)
     GetDays    - returns this object's days field (long)
     IsNeg      - returns TRUE if time object is negative, FALSE otherwise (boolean)
     ToString   - returns string representation of this time. Only non-zeroed fields are displayed (string)
     ToSeconds  - returns the total time value of this object, in seconds (double)
     ToMinutes  - returns the total time value of this object, in minutes (double)
     ToHours    - returns the total time value of this object, in hours (double)
     ToDays     - returns the total time value of this object, in days (double)
     StringParse - (Static Method) parse a timestring and return a structure holding the extracted elements
     Convert     - (Static Method) convert between units of time.
                     usage: dsc_time_absolute.convert(amount, input_unit, output_unit)
                       where input/output units are one of the following strings:
                       'd','h','m','s','ms'

    NOTES:
     +/- and print/implied print are overloaded for this class.
       e.g.,
         t1 = dsc_time_absolute('1h')
         t2 = dsc_time_absolute('55s')
         t3 = t1 + t2
         print,t3
           ==> 01h 55s
         t1
           ==> 01h

    CREATED BY: Ayris Narock (ADNET/GSFC) 2018

     $LastChangedBy: nikos $
     $LastChangedDate: 2018-03-12 09:55:28 -0700 (Mon, 12 Mar 2018) $
     $LastChangedRevision: 24869 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/dscovr/mission_compare/dsc_time_absolute__define.pro $

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[20]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the string representation of this time.
      Only non-zeroed fields are displayed (string)

      Use keyword /COMPACT to remove whitespace

    CALLING SEQUENCE:
      IDL> mt = dsc_time_absolute(d=3,h=42.5,s=10)
      IDL> mtstring = mt.ToString()
      IDL> print,mtstring
      04d 18h 30m 10s

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[21]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the total time value of this object, in seconds (double)

    CALLING SEQUENCE:
      IDL> mt.set,'1d1h1m1s1ms'
      IDL> mt.toSeconds()
            90061.001000000004
      IDL> mt.negate()
      IDL> mt.toSeconds()
           -90061.001000000004

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[22]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the total time value of this object, in minutes (double)

    CALLING SEQUENCE:
      IDL> mt.set,'1d1h1m1s1ms'
      IDL> mt.toMinutes()
            1501.0166833333333
      IDL> mt.negate()
      IDL> mt.toMinutes()
           -1501.0166833333333

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[23]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the total time value of this object, in hours (double)

    CALLING SEQUENCE:
      IDL> mt.set,'1d1h1m1s1ms'
      IDL> mt.toHours()
            25.016944722222224
      IDL> mt.negate()
      IDL> mt.toHours()
           -25.016944722222224

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[24]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Returns the total time value of this object, in days (double)

    CALLING SEQUENCE:
      IDL> mt.set,'1d1h1m1s1ms'
      IDL> mt.toDays()
            1.0423726967592593
      IDL> mt.negate()
      IDL> mt.toDays()
           -1.0423726967592593

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[25]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      (Private Method)

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[26]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      (Static Method)
      Convert between units of time.
    	 Usage:
        dsc_time_absolute.convert(amount, input_unit, output_unit)
          where input/output units are one of the following strings:
          'd','h','m','s','ms'

    CALLING SEQUENCE:
      IDL> dsc_time_absolute.convert(15, 'm', 's')
           900.00000000000000
      IDL> dsc_time_absolute.convert(368, 'm', 'h')
    				6.1333333333333329

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[2]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Set the class values by passing a timestring argument or keywords

      Timestring argument will supsercede other keywords.

      Called with no arguments sets the object to 0 time.

    SYNTAX:
      DSC_TIME_ABSOLUTE::Set,timestring,neg=neg,ms=ms,s=s,mn=m,h=h,d=d

    CALLING SEQUENCE:
      mt = dsc_time_absolute()
      mt.set,h=3,mn=32,ms=400    --> time is 3 hours 32 minutes and 0.400 seconds

      mt.set,d=3.5,/neg   --> time is negative 3 days,12 hours

      mt.set,'3h42s'    --> time is 3 hours and 42 seconds

      mt.set,'-3m'      --> time is negative 3 minutes

      mt.set    --> time is 0 seconds

      mt.set,'15h2m',d=2,h=4  --> sets time to 15 hours and 2 minutes NOT  2 days and 4 hours

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[2]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Set the class values by passing a structure.
      The fields MS, S, M, H, D, and NEG
        will be assigned if they exist
        or set to 0 if they are missing from the passed structure.

      NEG field must be a boolean.

    CALLING SEQUENCE:
      mt = dsc_time_absolute()
      mstruct = {neg:!TRUE, d:4, s:32}
      mt.SetAll,mstruct
        --> time is negative 4 days and 32 seconds

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[3]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Switch the sign of the time value stored

    CALLING SEQUENCE:
      mt = dsc_time_absolute('4h15m') --> time is 04h 15m
      mt.negate                   --> time is -04h 15m
      mt.negate                   --> time is 04h 15m

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[4]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Create a copy of this object

    CALLING SEQUENCE:
      mt = dsc_time_absolute(s=40,mn=12,/neg)
      mtcopy = mt.copy()

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[5]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Add an amount of time to this object by passing a
      time string.
      The overloaded '+' operator uses this method internally.

      Timestring rules:
        - A string composed of the concatenation of one or more substrings
          of the form substring = '{number}{unit_string}' where:
    	      * {number} is a positive integer
    	      * {unit_string} is one of  'd','h','m',s', or 'ms'
    	        [Representing days, hours, minutes, seconds, and milliseconds, respectively.]
    	  - The substrings can be combined in any order, with a limit of one
    	    substring per {unit_string} type.
    	  - A leading '-' is accepted to indicate a negative time amount.
    	  - A leading '+' is accepted (but not required) to indicate a positive time amount.

    	  Time is always stored in reduced form in the dsc_time_absolute object.
    	  I.e., 300 seconds will show as 5 minutes; 1 hour 90 minutes as 2 hours 30 minutes, etc.

    CALLING SEQUENCE:
      mt = dsc_time_absolute('3h20m')
      mt.add,'40m'
      --> time is now 4 hours

      Alternately, use the '+' operator:
      mt1 = dsc_time_absolute('3h20m')
      mt2 = dsc_time_absolute('40m')
      mt = mt1 + mt2

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[6]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      Subtract an amount of time from this object by passing a
      time string.
      The overloaded '-' operator uses this method internally.

      Timestring rules:
        - A string composed of the concatenation of one or more substrings
          of the form substring = '{number}{unit_string}' where:
    	      * {number} is a positive integer
    	      * {unit_string} is one of  'd','h','m',s', or 'ms'
    	        [Representing days, hours, minutes, seconds, and milliseconds, respectively.]
    	  - The substrings can be combined in any order, with a limit of one
    	    substring per {unit_string} type.
    	  - A leading '-' is accepted to indicate a negative time amount.
    	  - A leading '+' is accepted (but not required) to indicate a positive time amount.

    	  Time is always stored in reduced form in the dsc_time_absolute object.
    	  I.e., 300 seconds will show as 5 minutes; 1 hour 90 minutes as 2 hours 30 minutes, etc.

    CALLING SEQUENCE:
      mt = dsc_time_absolute('3h20m')
      mt.sub,'40m'
      --> time is now 2 hours 40 minutes

      Alternately, use the '-' operator:
      mt1 = dsc_time_absolute('3h20m')
      mt2 = dsc_time_absolute('40m')
      mt = mt1 - mt2

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[7]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      (Static Method)
      Parse a timestring and return a structure holding the extracted elements

    CALLING SEQUENCE:
      IDL> elements = dsc_time_absolute.StringParse('-1d12h15m')
      IDL> print,elements,/implied
      {
          "D": -1,
          "H": -12,
          "M": -15,
          "S": 0,
          "MS": 0
      }

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[8]

[Previous Routine] [Next Routine] [List of Routines]

    DESCRIPTION:
      (Private Method)

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)

## DSC_TIME_ABSOLUTE__DEFINE[9]

[Previous Routine] [List of Routines]

    DESCRIPTION:
      (Private Method)

(See projects/dscovr/mission_compare/dsc_time_absolute__define.pro)