binny.surveys.sky module#

Conversion functions for sky areas and surface densities.

binny.surveys.sky.arcmin2_to_deg2(area_arcmin2: float) → float#

Converts survey area in arcmin^2 to deg^2.

Parameters:: area_arcmin2 – Survey area in square arcminutes.
Returns:: Survey area in square degrees.
Raises:: ValueError – If area_arcmin2 is negative.

binny.surveys.sky.arcmin2_to_sr(area_arcmin2: float) → float#

Converts an area in arcmin^2 to steradians.

Parameters:: area_arcmin2 – Area in square arcminutes.
Returns:: Area in steradians.
Raises:: ValueError – If area_arcmin2 is negative.

binny.surveys.sky.area_to_arcmin2(area: float, unit: str = 'arcmin2') → float#

Converts a survey area to square arcminutes (arcmin^2).

This is a small convenience wrapper around the explicit conversion helpers in this module. It is intended for APIs that accept survey areas in common sky units (arcmin^2, deg^2, or sr) but standardize internally to arcmin^2.

Supported unit strings:

"arcmin2" or "arcmin^2": square arcminutes (returned unchanged).
"deg2" or "deg^2": square degrees.
"sr", "steradian", "steradians": steradians.

Notes

A survey area of 0 is allowed but likely indicates a user mistake. This function emits a warning in that case.
Conversion factors follow the definitions used by this module: 1 deg^2 = 3600 arcmin^2 and 1 sr = (180/pi)^2 deg^2.

Parameters:

area – Area value to convert.
unit – Unit string describing the input area.

Returns:

Area converted to square arcminutes (arcmin^2).

Raises:

ValueError – If area is negative.
ValueError – If unit is not one of the supported strings.

binny.surveys.sky.deg2_to_arcmin2(area_deg2: float) → float#

Converts survey area in deg^2 to arcmin^2.

Parameters:: area_deg2 – Survey area in square degrees.
Returns:: Survey area in square arcminutes.
Raises:: ValueError – If area_deg2 is negative.

binny.surveys.sky.deg2_to_f_sky(area_deg2: float) → float#

Converts survey area in deg^2 to sky fraction f_sky.

Parameters:: area_deg2 – Survey area in square degrees.
Returns:: Sky fraction f_sky in [0, 1].
Raises:: ValueError – If area_deg2 is negative.

binny.surveys.sky.deg2_to_sr(area_deg2: float) → float#

Converts survey area in deg^2 to steradians.

Parameters:: area_deg2 – Survey area in square degrees.
Returns:: Survey area in steradians.
Raises:: ValueError – If area_deg2 is negative.

binny.surveys.sky.density_arcmin2_to_sr(density_per_bin: Mapping[int, float]) → dict[int, float]#

Converts per-bin densities from gal/arcmin^2 to gal/sr.

This multiplies by the conversion factor arcmin^2 per steradian.

Parameters:: density_per_bin – Mapping bin -> density in gal/arcmin^2.
Returns:: Mapping bin -> density in gal/sr.
Raises:: ValueError – If any density is negative.

binny.surveys.sky.density_sr_to_arcmin2(density_per_bin: Mapping[int, float]) → dict[int, float]#

Converts per-bin densities from gal/sr to gal/arcmin^2.

This divides by the conversion factor arcmin^2 per steradian.

Parameters:: density_per_bin – Mapping bin -> density in gal/sr.
Returns:: Mapping bin -> density in gal/arcmin^2.
Raises:: ValueError – If any density is negative.

binny.surveys.sky.density_to_per_arcmin2(density: float, unit: str = 'arcmin2') → float#

Converts a surface number density to galaxies per square arcminute.

This helper standardizes surface densities to gal/arcmin^2. It is useful for binning and noise/covariance utilities that accept densities expressed per deg^2 or per steradian but store and compute internally in per-arcmin^2 units.

Interpretation of unit:

The unit describes the area in the denominator of the density, i.e. density is interpreted as galaxies per unit area.

Supported unit strings:

"arcmin2" or "arcmin^2": galaxies per square arcminute (identity).
"deg2" or "deg^2": galaxies per square degree.
"sr", "steradian", "steradians": galaxies per steradian.

Notes

This function enforces a non-negative density.
Conversion uses the same factors as the area conversions: 1 deg^2 = 3600 arcmin^2 and 1 sr = (180/pi)^2 deg^2.

Parameters:

density – Surface number density value to convert.
unit – Unit string describing the input density denominator.

Returns:

Density converted to galaxies per square arcminute (gal/arcmin^2).

Raises:

ValueError – If density is negative.
ValueError – If unit is not one of the supported strings.

binny.surveys.sky.f_sky_to_deg2(f_sky: float) → float#

Converts sky fraction f_sky to survey area in deg^2.

Parameters:: f_sky – Sky fraction in [0, 1].
Returns:: Survey area in square degrees.
Raises:: ValueError – If f_sky is not in [0, 1].

binny.surveys.sky.f_sky_to_sr(f_sky: float) → float#

Converts sky fraction f_sky to survey area in steradians.

Parameters:: f_sky – Sky fraction in [0, 1].
Returns:: Survey area in steradians.
Raises:: ValueError – If f_sky is not in [0, 1].

binny.surveys.sky.sr_to_arcmin2(area_sr: float) → float#

Converts an area in steradians to arcmin^2.

Parameters:: area_sr – Area in steradians.
Returns:: Area in square arcminutes.
Raises:: ValueError – If area_sr is negative.

binny.surveys.sky.sr_to_deg2(area_sr: float) → float#

Converts survey area in steradians to deg^2.

Parameters:: area_sr – Survey area in steradians.
Returns:: Survey area in square degrees.
Raises:: ValueError – If area_sr is negative.

binny.surveys.sky.sr_to_f_sky(area_sr: float) → float#

Converts survey area in steradians to sky fraction f_sky.

Parameters:: area_sr – Survey area in steradians.
Returns:: Sky fraction f_sky in [0, 1].
Raises:: ValueError – If area_sr is negative.