NASA-Planetary-Science/rss_ringoccs: rss_ringoccs v1.1

rss_ringoccs v1.1

rss_ringoccs is a suite of open-source Python-based analysis tools for Cassini Radio Science (RSS) ring occultations. It was developed by Team Cassini at Wellesley College (Sophia Flury, Jolene Fong, Ryan Maguire, and Glenn Steranka) under the direction of Richard French, Cassini RSS Team Leader, with funding provided by the NASA/JPL Cassini project.

Version 1.1 was officially released on February 1, 2019.

Introduction

The Cassini Radio Science Subsystem (RSS) was used during the Cassini orbital tour of Saturn to observe a superb series of ring occultations that resulted in high-resolution, high-SNR radial profiles of Saturn's rings at three radio wavelengths: 13 cm (S band), 3.6 cm (X band), and 0.9 cm (Ka band). Radial optical depth profiles of the rings at 1- and 10-km resolution produced by the Cassini RSS team, using state of the art signal processing techniques to remove diffraction effects, are available on NASA's Planetary Data System (PDS). These archived products are likely to be quite adequate for many ring scientists, but for those who wish to generate their own diffraction-reconstructed ring profiles from Cassini RSS observations, we offer rss_ringoccs: a suite of Python-based  analysis tools for Cassini Radio Science (RSS) ring occultations.
The purpose of rss_ringoccs is to enable scientists to produce "on demand" radial optical depth profiles of Saturn's rings from the raw RSS data, without requiring a deep familiarity with the complex processing steps involved in calibrating the data and correcting for the effects of diffraction. The code and algorithms are extensively documented, providing a starting point for users who wish to test, refine, or optimize the straightforward methods we have employed. Our emphasis has been on clarity, sometimes at the expense of programming efficiency and execution time. rss_ringoccs does an excellent job of reproducing existing 1km-resolution RSS processed ring occultation data already present on NASA's PDS Ring-Moons Node, but we make no claim to having achieved the state-of-the-art in every respect. We encourage users to augment our algorithms and to report on those improvements, so that they can be  incorporated in future editions of rss_ringoccs.

Installation and Documentation

Detailed installation instructions and full documentation are contained in github.com/NASA-Planetary-Science/rss_ringoccs/tree/master/docs/rss_ringoccs__User_Guide.pdf.

Release notes are contained in github.com/NASA-Planetary-Science/rss_ringoccs/blob/master/ReleaseNotes.md

Source code documentation is found at rss-ringoccs.readthedocs.io

Batch Data Processing

To simplify and expedite the use of rss_ringoccs, we provide a single python script which, when executed, will run the end-to-end pipeline for a list of files referenced in a reference ASCII text file. The default list is the 1 kHz Cassini RSR files prior to the USO failure, which can be found in the ./tables/ directory. This batch script implementation of the pipeline is located in the ./pipeline/ directory. We suggest running the batch script using the yes command as shown here:

cd rss_ringoccs_master/pipeline
yes | python e2e_batch.py | tee ../output/e2e_batch.py.out

How to (Get) Help

If you have trouble with installation or execution of the rss_ringoccs package, we encourage you to post a issue to https://github.com/NASA-Planetary-Science/rss_ringoccs/issues. We will attempt to respond promptly, and other users will benefit. Alternatively, you can email project leader Richard French at rfrench@wellesley.edu.

Changes from V1.0

1. Output file formats for GEO, CAL, DLP, and TAU files modified to be consistent with December 2018 PDS RSS archive submission.
2. Use 1 kHz RSR files by default, since they are now available on the PDS.
3. Modify power normalization and frequency offset components of calibration steps to reduce/eliminate need for GUIs.
4. Major speed-ups of many routines.
5. Include calculation of threshold optical depth.
6. Ability to produce summary plots of elevation vs time of the Cassini spacecraft from each DSN, for each occultation.
7. Ability to produce Earth views of each occultation.
8. Ability to produce summary PDF files for each occultation, in same format as PDF versions.
9. All output files now include full history of commands used to produce them.
10. Documentation at rss-ringoccs.readthedocs.io
    for most rss_ringoccs routines.
11. Describe validation tests in User Guide. (do we want to include source code to produce these as well? I like that idea...)
12. Provide sample scripts for end-to-end runs of representative occultations.
13. Provide additional details of steps in processing pipeline in User Guide.
    Resolved V1.0-1
14. Redefine our effective resolution to match Marouf's PDS results by scaling our nominal resolution by a factor of 1/0.75. This gives an excellent match to the PDS results, and makes our results consistent with his for any given user-requested resolution.
    Resolved V1.0-2
15. Eliminated GUI that produced this error.
    Resolved V1.0-3
16. Eliminated GUI that produced this error.

Known Issues and Limitations of V1.1

V1.1-1: For extreme geometry of Rev133E at X-band, rss_ringoccs gives slightly different results from PDS, traceable to a difference of about 10% in the cubic term of psi. Origin of this discrepancy unknown, but it is not important for any other occultation data sets we have reduced so far.

Lien list for V1.2

1. Extend support to RSR files with NaNs in header columns needed to predict sky frequency.
2. More extensive documentation to demonstrate the use of the software.
3. Data catalog query - we will work with the PDS to ensure that our recently-submitted RSS ring occultation observation data catalog is compliant with current PDS search capabilities.
4. Improve speed of slowest routines by using tested multiprocessor code.
5. Explore possibility of processing post-USO failure RSR files.
6. Explore feasibility, level of effort, and value of archiving scattered signal data.

Citing rss_ringoccs

If you use rss_ringoccs as the basis of a publication, please consider citing rss_ringoccs using the DOI provided here.

Licensing

Copyright © 2019  Team Cassini at Wellesley College
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://gnu.org/licenses.
This program is part of the rss_ringoccs repository hosted at https://github.com/NASA -Planetary -Science/rss_ringoccs and developed with the financial support of NASA’s Cassini Mission to Saturn.

Acknowledgements

This work was supported by the NASA/JPL Cassini mission. We are especially grateful to Linda Spilker and Kathryn Weld for their encouragement and support, and to RSS Team Member Essam Marouf for developing the diffraction reconstruction technique that underlies this work.