proper-transient-finder 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. proper_transient_finder-0.3.1/.gitattributes +7 -0
  2. proper_transient_finder-0.3.1/.github/instructions/proper-transient-finder.instructions.md +12 -0
  3. proper_transient_finder-0.3.1/.github/workflows/proper-transient-finder.yml +86 -0
  4. proper_transient_finder-0.3.1/LICENSE +28 -0
  5. proper_transient_finder-0.3.1/MANIFEST.in +14 -0
  6. proper_transient_finder-0.3.1/PKG-INFO +478 -0
  7. proper_transient_finder-0.3.1/README.md +435 -0
  8. proper_transient_finder-0.3.1/USER_GUIDE.md +1729 -0
  9. proper_transient_finder-0.3.1/docs/API.md +325 -0
  10. proper_transient_finder-0.3.1/docs/publishing.md +124 -0
  11. proper_transient_finder-0.3.1/experiments/completeness.py +442 -0
  12. proper_transient_finder-0.3.1/experiments/robustness.py +672 -0
  13. proper_transient_finder-0.3.1/mkdocs.yml +66 -0
  14. proper_transient_finder-0.3.1/pyproject.toml +79 -0
  15. proper_transient_finder-0.3.1/run_proper_transient_finder.py +25 -0
  16. proper_transient_finder-0.3.1/scripts/bootstrap.ps1 +39 -0
  17. proper_transient_finder-0.3.1/scripts/build.ps1 +50 -0
  18. proper_transient_finder-0.3.1/scripts/docs.ps1 +47 -0
  19. proper_transient_finder-0.3.1/scripts/generate_docs.py +156 -0
  20. proper_transient_finder-0.3.1/scripts/lint.ps1 +39 -0
  21. proper_transient_finder-0.3.1/scripts/mkdocs_hooks.py +46 -0
  22. proper_transient_finder-0.3.1/scripts/tasks.sh +261 -0
  23. proper_transient_finder-0.3.1/scripts/test.ps1 +30 -0
  24. proper_transient_finder-0.3.1/scripts/verify_install.ps1 +114 -0
  25. proper_transient_finder-0.3.1/setup.cfg +4 -0
  26. proper_transient_finder-0.3.1/src/proper_transient_finder/__init__.py +51 -0
  27. proper_transient_finder-0.3.1/src/proper_transient_finder/__main__.py +8 -0
  28. proper_transient_finder-0.3.1/src/proper_transient_finder/_version.py +6 -0
  29. proper_transient_finder-0.3.1/src/proper_transient_finder/api.py +438 -0
  30. proper_transient_finder-0.3.1/src/proper_transient_finder/astro.py +2371 -0
  31. proper_transient_finder-0.3.1/src/proper_transient_finder/py.typed +1 -0
  32. proper_transient_finder-0.3.1/src/proper_transient_finder/survey.py +1168 -0
  33. proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/PKG-INFO +478 -0
  34. proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/SOURCES.txt +39 -0
  35. proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/dependency_links.txt +1 -0
  36. proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/entry_points.txt +2 -0
  37. proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/requires.txt +21 -0
  38. proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/top_level.txt +1 -0
  39. proper_transient_finder-0.3.1/tests/test_astro.py +3178 -0
  40. proper_transient_finder-0.3.1/tests/test_documentation.py +258 -0
  41. proper_transient_finder-0.3.1/tests/test_survey_hips.py +370 -0
@@ -0,0 +1,7 @@
1
+ * text=auto eol=crlf
2
+ *.py text eol=lf
3
+ *.sh text eol=lf
4
+ *.toml text eol=lf
5
+ *.md text eol=lf
6
+ *.yml text eol=lf
7
+ *.yaml text eol=lf
@@ -0,0 +1,12 @@
1
+ ---
2
+ description: "Use when modifying the Proper Transient Finder Python project, FITS pipeline, synthetic tests, packaging, scripts, or user guide."
3
+ name: "Proper Transient Finder Project"
4
+ applyTo: "**/*.py, scripts/**/*.ps1, scripts/**/*.sh, pyproject.toml, MANIFEST.in, USER_GUIDE.md"
5
+ ---
6
+ # Proper Transient Finder Project
7
+
8
+ - Treat this repository as a separately installable Python 3.11+ project; its package is `src/proper_transient_finder`.
9
+ - Keep astronomy production code in that package and focused synthetic regression tests in `tests`.
10
+ - Run `scripts/lint.ps1` and `scripts/test.ps1` for project changes.
11
+ - Follow the shared Python security requirements: validate FITS/CLI input, avoid unsafe subprocesses, and do not log private image data.
12
+ - Keep the user guide at `USER_GUIDE.md`.
@@ -0,0 +1,86 @@
1
+ name: Proper Transient Finder
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ env:
12
+ OMP_NUM_THREADS: "1"
13
+
14
+ jobs:
15
+ windows:
16
+ name: Windows / Python ${{ matrix.python-version }}
17
+ runs-on: windows-latest
18
+ timeout-minutes: 30
19
+ strategy:
20
+ fail-fast: false
21
+ matrix:
22
+ python-version: ["3.11", "3.12", "3.13"]
23
+ defaults:
24
+ run:
25
+ shell: pwsh
26
+ working-directory: .
27
+ steps:
28
+ - name: Check Out
29
+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
30
+ with:
31
+ persist-credentials: false
32
+ - name: Set Up Python
33
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
34
+ with:
35
+ python-version: ${{ matrix.python-version }}
36
+ - name: Install Development Environment
37
+ run: ./scripts/bootstrap.ps1 -PythonPath (Get-Command python).Source
38
+ - name: Install Documentation Tools
39
+ run: python -m pip install --editable ".[docs]"
40
+ - name: Check Lint And Formatting
41
+ run: ./scripts/lint.ps1 -PythonPath (Get-Command python).Source
42
+ - name: Run Astronomy Tests
43
+ run: ./scripts/test.ps1 -PythonPath (Get-Command python).Source
44
+ - name: Check And Build Documentation
45
+ if: matrix.python-version == '3.13'
46
+ run: ./scripts/docs.ps1 -PythonPath (Get-Command python).Source -Check -Build
47
+ - name: Build Wheel And Source Archive
48
+ if: matrix.python-version == '3.13'
49
+ run: ./scripts/build.ps1 -PythonPath (Get-Command python).Source -NoIsolation
50
+
51
+ posix:
52
+ name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
53
+ runs-on: ${{ matrix.os }}
54
+ timeout-minutes: 30
55
+ strategy:
56
+ fail-fast: false
57
+ matrix:
58
+ os: [ubuntu-latest, macos-latest]
59
+ python-version: ["3.11", "3.12", "3.13"]
60
+ defaults:
61
+ run:
62
+ shell: bash
63
+ working-directory: .
64
+ steps:
65
+ - name: Check Out
66
+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
67
+ with:
68
+ persist-credentials: false
69
+ - name: Set Up Python
70
+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
71
+ with:
72
+ python-version: ${{ matrix.python-version }}
73
+ - name: Install Development Environment
74
+ run: PYTHON=python bash scripts/tasks.sh bootstrap
75
+ - name: Install Documentation Tools
76
+ run: python -m pip install --editable ".[docs]"
77
+ - name: Check Lint And Formatting
78
+ run: PYTHON=python bash scripts/tasks.sh lint
79
+ - name: Run Astronomy Tests
80
+ run: PYTHON=python bash scripts/tasks.sh test
81
+ - name: Check And Build Documentation
82
+ if: matrix.python-version == '3.13'
83
+ run: PYTHON=python bash scripts/tasks.sh docs --check --build
84
+ - name: Build Wheel And Source Archive
85
+ if: matrix.python-version == '3.13'
86
+ run: PYTHON=python bash scripts/tasks.sh build --no-isolation
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Pier-Francesco Rocci
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,14 @@
1
+ include pyproject.toml README.md USER_GUIDE.md LICENSE run_proper_transient_finder.py mkdocs.yml
2
+ include .gitattributes .github/workflows/proper-transient-finder.yml
3
+ include .github/instructions/proper-transient-finder.instructions.md
4
+ recursive-include src *.py py.typed
5
+ recursive-include tests *.py
6
+ recursive-include experiments *.py
7
+ recursive-include scripts *.ps1 *.sh *.py
8
+ recursive-include docs *.md
9
+ prune artifacts
10
+ prune build
11
+ prune dist
12
+ prune site
13
+ prune .venv
14
+ global-exclude *.py[cod]
@@ -0,0 +1,478 @@
1
+ Metadata-Version: 2.4
2
+ Name: proper-transient-finder
3
+ Version: 0.3.1
4
+ Summary: PSF-matched FITS difference imaging and transient candidate analysis.
5
+ Author: Pier-Francesco Rocci
6
+ License-Expression: BSD-3-Clause
7
+ Project-URL: Homepage, https://github.com/pierfra-rocci/proper_transient_finder
8
+ Project-URL: Repository, https://github.com/pierfra-rocci/proper_transient_finder
9
+ Project-URL: Issues, https://github.com/pierfra-rocci/proper_transient_finder/issues
10
+ Project-URL: Documentation, https://pierfra-rocci.github.io/proper_transient_finder/
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Scientific/Engineering :: Astronomy
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: properimage==0.7.2
24
+ Requires-Dist: astropy<9,>=8.0
25
+ Requires-Dist: numpy<3,>=2.0
26
+ Requires-Dist: scipy<2,>=1.15
27
+ Requires-Dist: pandas<4,>=2.2
28
+ Requires-Dist: matplotlib<4,>=3.9
29
+ Requires-Dist: sep<2,>=1.4
30
+ Requires-Dist: astroscrappy<2,>=1.3
31
+ Requires-Dist: astroalign<3,>=2.6
32
+ Requires-Dist: reproject<1,>=0.18
33
+ Provides-Extra: docs
34
+ Requires-Dist: mkdocs<2,>=1.6.1; extra == "docs"
35
+ Requires-Dist: mkdocs-material<10,>=9.7; extra == "docs"
36
+ Provides-Extra: dev
37
+ Requires-Dist: build<2,>=1.2; extra == "dev"
38
+ Requires-Dist: setuptools<81,>=77; extra == "dev"
39
+ Requires-Dist: wheel; extra == "dev"
40
+ Requires-Dist: pytest>=8.0; extra == "dev"
41
+ Requires-Dist: ruff>=0.8; extra == "dev"
42
+ Dynamic: license-file
43
+
44
+ # Proper Transient Finder
45
+
46
+ **Compare two images of the sky to spot what changed.**
47
+
48
+ Python library for PSF-matched FITS difference imaging and unconfirmed
49
+ transient-candidate analysis. Python 3.11 or newer is required.
50
+
51
+ The distribution is named `proper-transient-finder`; import it as
52
+ `proper_transient_finder`.
53
+
54
+ Current release: `0.3.1`.
55
+
56
+ Inputs can use `.fits`, `.fit`, `.fts`, gzip compression (`.fits.gz`, `.fit.gz`,
57
+ `.fts.gz`) or FITS tiled compression (`.fits.fz`, `.fit.fz`, `.fts.fz`). No manual
58
+ decompression is required; files must retain their original binary contents.
59
+
60
+ ## Installation
61
+
62
+ Install a built wheel into your chosen Python environment:
63
+
64
+ ```powershell
65
+ python -m pip install ./dist/proper_transient_finder-0.3.1-py3-none-any.whl
66
+ python -m pip check
67
+ ```
68
+
69
+ From a source distribution or checkout, `python -m pip install .` also
70
+ installs the package and its declared scientific dependencies. Build tools
71
+ and test tools are optional: `python -m pip install ".[dev]"`.
72
+
73
+ ProperImage 0.7.2 depends on legacy `tinynpydb`. If no compatible cached wheel
74
+ is available and its source build fails, install the following prerequisites
75
+ using your approved package source before installing this library:
76
+
77
+ ```powershell
78
+ python -m pip install "setuptools>=77,<81" wheel
79
+ python -m pip install --no-build-isolation tinynpydb==0.1.2
80
+ ```
81
+
82
+ No package-index, certificate, or execution-policy bypass is required.
83
+ See [USER_GUIDE.md](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/USER_GUIDE.md) for FITS requirements, installation details,
84
+ offline installation, and scientific limitations.
85
+
86
+ ## Python API
87
+
88
+ ```python
89
+ from proper_transient_finder import PipelineConfig, compare_images
90
+
91
+ config = PipelineConfig(plots=False)
92
+ result = compare_images("reference.fits", "science.fits", config=config)
93
+
94
+ print(result.candidates)
95
+ print(result.rejected_candidates)
96
+ print(result.metadata["quality_summary"])
97
+ difference, score, mask = result.difference, result.score, result.mask
98
+ ```
99
+
100
+ No products are written unless you provide `output_dir`:
101
+
102
+ ```python
103
+ result = compare_images(
104
+ "reference.fits", "science.fits", output_dir="results/run_001", config=config
105
+ )
106
+ print(result.output_dir)
107
+ ```
108
+
109
+ `PipelineResult` includes accepted/rejected catalogs, background diagnostics,
110
+ the signed difference, calibrated score, effective PSF, exclusion mask, backend
111
+ products, and provenance. Arrays and tables remain editable. `PipelineConfig`
112
+ is copied and revalidated; dictionaries remain supported. Library calls raise
113
+ ordinary Python exceptions rather than exiting the interpreter.
114
+
115
+ For input-only checks or manual stage control, use `ProperTransientFinder`:
116
+
117
+ ```python
118
+ from proper_transient_finder import ProperTransientFinder
119
+
120
+ pipeline = ProperTransientFinder("reference.fits", "science.fits", "results/run_002", config)
121
+ report = pipeline.preflight()
122
+ ```
123
+
124
+ Preflight does not certify registration, PSF seeing, photometric consistency,
125
+ or detectability. Cross-filter comparison remains explicitly experimental:
126
+ set `PipelineConfig(cross_filter=True)` or use the existing
127
+ `compare_cross_filter()` helper, which still returns a DataFrame and saves
128
+ products. A global stellar scale does not correct color differences.
129
+
130
+ ## Command Line
131
+
132
+ ```powershell
133
+ proper-transient-finder --ref reference.fits --new science.fits --output results/run_003
134
+ python -m proper_transient_finder --help
135
+ ```
136
+
137
+ Both entry points use the same validated pipeline as the Python API.
138
+ Scores and artifact cuts do not establish astrophysical origin. Review
139
+ candidates and independent observations before claiming variability.
140
+
141
+ ## Batch Processing
142
+
143
+ Run multiple pairs sequentially, including a shared reference:
144
+
145
+ ```python
146
+ from proper_transient_finder import BatchJob, PipelineConfig, compare_batch
147
+
148
+ report = compare_batch(
149
+ [
150
+ BatchJob("epoch_1", "reference.fits", "science_1.fits"),
151
+ BatchJob("epoch_2", "reference.fits", "science_2.fits"),
152
+ ],
153
+ output_dir="results/batch_001",
154
+ config=PipelineConfig(plots=False),
155
+ )
156
+ for item in report.items:
157
+ print(item.name, item.state, item.accepted_candidates, item.error)
158
+ print(report.successful)
159
+ ```
160
+
161
+ Each pair gets a separate output folder and normal logs/products. An atomic
162
+ `batch_summary.json` tracks progress and failures. Failed pairs do not stop
163
+ later pairs unless `fail_fast=True`. The batch root must be new or empty, or
164
+ is cleared first when `overwrite=True`/`--overwrite` is given; without the flag
165
+ an interactive terminal is asked to confirm the replacement, and `--yes` answers
166
+ that prompt. Persisted batches retain lightweight reports;
167
+ without `output_dir`, they write nothing and retain full results in
168
+ `item.result`. Use `retain_results` to override that memory policy.
169
+
170
+ For the CLI, a JSON manifest such as `pairs.json` contains:
171
+
172
+ ```json
173
+ [
174
+ {"name": "epoch_1", "ref": "reference.fits", "new": "science_1.fits"},
175
+ {"name": "epoch_2", "ref": "reference.fits", "new": "science_2.fits"}
176
+ ]
177
+ ```
178
+
179
+ ```powershell
180
+ proper-transient-finder --batch pairs.json --output results/batch_check --check-only
181
+ proper-transient-finder --batch pairs.json --output results/batch_002 --no-plots
182
+ ```
183
+
184
+ Manifest paths are relative to the manifest, not the current directory.
185
+ Shared CLI settings can be overridden by each job's `config` object and
186
+ `threshold_sigma`. Add `--fail-fast` to stop on the first failure. The CLI
187
+ returns 1 if any job fails; successful preflight does not certify subtraction
188
+ or transient detectability. Execution is sequential, with no automatic resume
189
+ or parallel workers. See [the full batch guide](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/USER_GUIDE.md#batch-processing)
190
+ for schema, naming, configuration, and retry details.
191
+
192
+ ## Survey References
193
+
194
+ Opt in to downloading a HiPS survey reference for a science FITS image with
195
+ valid celestial WCS. The library asks the CDS `hips2fits` service for exactly
196
+ the science WCS and shape, so the complete footprint arrives as one cutout on
197
+ the science pixel grid. No local tiling or mosaic is built, and the comparison
198
+ pipeline runs without a second reprojection. Choose the template filter
199
+ explicitly:
200
+
201
+ ```powershell
202
+ proper-transient-finder --survey auto --new science.fits --template-filter r --check-only
203
+ proper-transient-finder --survey auto --new science.fits --template-filter r --template-units adu --output results/survey_001
204
+ proper-transient-finder --survey auto --science-list science.txt --template-filter r --template-units adu --output results/survey_batch
205
+ ```
206
+
207
+ `--survey` accepts `auto`, `panstarrs`, `skymapper`, or an explicit HiPS
208
+ identifier such as `PanSTARRS/DR1/i`. Pan-STARRS uses dec >= -30 and supports
209
+ `g r i z y`; SkyMapper DR4 uses dec <= 0 and publishes `g r i` HiPS maps. `auto`
210
+ prefers Pan-STARRS where both are eligible. It never switches provider or
211
+ filter after a failed request.
212
+
213
+ Other CDS HiPS maps can be selected by identifier with one explicit band label:
214
+
215
+ | Template | HiPS identifier | Notes |
216
+ | --- | --- | --- |
217
+ | DESI Legacy Survey DR10 `g r i z` | `CDS/P/DESI-Legacy-Surveys/DR10/{g,r,i,z}` | Optical; survey footprint only, not all-sky |
218
+ | WISE/NEOWISE `W1 W2` | `CDS/P/NEOWISER/W1`, `CDS/P/NEOWISER/W2` | Per-band mid-infrared images with a coarse PSF |
219
+ | unWISE | Not recommended as a template | CDS publishes a W1+W2 color composite only, which is unsuitable for difference imaging |
220
+
221
+ Explicit identifiers accept multi-character labels such as `--template-filter W1`.
222
+ Before downloading one, the library asks the CDS MOCServer whether the HiPS
223
+ coverage map fully encloses the science footprint (`intersect=enclosed`). A
224
+ negative result stops acquisition; an unreachable MOC service is recorded as a
225
+ warning and acquisition continues. The pre-check is only as accurate as the
226
+ published survey MOC and is not performed by `--check-only`. Pass
227
+ `--no-moc-precheck` to skip this query for explicit identifiers; the run then
228
+ records that coverage was not verified and adds a warning.
229
+ Only Pan-STARRS asinh scaling is converted; other HiPS pixel conventions, zero
230
+ points, masks, coadd epochs and PSFs are used as delivered and remain
231
+ uncertified. Confirm current identifiers and coverage in the CDS HiPS list before
232
+ relying on them.
233
+
234
+ ```powershell
235
+ proper-transient-finder --survey CDS/P/DESI-Legacy-Surveys/DR10/r --new science.fits --template-filter r --template-units adu --output results/survey_legacy
236
+ ```
237
+
238
+ HiPS pixels are coadded and resampled products, not original detector counts.
239
+ Pan-STARRS bands other than `g` are stored with asinh scaling; the library
240
+ linearizes those values and masks non-finite pixels. No variance plane is
241
+ invented. Cache-owned copies are labeled with the verified science count unit so
242
+ that the pipeline can fit one global stellar flux scale. `--template-units`
243
+ may declare that label explicitly, but it must match the science unit, and it
244
+ does not calibrate or convert pixels. `--template-gain` sets the reference
245
+ electrons-per-count used by its background noise model. Science input needs
246
+ declared count units and FILTER, or an explicit science filter override. No
247
+ input FITS is edited.
248
+
249
+ ```python
250
+ from proper_transient_finder import compare_survey_images
251
+
252
+ result = compare_survey_images(
253
+ "science.fits",
254
+ "results/survey_002",
255
+ template_filter="r",
256
+ survey="auto",
257
+ template_units="adu",
258
+ cache_dir="survey_cache",
259
+ )
260
+ ```
261
+
262
+ Matching band labels select ordinary subtraction; different bands select the
263
+ existing **experimental cross-filter** mode. Labels do not guarantee identical
264
+ instrument bandpasses. HiPS templates carry no survey variance plane and their
265
+ noise is correlated; scores and photometric errors are approximate, not
266
+ confirmed variability.
267
+
268
+ `science.txt` is one path per line, with optional `#` comment lines; a JSON array
269
+ of path strings is also supported. Paths are relative to the list file. This is
270
+ separate from the existing `--batch` ref/new manifest. Processing is sequential,
271
+ continues after failed images unless `--fail-fast` is set, and retains lightweight
272
+ reports. Results and cache directories must be separate; results must be new or empty
273
+ unless `--overwrite` is given, which clears the previous results root first, or an
274
+ interactive terminal (or `--yes`) confirms the replacement.
275
+
276
+ Each processed image gets `survey_reference.json`, `survey_diagnostic.png`, and
277
+ the existing products under `analysis/`. Failed processing is explicitly labeled;
278
+ `--no-plots` disables plots. `--check-only` performs no downloads or writes and
279
+ does not certify remote availability, calibration, registration or detectability.
280
+ Only the WCS, image dimensions, HiPS identifier, band and optional epoch are
281
+ sent to the service; science FITS pixels are never uploaded. The default transfer
282
+ cap is 512 MB per response. Larger files can be split or cropped upstream, but
283
+ the survey mode does not assemble mosaics. See
284
+ [the survey workflow guide](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/USER_GUIDE.md#automatic-survey-reference-workflow).
285
+
286
+ ## Medium FITS Robustness And Timing
287
+
288
+ Run the standalone experiment from this project directory:
289
+
290
+ ```powershell
291
+ python experiments/robustness.py --output artifacts/medium-auto --sizes-mb 20 50 --trials 2
292
+ python experiments/robustness.py --output artifacts/medium-known --sizes-mb 20 50 --trials 2 --known-psf
293
+ ```
294
+
295
+ Each FITS is approximately 20 or 50 decimal MB **including science, variance and
296
+ mask planes**. Five scenes cover clean images, cosmic/hot pixels, saturation/bad
297
+ columns, a satellite trail without a supplied mask, the same trail masked, and
298
+ combined detector/trail contamination. Each has a null control and five signed
299
+ point-source injections, including a host-galaxy source. Reports retain per-stage
300
+ times, peak process memory, recoveries, mask losses, false positives and failures.
301
+
302
+ **Measured 2026-11-02:** 40 known-PSF control analyses completed, with overall median
303
+ times of 12.0 s/pair at 20 MB/file and 28.3 s/pair at 50 MB/file. Peak process memory
304
+ was approximately 0.78/1.67 GB. All usable injections were recovered; masked
305
+ injections were lost. The 50 MB cases had a recurrent false positive for one noise
306
+ seed. These are exploratory timings, not guaranteed performance.
307
+
308
+ **Automatic PSF (fixed 2026-11-03):** the earlier failure of the four clean
309
+ 20/50 MB pilot cases was traced to ProperImage's strict star selection silently
310
+ falling back to *every* detected source when fewer than 15 stars pass its cuts;
311
+ galaxy light, blends and noise peaks then widened the Gaussian fit until the
312
+ support guard rejected it. The estimator now seeds ProperImage's source cache
313
+ with the pipeline's own isolated SEP stars. Re-checked clean pairs with
314
+ automatic PSFs completed in 25.5 s at 20 MB and 65.5 s at 50 MB, with FWHM
315
+ 3.19/4.30 and 3.19/4.34 pixels against injected 3.06/4.24, recovering all five
316
+ 50 MB injections (the 1,800 ADU source was missed at 20 MB). These are
317
+ single-pair checks, not a rerun of the 40-case campaign, and other scenes and
318
+ observed transients remain unvalidated. The known-PSF control above used the
319
+ injection-model PSFs and did **not** exercise automatic estimation. Measured PSF
320
+ widths, 4σ support, and their guard limits are reported in `quality_summary.json`.
321
+ See [the full benchmark guide](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/USER_GUIDE.md#medium-fits-robustness-and-timing).
322
+
323
+ ## Documentation
324
+
325
+ - [User Guide](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/USER_GUIDE.md): setup, scientific assumptions, outputs, and validation.
326
+ - [API Reference](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/docs/API.md): generated signatures, configuration defaults, and result fields.
327
+ - [Publish Documentation](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/docs/publishing.md): MkDocs setup, preview, and hosting.
328
+
329
+ ### MkDocs Website
330
+
331
+ Build a searchable Material for MkDocs site from this README, the user guide,
332
+ and the API reference. Run from the project directory:
333
+
334
+ ```powershell
335
+ python -m pip install ".[docs]"
336
+ .\scripts\docs.ps1 -Build
337
+ .\scripts\docs.ps1 -Serve
338
+ ```
339
+
340
+ On Linux, macOS, or Git Bash, use `PYTHON` instead of `-PythonPath`:
341
+
342
+ ```bash
343
+ python -m pip install ".[docs]"
344
+ bash scripts/tasks.sh docs --build
345
+ bash scripts/tasks.sh docs --serve
346
+ ```
347
+
348
+ The publishable static site is written to `site/`. The local preview is at
349
+ <http://127.0.0.1:8001/>. Pass `-PythonPath` (PowerShell) or `PYTHON=<path>`
350
+ (`scripts/tasks.sh`) when using another prepared interpreter. See the
351
+ publication guide for GitHub Pages and other static hosts. No publication is
352
+ performed automatically.
353
+
354
+ ### API Markdown
355
+
356
+ Regenerate the API reference from the project directory:
357
+
358
+ ```powershell
359
+ .\scripts\docs.ps1 -PythonPath .\.venv\Scripts\python.exe
360
+ .\scripts\docs.ps1 -PythonPath .\.venv\Scripts\python.exe -Check
361
+ ```
362
+
363
+ ```bash
364
+ PYTHON=.venv/bin/python bash scripts/tasks.sh docs
365
+ PYTHON=.venv/bin/python bash scripts/tasks.sh docs --check
366
+ ```
367
+
368
+ Use the path to your existing Python 3.11+ interpreter when the project environment
369
+ does not exist. Generation uses only the standard library, makes no network
370
+ requests, and produces Markdown that GitHub renders without a site build.
371
+
372
+ ## GitHub Readiness
373
+
374
+ The repository includes a GitHub Actions workflow that tests Python 3.11, 3.12,
375
+ and 3.13 on Windows, Linux, and macOS for lint, tests, documentation freshness,
376
+ and wheel/source builds. Windows uses the PowerShell scripts; Linux and macOS
377
+ use `scripts/tasks.sh`. Documentation is ordinary checked-in Markdown; the
378
+ GitHub Pages site is deployed by `.github/workflows/docs.yml` once
379
+ **Settings → Pages → Source** is set to **GitHub Actions**.
380
+ Build outputs, virtual environments, and generated observation/test artifacts
381
+ are ignored and should not be committed.
382
+
383
+ **License:** this project is released under the BSD 3-Clause License; see
384
+ [LICENSE](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/LICENSE). Third-party components keep their own licenses (ProperImage,
385
+ Astropy, and most of the scientific stack are BSD-3-Clause; SEP is LGPLv3+), and
386
+ their citation and license obligations still apply.
387
+
388
+ Before publishing, confirm permission to publish the repository and review
389
+ tracked files for private data/secrets. No GitHub publication or PyPI upload is
390
+ performed by the supplied scripts.
391
+
392
+ The checked-in workflow runs from the repository root (`working-directory: .`)
393
+ on every push and pull request. It deliberately has no `paths` filter, so a
394
+ change to `pyproject.toml`, the tests, or the documentation still runs the
395
+ quality job. If the project files ever move, update that setting and the script
396
+ paths in the same commit. Package metadata points at
397
+ <https://github.com/pierfra-rocci/proper_transient_finder> for source, issues,
398
+ and documentation.
399
+
400
+ **Author:** Pier-Francesco Rocci
401
+ Developed with assistance from ChatGPT, Claude, and Mistral.
402
+
403
+ ## Releasing to PyPI
404
+
405
+ Releases are published by `.github/workflows/publish.yml` with PyPI Trusted
406
+ Publishing (GitHub OIDC), so no PyPI API token is created or stored in GitHub
407
+ Secrets. The workflow runs on `v*` tag pushes and can also be started manually.
408
+ Each run installs the development environment and executes the astronomy test
409
+ suite before building, so a failing test stops the release before any upload.
410
+
411
+ | Index | Workflow | Environment |
412
+ | --- | --- | --- |
413
+ | TestPyPI | `publish.yml` | `testpypi` |
414
+ | PyPI | `publish.yml` | `pypi` |
415
+
416
+ Both publishers must be registered once, before the first upload. Add a pending
417
+ publisher for `proper-transient-finder` at
418
+ <https://test.pypi.org/manage/account/publishing/> and
419
+ <https://pypi.org/manage/account/publishing/>, using owner `pierfra-rocci`,
420
+ repository `proper_transient_finder`, workflow name `publish.yml`, and the
421
+ environment from the table. Then create the same named environments under GitHub
422
+ `Settings → Environments`; add required reviewers to `pypi` if a production
423
+ upload should wait for approval.
424
+
425
+ ### TestPyPI Dry Run
426
+
427
+ Open `Actions → Publish Python package to PyPI → Run workflow`, choose the branch
428
+ or tag to build, and run it. The build job produces the wheel and source archive,
429
+ and the `Publish to TestPyPI` job uploads them to
430
+ <https://test.pypi.org/project/proper-transient-finder/>; the production job is
431
+ skipped on manual runs. TestPyPI does not host this project's scientific
432
+ dependencies, so check the uploaded files rather than expecting a usable install
433
+ there:
434
+
435
+ ```bash
436
+ python -m pip install --index-url https://test.pypi.org/simple/ \
437
+ --extra-index-url https://pypi.org/simple proper-transient-finder
438
+ ```
439
+
440
+ A version can be uploaded to TestPyPI only once. `skip-existing` keeps repeated
441
+ runs of the same version green, but bump `_version.py` to dry-run changed code.
442
+
443
+ ### Tagged Release
444
+
445
+ 1. Set the version in `src/proper_transient_finder/_version.py` and update the
446
+ `Current release` line near the top of this README.
447
+ 2. Commit the change, then tag and push it:
448
+
449
+ ```bash
450
+ git tag v0.3.1
451
+ git push origin v0.3.1
452
+ ```
453
+
454
+ The build job fails before building if the pushed tag is not `v<version>` taken
455
+ from `_version.py`, so a mistagged release never reaches an index. The
456
+ historical `v_<version>` form (tags `v_0.1.0` through `v_0.3.1`) is accepted
457
+ too. After that check the test suite runs against the tagged commit, and the
458
+ wheel and source archive are built only when it passes. The `Publish to PyPI`
459
+ job then uploads to
460
+ <https://pypi.org/project/proper-transient-finder/>. Published versions are
461
+ immutable: always increment the version instead of reusing one.
462
+
463
+ ## License
464
+
465
+ Released under the BSD 3-Clause License; see [LICENSE](https://github.com/pierfra-rocci/proper_transient_finder/blob/main/LICENSE). Third-party
466
+ components keep their own licenses, and their citation and license obligations
467
+ still apply.
468
+
469
+ ## Acknowledgments
470
+
471
+ This library builds on the work of the astronomy community, particularly:
472
+
473
+ - [ProperImage](https://github.com/quatrope/ProperImage), for astronomical image
474
+ processing and PSF/subtraction tools.
475
+ - [Astropy](https://www.astropy.org/), for FITS, celestial coordinates, WCS, and
476
+ astronomy utilities.
477
+
478
+ Please also follow these projects' own citation and license requirements.