# 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:

```bash
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).

```bash
# 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:

```bash
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`.
