Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
wnsumd_c

Table of contents
Procedure
Abstract
Required_Reading
Keywords
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version
Index_Entries

Procedure

   wnsumd_c ( Summary of a double precision window ) 

   void wnsumd_c ( SpiceCell      * window,
                   SpiceDouble    * meas,
                   SpiceDouble    * avg,
                   SpiceDouble    * stddev,
                   SpiceInt       * idxsml,
                   SpiceInt       * idxlon   )

Abstract

   Summarize the contents of a double precision window.

Required_Reading

   WINDOWS

Keywords

   WINDOWS


Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   window     I   Window to be summarized.
   meas       O   Total measure of intervals in window.
   avg        O   Average measure.
   stddev     O   Standard deviation.
   idxsml,
   idxlon     O   Locations of shortest, longest intervals.

Detailed_Input

   window      is a window containing zero or more intervals.

               `window' must be declared as a double precision SpiceCell.

               CSPICE provides the following macro, which declares and
               initializes the cell

                  SPICEDOUBLE_CELL        ( window, WINDOWSZ );

               where WINDOWSZ is the maximum capacity of `window'.

Detailed_Output

   meas        is the total measure of the intervals in the input
               window. This is just the sum of the measures of the
               individual intervals.

   avg         is the average of the measures of the intervals in the
               input window.

   stddev      is the standard deviation of the measures of the
               intervals in the input window.

   idxsml,
   idxlon      are the locations of the shortest and longest intervals
               in the input window. The shortest interval is

                  [   SPICE_CELL_ELEM_D( window, idxsml   ),
                      SPICE_CELL_ELEM_D( window, idxsml+1 )   ]

               and the longest is

                  [   SPICE_CELL_ELEM_D( window, idxlon   ),
                      SPICE_CELL_ELEM_D( window, idxlon+1 )   ]

               `idxsml' and `idxlon' are both -1 if the input window
               contains no intervals.

               If `window' contains multiple intervals having the shortest
               length, `idxsml' is the index of the first such interval.
               Likewise for the longest length.

               Indices range from 0 to 2N-2, where N is the number of
               intervals in the window.

Parameters

   None.

Exceptions

   1)  If `window' has odd cardinality, the error
       SPICE(INVALIDCARDINALITY) is signaled by a routine in the call
       tree of this routine.

   2)  Left endpoints of stored intervals must be strictly greater
       than preceding right endpoints. Right endpoints must be
       greater than or equal to corresponding left endpoints.
       Invalid window data are not diagnosed by this routine and may
       lead to unpredictable results.

   3)  If the `window' cell argument has a type other than
       SpiceDouble, the error SPICE(TYPEMISMATCH) is signaled.

Files

   None.

Particulars

   This routine provides a summary of the input window, consisting
   of the following items:

   -  The measure of the window.

   -  The average and standard deviation of the measures
      of the individual intervals in the window.

   -  The indices of the left endpoints of the shortest
      and longest intervals in the window.

   All of these quantities are zero if the window contains no
   intervals.

Examples

   The numerical results shown for these examples may differ across
   platforms. The results depend on the SPICE kernels used as input,
   the compiler and supporting libraries, and the machine specific
   arithmetic implementation.

   1) Define a window with six intervals, and calculate the
      summary for that window.

      Example code begins here.


      /.
         Program wnsumd_ex1
      ./
      #include <stdio.h>
      #include "SpiceUsr.h"

      int main( )
      {
         /.
         Local parameters.
         ./
         #define WNSIZE           12

         /.
         Local variables.
         ./
         SpiceDouble              avg;
         SpiceDouble              left;
         SpiceDouble              meas;
         SpiceDouble              right;
         SpiceDouble              stddev;

         SPICEDOUBLE_CELL ( window, WNSIZE );

         SpiceInt                 idxlon;
         SpiceInt                 idxsml;
         SpiceInt                 intlon;
         SpiceInt                 intsml;

         /.
         Validate the window with size WNSIZE and zero elements.
         ./
         wnvald_c ( WNSIZE, 0, &window );

         /.
         Insert the intervals

            [ 1, 3 ] [ 7, 11 ] [ 18, 18 ] [ 23, 27 ] [ 30, 69 ] [ 72, 80 ]

         into `window'.
         ./
         wninsd_c (  1.0,   3.0, &window );
         wninsd_c (  7.0,  11.0, &window );
         wninsd_c ( 18.0,  18.0, &window );
         wninsd_c ( 23.0,  27.0, &window );
         wninsd_c ( 30.0,  69.0, &window );
         wninsd_c ( 72.0,  80.0, &window );

         /.
         Calculate the summary for `window'.
         ./
         wnsumd_c ( &window, &meas, &avg, &stddev, &idxsml, &idxlon );

         /.
         `idxsml' and `idxlon' refer to the indices of
         the SPICE Cell data array.
         ./
         intsml = idxsml/2;
         intlon = idxlon /2;

         printf( "Measure           : %f\n", meas   );
         printf( "Average           : %f\n", avg    );
         printf( "Standard Dev      : %f\n", stddev );
         printf( "Index shortest    : %d\n", idxsml );
         printf( "Index longest     : %d\n", idxlon );
         printf( "Interval shortest : %d\n", intsml );
         printf( "Interval longest  : %d\n", intlon );

         /.
         Output the shortest and longest intervals.
         ./
         wnfetd_c( &window, intsml, &left, &right );
         printf( "Shortest interval : [ %f, %f ]\n", left, right );
         wnfetd_c( &window, intlon, &left, &right );
         printf( "Longest interval  : [ %f, %f ]\n", left, right );

         return( 0 );
      }


      When this program was executed on a Mac/Intel/cc/64-bit
      platform, the output was:


      Measure           : 57.000000
      Average           : 9.500000
      Standard Dev      : 13.413302
      Index shortest    : 4
      Index longest     : 8
      Interval shortest : 2
      Interval longest  : 4
      Shortest interval : [ 18.000000, 18.000000 ]
      Longest interval  : [ 30.000000, 69.000000 ]


   2) Let A contain the intervals

         [ 1, 3 ]  [ 7, 11 ]  [ 23, 27 ]

      Let B contain the singleton intervals

         [ 2, 2 ]  [ 9, 9 ]  [ 27, 27 ]

      The measures of A and B are

         (3-1) + (11-7) + (27-23) = 10

      and

         (2-2) + (9-9) + (27-27) = 0

      respectively. Each window has three intervals; thus, the average
      measures of the windows are 10/3 and 0. The standard deviations
      are

           ------------------------------------------
          |       2         2          2
          |  (3-1)  + (11-7)  + (27-23)           2           1/2
          |  ---------------------------  - (10/3)     = (8/9)
          |             3
        \ |
         \|

      and 0. Neither window has one "shortest" interval or "longest"
      interval; so the first ones found are returned: `idxsml' and
      `idxlon' are 0 and 2 for A, 0 and 0 for B.

Restrictions

   None.

Literature_References

   None.

Author_and_Institution

   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)
   H.A. Neilan         (JPL)
   W.L. Taber          (JPL)
   I.M. Underwood      (JPL)
   E.D. Wright         (JPL)

Version

   -CSPICE Version 1.1.0, 05-AUG-2021 (JDR)

       Changed output argument names "shortest" and "longest" to
       "idxsml" and "idxlon" for consistency with other routines.

       Edited the header to comply with NAIF standard. Added complete code
       example.

       Extended description of argument "window" in -Detailed_Input to include
       type and preferred declaration method.

       Fixed error in documentation of arguments "idxsml" and "idxlon": if the
       input window contains no intervals, both are -1 and not zero.

       Added entries #1 and #2 in -Exceptions section.

   -CSPICE Version 1.0.1, 27-JAN-2009 (EDW)

       Corrected argument names shown in Brief I/O list.
       "short" to "shortest"; "long" to "longest".

   -CSPICE Version 1.0.0, 29-JUL-2002 (NJB) (HAN) (WLT) (IMU)

Index_Entries

   summary of a d.p. window
Fri Dec 31 18:41:15 2021