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.
- proper_transient_finder-0.3.1/.gitattributes +7 -0
- proper_transient_finder-0.3.1/.github/instructions/proper-transient-finder.instructions.md +12 -0
- proper_transient_finder-0.3.1/.github/workflows/proper-transient-finder.yml +86 -0
- proper_transient_finder-0.3.1/LICENSE +28 -0
- proper_transient_finder-0.3.1/MANIFEST.in +14 -0
- proper_transient_finder-0.3.1/PKG-INFO +478 -0
- proper_transient_finder-0.3.1/README.md +435 -0
- proper_transient_finder-0.3.1/USER_GUIDE.md +1729 -0
- proper_transient_finder-0.3.1/docs/API.md +325 -0
- proper_transient_finder-0.3.1/docs/publishing.md +124 -0
- proper_transient_finder-0.3.1/experiments/completeness.py +442 -0
- proper_transient_finder-0.3.1/experiments/robustness.py +672 -0
- proper_transient_finder-0.3.1/mkdocs.yml +66 -0
- proper_transient_finder-0.3.1/pyproject.toml +79 -0
- proper_transient_finder-0.3.1/run_proper_transient_finder.py +25 -0
- proper_transient_finder-0.3.1/scripts/bootstrap.ps1 +39 -0
- proper_transient_finder-0.3.1/scripts/build.ps1 +50 -0
- proper_transient_finder-0.3.1/scripts/docs.ps1 +47 -0
- proper_transient_finder-0.3.1/scripts/generate_docs.py +156 -0
- proper_transient_finder-0.3.1/scripts/lint.ps1 +39 -0
- proper_transient_finder-0.3.1/scripts/mkdocs_hooks.py +46 -0
- proper_transient_finder-0.3.1/scripts/tasks.sh +261 -0
- proper_transient_finder-0.3.1/scripts/test.ps1 +30 -0
- proper_transient_finder-0.3.1/scripts/verify_install.ps1 +114 -0
- proper_transient_finder-0.3.1/setup.cfg +4 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder/__init__.py +51 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder/__main__.py +8 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder/_version.py +6 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder/api.py +438 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder/astro.py +2371 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder/py.typed +1 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder/survey.py +1168 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/PKG-INFO +478 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/SOURCES.txt +39 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/dependency_links.txt +1 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/entry_points.txt +2 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/requires.txt +21 -0
- proper_transient_finder-0.3.1/src/proper_transient_finder.egg-info/top_level.txt +1 -0
- proper_transient_finder-0.3.1/tests/test_astro.py +3178 -0
- proper_transient_finder-0.3.1/tests/test_documentation.py +258 -0
- proper_transient_finder-0.3.1/tests/test_survey_hips.py +370 -0
|
@@ -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.
|