timetag-explorer 1.0.1__tar.gz

timetag_explorer-1.0.1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Sean Lockwood
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

timetag_explorer-1.0.1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: timetag-explorer
+Version: 1.0.1
+Summary: The science code behind TIME-TAG Explorer: HST/STIS FUV TIME-TAG processing, reference frames, planet maps and selection scripts
+Author: Sean Lockwood
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://explorer.planetarylightshow.com
+Project-URL: Documentation, https://timetag-explorer.readthedocs.io
+Project-URL: Source, https://github.com/sean-lockwood/timetag-explorer
+Project-URL: Issues, https://github.com/sean-lockwood/timetag-explorer/issues
+Project-URL: Changelog, https://github.com/sean-lockwood/timetag-explorer/blob/main/CHANGELOG.md
+Keywords: astronomy,HST,STIS,TIME-TAG,FUV,aurora
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: astropy>=7.0
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: astroquery>=0.4.10
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Dynamic: license-file
+
+# timetag-explorer
+
+[![Tests](https://github.com/sean-lockwood/timetag-explorer/actions/workflows/ci.yml/badge.svg)](https://github.com/sean-lockwood/timetag-explorer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/timetag-explorer)](https://pypi.org/project/timetag-explorer/)
+[![Documentation](https://app.readthedocs.org/projects/timetag-explorer/badge/?version=latest)](https://timetag-explorer.readthedocs.io)
+
+The science code behind [TIME-TAG Explorer](https://explorer.planetarylightshow.com), 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](https://github.com/sean-lockwood/timetag-explorer/blob/main/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
+
+```python
+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](https://www.planetarylightshow.com/static/data/combined_flat.fits);
+[how it was made](https://www.planetarylightshow.com/aurora_processing.html#Flat-Fielding)) 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 standalone Python script that reproduces a
+selection on the original TIME-TAG file and writes flag columns into a copy of it.
+
+## What is where
+
+| Module | Contents |
+|---|---|
+| `regions` | `Box`, `Circle`, `Polygon`: which detector pixels a region holds |
+| `frames` | the processing switches (`Corrections`), reference frames, header parsing (pointing, slew, WCS) |
+| `horizons` | planet and moon positions from JPL Horizons, and the local cache of them |
+| `planet` | Jupiter and Saturn orientation (IAU rotation model, light time) and the sky / surface / map projections |
+| `transforms` | detector pixels to frames and maps, exposure-time maps, the distortion lookup table |
+| `dataset` | `TagDataset`: events, slicing in time, binning, light curves, count-rate images |
+| `analysis` | areas, mean brightness and the exposure for a selection |
+| `selection_script` | the generator of selection scripts (and its version, `SELVER`) |
+| `gdcorr` | the geometric distortion polynomial (placeholder coefficients for now) |
+| `constants`, `config`, `log` | shared numbers; file locations; logging |
+
+## 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](https://github.com/sean-lockwood/timetag-explorer/blob/main/VALIDATION.md) for what each step is checked against.
+
+## Contributing
+
+Questions and concerns about the science are welcome as [issues](https://github.com/sean-lockwood/timetag-explorer/issues); proposed changes as pull requests.
+Please read [CONTRIBUTING.md](https://github.com/sean-lockwood/timetag-explorer/blob/main/CONTRIBUTING.md) first. Requests for access to the web app go to the address on the
+[app's front page](https://explorer.planetarylightshow.com/about), not here.
+
+## Citing
+
+Use the "Cite this repository" button on GitHub, or [CITATION.cff](https://github.com/sean-lockwood/timetag-explorer/blob/main/CITATION.cff). A DOI will be added once the first
+release is archived.
+
+## License
+
+BSD 3-Clause. See [LICENSE](https://github.com/sean-lockwood/timetag-explorer/blob/main/LICENSE).

timetag_explorer-1.0.1/README.md

@@ -0,0 +1,95 @@
+# timetag-explorer
+
+[![Tests](https://github.com/sean-lockwood/timetag-explorer/actions/workflows/ci.yml/badge.svg)](https://github.com/sean-lockwood/timetag-explorer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/timetag-explorer)](https://pypi.org/project/timetag-explorer/)
+[![Documentation](https://app.readthedocs.org/projects/timetag-explorer/badge/?version=latest)](https://timetag-explorer.readthedocs.io)
+
+The science code behind [TIME-TAG Explorer](https://explorer.planetarylightshow.com), 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](https://github.com/sean-lockwood/timetag-explorer/blob/main/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
+
+```python
+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](https://www.planetarylightshow.com/static/data/combined_flat.fits);
+[how it was made](https://www.planetarylightshow.com/aurora_processing.html#Flat-Fielding)) 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 standalone Python script that reproduces a
+selection on the original TIME-TAG file and writes flag columns into a copy of it.
+
+## What is where
+
+| Module | Contents |
+|---|---|
+| `regions` | `Box`, `Circle`, `Polygon`: which detector pixels a region holds |
+| `frames` | the processing switches (`Corrections`), reference frames, header parsing (pointing, slew, WCS) |
+| `horizons` | planet and moon positions from JPL Horizons, and the local cache of them |
+| `planet` | Jupiter and Saturn orientation (IAU rotation model, light time) and the sky / surface / map projections |
+| `transforms` | detector pixels to frames and maps, exposure-time maps, the distortion lookup table |
+| `dataset` | `TagDataset`: events, slicing in time, binning, light curves, count-rate images |
+| `analysis` | areas, mean brightness and the exposure for a selection |
+| `selection_script` | the generator of selection scripts (and its version, `SELVER`) |
+| `gdcorr` | the geometric distortion polynomial (placeholder coefficients for now) |
+| `constants`, `config`, `log` | shared numbers; file locations; logging |
+
+## 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](https://github.com/sean-lockwood/timetag-explorer/blob/main/VALIDATION.md) for what each step is checked against.
+
+## Contributing
+
+Questions and concerns about the science are welcome as [issues](https://github.com/sean-lockwood/timetag-explorer/issues); proposed changes as pull requests.
+Please read [CONTRIBUTING.md](https://github.com/sean-lockwood/timetag-explorer/blob/main/CONTRIBUTING.md) first. Requests for access to the web app go to the address on the
+[app's front page](https://explorer.planetarylightshow.com/about), not here.
+
+## Citing
+
+Use the "Cite this repository" button on GitHub, or [CITATION.cff](https://github.com/sean-lockwood/timetag-explorer/blob/main/CITATION.cff). A DOI will be added once the first
+release is archived.
+
+## License
+
+BSD 3-Clause. See [LICENSE](https://github.com/sean-lockwood/timetag-explorer/blob/main/LICENSE).

timetag_explorer-1.0.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "timetag-explorer"
+dynamic = ["version"]
+description = "The science code behind TIME-TAG Explorer: HST/STIS FUV TIME-TAG processing, reference frames, planet maps and selection scripts"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Sean Lockwood" }]
+keywords = ["astronomy", "HST", "STIS", "TIME-TAG", "FUV", "aurora"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = [
+    "numpy>=2.0",
+    "astropy>=7.0",
+    "matplotlib>=3.9",      # only for its point-in-polygon test
+    "astroquery>=0.4.10",   # JPL Horizons, for the planet frames and maps
+]
+
+[project.optional-dependencies]
+docs = ["sphinx>=7.2", "sphinx-rtd-theme>=2.0"]
+
+[project.urls]
+Homepage = "https://explorer.planetarylightshow.com"
+Documentation = "https://timetag-explorer.readthedocs.io"
+Source = "https://github.com/sean-lockwood/timetag-explorer"
+Issues = "https://github.com/sean-lockwood/timetag-explorer/issues"
+Changelog = "https://github.com/sean-lockwood/timetag-explorer/blob/main/CHANGELOG.md"
+
+[tool.setuptools.dynamic]
+version = { attr = "timetag_explorer.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["timetag_explorer*"]

timetag_explorer-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

timetag_explorer-1.0.1/tests/test_dataset.py

@@ -0,0 +1,55 @@
+"""TagDataset on small synthetic exposures: counts, rates, exposure, regions and the processing steps."""
+import support  # noqa: F401
+import numpy as np
+from support import OFF, dataset
+
+from timetag_explorer.constants import EDGE_TRIM_PIXELS, SPATIAL_BIN
+from timetag_explorer.frames import Corrections
+from timetag_explorer.regions import Box
+
+# 1000 events, 10 per second for 100 s, all in one pixel
+n = 1000
+t = np.linspace(0, 99.9, n)
+ds = dataset(t, np.full(n, 100), np.full(n, 100))
+assert ds.exposure() == 100.0 and abs(ds.tmax - 99.9) < 1e-3
+img = ds.image(None, 'image', OFF)
+assert abs(img.sum() - 10.0) < 1e-9, img.sum()                 # counts per second
+img10 = ds.image((0.0, 10.0), 'image', OFF)
+assert abs(img10.sum() - 10.0) < 1e-9                          # a time window gives the rate in that window
+edges, rate = ds.light_curve(10.0, None, 'image', OFF)
+assert np.allclose(rate, 10.0) and len(rate) == 10
+
+# a gap in the good-time intervals: its bins have no exposure (NaN) and the others are still right
+gap = dataset(t[(t < 40) | (t >= 60)], np.full(800, 100), np.full(800, 100), gti=((0, 40), (60, 100)))
+assert gap.exposure() == 80.0 and abs(gap.exposure(30, 70) - 20.0) < 1e-9
+_, r = gap.light_curve(10.0, None, 'image', OFF)
+assert np.isnan(r[4]) and np.isnan(r[5]) and np.allclose(r[[0, 1, 2, 3, 6, 7, 8, 9]], 10.0)
+
+# a region: counts inside it only
+x = np.where(np.arange(n) % 2 == 0, 100, 300)      # every other event in each of two places
+two = dataset(t, x, np.full(n, 100))
+inside = two.light_curve(10.0, Box(90, 110, 90, 110), 'image', OFF)[1]
+assert np.allclose(inside, 5.0)
+assert abs(two.image(None, 'image', OFF).sum() - 10.0) < 1e-9
+mask = two.region_mask(Box(90, 110, 90, 110), 'image', OFF)
+assert mask.sum() == 500 and mask.dtype == bool
+
+# flat-field weights multiply the counts
+weighted = dataset(t, np.full(n, 100), np.full(n, 100), weight=np.full(n, 2.0))
+assert abs(weighted.image(None, 'image', Corrections(randcorr=False, geocorr=False, flatcorr=True, timecorr=False)).sum() - 20.0) < 1e-6
+assert abs(weighted.image(None, 'image', OFF).sum() - 10.0) < 1e-9     # switched off: unweighted
+
+# the vignetted border is discarded only with the exposure-time correction
+edge = dataset(t, np.full(n, EDGE_TRIM_PIXELS - 20), np.full(n, 100))
+assert abs(edge.image(None, 'image', OFF).sum() - 10.0) < 1e-9
+assert edge.image(None, 'image', Corrections(randcorr=False, geocorr=False, flatcorr=False, timecorr=True)).sum() == 0.0
+
+# the random sub-pixel offset moves events by less than a pixel, keeps the total, and repeats exactly
+rand = Corrections(randcorr=True, geocorr=False, flatcorr=False, timecorr=False)
+a = dataset(t, np.full(n, 100), np.full(n, 100)).image(None, 'image', rand)
+b = dataset(t, np.full(n, 100), np.full(n, 100)).image(None, 'image', rand)
+assert np.array_equal(a, b) and abs(a.sum() - 10.0) < 1e-9 and a.shape[0] * SPATIAL_BIN <= 2048
+
+# a window outside the data
+assert ds.image((200.0, 300.0), 'image', OFF).sum() == 0.0
+print('dataset ok')

timetag_explorer-1.0.1/tests/test_frames.py

@@ -0,0 +1,28 @@
+"""Header parsing and the small rules around frames and light-curve bins."""
+import support  # noqa: F401
+
+from timetag_explorer.constants import DEFAULT_TIME_BIN, MAX_LIGHT_CURVE_BINS, MIN_TIME_BIN
+from timetag_explorer.frames import (FRAMES, FrameInfo, clamp_binsize, is_map, is_north, is_planet, names_from_levels,
+                                     parse_mt_levels)
+
+# Motion-tracking levels: parts of one level are joined in order
+header = {'MT_LV1_1': 'TYPE=STD,NAME=JUPI', 'MT_LV1_2': 'TER', 'MT_LV2_1': 'TYPE=POS_ANGLE,ANG=44.0,R_RAD=0.5',
+          'OTHER': 'x'}
+levels = parse_mt_levels(header)
+assert levels[0] == {'TYPE': 'STD', 'NAME': 'JUPITER'}
+assert levels[1] == {'TYPE': 'POS_ANGLE', 'ANG': '44.0', 'R_RAD': '0.5'}
+assert parse_mt_levels({}) == []
+assert isinstance(names_from_levels(levels), tuple)
+
+# Light-curve bins are always usable, whatever was typed
+assert clamp_binsize(3) == 3.0
+assert clamp_binsize('nan') == DEFAULT_TIME_BIN and clamp_binsize(None) == DEFAULT_TIME_BIN
+assert clamp_binsize(0) == MIN_TIME_BIN and clamp_binsize(-5) == MIN_TIME_BIN
+assert clamp_binsize(1e-9, tmax=1000.0) == 1000.0 / MAX_LIGHT_CURVE_BINS      # not billions of bins
+
+# Frame names
+assert is_map('map_rect') and not is_map('planet') and is_planet('planet_north') and is_north('rest_north')
+assert 'image' in FRAMES and all(isinstance(v, str) for v in FRAMES.values())
+info = FrameInfo(orientat=0.0, slew_angle=0.0, slew_rate=0.0)
+assert info.unavailable_reason('image') is None and info.unavailable_reason('map_rect') is not None
+print('frames ok')

timetag_explorer-1.0.1/tests/test_gdcorr.py

@@ -0,0 +1,26 @@
+"""The geometric-distortion polynomial, and the placeholder state of this release."""
+import support  # noqa: F401
+import numpy as np
+
+from timetag_explorer import gdcorr
+from timetag_explorer.frames import DEFAULT_CORRECTIONS, geocorr_available
+
+# The polynomial itself: each coefficient multiplies one monomial.
+x, y = 3.0, 5.0
+monomials = [y, x, y * y, x * y, x * x, y ** 3, y * y * x, y * x * x, x ** 3, y ** 4, y ** 3 * x, y * y * x * x,
+             y * x ** 3, x ** 4]
+for k, expected in enumerate(monomials):
+    c = [0.0] * 14
+    c[k] = 1.0
+    assert gdcorr.polyd4(x, y, c) == expected, k
+
+# Placeholder coefficients: nothing is corrected, and the Explorer knows it.
+assert gdcorr.PLACEHOLDER == (not (any(gdcorr.a) or any(gdcorr.b)))
+if gdcorr.PLACEHOLDER:
+    gx, gy = np.meshgrid(np.arange(0, 2048, 64, dtype=float), np.arange(0, 2048, 64, dtype=float))
+    xc, yc = gdcorr.gdcorr(gx, gy)
+    assert np.array_equal(xc, gx) and np.array_equal(yc, gy)
+    assert not geocorr_available() and not DEFAULT_CORRECTIONS.geocorr
+else:   # real coefficients: the switch is available and on by default
+    assert geocorr_available()
+print('gdcorr ok')

timetag_explorer-1.0.1/tests/test_package.py

@@ -0,0 +1,43 @@
+"""The package stays free of web-server code, and its version numbers agree."""
+import ast
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import support  # noqa: F401
+
+root = Path(__file__).resolve().parent.parent
+FORBIDDEN = {'nicegui', 'starlette', 'fastapi', 'uvicorn', 'httpx', 'authlib', 's3fs'}
+
+# 1. No module imports a web framework (or anything else the server alone needs).
+for path in sorted((root / 'timetag_explorer').glob('*.py')):
+    for node in ast.walk(ast.parse(path.read_text())):
+        names = [a.name for a in node.names] if isinstance(node, ast.Import) else (
+            [node.module or ''] if isinstance(node, ast.ImportFrom) and node.level == 0 else [])
+        for name in names:
+            assert name.split('.')[0] not in FORBIDDEN, f'{path.name} imports {name}'
+
+# 2. Importing the package does not pull in a web framework or pyplot, and nothing runs at import time.
+out = subprocess.run([sys.executable, '-c',
+                      'import sys, timetag_explorer\n'
+                      'bad = [m for m in sys.modules if m.split(".")[0] in %r or m == "matplotlib.pyplot"]\n'
+                      'print(",".join(bad))' % sorted(FORBIDDEN)],
+                     capture_output=True, text=True, cwd=root)
+assert out.returncode == 0, out.stderr
+assert out.stdout.strip() == '', out.stdout
+
+# 3. One version number, everywhere.
+import timetag_explorer  # noqa: E402
+
+version = timetag_explorer.__version__
+assert re.fullmatch(r'\d+\.\d+\.\d+', version), version
+cff = (root / 'CITATION.cff').read_text()
+assert re.search(rf'^version: "?{re.escape(version)}"?\s*$', cff, re.M), 'CITATION.cff version differs from __version__'
+assert f'## [{version}]' in (root / 'CHANGELOG.md').read_text(), 'CHANGELOG.md has no entry for this version'
+
+# 4. No private data in the package: no personal paths or addresses.
+for path in sorted((root / 'timetag_explorer').glob('*.py')):
+    text = path.read_text()
+    assert '/home/' not in text and '@gmail.com' not in text, path.name
+print('package ok')

timetag_explorer-1.0.1/tests/test_planet.py

@@ -0,0 +1,71 @@
+"""Planet geometry against answers that can be derived independently: round trips, areas of spheres and caps,
+the rotation rate, and the leap seconds."""
+import support  # noqa: F401
+import numpy as np
+
+from timetag_explorer.planet import (AU_KM, BODIES, LIGHT_TIME_PER_AU, map_bin_area, map_plane_coordinates,
+                                     map_plane_to_surface, limb_outline, planet_orientation, screen_to_surface,
+                                     spheroid_radii, surface_to_screen, tdb_minus_utc)
+
+jup = BODIES['JUPITER']
+assert (jup.radius_eq_km, jup.radius_pol_km) == (71492.0, 66854.0)          # IAU 2015 radii
+assert spheroid_radii(jup, 0.0) == (1.0, 66854.0 / 71492.0)
+
+# Leap seconds: TAI-UTC was 36 s until the end of 2016 and 37 s from 1 January 2017 (MJD 57754); TDB = TT + ~0.
+assert tdb_minus_utc(57753) == 36 + 32.184 and tdb_minus_utc(57754) == 37 + 32.184
+assert tdb_minus_utc(50082) == 29 + 32.184 or tdb_minus_utc(50082) == 30 + 32.184   # before the table: first entry
+
+# The sub-observer point is at the centre of the disc, looking straight at it.
+x, y, mu = surface_to_screen(100.0, 0.0, 0.0, 100.0, 1.0, 1.0)
+assert abs(x) < 1e-12 and abs(y) < 1e-12 and abs(mu - 1.0) < 1e-12
+# ... and the limb of a sphere seen from its equator is a circle of radius 1.
+lx, ly = limb_outline(0.0, 1.0, 1.0)
+assert np.allclose(np.hypot(lx, ly), 1.0)
+
+# Round trip, surface -> screen -> surface, over the visible hemisphere of an oblate planet seen from 3 N.
+a, b = spheroid_radii(jup, 400.0)
+rng = np.random.default_rng(0)
+lon = rng.uniform(0, 360, 2000)
+lat = rng.uniform(-85, 85, 2000)
+sx, sy, smu = surface_to_screen(lon, lat, 3.0, 120.0, a, b)
+vis = smu > 0.05
+lon2, lat2, mu2, on = screen_to_surface(sx[vis], sy[vis], 3.0, 120.0, a, b)
+assert on.all() and np.allclose(mu2, smu[vis], atol=1e-9)
+assert np.allclose(((lon2 - lon[vis] + 180) % 360) - 180, 0, atol=1e-7) and np.allclose(lat2, lat[vis], atol=1e-7)
+# a point outside the disc is not on the planet
+assert not screen_to_surface(np.array([2.0]), np.array([0.0]), 3.0, 120.0, a, b)[3][0]
+
+# Map planes: round trips, and the area of a whole sphere and of a polar cap.
+for frame in ('map_rect', 'map_north', 'map_south'):
+    lo = rng.uniform(0, 360, 200)
+    la = rng.uniform(45, 85, 200) * (-1 if frame == 'map_south' else 1) if frame != 'map_rect' else rng.uniform(-80, 80, 200)
+    u, v, ok = map_plane_coordinates(lo, la, frame, 180.0)
+    lo2, la2 = map_plane_to_surface(u, v, frame)
+    assert np.allclose(((lo2 - lo + 180) % 360) - 180, 0, atol=1e-7) and np.allclose(la2, la, atol=1e-7), frame
+R = 71492.0
+step = 0.5
+cu = np.arange(0, 360, step) + step / 2
+cv = np.arange(-90, 90, step) + step / 2
+gu, gv = np.meshgrid(cu, cv)
+area = map_bin_area(gu, gv, 'map_rect', step, R, R).sum()
+assert abs(area / (4 * np.pi * R ** 2) - 1) < 1e-4, area
+# north polar map out to 50 degrees of colatitude: a cap of area 2 pi R^2 (1 - cos 50 deg)
+step = 0.25
+c = np.arange(-50, 50, step) + step / 2
+gu, gv = np.meshgrid(c, c)
+inside = np.hypot(gu, gv) < 50.0
+area = map_bin_area(gu[inside], gv[inside], 'map_north', step, R, R).sum()
+cap = 2 * np.pi * R ** 2 * (1 - np.cos(np.radians(50.0)))
+assert abs(area / cap - 1) < 2e-3, (area, cap)
+
+# Orientation: Jupiter 4.5 AU away is 71492 km / 4.5 AU across, and System III turns 870.5366 deg per day.
+n = 5
+jd = 2460000.5 + np.arange(n) / 24.0
+positions = np.column_stack([jd, np.full(n, 150.0), np.full(n, 15.0), np.full(n, 4.5)])
+orient = planet_orientation(positions, jup, jd[0] - 2400000.5)
+assert np.allclose(orient.radius_arcsec, 71492.0 / (4.5 * AU_KM) * 206264.80624709636)
+rate = np.diff(orient.lon_obs) / np.diff(orient.t)                  # deg per second, west longitude
+assert np.allclose(np.abs(rate) * 86400, 870.5366420, rtol=1e-3), rate * 86400
+assert abs(LIGHT_TIME_PER_AU - 499.0048) < 1e-3
+assert np.all(np.abs(orient.lat_obs_c) < 90) and np.all(np.abs(orient.lat_obs_g) < 90)
+print('planet ok')

timetag_explorer-1.0.1/tests/test_regions.py

@@ -0,0 +1,38 @@
+"""Region shapes: which pixels they contain, and how they describe themselves."""
+import support  # noqa: F401
+import numpy as np
+
+from timetag_explorer.regions import Box, Circle, Polygon
+
+x, y = np.meshgrid(np.arange(0, 10, dtype=float), np.arange(0, 10, dtype=float))
+
+# Box: half-open, so adjacent boxes never count a pixel twice
+box = Box(2, 5, 3, 6)
+m = box.contains(x, y)
+assert m.sum() == 9 and m[3:6, 2:5].all()
+assert box.contains(np.array([2.0]), np.array([3.0]))[0] and not box.contains(np.array([5.0]), np.array([3.0]))[0]
+assert Box(2, 5, 3, 6).describe() == 'box x 2-5, y 3-6'
+
+# Circle: the boundary counts as inside
+c = Circle(5, 5, 2)
+assert c.contains(np.array([7.0]), np.array([5.0]))[0] and not c.contains(np.array([7.1]), np.array([5.0]))[0]
+assert abs(c.contains(x, y).sum() - np.pi * 4) <= 3          # a pixel grid approximates pi r^2
+assert Circle(5, 5, 2).describe().startswith('circle centre (5, 5), r = 2')
+
+# Polygon: a square given as vertices, and a triangle
+sq = Polygon(((1, 1), (4, 1), (4, 4), (1, 4)))
+inside = sq.contains(np.array([2.5, 0.5, 5.0]), np.array([2.5, 2.5, 2.5]))
+assert list(inside) == [True, False, False]
+tri = Polygon(((0, 0), (8, 0), (0, 8)))
+assert tri.contains(np.array([1.0]), np.array([1.0]))[0] and not tri.contains(np.array([7.0]), np.array([7.0]))[0]
+assert not Polygon(((0, 0), (1, 1))).contains(x, y).any()    # fewer than three vertices contain nothing
+assert 'free-form, 4 vertices' in sq.describe()
+
+# hashable (they are used in cache keys) and immutable
+assert len({Box(0, 1, 0, 1), Box(0, 1, 0, 1), Circle(0, 0, 1)}) == 2
+try:
+    box.x0 = 9
+    raise SystemExit('a Box must be immutable')
+except AttributeError:
+    pass
+print('regions ok')

timetag_explorer-1.0.1/tests/test_selection_script.py

@@ -0,0 +1,36 @@
+"""The selection-script generator: the script it writes is valid Python, carries its version, and says what it does.
+(Running the scripts on real data is done by validation/check_selection_scripts.py.)"""
+import support  # noqa: F401
+import numpy as np
+from support import OFF, dataset
+
+import timetag_explorer as tte
+from timetag_explorer.frames import Corrections
+from timetag_explorer.regions import Box, Circle, Polygon
+
+n = 200
+ds = dataset(np.linspace(0, 99, n), np.full(n, 600), np.full(n, 700))
+cases = [((10.0, 20.0), None, 'image', OFF),
+         (None, Box(500, 700, 600, 800), 'image', OFF),
+         ((10.0, 20.0), Circle(600, 700, 50), 'rest', Corrections(randcorr=True, geocorr=False, timecorr=True)),
+         (None, Polygon(((500, 500), (700, 500), (600, 700))), 'image', Corrections(randcorr=False, geocorr=True))]
+for time_sel, region, frame, corr in cases:
+    try:
+        s = tte.build_selection_script(ds, time_sel, region, frame, corr)
+    except ValueError as exc:       # a rest frame needs the SPT file's pointing information
+        assert frame != 'image', exc
+        continue
+    assert not s.warnings or frame != 'image', s.warnings
+    compile(s.code, s.filename, 'exec')                                  # valid Python
+    assert tte.SELECTION_SCRIPT_VERSION in s.code and 'SELVER' in s.code
+    assert s.filename.endswith('.py') and ds.rootname in s.filename
+    assert isinstance(s.packages, (list, tuple)) and s.notes
+    assert f"SCRIPT_VERSION = '{tte.SELECTION_SCRIPT_VERSION}'" in s.code
+    if time_sel is not None:
+        assert f'TIME_WINDOW = ({time_sel[0]}, {time_sel[1]})' in s.code
+    if isinstance(region, Box):
+        assert f'X0, X1 = {float(region.x0)}, {float(region.x1)}' in s.code
+    if region is not None:
+        assert region.describe() in s.code        # the region is written out in words, too
+assert tte.SELECTION_SCRIPT_VERSION == '1.0'
+print('selection script ok')

timetag_explorer-1.0.1/timetag_explorer/__init__.py

@@ -0,0 +1,21 @@
+"""TIME-TAG Explorer science code: the calculations behind the web app for HST/STIS FUV TIME-TAG data.
+
+This package has no web-server code. It reads a TIME-TAG (and SPT) file, applies the processing steps, transforms
+positions between reference frames and planet maps, and writes the standalone selection scripts.
+
+    from timetag_explorer import TagDataset, Corrections, Box
+"""
+from __future__ import annotations
+
+__version__ = '1.0.1'
+
+from .analysis import describe_selection
+from .constants import SELECTION_SCRIPT_VERSION
+from .dataset import TagDataset, load_dataset
+from .frames import DEFAULT_CORRECTIONS, FRAMES, Corrections, FrameInfo
+from .regions import Box, Circle, Polygon, Region
+from .selection_script import SelectionScript, build_selection_script
+
+__all__ = ['__version__', 'SELECTION_SCRIPT_VERSION', 'TagDataset', 'load_dataset', 'describe_selection',
+           'Corrections', 'DEFAULT_CORRECTIONS', 'FRAMES', 'FrameInfo', 'Box', 'Circle', 'Polygon', 'Region',
+           'SelectionScript', 'build_selection_script']