timetag-explorer

The science code behind TIME-TAG Explorer, a web app for exploring HST/STIS FUV TIME-TAG observations (aurorae on Jupiter and Saturn, and other targets that move or vary).

This repository holds only the calculations: reading a TIME-TAG file, the processing steps, the transformations between reference frames and planet maps, the exposure-time maps, and the generator of the standalone "selection scripts". The web server around it (sign-in, pages, plots and mouse selection) is a separate, private project, and this package knows nothing about it. Everything the app computes about the data comes from here, so this is the part that scientific review should look at.

Status: first release, not yet validated. VALIDATION.md lists each step with its reference and its review status. The geometric distortion correction is disabled in this release: gdcorr.py holds placeholder (zero) coefficients until values from a public reference file replace them.

Install

Python 3.11 or newer.

pip install timetag-explorer

To work on the code, clone the repository and pip install -e . in it. Documentation: https://timetag-explorer.readthedocs.io.

A first look

from timetag_explorer import load_dataset, Corrections, Box, describe_selection

ds = load_dataset('od8k57itq_tag.fits')       # a TIME-TAG file from MAST; its _spt.fits file, if next to it, is used too
corr = Corrections(randcorr=True, flatcorr=False, timecorr=True)   # which processing steps are on

edges, rate = ds.light_curve(3.0)                                    # count rate in 3 s bins
image = ds.image(time_sel=(100.0, 250.0), frame='image', corr=corr)     # counts/s per 4x4 hi-res-pixel bin
region = Box(900, 1100, 900, 1100)                                   # detector pixels
edges, region_rate = ds.light_curve(3.0, region=region, corr=corr)
print(describe_selection(ds, corr, 'image', (100.0, 250.0), region))

Rest frames and planet maps (frame='rest', 'planet', 'map_rect', ...) need the exposure's SPT file next to the TIME-TAG file; the planet ones also ask JPL Horizons for positions (through astroquery) and keep the answers in config.HORIZONS_DIR. The flat field is optional: put combined_flat.fits (download; how it was made) where config.FLAT_FILE points, or set the environment variables TAG_EXPLORER_FLAT and TAG_EXPLORER_HORIZONS.

build_selection_script(ds, time_sel, region, frame, corr) returns a short Python script that reproduces a selection on the original TIME-TAG file and writes a copy of it (<rootname>_tagsel.fits) with columns added: selection flags, the corrected positions (XCORR, YCORR) and positions in each reference frame, and the weights. The script calls timetag_explorer.tagsel.make_tagsel and names the exact package version to install (see CHANGELOG.md).

What is where

Tests and validation

pip install -e .
for t in tests/test_*.py; do python "$t"; done            # quick: synthetic data, no network
python validation/check_selection_scripts.py OFAP44G5Q    # slow: runs generated scripts on a real exposure (downloads it)

The first set runs on every pull request. The second runs every week on GitHub Actions. See VALIDATION.md for what each step is checked against.

Contributing

Questions and concerns about the science are welcome as issues; proposed changes as pull requests. Please read CONTRIBUTING.md first. Requests for access to the web app go to the address on the app's front page, not here.

AI disclosure

TIME-TAG Explorer, including this science code, was built with AI assistance: the code was written with Claude, Anthropic's AI model (mainly Claude Sonnet 5.5), under human direction. It was developed iteratively, deployed continuously, and checked against expected results at each step. Snippets of previously validated algorithms served as references for the scientific steps, such as the corrections and reference frame transformations. Features still under review, including the planet maps, planet registration, and script generation, are marked experimental. Script generation has not yet been tested by the author. Please check any result you plan to publish against your own analysis. Report problems as issues.

Citing

Use the "Cite this repository" button on GitHub, or CITATION.cff. A DOI will be added once the first release is archived.

License

BSD 3-Clause. See LICENSE.