>Date: Thu, 25 Mar 2004 12:46:01 -0800 (PST)
>From: Shawn Brooks <sbrooks@sp18.jpl.nasa.gov>
>Reply-To: sbrooks@dcs04.jpl.nasa.gov
>To: Mitch Gordon <mgordon@mail.arc.nasa.gov>
>cc: Mark Showalter <mshowalter@mail.arc.nasa.gov>
>Subject: Voyager UVS Archive Peer Review
>
>	The Voyager UVS ring occultation data set is a rather extensive
>one, seeing as how it contains occultation data from three planetary
>encounters.  Furthermore, the differing characteristics of the three ring
>systems also complicates the archiving of these data into one volume.  
>Thus, it is a testament to the cleverness of the architecture of the PDS
>archiving system that these data can be archived into one consistent,
>sensible (albeit complex) volume.  The data contained within are well
>documented.  They appear at different stages from raw data to a
>fully-polished, edited data set.  The documentation that appears with the
>data look to be rather complete.  For example, the detail provided in the
>documentation of the derivation of the Saturn occultation calibration
>profile is very useful.  The determination of these background counts is
>clearly not a trivial matter and the description included in file
>/DOCUMENT/SPROFILE/SPROFILE.PDF yields insight into the preparation of the
>data.
>
>	Generally speaking, the data are carefully presented in a fashion
>that make them easy to examine once the background information to the
>volume has been fully digested by the user (and there is a lot of this!).  
>More specific comments follow.  They are generally organized by the archive
>directory to which the comments are pertinent.  They are preceded by some
>more general comments and followed by typographical errors I catalogued as
>I read through the documentation files.
>
>
>  General comments
>
>	The naming conventions strike me as somewhat awkward.  Is it
>necessary, for example, to begin each file in this archive with a 'U' for
>UVS?  Is this some PDS restriction?  Otherwise, this one extra character
>could be used to further specify the data files, seeing as how all of the
>data on this archive are UVS data and every file begins with a 'U'.  In a
>similar vein, I found the way in which the particular occultations are
>named to be a little awkward as well.  Seems that there should be a more
>descriptive way to differentiate occultations by two different stars other
>than something such as 'U1' versus 'U2', but I admittedly cannot think of
>one that also conforms to PDS restrictions.  This is perhaps a personal
>preference, however, and I do not strongly advocate any changes.

The PDS no longer restricts file names to 8.3, but that restriction was
in effect when we began this archive.  In the future, file names can be
much more descriptive. Nevertheless, even in the Cassini occultation
archives, the only information embedded into file names to distinguish
occultations will be dates.  For the case of Voyager 2 at Uranus, both
occultations were on the same day!

Working under the 8.3 restriction, the best we could do is number the
occultations.  We did this consistently across all three Voyager
occultation data sets---PPS, UVS and RSS.  Also, the U was chosen so
that file names would be unique across all three data sets; PPS files
begin with "P" and RSS files begin with "R". That was chosen because we
expected people to copy files off the CDs and work with them on their
own disk drives; we felt that a unique file name would be important
under those circumstances.

Because you present this as a reservation but not a show-stopper, and
because the effort involved in renaming all the files would be enormous,
I think we need to leave it unchanged.  However, we agree to use more
informative names in future data sets.

>	I would naively think that all of the programs that were used to
>manipulate the raw data should be located under the SOFTWARE directory.  
>I think they should be.  Could the program files located under the
>DOCUMENTS directory not be moved to the SOFTWARE directory?  It seems that
>there was some motivation to separate the supported software from the
>unsupported software, but I think that this distinction could be
>maintained with a specific subdirectory titled something like UNSUPPORTED
>within the SOFTWARE directory.

You infer correctly that, on this volume, the SOFTWARE directory only
contains software tools that we plan to support.

Our decision was based on the fact that the DOCUMENT directory contains
not just programs, but also descriptions of algorithms and intermediate
data files.  To us, it seemed to make more sense to keep all of the
associated files in one place.  As you realized, we did a lot of work
analyzing and re-formatting the data; it seemed important to include the
programs to serve as unambiguous documentation of what we did.

Instead of the reorganization as you propose, I have added further notes
in both the SOFTWARE and DOCUMENT directories to make it clear where to
find things and to explain why they are located at different places in the
directory tree.  See SOFTWARE/SOFTINFO.TXT and DOCUMENT/DOCINFO.TXT.

>	This is probably a minor point, but it was initially unclear to me
>that ring opacity is used interchangeably with optical depth.  For
>example, in the calibration description file CALIB/CALINFO.TXT, it is
>stated that
>
>  "With these parameters, it is possible to convert from UVS counts to
>  optical depth tau by inverting this equation:
>
>      counts = STELLAR_SIGNAL * exp(-tau/MU) + BACKGROUND_SIGNAL
>
>  Here MU is the cosine of the incidence angle, which can be found in
>  the label of the corresponding geometry file."
>
>All of the data file labels refer to MEDIAN_NORMAL_OPACITY.  This would
>probably not confuse anyone more familiar with ring occultation data, but
>it may be useful for a beginner to know.  An additional statement after
>the quote above to the effect of tau represents optical depth or ring
>opacity would have cleared this up for me.  Or, some mention of this in
>the .LBL files.  (I see some mention in the DOCUMENT/TUTORIAL.TXT beneath
>a discussion of the calibration files now, but an extra mention or two
>couldn't hurt, given the large number of files in this volume.)

You're right that we have been inconsistent about the use of "optical
depth" vs. "opacity", and that we use them interchangeably.  We have
started to prefer the word "opacity" because "optical depth" is a bit
of a misnomer in the context of radio occultations.  (I suppose the
correct term there would be "radio depth".)

I have done a global search and made the data set much more consistent
in its use of the word "opacity".  But where appropriate, I also note
that this is equivalent to optical depth.

>  DOCUMENT
>
>	This issue of descattering seems to be an important one.  Can
>anything be said about the extent to which this would affect the UVS
>spectra (i.e. the data that have not been co-added)?

I tried very hard to get a clearer description of descattering by the
UVS team members. The text I provided was as much as I could get from
them.

>	Likewise, the limit-cycle motion effects mentioned in the
>TUTOIRAL.TXT file seem important.  I could not find mention of it anywhere
>but in this file.  Should this information not be repeated?  A quick
>reference in the information files in the EDITDATA or NOISDATA
>directories, for instance, might be appropriate.

Good point. I have added more information about limit cycle motion and
its significance in the following files:
  DOCUMENT/SPROFILE/SPROFILE.*
  CALIB/CALINFO.TXT
  EASYDATA/DATAINFO.TXT

>  EASYDATA
>
>	The .LBL files all say that MEAN_SIGNAL field in the .TAB files is
>formatted F7.3.  However, they all appear to formatted F8.3!!!  All of the
>other fields are formatted in a fashion consistent with what appears in
>the .LBL files.

Wow.  You're the only one to catch this.  The labels are all fixed now.

>  IMAGES
>
>	I've always found that dealing with images in VICAR format can be
>difficult.  I have an IDL routine (it originated with Joel Plutchak at
>Brown University) that reads VICAR images into IDL format.  Otherwise, I
>would be routinely frustrated by them.  Would it not be possible to
>include the support images in some other format or include some software
>such as the routine that I described above?  Getting the VICAR software
>can be very difficult and, I think, might be nearly impossible for foreign
>users of this data set.  I suspect that reading images in VICAR format
>will be increasingly difficult decades from now.

I certainly agree with you about issues with the VICAR format.

I have added TIFF versions of all the files.  That should be easier for
most users to view. The labels are now combined-detached labels that
describe both the VICAR and TIFF formats of the files.

>  VECTORS
>
>	Could not characters 7 and/or 8 be used to identify those VECTOR
>files that were generated under the assumption that the ring system is
>extended and equatorial?  I think this would be useful for the user of
>these data.

I assume you are talking about the Uranian ring occultations, because
these are the only ones where the ring plane varies due to
inclinations. The standard we have used here and elsewhere in the data
set is to use the last two characters to identify a particular ring
occultation and direction. For the files generated under the
assumption that the rings are equatorial, we leave off these last to
characters. So UU1VC1DE.TAB describes the Delta ring egress, whereas
UU1VC1.TAB describes the whole ring system under the assumption that
it is equatorial. This convention is also consistent with what we do
for the other planets, where most file names are only six characters
long.

I would prefer to retain this consistency in our file naming. I have
made sure that the file VECTORS/DATAINFO.TXT makes this distinction
clear.

>	Mention is made of "small, systematic errors of order 0.01
>degrees" introduced by the rotation algorithm of routine J2000_VR.FOR.  
>It is not clear to me whether or not these errors are limited to this
>routine or whether or not such errors are manifest in the files generated
>by the routines J2000_VC.FOR and J2000_VE.FOR.  Can this be made clear?

The errors only occur for inclined Uranian rings in J2000 coordinates.
I have updated VECTORS/DATAINFO.TXT to make this point clear.

>TYPOGRAPHICAL ERRORS:
>
>
>DOCUMENT/TUTORIAL.TXT -
>
>    "The instrument intrinsically recorded integers counts, where a single
>    photon generated on average 2.5 counts.  See DOCUMENT/NOISE/NOISE.PDF
>    and NOISE.ASC for a the Rings Node's own estimate of UVS counts per
>    photon."
>
>  Should read
>
>    "The instrument intrinsically recorded integer counts, where a single
>    photon generated on average 2.5 counts. See DOCUMENT/NOISE/NOISE.PDF
>    and NOISE.ASC for the Rings Node's own estimate of UVS counts per
>    photon."

Fixed.  Thanks.

>--------------------------------------------------------------------------
>
>    "Because the signal in any give UVS spectrum is often rather small, it
>    is conventional to coadd the spectral samples down into a single value
>    per time step."
>
>  Should read
>
>    "Because the signal in any given UVS spectrum is often rather small, 
>    it is conventional to coadd the spectral samples down into a single
>    value per time step."

Fixed.

>--------------------------------------------------------------------------
>
>    "As discussed in our Saturn Profile analysis,
>    DOCUMENT/SPROFILE/SPROFILE.PDF and .ASC, the UVS team when to
>    extraordinary efforts to model out these variations."
>
>  Should read
>
>    "As discussed in our Saturn Profile analysis,
>    DOCUMENT/SPROFILE/SPROFILE.PDF and .ASC, the UVS team went to
>    extraordinary efforts to model out these variations."

Fixed.

>--------------------------------------------------------------------------
>
>    "In addition, all invalid or missing samples have been flagged,
>    meaning that they have been replaced a particular numeric value."
>
>  Should read
>
>    "In addition, all invalid or missing samples have been flagged,
>    meaning that they have been replaced by a particular numeric value."

Fixed.

>--------------------------------------------------------------------------
>
>    "PN1G02 describes a hypothetical ring system using the pole inferred
>    by Porco (1991) for the Adams Ring; this file is likely to more
>    accurate for the Adams Ring and maybe for other rings as well."
>
>  Should read
>
>    "PN1G02 describes a hypothetical ring system using the pole inferred
>    by Porco (1991) for the Adams Ring; this file is likely to be more
>    accurate for the Adams Ring and maybe for other rings as well."

Fixed.

>--------------------------------------------------------------------------
>
>
>EASYDATA/DATAINFO.TXT - 
>
>    "Note that, because the data from the beta Per occultation were
>    dominated by the Uranian charged particle background, no ring
>    profiles could be generated from the this occultation experiment."
>
>  Should read
>
>    "Note that, because the data from the beta Per occultation were
>    dominated by the Uranian charged particle background, no ring
>    profiles could be generated from this occultation experiment."

Fixed.

>--------------------------------------------------------------------------
>
>
>GEOMETRY/GEOMINFO.TXT - 
>
>    "Describes a hypothetical ring system using the pole inferred by Porco
>    (1991) for the Adams Ring. This file is likely to more accurate for 
>    the Adams Ring and maybe for other rings as well."
>
>  Should read
>
>    "Describes a hypothetical ring system using the pole inferred by Porco
>    (1991) for the Adams Ring. This file is likely to be more accurate for
>    the Adams Ring and maybe for other rings as well."

Fixed.

>--------------------------------------------------------------------------
>
>
>VECTORS/DATAINFO.TXT
>
>    "See DOCUMENT/POLES.TXT for a discussion of these rotation angle."
>
>  Should read
>
>    "See DOCUMENT/POLES.TXT for a discussion of these rotation angles."

Fixed.

>--------------------------------------------------------------------------
>
>    "Each vector file tabulates geometry parameters as a function of UVS
>    spectrum index; this same index can be used to identify the 
>    corresponding data record or sample in one of the EDTIDATA files."
>
>  Should read
>
>    "Each vector file tabulates geometry parameters as a function of UVS
>    spectrum index; this same index can be used to identify the
>    corresponding data record or sample in one of the EDITDATA files."

Fixed.