tract7dt 0.2.0

7DT image-specific Tractor photometry pipeline

tract7dt

7DT image-specific Tractor photometry pipeline. This distribution is licensed under MIT.

Installation

1. Install Tractor (see https://github.com/dstndstn/tractor; however the upstream README seems outdated; use the recommended steps below).
2. Install this package:

python -m pip install tract7dt

Tractor and astrometry.net must be installed separately. Python prerequisites like numpy, scipy, astropy, photutils, sep, matplotlib, fitsio, emcee, and PyYAML are declared as dependencies.

Tractor installation (recommended)

1) Conda environment

conda create -n {envname} python=3.11 -y
conda activate {envname}

2) System dependencies (apt)

sudo apt update
sudo apt install -y build-essential python3-dev git pkg-config \
    libcfitsio-dev libeigen3-dev swig libceres-dev \
    libgoogle-glog-dev libgflags-dev libsuitesparse-dev

3) Python build tools + scientific stack

pip install -U pip setuptools wheel cython numpy scipy fitsio emcee matplotlib

4) astrometry.net (required by Tractor)

conda install -c conda-forge astrometry -y

5) Tractor build (Cython + Ceres enabled)

git clone https://github.com/dstndstn/tractor.git
cd tractor
python setup.py build_ext --inplace --with-ceres --with-cython
pip install . --no-build-isolation

6) Verify install

python -c "import tractor; print(tractor.__version__)"
python -c "from tractor.ceres_optimizer import CeresOptimizer; print('CeresOptimizer OK')"
python examples/tractor-sdss-synth.py

Quick start

1. Create a YAML config (see tract7dt/data/sample_config.yaml or generate one below).

# Writes sample_config.yaml in the current directory by default.
tract7dt dump-config

# Or write to a specific path.
tract7dt dump-config --out sample_config.yaml

# Use --force option to overwrite an existing file.
tract7dt dump-config --force

2. Run the full pipeline:

tract7dt run --config /path/to/config.yaml

Commands

• run: full pipeline (load → ePSF → patches → patch inputs → patch runs → merge)

• run-epsf: initial load + build ePSF only

• build-patches: build patch definitions only

• build-patch-inputs: build patch inputs only

• run-patches: run Tractor on patch inputs

• merge: merge patch results into final catalog

• dump-config: write the sample config to a file

Inputs and formats

Image list

• Directs the pipeline which image files to use.
• inputs.image_list_file is a text file with one FITS path per line.
• Blank lines and # comments are allowed.
• Relative paths are resolved against the directory of the YAML config.

Input catalog

• Defines which sources to fit and their basic parameters.
• Must contain RA/DEC columns (case-insensitive). RA/DEC is recommended.
• Recommended columns: ID (used as merge key; otherwise RA/DEC is used) and TYPE (defaults to patch_run.gal_model if missing).
• Optional columns: FLUX_{band}, ELL, THETA, Re. If missing, the pipeline estimates initial guesses from the images.
• If FLUX_{band} columns exist, they must match the image FILTER headers.
• Units: RA/DEC in deg; FLUX_{band} in image pixel units; ELL, THETA, Re follow Source Extractor conventions (pixels, degrees, pixels).

Required FITS headers

• Required: FILTER, ZP_AUTO, SKYSIG, EGAIN, and standard WCS keys.
• Recommended: SATURATE (improves masking).
• Recommended: PEEING or SEEING (used for Moffat fallback when ePSF is missing).

WCS alignment requirements

• Input images must be pre-aligned and share the same WCS (CRVAL/CRPIX/CD or CDELT/PC) within the configured tolerances. This is typically satisfied if you use combined images from the 7DT pipeline (e.g., gppy or py7dt).
• By default, the pipeline enforces WCS alignment and identical image shapes (checks.require_wcs_alignment and checks.require_same_shape).

Path resolution

• Inputs resolve relative to the config file location.
• Outputs resolve relative to outputs.work_dir unless an absolute path is used.

Outputs

With the current sample config, outputs.work_dir contains:

• ePSF outputs: EPSFs/
• patch definitions: patches/
• patch payloads: patch_payloads/
• patch results: outputs/
• merged catalog: output_catalog.csv
• crop/overlay PNGs: cropped_images/

Each patch output directory includes per-patch logs, {tag}_cat_fit.csv, cutout montages, and an optional patch overview PNG.

Notes and behavior

• WCS alignment and shape checks are enforced when enabled.
• Crop filtering removes catalog rows outside the crop region.
• patch_run.resume=true skips patches that already have {tag}_cat_fit.csv. Use with care if you changed config values.
• merge run standalone requires merge.wcs_fits; in the full pipeline this is taken from inputs automatically.

References

• Parameter mapping reference: docs/CONFIG_MAPPING.md.