# 2MASS Point Source Catalog sample

`raw/2mass_psc_m31_0p5deg.tbl` is an unmodified IPAC ASCII-table response from the
NASA/IPAC Infrared Science Archive (IRSA) Gator service, drawn from the **2MASS
All-Sky Point Source Catalog (PSC)**.

It is a circular field of view centred on M31:

- Centre: ICRS/J2000 RA 10.6847083 deg, Dec +41.2687500 deg
- Cone radius: 0.5 deg
- Retrieved rows: 9,047
- Retrieval date: 2026-08-25 (recorded in the table header)

The all-sky PSC has hundreds of millions of entries, so it is deliberately not
vendored.  This real-survey slice keeps the repository lightweight while
providing a reproducible replacement for the synthetic latitude/longitude grid.
Run `bash scripts/download_2mass_psc_m31.sh` from any directory to refresh it.

The table preserves the service response.  Its relevant source fields are:

| Field | Meaning |
| --- | --- |
| `ra`, `dec` | ICRS/J2000 right ascension and declination, in degrees |
| `j_m`, `h_m`, `k_m` | 2MASS J, H, and Ks default magnitudes, in mag |
| `dist` | Angular distance from the stated field centre, in arcsec |
| `rd_flg` | Per-band source/read flag needed to interpret the default magnitudes |

`j_m`, `h_m`, and `k_m` may be null in the original PSC.  No temperature is
included or inferred: the PSC provides photometry, not source temperatures.
Do not treat magnitudes as linear fluxes without applying the appropriate 2MASS
band zero points.

`processed/2mass_psc_m31_0p5deg_stars.csv` is generated from the raw table by
`python3 scripts/process_2mass_psc.py`.  It retains only `ra_deg`, `dec_deg`,
`temperature_K`, and `amplitude_sr`.  See its directory README for the fitting
model and quality cut.

`raw/2mass_psc_m44_1p0deg.tbl` is the corresponding unmodified 1.0-degree
cone around M44 (Beehive/Praesepe), centred on ICRS/J2000 RA 129.99165 deg and
Dec +19.54139 deg. It contains 8,790 retrieved PSC rows (2026-08-25) and is
downloaded by
`bash scripts/download_2mass_psc_m44.sh`; process it with:

```sh
python3 scripts/process_2mass_psc.py \
  --input assets/2mass/raw/2mass_psc_m44_1p0deg.tbl \
  --output assets/2mass/processed/2mass_psc_m44_1p0deg_stars.csv
```

The resulting M44 CSV contains 7,802 sources after the documented three-band
photometry and `rd_flg` selection.

## Full-sky acquisition

`scripts/download_2mass_psc_all_sky.py` provides a resumable full-sky
acquisition without asking IRSA for a cone larger than 1 degree. Inspect its
storage plan before starting the long download:

```sh
python3 scripts/download_2mass_psc_all_sky.py --plan
python3 scripts/download_2mass_psc_all_sky.py --download --workers 2
```

It covers each latitude band with integer-RA cone sectors, wider at high
latitudes, while outputs are cleaned and retained by unique 1-degree RA/Dec
ownership cells. Cone overlap cannot create duplicate stars. Temporary raw
tables and cleaning intermediates are stored under `/tmp/2mass_psc_all_sky/`
and deleted after each successful cover. The generated full-sky catalogue has
one CSV per ownership cell under `processed/all_sky/`, named
`tile_raRRR_decDDD.csv`. `RRR` is
`floor(RA_deg mod 360)` and `DDD` is `min(179, floor(Dec_deg + 90))`; the
corresponding range is `[RRR, RRR+1) x [DDD-90, DDD-89)` degrees. It is
intentionally not a single CSV because that would duplicate a roughly 15--17
GiB result during merging.
See that directory's README for restart and raw-retention behavior.

Provenance: [IRSA Gator program interface](https://irsa.ipac.caltech.edu/docs/howto/gator_prog_interface.html),
[2MASS PSC column descriptions](https://irsa.ipac.caltech.edu/2MASS/download/allsky/format_psc.html).