hst123 1.1.0__tar.gz

hst123-1.1.0/.github/workflows/build-test.yml

@@ -0,0 +1,36 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        # Required so conda env is activated in run steps (setup-miniconda)
+        shell: bash -el {0}
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+        fetch-depth: 0
+        persist-credentials: false
+    - name: Set up Conda with Python 3.12
+      uses: conda-incubator/setup-miniconda@v3
+      with:
+        environment-file: environment.yml
+        activate-environment: hst123
+        auto-update-conda: true
+    - name: Install the package and dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        # Editable install: tests and monkeypatches target the checkout, not a
+        # stale copy under site-packages.
+        python -m pip install -e ".[test]"
+    - name: Run tests
+      run: |
+        python -m pytest tests/ -v --tb=short

hst123-1.1.0/.github/workflows/documentation.yml

@@ -0,0 +1,42 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.12]
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+        fetch-depth: 0
+        persist-credentials: false
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install the package with doc dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        pip install .[docs]
+    - name: Build the docs
+      run: |
+        cd docs
+        make html
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        publish_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html/
+        force_orphan: true

hst123-1.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,43 @@
+# Publish the hst123 package to https://pypi.org/project/hst123/
+#
+# Setup (one-time on PyPI):
+#   1. Create the "hst123" project on PyPI (or claim the name if reserved).
+#   2. Publishing → "Add a new publisher" → GitHub → this repo → this workflow file.
+#      (Optional: restrict to a GitHub Environment named "pypi" and add the same
+#       name under "Publisher" on PyPI.)
+#
+# Release:
+#   git tag v1.2.3 && git push origin v1.2.3
+#   (setuptools-scm reads the tag; requires fetch-depth: 0 below)
+#
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install --upgrade pip build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hst123-1.1.0/.gitignore

@@ -0,0 +1,13 @@
+*.pyc
+__pycache__
+
+# Editor / IDE (local)
+.vscode/
+
+# Local integration / regression data (large FITS, logs); not versioned
+test_data/
+*.egg-info/
+build/
+docs/build/
+# Setuptools-scm writes this at build time; do not commit
+hst123/_version.py

hst123-1.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Charles D. Kilpatrick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hst123-1.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: hst123
+Version: 1.1.0
+Summary: An all-in-one script for downloading, registering, and drizzling HST images, running dolphot, and scraping data from dolphot catalogs.
+License: BSD-3-Clause
+Keywords: astronomy,HST,Hubble,dolphot,drizzle,photometry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: setuptools<82,>=64.0
+Requires-Dist: astropy<6,>=5.3
+Requires-Dist: astroquery>=0.4.6
+Requires-Dist: astroscrappy>=1.1.0
+Requires-Dist: drizzlepac>=3.5.1
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: progressbar33>=2.4
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: requests>=2.32.0
+Requires-Dist: scipy<2,>=1.11
+Requires-Dist: h5py>=3.8
+Requires-Dist: jhat
+Provides-Extra: perf
+Requires-Dist: numba>=0.59; extra == "perf"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: hdf5
+Requires-Dist: h5py>=3.8; extra == "hdf5"
+Provides-Extra: docs
+Requires-Dist: sphinx>=5.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
+Requires-Dist: numpydoc>=1.5; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Dynamic: license-file
+
+# hst123
+
+[![Build and Test](https://github.com/charliekilpatrick/hst123/actions/workflows/build-test.yml/badge.svg)](https://github.com/charliekilpatrick/hst123/actions/workflows/build-test.yml)
+[![Documentation](https://github.com/charliekilpatrick/hst123/actions/workflows/documentation.yml/badge.svg)](https://github.com/charliekilpatrick/hst123/actions/workflows/documentation.yml)
+[![Documentation site](https://img.shields.io/badge/documentation-GitHub%20Pages-4b32b3)](https://charliekilpatrick.github.io/hst123/)
+
+Pipeline for HST data: download from MAST, align (tweakreg/jhat), drizzle, run DOLPHOT, and scrape photometry. Optimized for point-source photometry across multiple visits and filters.
+
+**Issues:** Report bugs and feature requests via the project issue tracker. Other questions or publications using hst123: [Contact](#contact).
+
+---
+
+## Repository status
+
+- **Python:** **3.12** (``requires-python`` in ``pyproject.toml`` pins the **3.12** line: ``>=3.12,<3.13``)
+- **Versioning:** From git tags (setuptools-scm); `hst123 --version`
+- **Layout:** Main pipeline in `hst123/_pipeline.py`; helpers in `hst123/primitives/` (FITS, photometry, astrometry, DOLPHOT, scrape) and `hst123/utils/` (options, display, visit, WCS)
+- **Tests:** `pytest` in `tests/`; optional markers `network`, `dolphot` (see pyproject.toml)
+- **Docs:** Sphinx sources under `docs/` (MyST Markdown + reStructuredText, Read the Docs theme). Build: `pip install -e ".[docs]"` then `cd docs && make html`. **Hosted:** [GitHub Pages](https://charliekilpatrick.github.io/hst123/) (from the [Documentation workflow](https://github.com/charliekilpatrick/hst123/actions/workflows/documentation.yml)).
+
+---
+
+## Installation
+
+**1. Environment (recommended: Conda)**
+From the repo root:
+
+```bash
+conda env create -f environment.yml
+conda activate hst123
+```
+
+**2. Pipeline and heavy deps**
+
+```bash
+pip install drizzlepac
+pip install -e .
+```
+
+The **STScI WCS** stack used by hst123 (``updatewcs``, ``HSTWCS``, ``altwcs``) is **bundled** under ``hst123.utils.stwcs`` (see ``STWCS_VENDOR.txt`` there) and reached only via ``hst123.utils.stsci_wcs`` — **PyPI ``stwcs`` is not an hst123 dependency**. DrizzlePac may still install ``stwcs`` for its own use.
+
+The `hst123` command is available. Download, alignment, and drizzling work without DOLPHOT.
+
+**3. DOLPHOT (only for `--run-dolphot`)**
+DOLPHOT is external; not bundled. With **conda activated**, the helper downloads sources and PSF/PAM reference data under **`$CONDA_PREFIX/opt/hst123-dolphot`**, runs **`make`**, and symlinks **`dolphot`**, **`calcsky`**, and optional mask/split tools into **`$CONDA_PREFIX/bin`**. **Masking** (`acsmask` / `wfc3mask` / `wfpc2mask`) and **`splitgroups`** are implemented in Python by default (see **`hst123.utils.dolphot_mask`**, **`hst123.utils.dolphot_splitgroups`**); set **`HST123_DOLPHOT_MASK_EXTERNAL=1`** or **`HST123_DOLPHOT_SPLITGROUPS_EXTERNAL=1`** to force the C binaries.
+
+```bash
+conda activate hst123   # or your env with hst123 installed
+hst123-install-dolphot
+```
+
+Without conda (or to choose a location), pass **`--dolphot-dir /path/to/dolphot`**; use **`--no-link-conda-bin`** and **`export PATH="/path/to/dolphot:$PATH"`** if you do not want links in the env `bin/`. Manual install: [americano.dolphinsim.com/dolphot](http://americano.dolphinsim.com/dolphot/).
+
+The helper installs **DOLPHOT 3.1**, merges PSF tables into the tree DOLPHOT expects, and can apply small source patches for long paths on macOS. Re-running **`hst123-install-dolphot`** does not re-download already-installed artifacts; use **`--force-download`** to refresh. See **`hst123-install-dolphot --help`**.
+
+---
+
+## Usage
+
+```bash
+hst123 <ra> <dec> [options]
+# Example:
+hst123 12:30:00 -45.0 --download
+```
+
+- **`--work-dir`** — Absolute path is recommended; defaults to the current directory at startup. **`--raw-dir`** defaults to **`<work-dir>/raw`** (science FITS are written there, then copied into the work directory for reduction). **MAST / astroquery staging** (the temporary **`mastDownload`** tree) is always created under **`<work-dir>/.mast_download_staging/`** and removed after each file is moved to **`raw`** or **`--archive`**, so nothing is left in the directory you launched the command from when **`--work-dir`** points elsewhere. Most calibrated inputs and per-epoch drizzle outputs live under **`<work-dir>/workspace/`**; **`--drizzle-all`** writes the consolidated **`drizzle/`** directory under **`<work-dir>/drizzle/`** (the base work directory, not inside **`workspace/`**).
+- **`--download`** — Fetch data from MAST for the given RA/Dec (5′ radius). Use **`--token`** for private data ([MAST auth](https://auth.mast.stsci.edu/info)).
+- **`--run-dolphot`** — Run DOLPHOT (requires DOLPHOT on PATH).
+- **`--scrape-dolphot`** — Extract photometry at the target from DOLPHOT output.
+
+**DOLPHOT catalog → HDF5:** Optional helper **`hst123.utils.dolphot_catalog_hdf5.write_dolphot_catalog_hdf5`** writes the DOLPHOT table to a single **HDF5** file (columnar datasets + metadata). Requires **`h5py`** (`pip install h5py` or **`pip install .[hdf5]`**).
+
+Run in a directory that will hold (or already holds) your images. Without `--download`, hst123 uses existing files in the working directory. Full option list: **`hst123 --help`**.
+
+---
+
+## Supported instruments
+
+| Instrument | File types                |
+| ---------- | ------------------------- |
+| WFPC2      | c0m.fits, c1m.fits (both) |
+| ACS/WFC    | flc.fits                  |
+| ACS/HRC    | flt.fits                  |
+| WFC3/UVIS  | flc.fits                  |
+| WFC3/IR    | flt.fits                  |
+
+You can provide **`--reference`** or let hst123 build one from the data. Alignment: **tweakreg** (default) or **jhat** (**`--align-with`**). Photometry is reported in AB mag by default; see `docs/zeropoints.md`.
+
+---
+
+## Options (summary)
+
+- **Run environment:** `--work-dir`, `--raw-dir`, `--archive`, `--cleanup`, `--keep-drizzle-artifacts`, `--by-visit`
+- **Filters/dates:** `--before`, `--after`, `--only-filter`, `--only-wide`
+- **Reference:** `--reference` / `--ref`, `--reference-filter`, `--reference-instrument`, `--avoid-wfpc2`
+- **Alignment:** `--tweak-search`, `--tweak-min-obj`, `--tweak-thresh`, `--skip-tweakreg`, `--align-with`, `--hierarchical`
+- **Drizzle / parallelism:** `--drizzle-all`, `--drizzle-dim`, `--drizzle-scale`, `--sky-sub`, `--redrizzle`, `--fix-zpt`, `--no-rotation`, `--max-cores` (AstroDrizzle `num_cores` and DOLPHOT prep thread pool, capped by exposure count; default min(8, CPU count); `--max-cores 1` forces serial prep and single-worker drizzle)
+- **DOLPHOT:** `--run-dolphot`, `--dolphot` / `--dp`, `--dolphot-lim`, `--do-fake`, `--add-crmask`, `--include-all-splits`
+- **Scraping:** `--scrape-dolphot` / `--sd`, `--scrape-all`, `--scrape-radius`, `--no-cuts`, `--brightest`
+
+---
+
+## Documentation
+
+- **Online:** [charliekilpatrick.github.io/hst123](https://charliekilpatrick.github.io/hst123/) (API reference, user guide, changelog, zero points).
+- **Local build:** `pip install -e ".[docs]"` then `cd docs && make html` → `docs/build/html/index.html`.
+- **Sources:** `docs/index.rst`, `docs/user_guide.rst`, `docs/api.rst`, plus `docs/changelog.md` and `docs/zeropoints.md` (MyST).
+
+---
+
+## Citing and contact
+
+**Citation:** C. D. Kilpatrick, *hst123: HST download, alignment, drizzle, and DOLPHOT photometry pipeline*, GitHub (or project URL). If a DOI (e.g. Zenodo) is assigned to a release, cite that. We welcome notice of papers that use hst123.
+
+**Suggested references for citing hst123:** If you cite this software in a paper or proposal, you may also reference the following peer-reviewed works that use *Hubble Space Telescope* data heavily and describe the use of **hst123**:
+
+- Kilpatrick et al., “A cool and inflated progenitor candidate for the Type Ib supernova 2019yvr at 2.6 yr before explosion,” *MNRAS* **504**, 2073 (2021). [doi:10.1093/mnras/stab838](https://doi.org/10.1093/mnras/stab838) · [arXiv:2101.03185](https://arxiv.org/abs/2101.03185)
+- Kilpatrick et al., “Hubble Space Telescope Observations of GW170817: Complete Light Curves and the Properties of the Galaxy Merger of NGC 4993,” *ApJ* **926**, 49 (2022). [doi:10.3847/1538-4357/ac3e59](https://doi.org/10.3847/1538-4357/ac3e59) · [arXiv:2109.06211](https://arxiv.org/abs/2109.06211)
+- Kilpatrick et al., “Type II-P supernova progenitor star initial masses and SN 2020jfo: direct detection, light-curve properties, nebular spectroscopy, and local environment,” *MNRAS* **524**, 2161 (2023). [doi:10.1093/mnras/stad1954](https://doi.org/10.1093/mnras/stad1954) · [arXiv:2307.00550](https://arxiv.org/abs/2307.00550)
+
+**Contact:** Charlie Kilpatrick, ckilpatrick@northwestern.edu. **Bugs and feature requests:** please open an issue on the repository.

hst123-1.1.0/README.md

@@ -0,0 +1,121 @@
+# hst123
+
+[![Build and Test](https://github.com/charliekilpatrick/hst123/actions/workflows/build-test.yml/badge.svg)](https://github.com/charliekilpatrick/hst123/actions/workflows/build-test.yml)
+[![Documentation](https://github.com/charliekilpatrick/hst123/actions/workflows/documentation.yml/badge.svg)](https://github.com/charliekilpatrick/hst123/actions/workflows/documentation.yml)
+[![Documentation site](https://img.shields.io/badge/documentation-GitHub%20Pages-4b32b3)](https://charliekilpatrick.github.io/hst123/)
+
+Pipeline for HST data: download from MAST, align (tweakreg/jhat), drizzle, run DOLPHOT, and scrape photometry. Optimized for point-source photometry across multiple visits and filters.
+
+**Issues:** Report bugs and feature requests via the project issue tracker. Other questions or publications using hst123: [Contact](#contact).
+
+---
+
+## Repository status
+
+- **Python:** **3.12** (``requires-python`` in ``pyproject.toml`` pins the **3.12** line: ``>=3.12,<3.13``)
+- **Versioning:** From git tags (setuptools-scm); `hst123 --version`
+- **Layout:** Main pipeline in `hst123/_pipeline.py`; helpers in `hst123/primitives/` (FITS, photometry, astrometry, DOLPHOT, scrape) and `hst123/utils/` (options, display, visit, WCS)
+- **Tests:** `pytest` in `tests/`; optional markers `network`, `dolphot` (see pyproject.toml)
+- **Docs:** Sphinx sources under `docs/` (MyST Markdown + reStructuredText, Read the Docs theme). Build: `pip install -e ".[docs]"` then `cd docs && make html`. **Hosted:** [GitHub Pages](https://charliekilpatrick.github.io/hst123/) (from the [Documentation workflow](https://github.com/charliekilpatrick/hst123/actions/workflows/documentation.yml)).
+
+---
+
+## Installation
+
+**1. Environment (recommended: Conda)**
+From the repo root:
+
+```bash
+conda env create -f environment.yml
+conda activate hst123
+```
+
+**2. Pipeline and heavy deps**
+
+```bash
+pip install drizzlepac
+pip install -e .
+```
+
+The **STScI WCS** stack used by hst123 (``updatewcs``, ``HSTWCS``, ``altwcs``) is **bundled** under ``hst123.utils.stwcs`` (see ``STWCS_VENDOR.txt`` there) and reached only via ``hst123.utils.stsci_wcs`` — **PyPI ``stwcs`` is not an hst123 dependency**. DrizzlePac may still install ``stwcs`` for its own use.
+
+The `hst123` command is available. Download, alignment, and drizzling work without DOLPHOT.
+
+**3. DOLPHOT (only for `--run-dolphot`)**
+DOLPHOT is external; not bundled. With **conda activated**, the helper downloads sources and PSF/PAM reference data under **`$CONDA_PREFIX/opt/hst123-dolphot`**, runs **`make`**, and symlinks **`dolphot`**, **`calcsky`**, and optional mask/split tools into **`$CONDA_PREFIX/bin`**. **Masking** (`acsmask` / `wfc3mask` / `wfpc2mask`) and **`splitgroups`** are implemented in Python by default (see **`hst123.utils.dolphot_mask`**, **`hst123.utils.dolphot_splitgroups`**); set **`HST123_DOLPHOT_MASK_EXTERNAL=1`** or **`HST123_DOLPHOT_SPLITGROUPS_EXTERNAL=1`** to force the C binaries.
+
+```bash
+conda activate hst123   # or your env with hst123 installed
+hst123-install-dolphot
+```
+
+Without conda (or to choose a location), pass **`--dolphot-dir /path/to/dolphot`**; use **`--no-link-conda-bin`** and **`export PATH="/path/to/dolphot:$PATH"`** if you do not want links in the env `bin/`. Manual install: [americano.dolphinsim.com/dolphot](http://americano.dolphinsim.com/dolphot/).
+
+The helper installs **DOLPHOT 3.1**, merges PSF tables into the tree DOLPHOT expects, and can apply small source patches for long paths on macOS. Re-running **`hst123-install-dolphot`** does not re-download already-installed artifacts; use **`--force-download`** to refresh. See **`hst123-install-dolphot --help`**.
+
+---
+
+## Usage
+
+```bash
+hst123 <ra> <dec> [options]
+# Example:
+hst123 12:30:00 -45.0 --download
+```
+
+- **`--work-dir`** — Absolute path is recommended; defaults to the current directory at startup. **`--raw-dir`** defaults to **`<work-dir>/raw`** (science FITS are written there, then copied into the work directory for reduction). **MAST / astroquery staging** (the temporary **`mastDownload`** tree) is always created under **`<work-dir>/.mast_download_staging/`** and removed after each file is moved to **`raw`** or **`--archive`**, so nothing is left in the directory you launched the command from when **`--work-dir`** points elsewhere. Most calibrated inputs and per-epoch drizzle outputs live under **`<work-dir>/workspace/`**; **`--drizzle-all`** writes the consolidated **`drizzle/`** directory under **`<work-dir>/drizzle/`** (the base work directory, not inside **`workspace/`**).
+- **`--download`** — Fetch data from MAST for the given RA/Dec (5′ radius). Use **`--token`** for private data ([MAST auth](https://auth.mast.stsci.edu/info)).
+- **`--run-dolphot`** — Run DOLPHOT (requires DOLPHOT on PATH).
+- **`--scrape-dolphot`** — Extract photometry at the target from DOLPHOT output.
+
+**DOLPHOT catalog → HDF5:** Optional helper **`hst123.utils.dolphot_catalog_hdf5.write_dolphot_catalog_hdf5`** writes the DOLPHOT table to a single **HDF5** file (columnar datasets + metadata). Requires **`h5py`** (`pip install h5py` or **`pip install .[hdf5]`**).
+
+Run in a directory that will hold (or already holds) your images. Without `--download`, hst123 uses existing files in the working directory. Full option list: **`hst123 --help`**.
+
+---
+
+## Supported instruments
+
+| Instrument | File types                |
+| ---------- | ------------------------- |
+| WFPC2      | c0m.fits, c1m.fits (both) |
+| ACS/WFC    | flc.fits                  |
+| ACS/HRC    | flt.fits                  |
+| WFC3/UVIS  | flc.fits                  |
+| WFC3/IR    | flt.fits                  |
+
+You can provide **`--reference`** or let hst123 build one from the data. Alignment: **tweakreg** (default) or **jhat** (**`--align-with`**). Photometry is reported in AB mag by default; see `docs/zeropoints.md`.
+
+---
+
+## Options (summary)
+
+- **Run environment:** `--work-dir`, `--raw-dir`, `--archive`, `--cleanup`, `--keep-drizzle-artifacts`, `--by-visit`
+- **Filters/dates:** `--before`, `--after`, `--only-filter`, `--only-wide`
+- **Reference:** `--reference` / `--ref`, `--reference-filter`, `--reference-instrument`, `--avoid-wfpc2`
+- **Alignment:** `--tweak-search`, `--tweak-min-obj`, `--tweak-thresh`, `--skip-tweakreg`, `--align-with`, `--hierarchical`
+- **Drizzle / parallelism:** `--drizzle-all`, `--drizzle-dim`, `--drizzle-scale`, `--sky-sub`, `--redrizzle`, `--fix-zpt`, `--no-rotation`, `--max-cores` (AstroDrizzle `num_cores` and DOLPHOT prep thread pool, capped by exposure count; default min(8, CPU count); `--max-cores 1` forces serial prep and single-worker drizzle)
+- **DOLPHOT:** `--run-dolphot`, `--dolphot` / `--dp`, `--dolphot-lim`, `--do-fake`, `--add-crmask`, `--include-all-splits`
+- **Scraping:** `--scrape-dolphot` / `--sd`, `--scrape-all`, `--scrape-radius`, `--no-cuts`, `--brightest`
+
+---
+
+## Documentation
+
+- **Online:** [charliekilpatrick.github.io/hst123](https://charliekilpatrick.github.io/hst123/) (API reference, user guide, changelog, zero points).
+- **Local build:** `pip install -e ".[docs]"` then `cd docs && make html` → `docs/build/html/index.html`.
+- **Sources:** `docs/index.rst`, `docs/user_guide.rst`, `docs/api.rst`, plus `docs/changelog.md` and `docs/zeropoints.md` (MyST).
+
+---
+
+## Citing and contact
+
+**Citation:** C. D. Kilpatrick, *hst123: HST download, alignment, drizzle, and DOLPHOT photometry pipeline*, GitHub (or project URL). If a DOI (e.g. Zenodo) is assigned to a release, cite that. We welcome notice of papers that use hst123.
+
+**Suggested references for citing hst123:** If you cite this software in a paper or proposal, you may also reference the following peer-reviewed works that use *Hubble Space Telescope* data heavily and describe the use of **hst123**:
+
+- Kilpatrick et al., “A cool and inflated progenitor candidate for the Type Ib supernova 2019yvr at 2.6 yr before explosion,” *MNRAS* **504**, 2073 (2021). [doi:10.1093/mnras/stab838](https://doi.org/10.1093/mnras/stab838) · [arXiv:2101.03185](https://arxiv.org/abs/2101.03185)
+- Kilpatrick et al., “Hubble Space Telescope Observations of GW170817: Complete Light Curves and the Properties of the Galaxy Merger of NGC 4993,” *ApJ* **926**, 49 (2022). [doi:10.3847/1538-4357/ac3e59](https://doi.org/10.3847/1538-4357/ac3e59) · [arXiv:2109.06211](https://arxiv.org/abs/2109.06211)
+- Kilpatrick et al., “Type II-P supernova progenitor star initial masses and SN 2020jfo: direct detection, light-curve properties, nebular spectroscopy, and local environment,” *MNRAS* **524**, 2161 (2023). [doi:10.1093/mnras/stad1954](https://doi.org/10.1093/mnras/stad1954) · [arXiv:2307.00550](https://arxiv.org/abs/2307.00550)
+
+**Contact:** Charlie Kilpatrick, ckilpatrick@northwestern.edu. **Bugs and feature requests:** please open an issue on the repository.

hst123-1.1.0/docs/Makefile

@@ -0,0 +1,14 @@
+# Minimal Sphinx Makefile; output goes to build/html for GitHub Pages publish_dir.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = hst123
+SOURCEDIR     = .
+BUILDDIR      = build
+
+.PHONY: help Makefile
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

hst123-1.1.0/docs/_static/hst123-docs.css

@@ -0,0 +1,17 @@
+/* hst123 documentation — tweaks on sphinx_rtd_theme (Swift_host_subtraction style) */
+
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+    white-space: normal;
+}
+
+.wy-table-responsive {
+    margin-bottom: 24px;
+    max-width: 100%;
+    overflow: visible;
+}
+
+/* Slightly clearer admonitions in RTD */
+.rst-content .admonition {
+    border-radius: 4px;
+}

hst123-1.1.0/docs/_templates/layout.html

@@ -0,0 +1,2 @@
+{% extends "!layout.html" %}
+{% set css_files = css_files + ['_static/hst123-docs.css'] %}

hst123-1.1.0/docs/api.rst

@@ -0,0 +1,77 @@
+.. _api_reference:
+
+API reference
+=============
+
+This section documents the public Python API: the CLI entry point, the main
+:class:`~hst123._pipeline.hst123` orchestration class, CLI registration in
+:mod:`hst123.utils.options`, path helpers, optional HDF5 export for DOLPHOT
+tables, and shared primitive utilities.
+
+Entry point
+-----------
+
+.. autofunction:: hst123._pipeline.main
+
+Pipeline class
+--------------
+
+The class :class:`~hst123._pipeline.hst123` holds pipeline state (options,
+coordinates, input lists, reference path) and delegates to **primitives**
+(``_fits``, ``_phot``, ``_astrom``, ``_dolphot``, ``_scrape_dolphot``) for
+instrument-specific work.
+
+.. autoclass:: hst123._pipeline.hst123
+   :members:
+   :exclude-members: __weakref__
+
+CLI options and redo helpers
+----------------------------
+
+.. automodule:: hst123.utils.options
+   :members: add_options, want_redo_astrometry, want_redo_astrodrizzle
+
+Path helpers
+------------
+
+.. automodule:: hst123.utils.paths
+   :members:
+   :undoc-members:
+
+Parallel BLAS / OpenMP guard
+----------------------------
+
+.. automodule:: hst123.utils.stdio
+   :members:
+   :undoc-members:
+
+Work directory cleanup
+----------------------
+
+After AstroDrizzle or TweakReg, the pipeline can remove scratch FITS and replay
+external logs into the session log. Use ``--keep-drizzle-artifacts`` to retain
+intermediates.
+
+.. automodule:: hst123.utils.workdir_cleanup
+   :members: remove_files_matching_globs, cleanup_after_astrodrizzle, cleanup_after_tweakreg, remove_superseded_instrument_mask_reference_drizzle
+
+DOLPHOT catalog → HDF5
+----------------------
+
+.. automodule:: hst123.utils.dolphot_catalog_hdf5
+   :members:
+   :undoc-members:
+
+Data model
+----------
+
+.. automodule:: hst123.datamodels.hst_model
+   :members:
+   :undoc-members:
+
+Primitives base class
+---------------------
+
+.. autoclass:: hst123.primitives.base.BasePrimitive
+   :members:
+   :show-inheritance:

hst123-1.1.0/docs/changelog.md

@@ -0,0 +1,27 @@
+# Changelog
+
+Notable changes to hst123. Version numbering follows semantic versioning for full releases.
+
+## Pre-releases (historical)
+
+- **v1.00** (2019-02-07) — Base: download, tweakreg, drizzle, dolphot parameters.
+- **v1.01** (2019-02-15) — Run dolphot and scrape dolphot output.
+- **v1.02** (2019-02-22) — Fake star injection.
+- **v1.03** (2019-06-02) — Drizzle-all options and option/syntax cleanup.
+- **v1.04** (2020-02-10) — Python 3.7.
+- **v1.05** (2020-03-04) — Sanitizing reference images for tweakreg/dolphot.
+- **v1.06** (2020-03-07) — Archiving (`--archive`) for large-volume analysis.
+- **v1.07** (2020-03-08) — Archiving updates; `construct_hst_archive.py` helper.
+
+## Documentation (Sphinx)
+
+- Expanded sources: `installation.rst` (Python 3.12, Conda, DrizzlePac, DOLPHOT helper), `user_guide.rst` (work-directory layout, CLI overview, redo flags, output formats), `api.rst` (CLI entry point, full `hst123` pipeline class, `options`, `paths`, `stdio`, `workdir_cleanup`, `dolphot_catalog_hdf5`, `datamodels`, `BasePrimitive`).
+
+## Releases
+
+- **Unreleased** — **Python:** **3.12** only (``requires-python`` ``>=3.12,<3.13``; NumPy 1.x / Astropy 5.x / DrizzlePac stack). **Documentation:** Sphinx uses **MyST** (Markdown) + reStructuredText, **sphinx_rtd_theme**, custom CSS/layout (Swift_host_subtraction-style), intersphinx (Python/NumPy/Astropy), and GitHub Pages via CI; README badges for build, docs workflow, and site. `hst123.utils.dolphot_catalog_hdf5`: parse DOLPHOT ``*.columns`` / ``*.param`` / ``*.info`` / ``*.data`` / ``*.warnings`` and write **HDF5** (`pip install h5py` or `pip install .[hdf5]`) with the full numeric catalog plus descriptive column names and JSON metadata (merged per ``imgNNNN`` when possible). ``get_dolphot_column`` uses ``parse_column_index_and_description`` for robust column index parsing. `install_psfs` ends with `relocate_all_legacy_psf_into_canonical_layout`: merges legacy `dolphot2.0/...` **`*.psf`** into the canonical tree for **ACS**, **WFC3** (`wfc3/data`, `wfc3/IR`, `wfc3/UVIS`), and **WFPC2** (`wfpc2/data`), including **sibling** `dolphot2.0/` next to `dolphot3.1/` (common conda layout). `relocate_acs_psf_into_canonical_layout` remains for ACS-only use. `hst123-install-dolphot` applies `apply_dolphot_source_patches` before `make`: patches upstream `dolphot.c` (`main` stack buffer 82→4096 bytes) to avoid macOS `sprintf` overflow / SIGTRAP on long absolute output paths; `--no-source-patches` opts out. `tests/test_dolphot_c_python_parity.py` documents C vs Python parity for calcsky, splitgroups, acsmask, wfc3mask, wfpc2mask (optional binaries + DOLPHOT tree; marker `dolphot_parity`). `hst123.utils.progress_log.LoggedProgress`: throttled `logger.info` progress lines (`#---` bar, %, counts, elapsed, est. total duration, remaining) for reuse; wired to calcsky stage 1 in `write_sky_fits_fallback` / `compute_sky_map_dolphot` (Python per-row updates; **Numba: one full parallel pass** then a single progress completion—no sequential batched kernels that ruined throughput). Disable with `HST123_CALCSKY_PROGRESS=0` or `HST123_PROGRESS_LOG=0`. Optional **`pip install .[perf]`** adds `numba`; `environment.yml` includes `numba` for conda users. `*drc.noise.fits` (sky copy for drizzled stacks) removed in `run_dolphot` and `get_dolphot_photometry` primitive cleanup with `respect_keep_artifacts=False` so they are still removed when `--keep-drizzle-artifacts` is set (not in per-filter astrodrizzle cleanup, which would delete prior filters’ noise). Same glob listed in `settings.pipeline_products` for scripted cleanup; see `tests/test_pipeline_cleanup_validation.py`. Removed legacy CLI `--make-clean`, `--no-large-reduction`, `--large-num` and `hst123.make_clean` / `check_large_reduction`. CI: workflow uses `pip install -e ".[test]"`; `_psf_already_satisfied` treats ACS WFC PAM as present if either `make_root` or `source_dir` has a valid `acs/data` payload; scrape-dolphot unit tests supply minimal `pipeline.options`. Pure-Python DOLPHOT `splitgroups` (`hst123.utils.dolphot_splitgroups`); `HST123_DOLPHOT_SPLITGROUPS_EXTERNAL=1` forces the C binary. `DOLPHOT_REQUIRED_SCRIPTS` no longer lists `splitgroups`. DOLPHOT installer: `ACS_WFC_PAM.tar.gz` extracts under `dolphot2.0/acs/data/`; files are now copied to `acs/data/` and `dolphot_acs_data_dir` prefers directories that contain both PAM FITS. Python `calcsky` port: vectorized second pass (summed-area table); Numba first pass uses precomputed annulus offsets and a per-row scratch buffer (no per-pixel `calloc`).
+
+- **v1.1.0** (2025-03-02) — Post–v1.07: refactored pipeline (utils, primitives), setuptools-scm versioning, tests and docs updates.
+
+*Full releases are added here when tagging. Run from the repo root:*
+*`python scripts/update_changelog.py "Brief summary of changes"`*