# PSF Modeling

## Catalog Overview

In [Schutt et al. 2025](https://arxiv.org/abs/2501.05781), we describe the PSF models for the DES Y6 data made with PIFF ([Jarvis et al. 2021](https://arxiv.org/abs/2011.03409)). These PSF models were used in the Y6 weak lensing shape measurements ([Yamamoto & Becker et al. 2025](https://arxiv.org/abs/2501.05665)).

The catalog contains measurements of PSF stars and of the PIFF model interpolated to each star's location. The second- and fourth-order moments were measured using the weight function from the HSM algorithm ([Hirata & Seljak 2003](https://ui.adsabs.harvard.edu/abs/2003MNRAS.343..459H/abstract), [Mandelbaum et al. 2005](https://ui.adsabs.harvard.edu/abs/2005MNRAS.361.1287M/abstract)). The catalog has two samples:

- **reserve**: a random 20% of the candidate PSF stars, which were not used to constrain the PSF models. This is the sample used for all null tests in Schutt et al. 2025.
- **train**: stars used to constrain the PSF models, randomly subsampled to the same size as the reserve sample.

The stars are detected in single-epoch images. The catalog only contains stars from images that were included in the cell-based coadds used for shape measurement (see Yamamoto & Becker et al. 2025). Further, the mask defining the survey footprint for the shear catalog is already applied. Each star is matched to the Y6 Gold catalog (`COADD_OBJECT_ID`), and where possible to the [Gaia EDR3](https://datalab.noirlab.edu/data-explorer?showTable=gaia_edr3.gaia_source) catalog and [VHS DR5](https://datalab.noirlab.edu/data-explorer?showTable=vhs_dr5.vhs_cat_v3) + [VIKING DR1](https://cdsarc.cds.unistra.fr/viz-bin/cat/II/329#/article) catalogs.

## Download

The catalog is a single HDF5 file: piff_y6a2_v3_public_final.h5 (50.3 GB). It can be downloaded [here](TODO).

## Catalog Description

The file contains two groups, `/reserve` and `/train`, with 109,789,926 stars each, from 78,042 exposures in the g, r, i, z bands. Each group lists its column order in a `columns` attribute. Each column is a separate dataset with a `units` attribute.  All section and equation references in the schema refer to Schutt et al. 2025.

| Column Name | Description |
|---|---|
| RA, DEC | Right ascension and declination [degrees] |
| U, V | Position in field-of-view coordinates (arcsec relative to field center at 0,0) |
| X, Y | Position on the CCD [pixels] |
| EXPNUM | Exposure number |
| CCDNUM | DECam CCD number (1–62) |
| BAND | Bandpass of the observation (g, r, i, z) |
| T_DATA | Size of the observed star (Eq. 4.5) [arcsec²] |
| T_MODEL | Size of the PIFF model [arcsec²] |
| G1_DATA, G2_DATA | Second-order shape of the observed star (Eq. 4.6) |
| G1_MODEL, G2_MODEL | Second-order shape of the PIFF model |
| T4_DATA | Spin-0 fourth-order moment of the observed star (Eq. 4.12) [arcsec²] |
| T4_MODEL | Spin-0 fourth-order moment of the PIFF model [arcsec²] |
| G41_DATA, G42_DATA | Spin-2 fourth-order moments of the observed star (Eq. 4.13) |
| G41_MODEL, G42_MODEL | Spin-2 fourth-order moments of the PIFF model |
| DCR_1, DCR_2 | Differential chromatic refraction terms (Eqs. 4.18 & 4.19) |
| G_MAG, R_MAG, I_MAG, Z_MAG | Magnitudes of the matched Y6 Gold object. Sentinel value for missing mag: -99.9. [AB mag] |
| K_MAG | Ks magnitude of the matched VHS/VIKING object. Sentinel value for missing mag: -99.9. [AB mag] |
| FLAG_COLOR | Flag for missing Y6 Gold magnitudes (see Sec. 3.2):<br>• 1 if g-i is unavailable (missing g or i)<br>• 8 if i-z unavailable (missing i or z)<br>• 9 if both are unavailable (e.g., missing i or no Y6 Gold match)<br>• else 0 |
| COADD_OBJECT_ID | Y6 Gold coadd object identifier of the match (0 if unmatched) |
| GAIA_STAR | Flag for match to Gaia source (see Sec. 3.3):<br>• 1 if matched to an isolated Gaia source<br>• 3 if matched, but the DES source has an extreme size (large or small)<br>• 5 if matched to more than one Gaia source within 2″<br>• else 0 |
| GAIA_SOURCE_ID | Gaia EDR3 source ID of the match (0 if unmatched) |
| VHS_SOURCEID | VHS DR5 + VIKING DR1 source ID of the match (0 if unmatched) |

## Usage and Notes

```python
import h5py
with h5py.File('[FILENAME]') as f:
    print(list(f['reserve'].attrs['columns']))
    print(f['reserve/RA'].attrs['units'])
    ra = f['reserve/RA'][:]
```

`U`, `V` are sky coordinates, so the same detector pixel moves by several arcsec in `U`, `V` between exposures. For focal-plane maps that combine many exposures, use `CCDNUM`, `X`, `Y` with [toFocal.py](https://github.com/rmjarvis/DESWL/blob/master/psf/toFocal.py).

Note that `RA` is not wrapped; stars near `RA = 0` may have `RA` slightly below 0 or above 360.