Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 360) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 361) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.22 2004-04-01 08:52:29 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.23 2004-04-01 08:54:37 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -1006,5 +1006,5 @@ the list, pointed to by both \code{psDlist.head} and \code{psDlist.tail}. If the data entry is \code{NULL}, then an empty -list, with both pointers set to \code{NULL} should be created. +list, with both pointers are set to \code{NULL} should be created. An entry may be added to the list with the function: @@ -1016,6 +1016,6 @@ \code{psDlist} may have changed. The value of \code{where} specifies if the specified data item should be placed on the front of the list -(\code{PS_DLIST_HEAD}), at the end of the list (\code{PS_DLIST_TAIL}), -\tbd{use of other options?}. +(\code{PS_DLIST_HEAD}), or at the end of the list +(\code{PS_DLIST_TAIL}). A data item may be retrieved from the list with the function: @@ -1026,5 +1026,6 @@ of the special values: \code{PS_DLIST_HEAD}, \code{PS_DLIST_TAIL}, \code{PS_DLIST_PREV}, and \code{PS_DLIST_NEXT}, all of which are -defined as negative integers. +defined as negative integers, allowing \code{where} to also be the +index of one of the data items. A data item may be removed from the list with the function: @@ -1037,6 +1038,5 @@ \code{PS_DLIST_NEXT}, all of which are defined as negative integers. If the value of \code{which} is \code{PS_DLIST_UNKNOWN}, then the data -item is identified by matching the pointer value with \code{void -*data}. +item is identified by matching the pointer value with \code{void *data}. All data items placed onto lists (\code{psDlistAdd}) shall have their @@ -1112,6 +1112,6 @@ % where \code{nbucket} is the number of buckets defined for the hash -functions, and \code{buckets} are the individual buckets, each of -which is defined by: +functions, and \code{buckets} is an array of pointers to the +individual buckets, each of which is defined by: % \begin{verbatim} @@ -1124,13 +1124,12 @@ where each bucket contains the value of the \code{key}, a pointer to the \code{data}, and a pointer to the \code{next} list entry in the -bucket. +bucket (in the event that two or more keys have the same hash value). A hash table is created with the following function: \begin{verbatim} -psHash *psHashAlloc(int nbucket); +psHash *psHashAlloc(void); \end{verbatim} which allocates the space for the hash table and initializes all of -the buckets. \tbd{why specify nbucket? isn't it set by the hash -function?}. +the buckets. A data item may be added to the hash table with the function: @@ -1144,5 +1143,5 @@ same value of \code{key}. The routine \code{psHashInsert} must provide a non-NULL \code{itemFree} argument if it wishes to change the -value for previously inserted keys; if \code{itemFree} is NULL +value for previously inserted keys; if \code{itemFree} is NULL, attempting to insert a pre-existing key is an error, and the routine will return NULL. If \code{psHashInsert} succeeds it returns @@ -1159,5 +1158,6 @@ void *psHashRemove(psHash *table, char *key); \end{verbatim} -\tbd{what is return value?} +the return value of which is the value at the key that is removed (or +NULL if no match is found). A complete hash table may be freed by calling: @@ -1166,6 +1166,6 @@ \end{verbatim} where the function \code{itemFree} is provided to delete the -individual elements in the table. If it is NULL this is the -responsibility of the caller. +individual elements in the table. If it is NULL it is the +responsibility of the caller to free the elements. The function @@ -1173,6 +1173,6 @@ psDlist *psHashKeylist(psHast *table); \end{verbatim} -returns the complete list of defined keys associated with the psHash -table as a linked list. +returns the complete list of defined keys associated with the +\code{psHash} table as a linked list. \section{Data manipulation} @@ -1238,4 +1238,8 @@ \end{verbatim} +\code{psBitMaskSet} sets the specified \code{bit} in the +\code{psBitMask}, and returns the updated bitmask. The input bitmask +will be modified. + \begin{verbatim} /** Check a bit mask. Returns true or false */ @@ -1245,4 +1249,7 @@ ); \end{verbatim} + +\code{psBitMaskTest} returns a true value if the specified \code{bit} +is set; otherwise, it returns a false value. \begin{verbatim} @@ -1256,9 +1263,18 @@ \end{verbatim} +\code{psBitMaskOp} returns the \code{psBitMask} that is the result of +performing the specified \code{operator} (one of \code{"AND"}, +\code{"OR"}, or \code{"XOR"}) on \code{inMask1} and \code{inMask2}. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Sorting} -We require the ability to sort an array of floating-point values: +We require the ability to sort an array of floating-point values. The +following function returns the array, sorted from the smallest (i.e.\ +most negative) value in the first element, and the largest (i.e.\ most +positive) value in the last element. The input array, \code{myArray}, +may be sorted in-place if it is also specified as the \code{out} +array. \begin{verbatim} @@ -1270,8 +1286,9 @@ \end{verbatim} -We also require the ability to sort one array based on another. In -order to facilitate this, we will have a sort function return an array -containing the induces for the unsorted list in the order appropriate -for the sorted array: +We also require the ability to sort one array based on another. For +example, we may want to sort both \code{x} and \code{y} by the value +in \code{x}. In order to facilitate this, we will have a sort +function return an array containing the indices for the unsorted list +in the order appropriate for the sorted array: \begin{verbatim} @@ -1281,4 +1298,13 @@ const psFloatArray *restrict myArray ///< Array to sort ); +\end{verbatim} + +Then the sorted arrays may be accessed in the following manner: + +\begin{verbatim} +indexArray = psSortIndex(NULL, x); +for (int i = 0; i < indexArray.n; i++) { + doMyFunc(x[indexArray[i]], y[indexArray[i]]); +} \end{verbatim} @@ -1295,13 +1321,12 @@ \item Sample mean; \item Sample median; -\item Sample mode; \item Sample standard deviation; \item Sample upper and lower quartiles; -\item Robust mean, associated error and number of values used to calculate; -\item Robust median, associated error and number of values used to calculate; -\item Robust mode, associated error and number of values used to calculate; +\item Robust mean and number of values used to calculate; +\item Robust median and number of values used to calculate; +\item Robust mode and number of values used to calculate; \item Robust standard deviation; \item Robust upper and lower quartiles; -\item Clipped mean, associated error and number of values used to calculate; +\item Clipped mean and number of values used to calculate; \item Clipped standard deviation; and \item Minimum and maximum value in array. @@ -1325,4 +1350,9 @@ ); \end{verbatim} +% +This function takes the input data in \code{myArray} (with optional +masking in \code{maskArray}, so that the user may explicitly reject +specific entries) and a \code{psStats} structure, which will be +altered and returned. The \code{psStats} structure is defined with entries for each of the @@ -1332,40 +1362,78 @@ /** generic statistics structure */ typedef struct { - double sampleMean; ///< formal mean of sample - double sampleMedian; ///< formal median of sample - double sampleMode; ///< Formal mode of sample - double sampleStdev; ///< standard deviation of sample - double sampleUQ; ///< upper quartile of sample - double sampleLQ; ///< lower quartile of sample - double robustMean; ///< robust mean of array - double robustMeanError; ///< error on robust mean - int robustMeanNvalues; ///< number of measurements used for robust mean - double robustMedian; ///< robust median of array - double robustMedianError; ///< error on robust median - int robustMedianNvalues; ///< number of measurements used for robust median - double robustMode; ///< Robust mode of array - double robustModeErr; ///< Error in robust mode - int robustModeNvalues; ///< Number of measurements used for robust mode - double robustStdev; ///< robust standard deviation of array - double robustUQ; ///< robust upper quartile - double robustLQ; ///< robust lower quartile - double clippedMean; ///< Nsigma clipped mean - double clippedMeanError; ///< error on clipped mean - int clippedMeanNvalues; ///< number of data points used for clipped mean - double clippedStdev; ///< standard deviation after clipping - double clipSigma; ///< Nsigma used for clipping; user input - int clipIter; ///< Number of clipping iterations; user input - double min; ///< minimum data value in array - double max; ///< maximum data value in array - int nValues; ///< number of data values in array - psStatsOptions options; ///< bitmask of calculated values + double sampleMean; ///< formal mean of sample + double sampleMedian; ///< formal median of sample + double sampleStdev; ///< standard deviation of sample + double sampleUQ; ///< upper quartile of sample + double sampleLQ; ///< lower quartile of sample + double robustMean; ///< robust mean of array + int robustMeanNvalues; ///< number of measurements used for robust mean + double robustMedian; ///< robust median of array + int robustMedianNvalues; ///< number of measurements used for robust median + double robustMode; ///< Robust mode of array + int robustModeNvalues; ///< Number of measurements used for robust mode + double robustStdev; ///< robust standard deviation of array + double robustUQ; ///< robust upper quartile + double robustLQ; ///< robust lower quartile + double clippedMean; ///< Nsigma clipped mean + int clippedMeanNvalues; ///< number of data points used for clipped mean + double clippedStdev; ///< standard deviation after clipping + double clipSigma; ///< Nsigma used for clipping; user input + int clipIter; ///< Number of clipping iterations; user input + double min; ///< minimum data value in array + double max; ///< maximum data value in array + int nValues; ///< number of data values in array + psStatsOptions options; ///< bitmask of calculated values } psStats; \end{verbatim} +where \code{psStatsOptions} is defined with entries to turn on the +calculation of each of the statistics: + +\begin{verbatim} +/** statistics which may be calculated */ +typedef enum { + PS_STAT_SAMPLE_MEAN = 0x000001, + PS_STAT_SAMPLE_MEDIAN = 0x000002, + PS_STAT_SAMPLE_STDEV = 0x000004, + PS_STAT_SAMPLE_UQ = 0x000008, + PS_STAT_SAMPLE_LQ = 0x000010, + PS_STAT_ROBUST_MEAN = 0x000020, + PS_STAT_ROBUST_MEAN_NVALUES = 0x000040, + PS_STAT_ROBUST_MEDIAN = 0x000080, + PS_STAT_ROBUST_MEDIAN_NVALUES = 0x000100, + PS_STAT_ROBUST_MODE = 0x000200, + PS_STAT_ROBUST_MODE_NVALUES = 0x000400, + PS_STAT_ROBUST_STDEV = 0x000800, + PS_STAT_ROBUST_UQ = 0x001000, + PS_STAT_ROBUST_LQ = 0x002000, + PS_STAT_CLIPPED_MEAN = 0x004000, + PS_STAT_CLIPPED_MEAN_NVALUES = 0x008000, + PS_STAT_CLIPPED_MEAN_NSIGMA = 0x010000, + PS_STAT_CLIPPED_STDEV = 0x020000, + PS_STAT_MAX = 0x040000, + PS_STAT_MIN = 0x080000, + PS_STAT_NVALUES = 0x100000 +} psStatsOptions; +\end{verbatim} + +Associated constructors and destructors are also required: + +\begin{verbatim} +/** Constructor */ +psStats * +psStatsAlloc(psStatsOptions options ///< Statistics to measure + ); + +/** Destructor */ +void +psStatsFree(psStats *restrict stats ///< Stats structure to destroy + ); +\end{verbatim} + \subsubsection{Histograms} We also require to be able to generate histograms, given a list of -upper and lower bounds for each of the bins, and maximum and minimum -values. +upper and lower bounds for each of the bins. \begin{verbatim}