The toolkit includes routines for reading and manipulating PDS-formatted data files, including the filtering and resampling of data onto new sample grids. The routines keep track of the relationships between profiles, enabling the user to understand the statistical properties of derived data if the properties of the original data are known. The toolkit also includes routines for fitting curves to tabulated numbers, for the smooth interpolation of geometric or calibration quantities associated with a data file.
The toolkit is designed using the principles of object-oriented programming. The user freely creates objects by describing their properties and relationships, without worrying about the details of how they are implemented. This makes it possible to build extremely sophisticated tools very easily.
VERSION 1.1
First, the toolkit now includes a "Quick Mode" compile option that eliminates much internal checking and can speed up performance considerably. It is recommended that users always test their programs initially using Standard Mode, and only rebuild using Quick Mode after the software is fully debugged. Building instructions for both modes are found in Section 5 below.
Second, the toolkit now includes a function Pro_StatRange() that returns the range of samples in a statistical series that correlate with a given series. This enables some resampling operations to run much faster.
Third, the sample programs "ppsresam.for" and "ppsfilt.for" now print commas between the columns of the data files they generate, yielding files that are more compliant with PDS standards. Prior versions of these programs are still included for comparison.
Finally, Version 1.1 includes a modified version of routine "rprt_err.c", used by the PDS Object Access Library (OAL). This routine suppresses unnecessary warning messages and should be used as a replacement for the version distributed with OAL.
VERSION 1.2
It also provides a build script for Macintosh OS X, using GNU C and the Absoft FORTRAN compiler.
VERSION 1.3
It fixes a minor shortcoming of the example programs, in which the incidence angle was read from the wrong file.
It also includes a modified version of routine "struct_l.c", used by the PDS Object Access Library (OAL). This routine suppresses more unnecessary warning messages and should be used as a replacement for the version distributed with OAL.
| examples/ | A subdirectory containing sample programs and the data files needed to run them. Use these programs to confirm that the toolkit is working properly. |
| oalsrc/ | A subdirectory containing replacement source code for the PDS Object Access Library (OAL) 1.3. These files should replace those of the same name in the "source/" subdirectory of that toolkit. Note that the archived version of OAL 1.3, as found on PDS Ring-Moon Systems Node archive volumes, already contains these changes. |
| source/ | A subdirectory containing all the source files for Profile Library 1.3. |
| aareadme.txt | This file. |
| *.h | C header files needed for user-written programs that link with the Profile Library. Note that identical copies of these files are also found in the "source/" subdirectory. |
| *.inc | FORTRAN include files needed for user-written programs that link with the Profile Library. Note that identical copies of these files are also found in the "source/" subdirectory. |
| make*.com | Simple shell scripts for building the Profile Library on Sun/SGI, Macintosh OS X, Digital Unix, and VMS. |
|
profile.a profile.olb | After building the toolkit, this is the name of the object library (.a for Unix, .olb for VMS). |
|
qprofile.a qprofile.olb | After building the toolkit, this is the name of the "Quick Mode" version of the object library. See below for more information about Quick Mode. |
| profile.lbl | A PDS "combined-detached" label for all of the files in this directory (except this one), which has an attached label. |
The fundamental unit manipulated in the Profile Toolkit is an object. Each object has a class or type. The classes obey a hierarchy, in which each object class inherits the properties and behaviors of its superclass, while adding new properties of its own. The basic hierarchy of Profile object classes is as follows:
Object
___________|___________
| | |
Series Function Label
| |
Stat Curve
For C programmers, all the Profile Toolkit routines have names
beginning with "Pro_". Some more basic components of the Ring-Moon Systems Node
Library have names beginning with "RL_". For FORTRAN programmers, the
routine names are the same except that they have an "F" prepended. In
some circumstances, the numbers and types of the arguments differ
slightly between FORTRAN and C versions.
Defined in file object.c:
| (F)Pro_FreeObject | frees an object when it is no longer needed. |
| (F)Pro_PrintObject | prints a description of an object. |
| (F)Pro_ObjectName | returns the name of an object or coordinate. |
| (F)Pro_RenameObject | changes the name of an object or coordinate. |
| (F)Pro_ObjectDomain | returns the domain (X-limits) of an object. |
| (F)Pro_ObjectOverlap | determines the domain of overlap of multiple objects. |
In addition, all series objects have a sampling parameter. This is a floating-point number that varies linearly with the index, such as the time in seconds when a sample was acquired.
Defined in file series.c:
| (F)Pro_SeriesValue | returns the value of a sample given the index. |
| (F)Pro_SeriesIndices | returns the range of valid indices. |
| (F)Pro_SeriesSampling | returns the range and interval for the series' sampling parameter. |
| (F)Pro_SeriesIndex | converts from sampling parameter to index. |
| (F)Pro_SeriesXValue | converts from index to sampling parameter. |
| (F)Pro_WindowSeries | creates a new series that is identical to another except that it has a narrower range of valid indices. |
Defined in file array.c:
| (F)Pro_ArraySeries | creates a new series object that returns the sample values provided by the user in an array. |
| (F)Pro_ColumnSeries | creates a new series object using the values found in a column of a table or series in a PDS-labeled data file. |
Defined in file stat.c:
| (F)Pro_StatCovar | returns the covariance between two samples. |
| (F)Pro_StatRange | returns the range of samples that correlate with a given sample. |
Defined in file fixed.c:
| (F)Pro_FixedStat | creates a stat series in which the sample values match those of another series, while the covariances are just a function of the distance between samples. |
| (F)Pro_FilteredStat | creates a stat series in which each sample is a weighted sum of the nearby samples in another stat series. The set of coefficients is fixed. |
| (F)Pro_ResampledStat | creates a stat series which resamples another stat series onto a new sample grid. For example, the user can take data sampled uniformly in time and resample it uniformly in intercept radius on the ring plane. |
| (F)Pro_ResampledSize | returns the size of a buffer appropriate when resampling a buffered statistical series. |
| Pro_WeightedStat | creates a stat series in which each sample is a weighted sum of samples from another stat series. The user must provide a general routine that returns the set of coefficients on old series samples that go into each new sample. This routine has no FORTRAN equivalent. |
Defined in file function.c:
| (F)Pro_FuncValue | returns the value of y given x. |
| (F)Pro_WindowFunc | creates a new function that is identical to another except that it has a narrower domain. |
Defined in file lspline.c:
| (F)Pro_LSplineFunc | creates a function which interpolates linearly between the nearest samples of a series object. |
| (F)Pro_SoftFunc | creates a function object that returns the value of a C or FORTRAN function coded by the user. |
| (F)Pro_SoftFunc1 | creates a function object that performs a calculation on the result of another function. |
| (F)Pro_SoftFunc2 | creates a function object that performs a calculation on the results of two other functions. |
| (F)Pro_CompFunc | creates a function object that applies one function object to the result of another function object, i.e. y = f(g(x)) |
| (F)Pro_SlopeFunc | creates a function that returns the slope of a curve object. (See below). |
Curve objects are generally smooth and continuous. Because of this property, curves are invertible, meaning that a routine is provided to return the best value of x given y. For curve inversions, the user must also specify the segment of the curve to be inverted. Segments are numbered from one, starting at the lower endpoint of the domain and separated by extrema and inflection points in the file, up to the upper endpoint of the domain.
| (F)Pro_CurveValue | returns the y-value and, optionally, the slope at x. |
| (F)Pro_CurveInverse | returns the x-value within a specified segment such the f(x) equals, as closely as possible, the given value of y. |
| (F)Pro_CurveSegments | returns the number of curve segments within the domain. |
| (F)Pro_CurveExtremum | returns the location x and value y of the endpoint of an extremum. |
Defined in file spline.c:
| (F)Pro_SplineCurve | creates a curve that uses cubic splines to interpolate between samples tabulated in a series. |
| (F)Pro_InverseCurve | creates a curve that inverts the behavior of a curve by exchanging the x and y coordinates. |
A point spread function (abbreviated PSF) describes the sensitivity of an individual series sample to a theoretical, infinitesimal feature in the data, as a function of the distance between the sample's center point and the feature. Three PSFs are currently supported: boxcar, triangle and sinc.
A "boxcar" PSF has a constant value within a certain distance of the origin, but is zero outside that domain. If it has unit width, this means that a sample is uniformly sensitive to any point feature that falls less than half-way to either adjacent sample, but completely insensitive to features further away than that.
Defined in file boxcar.c:
| (F)Pro_BoxcarFunc | creates a boxcar PSF. |
| (F)Pro_BoxcarInfo | returns the parameters of a boxcar PSF. |
Defined in file triangle.c:
| (F)Pro_TriangleFunc | creates a triangle PSF. |
| (F)Pro_TriangleInfo | returns the parameters of a triangle PSF. |
Defined in file sinc.c:
| (F)Pro_SincFunc | creates a sinc PSF. |
| (F)Pro_SincInfo | returns the parameters of a sinc PSF. |
Defined in file psffilt.c:
| (F)Pro_PSFFilter | returns the best set of filter coefficients to convert from one PSF to another. |
Note that a label object does not make use of the coordinate name and domain properties of other Profile Toolkit objects such as series and functions.
Defined in file label.c:
| (F)Pro_OpenLabel | opens a PDS label or data file and constructs a label object. |
| (F)Pro_LabelCount | returns the number of TABLEs and SERIES in a label, the number of COLUMNs in a TABLE or SERIES, or the number of ITEMs in a COLUMN. |
| (F)Pro_LabelName | returns the name of a TABLE, SERIES or COLUMN. |
| (F)Pro_LabelXName | returns the sampling parameter name of a TABLE or SERIES. |
| (F)Pro_LabelFind | finds a TABLE, SERIES or COLUMN based on its name. |
| (F)Pro_LabelSampling | returns the sampling of a TABLE, SERIES or COLUMN. |
| (F)Pro_LabelInt | returns the integer value of a keyword from the PDS label. |
| (F)Pro_LabelFloat | returns the floating-point value of a keyword from the PDS label. |
| (F)Pro_LabelString | returns the string value of a keyword from the PDS label. |
| (F)RL_RaiseError | raises a particular error condition. |
| (F)RL_PipeErrors | redirects error messages to a file or the terminal. |
| (F)RL_TestError | tests the most recent error condition. |
| (F)RL_ClearError | clears the most recent error condition. |
| (F)RL_TestError1 | tests for a particular error condition. |
| (F)RL_ClearError1 | clears a particular error condition. |
| (F)RL_SetErrorType | defines what should happen when a particular error condition gets raised. |
| (F)RL_GetErrorType | returns information about what happens when a particular error condition gets raised. |
| PRO_CLASS_ERROR | if one attempts to apply an operation to an object of the wrong type. |
| PRO_COORD_MISMATCH | if coordinate names that should match do not. |
| PRO_DOMAIN_ERROR | if a number falls outside its allowed range. |
| PRO_EMPTY_DOMAIN | if the domain of an object is empty. |
| PRO_EVALUATION_FAILURE | if a quantity cannot be evaluated. |
| PRO_NOT_FOUND | if something cannot be found by name. |
| PRO_SETUP_FAILURE | if an object cannot be created. |
| RL_MEMORY_ERROR | if needed memory cannot be allocated. Note: it is very unwise to proceed after this error occurs; results will be unpredictable. |
| FORTRAN_POINTER_ERROR | if an object pointer in a FORTRAN program is not valid. |
| errors.c | Profile routines to construct standardized error messages. |
| fprofile.for | FORTRAN interfaces to Profile Toolkit routines that pass character strings as arguments. |
| rlmemory.c | RingLib routines to manage memory. |
| fortran.c | Ringlib routines to convert between FORTRAN integers and C pointers. |
| fortran.h | C header file for fortran.c. |
| ringlib.h | C header file for RingLib. |
| fringlib.for | FORTRAN interfaces to Ringlib routines that pass character strings as arguments. |
| fstrings.for | Ringlib routines to convert string representations between FORTRAN and C. |
File "filtout.tab" contains the output from a sample run of the program, using data files "ppsdata.lbl/.dat", "ppsgeom.lbl/.tab" and "ppscalib.lbl/.tab", also included. These are versions of the PDS-formatted files containing the data, geometry and calibration information from the Voyager PPS ring occultation experiment at Saturn, volume VG_2801. Consult the source code for an explanation of how to regenerate this file.
File "resamout.tab" contains the output from a sample run of the program, using data files "ppsdata.lbl/.dat", "ppsgeom.lbl/.tab" and "ppscalib.lbl/.tab", discussed above. Consult the source code for an explanation of how to regenerate this file.
Within the Profile Toolkit and the remainder of the Ring-Moon Systems Node Software Library, special data types are defined to "hide" some variations among implementations of C from one platform to the next. These special data types are as follows:
For FORTRAN programmers, the file "fprofile.inc" is provided. It declares the type of every function within the toolkit and also defines some useful parameters. All object pointers should be declared integer*4.
The difference is that when the library is compiled using "Quick" Mode, the code performs less self-checking so it runs faster; see Section 1.1 above. In general, user programs will not need to be modified to execute in Quick Mode; all the user will have to do is re-load the program with the "Quick" version of the Profile Library.
However, when building OAL, it is recommended that you replace the files "source/rprt_err.c" and "source/struct_l.c" with the versions found in the "oalsrc/" subdirectory accompanying this library. These revised versions suppress a large number of warnings and informational messages that interfere with the performance of the Profile Library.
NOTE: As a simpler alternative, the version of the OAL toolkit found on Ring-Moon Systems Node archive volumes already contains these changes in the "software/oal/source" subdirectory. Also, an included file "software/oal/aareadme.txt" contains a very streamlined description of how to build the toolkit.
For example, if the OAL is in a parallel directory called "oal/", then these commands will create the necessary links:
ln -s ../oal/source/oal.a oal.a
ln -s ../oal/source oal
This library has been tested on UNIX systems by DEC, Sun, and Silicon
Graphics and Macintosh OS X. To build the library and test binaries
on a Sun, type
chmod +x makesun.com
makesun.com
To build the library and binaries on a system by DEC or Silicon
Graphics, type
chmod +x makedec.com
makedec.com
To build the library and binaries on a Macintosh under OS X, type
chmod +x makemac.com
makemac.com
The script file "make*.com" will compile each file and build two
archive files called "profile.a" and "qprofile.a". (Note that any
pre-existent files called "profile.a" and "qprofile.a" should be
removed first). The sample program binaries are called "ppsfilt" and
"ppsresam" and are found in the "examples/" subdirectory.
Note that the commands "cc" and "f77" are used by these scripts. Be sure that your command search path includes these before executing the script.
To use the library, include either "profile.a" (for Standard Mode) or "qprofile.a" (for Quick Mode) among the files that appear on a cc or f77 command line. Also include "oal.a". Note that for C programs, you must also include the "-lm" option to load in the C math libraries.
For example, if the OAL is in a parallel directory called OAL.DIR, then this command will define the necessary symbol:
DEFINE OAL [-.OAL.SOURCE]
To build the library and executables on a Vax or Alpha using the VMS operating system, type
@MAKELIB
This will compile each file and build two object libraries called
PROFILE.OLB and QPROFILE.OLB. The sample program binaries are called
PPSFILT.EXE and PPSRESAM.EXE.
To use the library, specify PROFILE/LIBRARY (for Standard Mode) or QPROFILE/LIBRARY (for Quick Mode) among the files in a LINK command. You must also include OAL:OAL/LIBRARY. For programs written in FORTRAN, you must also include SYS$LIBRARY:VAXCRTL/LIBRARY because the C libraries are not linked in by default.