# Planet catalogs and populations: standalone science exercise

This folder can be copied outside Sandbox Physics. Its Python programs do not import the website, a protected Lab Engine, private source code or an account token.

There are two exercises. The synthetic example includes every input and runs offline. The real exercise uses a fixed earlier-Gaia K-star parent, official Kepler DR25 injections and externally supplied candidate classifications. It conditions on a restricted searched population; it does not reproduce a published radius-valley measurement.

## Install and verify

Use CPython 3.9–3.12. The checked reference environment is CPython 3.9, NumPy 2.0.2 and SciPy 1.13.1 on Apple Silicon. Other BLAS implementations can change the last digits or a stochastic chain trajectory; the output checker uses numerical tolerances and exploration diagnostics.

```sh
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 verify_inputs.py .
python3 offline_checks.py --out rerun-offline.json
python3 verify_synthetic.py --fixtures expected/synthetic-reference-fixtures.json --out rerun-synthetic.json
```

The offline example simulates 30,000 independent surveys from a known Poisson planet population and Bernoulli selection. It checks one specified one-sided upper-bound coverage point against an independent discrete sum, an integer classification mixture against direct integration, the zero-information prior limit and a known radius-migration matrix. This is not coverage certification over all parameter values.

The separate synthetic-reference program compares the website's frozen numerical records with Cartesian stellar-disk slices, adaptive finite-exposure integration, explicit event enumeration, SciPy Gamma quantiles and independent Monte Carlo. These are checks of the declared uniform-star, known-period template model.

## Obtain the two author inputs once

The fixed `stevepur/DR25-occurrence-tutorial` tree at `5eda15caeb3ba6204b34a4e9975738b527e3704d` has no identified license. Its parent ZIP, candidate CSV, notebook, pickles and row-level derivatives are therefore absent here. A GPL license in the separate later `DR25-occurrence-public` repository does not establish rights for this earlier source.

```sh
python3 fetch_author_inputs.py input
```

This is the first network step. The named client `SandboxPhysics-Public-Tutorial/1.0` obtains two anonymous, fixed original GitHub URLs and verifies complete sizes and SHA-256 before accepting them:

| Original | Bytes | SHA-256 |
| --- | ---: | --- |
| Earlier-Gaia K stellar ZIP | 3818428 | `c6da1271280a4aa978e3718663db54bbca9f5fe606f050a8334ba7084ce8d1eb` |
| GK candidate CSV | 603563 | `785085c6e1fcd22f2fc01570e0efa36ce4e12d1f8efaaadf43f6ec4ed7d461ee` |

Total author-source transfer is 4,421,991 bytes. A receipt distinguishes actual HTTP 200 acquisition from an already verified local cache. An unavailable or changed source stops the exercise. Source ownership stays with the authors; this download instruction grants no redistribution permission.

The two complete NASA injection source gzip files are already in `input/`, with original URLs, decoded counts and hashes in `SOURCES.json`. They are public mission products with their source attribution. No incomplete response is supplied as usable input.

## Recompute the real exercise offline

After the dependencies and author files are obtained, these commands make no network requests:

```sh
python3 replay.py --inputs input --out-dir rerun --sensitivities
python3 verify_outputs.py --expected expected --actual rerun
```

Omit `--sensitivities` for only the primary fit, independent posterior check, medium/fine exposure, rate family and Cartesian transfer check. The option also repeats both coherent reported stellar-radius shifts and the independently refitted source-Expected-MES condition. The unanchored physical-depth condition is always computed by the occurrence program. The sequence takes several minutes and prints each stage as it starts; fitting and finite-domain integration are real computations.

Individual stages remain available: `fit_magnitude_response.py`, `check_survey_calibration.py`, `survey_exposure.py`, `occurrence_family.py` and `verify_transfer.py`. Their `--help` output names every path option. The final occurrence program without an explicit `--exposure` also checks medium/fine convergence, 1024/2048 calibration draws and two alternative proper priors.

## What the result means

The author parent contains 16,107 stars; 12,363 have complete INJ1 matches. This intersection includes 11,985 stars without any listed candidate. In the declared ten-to-thirty-day, two-to-four-nominal-Earth-radius region, supplied radius ratios and nominal constants select 79 candidate rows. The stored author radius convention selects 80. The constant convention and counts are preserved separately.

The response uses 2202 trials over ten to one hundred days and source durations 1.5–15 hours. There are 914 same-period PC recoveries and 3 recognized alias-PC recoveries. The actual table's code 2 is checked against the half/double or third/triple period ratios permitted in KSCI-19110. Every failed recovery remains a Bernoulli failure. Held-out folds use whole target identities.

The saved pooled response failed magnitude-subgroup checks. The final five-coordinate response includes a magnitude shift, proper priors and eight independent chains with 24,000 retained positions each after 5000 discarded adaptation steps. Full correlated chains, including rejected/repeated positions, are supplied. An independent full-support Student-t importance integral checks posterior moments. Computational agreement cannot establish observational completeness.

The final signal proxy uses source aperture-corrected depth, log-log interpolation of measured CDPP and post-cut span times duty cycle divided by period. Its training median ratio to supplied Expected_MES is about 1.229. The earlier 1.315 comparison used a different linear-CDPP/weighted-transit feature and filters. Expected_MES already includes the source's stated correction. It is not corrected again.

For hypothetical radii, the main map retains each target's source-depth/four-coefficient-profile scale, whose median is 1.246. This is not identified as pure crowding and is never replaced by its average. The unanchored-depth and refitted source-MES maps are separate conditions. Whole-target held-out tests use source features; one injection per target does not independently validate new physical-radius-to-signal transfer across the whole domain. The source-MES condition leaves 444 source-duration mappings unavailable and carries them as unknown response.

Empirical recovery already includes the source cadence/window. No extra window factor is multiplied into it. All searched stars remain in the exposure. Measured CDPP, signal and magnitude support define where the response is calibrated; they are not observed-catalog cuts. True injection impact and duration do not replace fitted catalog observables. Outside support, including the uncalibrated finite-radius grazing shell, recovery ranges from zero to one. These bounds enter the final likelihood and posterior family.

The main known-response exposure median is about 210.876 effective stars; the unidentified geometric contribution is about 161.699. The posterior median family spans about 0.205–0.362 planet per searched star, with outer 95-percent envelope 0.162–0.450. Each unknown-response condition has its own proper posterior; the envelope is not one unique posterior interval or a distribution over unknown response. The unanchored-depth and source-MES alternatives give different conditional exposures and rate families. A change in mapping can move signals into the calibrated domain, increasing supported exposure.

Classifications form a proper mixture over integer latent catalogs using fixed external GK reliability probabilities. This modular analysis does not estimate a K-star false-event intensity jointly with occurrence. A rate degeneracy requires a generative false-event model and control data. The within-region shape is fixed uniform in logarithmic period and radius. The true full radius-valley profile is outside this slice.

Reported stellar-radius shifts move all planets of each host together and recompute both candidate membership and all-star exposure. They are sensitivity cases, not covariance-aware stellar/transit posterior draws. They do not replace the separate depth-mapping or unknown-support conditions. Mass, CDPP and limb coefficients stay fixed in these shifts.

## File boundaries

`expected/` contains aggregate reference JSON, the primary and source-MES full calibration chains, and aggregate exposure kernels. Per-star amplitude factors and mapping-validity arrays are deliberately omitted from delivered reference NPZs. Running on the separately obtained source tables may create local per-star intermediates; source rights still apply to them. The generated archive hashes in producer JSON refer to the original local outputs; the delivered-byte manifest `hashes.json` is authoritative for sanitized reference archive identity.

`history/` retains the earlier pooled magnitude failure, same-period-only definition, failed low-order period quadrature and failed three-point exposure calculation. These are historical records, not final estimates. The final exposure reference uses contact-split 16-point integration; the independent adaptive check resolves the earlier approximately 66.8 ppm error to about 0.000293 ppm in the checked states.

New independent Python code is under `LICENSE-code.txt`. Source datasets and cited papers retain their respective ownership; see `SOURCES.json`. No paper figure, author notebook/pickle, protected Engine or website executable is redistributed in this package.