Output column convention

Output column convention#

Injected catalogs use a single, uniform naming scheme for every column the injector produces, and it is always survey-namespaced — even for a single survey.

The scheme#

Every column is prefixed with the survey’s namespace, which is {name}_{release} (e.g. lsst_yr5, roman_dc2), or just {name} when the survey was loaded without a release. The namespace is always derived from the Survey itself (streamobs.surveys.Survey.namespace). Observed, error, and flag columns carry the full namespace (release included), so the same survey at two releases produces distinct, non-colliding observations. True-magnitude columns are the exception: because a star’s intrinsic (noiseless) magnitude does not depend on which survey/release observed it, they are keyed on the survey name only — the release is dropped (e.g. roman_F158_true, shared across roman_dc2 and roman_hlwas_*). When you construct a multi-survey injector from a {key: spec} dict the keys are containers only — they do not become the namespace (it is re-derived from each loaded Survey).

For a survey with namespace <survey> (= {name}_{release}), survey name <name>, and a photometric band <band>:

Column

Meaning

<name>_<band>_true

True (noiseless) apparent magnitude — keyed on the survey name only (release-independent)

<survey>_<band>_obs

Observed (noisy) magnitude; "BAD_MAG" where the noisy flux went negative

<survey>_<band>_err

Reported photometric error (the catalog error; see below)

<survey>_flag_observed

Detection flag — True if detected and classified as a star

<survey>_flag_perfect_galstarsep

Optional flag assuming perfect star/galaxy separation (detection only); emitted only when perfect_galstarsep=True

Plus the shared, un-namespaced sky coordinates ra, dec.

Examples (LSST loaded with release="yr5", Roman with release="dc2"): lsst_yr5_r_obs, lsst_yr5_g_err, roman_F158_true (true mag — name only), lsst_yr5_flag_observed.

These names are produced by the helpers in streamobs.columns (true_col, obs_col, err_col, flag_col, perfect_flag_col), which take a band and a survey namespace.

Important

This convention intentionally drops the historical mag_<band> / mag_<band>_obs / magerr_<band> names and the un-namespaced single-survey form (r_obs, flag_observed, …). It is not backward compatible with catalogs or downstream readers expecting those columns — everything is now namespaced by survey, even when only one survey is injected.

Two error curves: catalog vs. sample#

Each survey carries two photometric-error curves, both functions of delta_mag = mag − maglim:

  • Catalog error — the survey’s reported error (e.g. SExtractor magerr). This is what is written to <survey>_<band>_err, and it drives the S/N detection cut.

  • Sample error — an optional curve giving the true scatter of observed − true magnitudes. This is what is used to draw the observed magnitude (<survey>_<band>_obs).

The split exists because, for the Roman DC2 catalogs, the true photometric scatter is ≈ 2× the reported error — so the noise you draw and the error you report are genuinely different. When a survey has no sample curve loaded, the sample draw transparently falls back to the catalog curve, so the two are identical and outputs match the single-curve behaviour.

Select between them via streamobs.surveys.Survey.get_photo_error() with kind="catalog" (default, reproduces the reported error) or kind="sample" (true scatter).

See also#

Contents