Skip to content

API reference

Everything listed here is available directly from the top-level package, for example exohab.compute_esi_4p. This page is generated from the docstrings in the source code.

Metrics

Planetary habitability and similarity metrics.

All functions are vectorised: they accept Python scalars, lists, NumPy arrays or pandas Series (positional broadcasting). A scalar-only call returns a float; if any input is a Series the result is a Series carrying that Series' index; otherwise an ndarray is returned.

Invalid physical inputs (negative values, NaN, None or infinities) yield NaN rather than raising, so whole catalogues can be processed in one call.

References

.. [SM11] Schulze-Makuch, D. et al. (2011). "A Two-Tiered Approach to Assessing the Habitability of Exoplanets." Astrobiology 11(10), 1041-1052. doi:10.1089/ast.2010.0592 .. [PHL] Méndez, A. Planetary Habitability Laboratory, University of Puerto Rico at Arecibo: "Earth Similarity Index (ESI)", https://phl.upr.edu .. [K17] Kashyap Jagadeesh, M. (2017). "Earth Similarity Index and Habitability Studies of Exoplanets", M.Phil. dissertation, Christ University (arXiv:1801.07101), Sec. 3.2 and Table 3.2; companion paper: Kashyap Jagadeesh, Gudennavar, Doshi & Safonova, "Similarity indexing of exoplanets in search for potential habitability: application to Mars-like worlds", Astrophysics and Space Science (2017). .. [I14] Irwin, L. N., Méndez, A., Fairén, A. G., Schulze-Makuch, D. (2014). "Assessing the Possibility of Biological Complexity on Other Worlds, with an Estimate of the Occurrence of Complex Life in the Milky Way Galaxy." Challenges 5(1), 159-174. doi:10.3390/challe5010159

ESI_WEIGHTS module-attribute

ESI_WEIGHTS: Dict[str, float] = {'radius': 0.57, 'density': 1.07, 'escape_velocity': 0.7, 'surface_temp': 5.58}

ESI weight exponents (Schulze-Makuch et al. 2011, Table 1).

REFERENCE_BODIES module-attribute

REFERENCE_BODIES: Dict[str, Dict[str, Any]] = {'earth': {'radius': 1.0, 'density': 1.0, 'escape_velocity': 1.0, 'surface_temp': 288.0, 'weights': dict(ESI_WEIGHTS), 'source': 'Schulze-Makuch et al. (2011) ESI reference values and weights.'}, 'mars': {'radius': 3390.0 / EARTH_RADIUS_KM, 'density': 3.93 / EARTH_DENSITY_GCC, 'escape_velocity': 5.03 / EARTH_ESCAPE_VELOCITY_KMS, 'surface_temp': 240.0, 'weights': {'radius': 0.86, 'density': 2.1, 'escape_velocity': 1.09, 'surface_temp': 3.23}, 'source': 'Mars Similarity Index, Kashyap Jagadeesh et al. (2017).'}, 'venus': {'radius': 6051.8 / EARTH_RADIUS_KM, 'density': 5.243 / EARTH_DENSITY_GCC, 'escape_velocity': 10.36 / EARTH_ESCAPE_VELOCITY_KMS, 'surface_temp': 737.0, 'weights': dict(ESI_WEIGHTS), 'source': 'Reference values: NASA Planetary Fact Sheet. No body-specific weights are published; the Schulze-Makuch et al. (2011) ESI weights are reused.'}, 'titan': {'radius': 2574.7 / EARTH_RADIUS_KM, 'density': 1.88 / EARTH_DENSITY_GCC, 'escape_velocity': 2.639 / EARTH_ESCAPE_VELOCITY_KMS, 'surface_temp': 94.0, 'weights': dict(ESI_WEIGHTS), 'source': 'Reference values: NASA Saturnian Satellite Fact Sheet. No body-specific weights are published; the Schulze-Makuch et al. (2011) ESI weights are reused.'}}

Built-in reference bodies for :func:compute_similarity.

Radius, density and escape velocity are stored in Earth units; surface temperature in kelvin.

SURFACE_TEMP_METHODS module-attribute

SURFACE_TEMP_METHODS: Dict[str, str] = {'kashyap2017': 'T_s = 9.650 + 1.096 * T_eq (K); least-squares fit to Solar System bodies with a rocky surface and an atmosphere, Kashyap Jagadeesh (2017), eq. 3.12.'}

Available methods for :func:estimate_surface_temp.

ESIResult

Bases: NamedTuple

Interior, surface and global similarity index.

Attributes:

Name Type Description
interior (float, ndarray or Series)

Interior index (radius and bulk density).

surface (float, ndarray or Series)

Surface index (escape velocity and surface temperature).

esi (float, ndarray or Series)

Global index, sqrt(interior * surface).

compute_esi_4p

compute_esi_4p(radius: ArrayLike, density: ArrayLike, escape_velocity: ArrayLike, surface_temp: ArrayLike, weights: Optional[Mapping[str, float]] = None) -> ESIResult

Four-parameter Earth Similarity Index (Schulze-Makuch et al. 2011).

For each property x with Earth reference x0 and weight w::

ESI_x = (1 - |x - x0| / (x + x0)) ** w

and the indices are combined as geometric means::

ESI_I = sqrt(ESI_radius * ESI_density)               # interior
ESI_S = sqrt(ESI_escape_velocity * ESI_temperature)  # surface
ESI   = sqrt(ESI_I * ESI_S)                          # global

This is algebraically identical to the PHL form ESI = prod_i (1 - |(x_i - x_i0)/(x_i + x_i0)|) ** (w_i / n) with n = 4.

Reference values / weights [SM11]_: radius 1 EU (6371 km), w = 0.57; bulk density 1 EU (5.51 g cm^-3), w = 1.07; escape velocity 1 EU (11.19 km s^-1), w = 0.70; mean surface temperature 288 K, w = 5.58.

Parameters:

Name Type Description Default
radius array - like

Mean radius in Earth radii.

required
density array - like

Bulk density in Earth units.

required
escape_velocity array - like

Escape velocity in Earth units.

required
surface_temp array - like

Mean surface temperature in kelvin. Catalogue equilibrium temperatures are not surface temperatures (Earth: T_eq ~ 255 K vs T_s = 288 K); using them as a proxy biases the surface ESI.

required
weights mapping

Override weight exponents (keys radius, density, escape_velocity, surface_temp). Defaults to :data:ESI_WEIGHTS.

None

Returns:

Type Description
ESIResult

Named tuple (interior, surface, esi), each in [0, 1]; NaN where any required input is missing or negative.

Examples:

>>> res = compute_esi_4p(0.53, 0.71, 0.45, 240.0)  # Mars, Kashyap et al. 2017
>>> round(res.esi, 2)
0.73

compute_esi_2p

compute_esi_2p(radius: ArrayLike, flux: ArrayLike) -> Any

Two-parameter (radius + stellar flux) Earth Similarity Index (PHL).

Used by the Planetary Habitability Laboratory for transiting planets where only radius and insolation are known::

ESI = 1 - sqrt( 0.5 * [ ((S - S_E)/(S + S_E))**2 + ((R - R_E)/(R + R_E))**2 ] )

with S_E = 1 (Earth insolation) and R_E = 1 (Earth radius). This is one minus the quadratic mean of the two normalised distances; it is not numerically identical to the 4-parameter ESI. Worked check from arXiv:1712.01040: Proxima b (R = 1.12, S = 0.700522) gives ESI = 0.8692.

Parameters:

Name Type Description Default
radius array - like

Planet radius in Earth radii (>= 0).

required
flux array - like

Stellar insolation flux in Earth units (>= 0).

required

Returns:

Type Description
(float, ndarray or Series)

ESI in [0, 1]; NaN for negative or missing inputs.

compute_similarity

compute_similarity(radius: ArrayLike, density: ArrayLike, escape_velocity: ArrayLike, surface_temp: ArrayLike, reference: Union[str, Mapping[str, Any]] = 'earth', weights: Optional[Mapping[str, float]] = None) -> ESIResult

Similarity of a planet to an arbitrary reference body.

Applies exactly the ESI functional form of :func:compute_esi_4p but with the reference values x0 (and optionally weights) of another body.

Built-in presets (REFERENCE_BODIES):

  • "earth" - standard ESI (Schulze-Makuch et al. 2011).
  • "mars" - Mars Similarity Index (MSI) with its published reference values (3390 km, 3.93 g cm^-3, 5.03 km s^-1, 240 K) and weights (0.86, 2.10, 1.09, 3.23) from Kashyap Jagadeesh et al. (2017).
  • "venus", "titan" - reference values from the NASA planetary / satellite fact sheets. No body-specific weights have been published, so the Earth ESI weights are reused (documented convention, override via weights).

Parameters:

Name Type Description Default
radius array - like

Planet properties in Earth units (also for non-Earth references).

required
density array - like

Planet properties in Earth units (also for non-Earth references).

required
escape_velocity array - like

Planet properties in Earth units (also for non-Earth references).

required
surface_temp array - like

Mean surface temperature in kelvin.

required
reference str or mapping

Preset name (case-insensitive) or a mapping with keys radius, density, escape_velocity (Earth units), surface_temp (K) and optionally weights.

"earth"
weights mapping

Weight exponents overriding those of the reference.

None

Returns:

Type Description
ESIResult

(interior, surface, esi) similarity to the reference body.

Raises:

Type Description
KeyError

Unknown preset or missing keys in a custom reference.

ValueError

Non-positive reference values or weights.

compute_phi

compute_phi(substrate: ArrayLike, energy: ArrayLike, chemistry: ArrayLike, liquid: ArrayLike) -> Any

Planetary Habitability Index (Schulze-Makuch et al. 2011).

PHI = (S * E * C * L) ** (1/4)

the geometric mean of four factor scores for a stable substrate (S), available energy (E), appropriate polymeric chemistry (C) and a liquid solvent (L). Each factor must already be scored on [0, 1] following the categorical rubric of [SM11]_ - this function performs the combination only and does not invent a scoring of raw physical parameters.

Parameters:

Name Type Description Default
substrate array - like

Factor scores in [0, 1].

required
energy array - like

Factor scores in [0, 1].

required
chemistry array - like

Factor scores in [0, 1].

required
liquid array - like

Factor scores in [0, 1].

required

Returns:

Type Description
(float, ndarray or Series)

PHI in [0, 1]; NaN where any factor is outside [0, 1] or missing.

compute_bci

compute_bci(substrate: ArrayLike, energy: ArrayLike, temperature: ArrayLike, geophysics: ArrayLike, age: ArrayLike, relative: bool = False) -> Any

Biological Complexity Index (Irwin et al. 2014).

BCI_abs = (S * E * T * G * A) ** (1/5)

the geometric mean of factor scores for substrate (S), energy (E), temperature (T), geophysical activity (G) and age (A). The relative index is BCI_rel = BCI_abs / max(BCI_abs) over the evaluated set [I14]_.

Each factor must be pre-scored on [0, 1] using the rubric of [I14]_; this function implements only the published combination step.

Parameters:

Name Type Description Default
substrate array - like

Factor scores in [0, 1].

required
energy array - like

Factor scores in [0, 1].

required
temperature array - like

Factor scores in [0, 1].

required
geophysics array - like

Factor scores in [0, 1].

required
age array - like

Factor scores in [0, 1].

required
relative bool

If True return BCI_rel (normalised by the maximum finite BCI_abs among the inputs) instead of BCI_abs.

False

Returns:

Type Description
(float, ndarray or Series)

BCI in [0, 1]; NaN where any factor is outside [0, 1] or missing.

density_from_mass_radius

density_from_mass_radius(mass: ArrayLike, radius: ArrayLike) -> Any

Bulk density in Earth units from mass and radius in Earth units.

rho / rho_E = (M / M_E) / (R / R_E)**3 (uniform-sphere definition of bulk density).

Parameters:

Name Type Description Default
mass array - like

Planet mass in Earth masses.

required
radius array - like

Planet radius in Earth radii.

required

Returns:

Type Description
(float, ndarray or Series)

Bulk density in Earth units; NaN where mass < 0 or radius <= 0.

escape_velocity_from_mass_radius

escape_velocity_from_mass_radius(mass: ArrayLike, radius: ArrayLike) -> Any

Escape velocity in Earth units from mass and radius in Earth units.

From v_e = sqrt(2 G M / R): v_e / v_e,E = sqrt((M / M_E) / (R / R_E)).

Parameters:

Name Type Description Default
mass array - like

Planet mass in Earth masses.

required
radius array - like

Planet radius in Earth radii.

required

Returns:

Type Description
(float, ndarray or Series)

Escape velocity in Earth units; NaN where mass < 0 or radius <= 0.

estimate_surface_temp

estimate_surface_temp(teq: ArrayLike, method: str = 'kashyap2017') -> Any

Estimate mean surface temperature from equilibrium temperature.

Exoplanet catalogues list the equilibrium temperature T_eq, but the 4-parameter ESI is defined with the mean surface temperature (Earth: T_eq ~ 255 K, T_s = 288 K).

method="kashyap2017" uses the linear relation [K17]_ (eq. 3.12)::

T_s = 9.650 + 1.096 * T_eq

fitted to Earth, Mars, the Moon, Titan and Triton (T_eq ~ 34-255 K); Venus, with its runaway greenhouse, was excluded from the fit. With the published (rounded) coefficients it gives 289.1 K for Earth (T_eq = 255 K) and 247.5 K for Mars (T_eq = 217 K); the source's Table 3.3 lists 289.28 K and 247.61 K, the small difference coming from coefficient rounding.

.. warning:: The relation is empirical, rests on five bodies, and only applies to rocky planets with an atmosphere. It is not meaningful for gas giants, and is an extrapolation for T_eq above ~255 K.

Parameters:

Name Type Description Default
teq array - like

Equilibrium temperature in K.

required
method str

Key of :data:SURFACE_TEMP_METHODS.

"kashyap2017"

Returns:

Type Description
(float, ndarray or Series)

Estimated surface temperature in K; NaN for non-positive or missing teq.

Habitable zone

Circumstellar habitable-zone boundaries from Kopparapu et al. (2014).

The effective stellar flux at each boundary is a 4th-order polynomial fit::

S_eff = S_eff_sun + a*T + b*T**2 + c*T**3 + d*T**4,   T = T_eff - 5780 K

and the corresponding orbital distance is d = sqrt(L / S_eff) AU with L in solar luminosities (Kopparapu et al. 2013, eq. 3).

Coefficients are copied verbatim from the authors' public calculator hzcalc.py (R. K. Kopparapu, 2014) for a 1 Earth-mass planet, plus the 5 and 0.1 Earth-mass runaway-greenhouse limits. The fits are valid for 2600 K <= T_eff <= 7200 K.

References

Kopparapu, R. K. et al. (2014), ApJL 787, L29, arXiv:1404.5292. Kopparapu, R. K. et al. (2013), ApJ 765, 131, arXiv:1301.6674.

KOPPARAPU_2014 module-attribute

KOPPARAPU_2014: Dict[str, Tuple[float, float, float, float, float]] = {'recent_venus': (1.776, 0.0002136, 2.533e-08, -1.332e-11, -3.097e-15), 'runaway_greenhouse': (1.107, 0.0001332, 1.58e-08, -8.308e-12, -1.931e-15), 'maximum_greenhouse': (0.356, 6.171e-05, 1.698e-09, -3.198e-12, -5.575e-16), 'early_mars': (0.32, 5.547e-05, 1.526e-09, -2.874e-12, -5.011e-16), 'runaway_greenhouse_5me': (1.188, 0.0001433, 1.707e-08, -8.968e-12, -2.084e-15), 'runaway_greenhouse_0.1me': (0.99, 0.0001209, 1.404e-08, -7.418e-12, -1.713e-15)}

Kopparapu et al. (2014) HZ coefficients.

Conservative HZ: runaway_greenhouse (inner) to maximum_greenhouse (outer). Optimistic HZ: recent_venus (inner) to early_mars (outer).

TEFF_RANGE module-attribute

TEFF_RANGE: Tuple[float, float] = (2600.0, 7200.0)

Stellar effective temperature range (K) over which the fits are valid.

kopparapu_seff

kopparapu_seff(teff: ArrayLike, limit: str = 'runaway_greenhouse', extrapolate: bool = False) -> Any

Effective stellar flux at a habitable-zone boundary.

Parameters:

Name Type Description Default
teff array - like

Stellar effective temperature in K.

required
limit str

One of the keys of :data:KOPPARAPU_2014.

"runaway_greenhouse"
extrapolate bool

If False, return NaN for teff outside 2600-7200 K, where the published fit is not valid.

False

Returns:

Type Description
(float, ndarray or Series)

Effective flux S_eff in units of the present solar constant at Earth.

hz_distance

hz_distance(luminosity: ArrayLike, seff: ArrayLike, log_luminosity: bool = False) -> Any

Orbital distance (AU) receiving effective flux seff.

d = sqrt(L / S_eff) (Kopparapu et al. 2013, eq. 3).

Parameters:

Name Type Description Default
luminosity array - like

Stellar luminosity in solar units, or log10(L/L_sun) if log_luminosity is True (as in the NASA st_lum column).

required
seff array - like

Effective flux from :func:kopparapu_seff.

required
log_luminosity bool

Interpret luminosity as log10.

False

Returns:

Type Description
(float, ndarray or Series)

Distance in AU; NaN for non-positive luminosity or flux.

Uncertainty

Monte Carlo propagation of (asymmetric) measurement errors into the ESI.

Each input may be

  • a float - treated as exact (no uncertainty);
  • (nominal, err) - symmetric 1-sigma error;
  • (nominal, plus_err, minus_err) - asymmetric 1-sigma errors. The sign of minus_err is ignored, so NASA Exoplanet Archive err1/err2 pairs (e.g. +0.11/-0.18) can be passed directly.

Asymmetric errors are sampled from the two-piece ("split") normal distribution, the standard interpretation of x^{+a}_{-b} quotes: a normal with sigma b below the mode and sigma a above, joined continuously at the mode. Draws fall below the mode with probability b / (a + b); the mean is mode + sqrt(2/pi) * (a - b) (Wallis 2014, "The two-piece normal, binormal, or double Gaussian distribution", Statistical Science 29, 106).

Parameters are sampled independently unless mass is supplied to :func:compute_esi_mc, in which case density and escape velocity are derived per draw from the same (radius, mass) pair so their correlation is preserved.

Non-physical draws (radius, mass, flux, temperature <= 0) are handled in one of two ways:

  • truncate=False (default): they yield NaN in the metric and are discarded; n_valid reports how many remain.
  • truncate=True: they are redrawn (rejection sampling), i.e. each input follows the split normal truncated at zero and n_valid == n_samples.

Both correspond to the same truncated input distribution; truncate=True just keeps the requested sample size.

MCResult dataclass

MCResult(mean: float, median: float, std: float, ci68: Tuple[float, float], ci95: Tuple[float, float], samples: ndarray, n_valid: int, n_samples: int, components: Dict[str, 'MCResult'] = dict())

Summary of a Monte Carlo distribution.

Attributes:

Name Type Description
mean, median, std float

Sample mean, median and standard deviation (ddof=1).

ci68 tuple of float

Central 68.27% interval (15.865th - 84.135th percentiles).

ci95 tuple of float

Central 95% interval (2.5th - 97.5th percentiles). Use :meth:interval for other levels.

samples ndarray

Valid (finite) samples.

n_valid int

Number of valid samples.

n_samples int

Number of draws requested.

components dict

Sub-results (e.g. "interior", "surface" for the 4-parameter ESI).

from_samples classmethod

from_samples(samples: ndarray, n_samples: Optional[int] = None) -> 'MCResult'

Build a summary from raw draws (non-finite values are dropped).

interval

interval(level: float) -> Tuple[float, float]

Central credible interval containing fraction level of samples.

to_dict

to_dict() -> Dict[str, Any]

Plain-dict summary (without the sample array).

compute_esi_mc

compute_esi_mc(radius: Measurement, density: Optional[Measurement] = None, escape_velocity: Optional[Measurement] = None, surface_temp: Optional[Measurement] = None, *, mass: Optional[Measurement] = None, n_samples: int = 10000, seed: SeedLike = None, weights: Optional[Mapping[str, float]] = None, truncate: bool = False) -> MCResult

Monte Carlo distribution of the 4-parameter ESI.

Either give density and escape_velocity directly, or give mass (Earth masses) and leave them as None; then per draw density = M / R**3 and escape_velocity = sqrt(M / R) (Earth units), which keeps their physical correlation through the shared radius and mass.

Parameters:

Name Type Description Default
radius float or tuple

Radius in Earth radii (see module docstring for tuple formats).

required
density float or tuple

In Earth units. Required unless mass is given.

None
escape_velocity float or tuple

In Earth units. Required unless mass is given.

None
surface_temp float or tuple

Mean surface temperature in K.

None
mass float or tuple

Mass in Earth masses.

None
n_samples int

Number of Monte Carlo draws.

10000
seed int or Generator

Seed for reproducibility.

None
weights mapping

ESI weight overrides (see :func:exohab.compute_esi_4p).

None
truncate bool

Redraw non-positive input draws instead of discarding them.

False

Returns:

Type Description
MCResult

Global-ESI summary; components["interior"] and components["surface"] hold the sub-index distributions.

compute_esi_2p_mc

compute_esi_2p_mc(radius: Measurement, flux: Measurement, *, n_samples: int = 10000, seed: SeedLike = None, truncate: bool = False) -> MCResult

Monte Carlo distribution of the 2-parameter (radius + flux) ESI.

Parameters:

Name Type Description Default
radius float or tuple

Radius in Earth radii, e.g. (1.34, 0.11, -0.18).

required
flux float or tuple

Insolation in Earth units.

required
n_samples int

Number of draws.

10000
seed int or Generator

Seed for reproducibility.

None
truncate bool

Redraw non-positive input draws instead of discarding them.

False

Returns:

Type Description
MCResult

Summary of the ESI distribution.

compute_esi_mc_catalog

compute_esi_mc_catalog(df: DataFrame, method: str = '2p', n_samples: int = 2000, seed: SeedLike = None, truncate: bool = False, radius_col: str = 'pl_rade', flux_col: str = 'pl_insol', mass_col: str = 'pl_bmasse', temp_col: str = 'pl_eqt', surface_temp_method: Optional[str] = None, chunk_size: int = 500) -> DataFrame

Monte Carlo ESI distribution summaries for every row of a catalogue.

Uses the NASA Exoplanet Archive error convention: for a column x the 1-sigma errors are in xerr1 (upper) and xerr2 (lower, negative). Each planet's inputs are sampled from split normals (see module docstring).

  • method="2p" - radius and insolation (:func:exohab.compute_esi_2p).
  • method="4p" - radius, mass and temperature; density and escape velocity are derived per draw from mass and radius (correlated). temp_col is used as surface temperature unless surface_temp_method is given (then it is converted per draw with :func:exohab.estimate_surface_temp).

Rows with a missing nominal value get NaN summaries. A missing error is treated as zero (exact value) and flagged by *_errors_complete = False, so such intervals are lower limits on the true uncertainty.

Parameters:

Name Type Description Default
df DataFrame

Catalogue, e.g. from :func:exohab.load_nasa_exoplanets.

required
method ('2p', '4p')

Which ESI to propagate.

"2p"
n_samples int

Draws per planet.

2000
seed int or Generator

Seed for reproducibility.

None
truncate bool

Redraw non-positive input draws instead of discarding them.

False
radius_col str

Column names.

'pl_rade'
flux_col str

Column names.

'pl_rade'
mass_col str

Column names.

'pl_rade'
temp_col str

Column names.

'pl_rade'
surface_temp_method str

e.g. "kashyap2017" (4p only).

None
chunk_size int

Rows processed per vectorised batch (bounds memory use).

500

Returns:

Type Description
DataFrame

Same index as df with columns esi_{method}_mc_mean, _median, _std, _ci68_low, _ci68_high, _ci95_low, _ci95_high, _n_valid and _errors_complete.

sample_split_normal

sample_split_normal(nominal: float, plus_err: float, minus_err: float, size: int, rng: Optional[Generator] = None, lower: Optional[float] = None) -> ndarray

Draw from a two-piece (split) normal distribution.

Parameters:

Name Type Description Default
nominal float

Mode of the distribution (the quoted value).

required
plus_err float

Upper and lower 1-sigma widths (absolute values are used).

required
minus_err float

Upper and lower 1-sigma widths (absolute values are used).

required
size int

Number of draws.

required
rng Generator

Random generator; a fresh default generator is used if omitted.

None
lower float

If given, sample the distribution truncated to x > lower by rejection (draws <= lower are redrawn).

None

Returns:

Type Description
ndarray

size samples.

Raises:

Type Description
ValueError

If lower excludes more than 99.9% of the probability mass (the measurement is inconsistent with the bound).

split_normal_cdf

split_normal_cdf(x: Any, nominal: float, plus_err: float, minus_err: float) -> Any

Cumulative distribution function of the two-piece normal.

With s1 = minus_err, s2 = plus_err and Phi the standard normal CDF::

F(x) = 2 s1 / (s1 + s2) * Phi((x - mu) / s1)                    x <  mu
F(x) = (s1 + s2 * (2 Phi((x - mu) / s2) - 1)) / (s1 + s2)      x >= mu

Parameters:

Name Type Description Default
x float or array - like

Evaluation points.

required
nominal float

Mode and 1-sigma widths.

required
plus_err float

Mode and 1-sigma widths.

required
minus_err float

Mode and 1-sigma widths.

required

Returns:

Type Description
float or ndarray

P(X <= x).

parse_measurement

parse_measurement(value: Measurement) -> Tuple[float, float, float]

Normalise a measurement to (nominal, plus_err, minus_err).

Parameters:

Name Type Description Default
value float or sequence

x, (x, err) or (x, plus_err, minus_err).

required

Returns:

Type Description
tuple of float

Nominal value and non-negative upper / lower 1-sigma errors.

Raises:

Type Description
ValueError

Wrong tuple length or non-finite values.

Data

Live data from the NASA Exoplanet Archive (no API key required).

Queries the Table Access Protocol (TAP) synchronous endpoint for the Planetary Systems Composite Parameters table (pscomppars: one row per confirmed planet, best available value per column) and caches the raw CSV in ~/.exohab/cache (override with EXOHAB_CACHE_DIR or cache_dir).

Column meanings follow the archive's documentation: pl_rade radius [R_earth], pl_bmasse best mass [M_earth] (true mass or M sin i), pl_dens density [g/cm^3], pl_insol insolation [S_earth], pl_eqt equilibrium temperature [K], st_teff [K], st_lum [log10(L/L_sun)].

DEFAULT_COLUMNS module-attribute

DEFAULT_COLUMNS: tuple = ('pl_name', 'hostname', 'discoverymethod', 'disc_year', 'pl_orbper', 'pl_orbsmax', 'pl_rade', 'pl_radeerr1', 'pl_radeerr2', 'pl_bmasse', 'pl_bmasseerr1', 'pl_bmasseerr2', 'pl_dens', 'pl_insol', 'pl_insolerr1', 'pl_insolerr2', 'pl_eqt', 'pl_eqterr1', 'pl_eqterr2', 'st_teff', 'st_lum', 'st_mass', 'st_rad', 'sy_dist')

TAP_URL module-attribute

TAP_URL = 'https://exoplanetarchive.ipac.caltech.edu/TAP/sync'

load_nasa_exoplanets

load_nasa_exoplanets(columns: Optional[Sequence[str]] = None, where: Optional[str] = None, cache_dir: Optional[Union[str, Path]] = None, refresh: bool = False, max_age_days: Optional[float] = None, timeout: float = 120.0, add_metrics: bool = True, session: Optional[Session] = None, surface_temp_method: Optional[str] = None) -> DataFrame

Load confirmed exoplanets from the NASA Exoplanet Archive.

The first call downloads pscomppars through the TAP API (no API key) and writes the raw CSV to the cache; later calls with the same query read the cache and work offline. If a refresh fails because the network is unavailable, the cached copy is returned with a warning.

Parameters:

Name Type Description Default
columns sequence of str

Archive columns to select (default :data:DEFAULT_COLUMNS). Columns needed for the ESI are always included.

None
where str

ADQL filter, e.g. "pl_rade < 2".

None
cache_dir str or Path

Cache location (default :func:default_cache_dir).

None
refresh bool

Ignore the cache and re-download.

False
max_age_days float

Re-download if the cache file is older than this. None = never expire.

None
timeout float

HTTP timeout in seconds.

120
add_metrics bool

Append derived columns via :func:add_habitability_columns.

True
session Session

Session to use for the HTTP request.

None
surface_temp_method str

Passed to :func:add_habitability_columns; e.g. "kashyap2017" to estimate surface temperature from pl_eqt for the 4-parameter ESI.

None

Returns:

Type Description
DataFrame

One row per planet.

Raises:

Type Description
RequestException or RuntimeError

If the download fails and no cached copy exists.

add_habitability_columns

add_habitability_columns(df: DataFrame, radius_col: str = 'pl_rade', mass_col: str = 'pl_bmasse', density_col: Optional[str] = 'pl_dens', flux_col: str = 'pl_insol', surface_temp_col: str = 'pl_eqt', surface_temp_method: Optional[str] = None) -> DataFrame

Append derived Earth-unit properties and ESI columns.

Added columns:

  • density_eu - M / R**3 when mass and radius exist, otherwise pl_dens / 5.51.
  • escape_velocity_eu - sqrt(M / R); if mass is missing but radius and density exist, R * sqrt(rho_eu) (same physics: M = rho R^3).
  • esi_2p - radius + insolation ESI (:func:exohab.compute_esi_2p).
  • esi_4p_interior, esi_4p_surface, esi_4p - 4-parameter ESI.
  • surface_temp_est - only when surface_temp_method is given.

The temperature used for the 4-parameter ESI is recorded in out.attrs["esi_4p_temperature"].

.. warning:: Exoplanet catalogues list equilibrium temperature, not surface temperature. By default (surface_temp_method=None) pl_eqt is used directly against the 288 K reference. This is a proxy and systematically lowers the surface ESI of temperate planets (Earth: T_eq ~ 255 K). Pass surface_temp_method="kashyap2017" to convert it first with :func:exohab.estimate_surface_temp (rocky planets with atmospheres only), or point surface_temp_col at modelled surface temperatures.

Parameters:

Name Type Description Default
df DataFrame

Input table (not modified).

required
radius_col str

Column names to use.

'pl_rade'
mass_col str

Column names to use.

'pl_rade'
density_col str

Column names to use.

'pl_rade'
flux_col str

Column names to use.

'pl_rade'
surface_temp_col str

Column names to use.

'pl_rade'
surface_temp_method str

If given, surface_temp_col is treated as equilibrium temperature and converted with :func:exohab.estimate_surface_temp.

None

Returns:

Type Description
DataFrame

Copy of df with the extra columns.

build_query

build_query(columns: Optional[Iterable[str]] = None, where: Optional[str] = None) -> str

Build the ADQL query sent to the TAP service.

Parameters:

Name Type Description Default
columns iterable of str

Columns to select; the columns needed for the ESI are always added.

None
where str

ADQL WHERE clause body, e.g. "pl_rade < 2 and sy_dist < 50".

None

Returns:

Type Description
str

ADQL query string.

default_cache_dir

default_cache_dir() -> Path

Cache directory: $EXOHAB_CACHE_DIR or ~/.exohab/cache.

Machine learning

scikit-learn compatible habitability feature engineering.

Requires the optional dependency scikit-learn (pip install exohab[ml] or exohab[all]). Importing this module without it does not fail; instantiating the transformer raises a clear ImportError.

FEATURE_NAMES module-attribute

FEATURE_NAMES: List[str] = ['density_eu', 'escape_velocity_eu', 'esi_2p', 'esi_4p_interior', 'esi_4p_surface', 'esi_4p', 'esi_interior_surface_ratio', 'hz_seff_inner', 'hz_seff_outer', 'hz_seff_inner_optimistic', 'hz_seff_outer_optimistic', 'hz_inner_au', 'hz_outer_au', 'in_conservative_hz', 'in_optimistic_hz']

HabitabilityFeatureTransformer

HabitabilityFeatureTransformer(radius_col: str = 'pl_rade', mass_col: str = 'pl_bmasse', density_col: Optional[str] = 'pl_dens', flux_col: str = 'pl_insol', surface_temp_col: str = 'pl_eqt', teff_col: str = 'st_teff', luminosity_col: str = 'st_lum', luminosity_is_log: bool = True, keep_original: bool = False, surface_temp_method: Optional[str] = None)

Bases: TransformerMixin, BaseEstimator

Engineer habitability features from raw planetary/stellar columns.

Features produced (see :data:FEATURE_NAMES):

  • density_eu, escape_velocity_eu - from mass and radius.
  • esi_2p, esi_4p_interior, esi_4p_surface, esi_4p - see :func:exohab.data.add_habitability_columns (equilibrium temperature is used as a surface-temperature proxy unless another column is given).
  • esi_interior_surface_ratio - interior / surface ESI.
  • hz_seff_inner / hz_seff_outer - conservative HZ flux limits (runaway / maximum greenhouse) and *_optimistic (recent Venus / early Mars), Kopparapu et al. (2014), valid for 2600-7200 K (NaN outside).
  • hz_inner_au / hz_outer_au - conservative HZ distances, sqrt(L / S_eff).
  • in_conservative_hz / in_optimistic_hz - 1.0 if the planet's insolation lies within the flux limits, 0.0 if not, NaN if unknown.

Parameters:

Name Type Description Default
radius_col str

Input column names (NASA Exoplanet Archive defaults).

'pl_rade'
mass_col str

Input column names (NASA Exoplanet Archive defaults).

'pl_rade'
density_col str

Input column names (NASA Exoplanet Archive defaults).

'pl_rade'
flux_col str

Input column names (NASA Exoplanet Archive defaults).

'pl_rade'
surface_temp_col str

Input column names (NASA Exoplanet Archive defaults).

'pl_rade'
teff_col str

Input column names (NASA Exoplanet Archive defaults).

'pl_rade'
luminosity_col str

Input column names (NASA Exoplanet Archive defaults).

'pl_rade'
luminosity_is_log bool

luminosity_col holds log10(L/L_sun) (as st_lum does).

True
keep_original bool

If True, return the input columns followed by the new features.

False
surface_temp_method str

e.g. "kashyap2017" to convert equilibrium to surface temperature before computing the 4-parameter ESI (see :func:exohab.estimate_surface_temp).

None
Notes

The transformer is stateless: fit only validates the input and records column names. Input must be a pandas DataFrame.

fit

fit(X: DataFrame, y: Any = None) -> 'HabitabilityFeatureTransformer'

Validate X and record its columns. Returns self.

transform

transform(X: DataFrame) -> DataFrame

Return the engineered feature DataFrame (same index as X).

get_feature_names_out

get_feature_names_out(input_features: Any = None) -> ndarray

Names of the output columns.

Plots

One-line plots for habitability results.

Requires the optional dependency matplotlib (pip install exohab[viz] or exohab[all]). Importing this module never fails; calling a plot function without matplotlib raises a clear ImportError.

plot_esi_scatter

plot_esi_scatter(df: DataFrame, interior_col: str = 'esi_4p_interior', surface_col: str = 'esi_4p_surface', esi_col: Optional[str] = 'esi_4p', name_col: Optional[str] = 'pl_name', top_n: int = 10, threshold: float = 0.8, isolines: tuple = (0.6, 0.8), ax: Optional[Any] = None) -> Any

Interior vs. surface ESI scatter with quadrants and labelled top candidates.

Dashed lines at threshold split the plane into quadrants (Earth-like interior and/or surface). Dotted curves are isolines of constant global ESI, surface = ESI**2 / interior since ESI = sqrt(I * S).

Parameters:

Name Type Description Default
df DataFrame

Table with interior and surface ESI columns.

required
interior_col str

Column names of the sub-indices.

'esi_4p_interior'
surface_col str

Column names of the sub-indices.

'esi_4p_interior'
esi_col str

Global ESI column used for colouring and ranking; computed as sqrt(I * S) if missing or None.

'esi_4p'
name_col str

Column with labels for the top candidates.

'pl_name'
top_n int

Number of highest-ESI rows to label (0 disables labels).

10
threshold float

Quadrant divider (PHL "Earth-like" threshold).

0.8
isolines tuple of float

Global-ESI levels drawn as isolines.

(0.6, 0.8)
ax matplotlib Axes

Axes to draw on; a new figure is created if omitted.

None

Returns:

Type Description
Axes

plot_habitable_zone

plot_habitable_zone(df: DataFrame, flux_col: str = 'pl_insol', teff_col: str = 'st_teff', name_col: Optional[str] = 'pl_name', labels: Optional[list] = None, color_col: Optional[str] = None, ax: Optional[Any] = None) -> Any

Stellar effective temperature vs. insolation with Kopparapu (2014) HZ bands.

The conservative habitable zone (runaway to maximum greenhouse) is shaded dark green and the optimistic one (recent Venus to early Mars) light green, over the 2600-7200 K range where the fits are valid. The insolation axis is logarithmic and inverted (hot planets on the left), as in Kopparapu et al. (2013, 2014).

Parameters:

Name Type Description Default
df DataFrame

Table with insolation (Earth units) and stellar effective temperature.

required
flux_col str

Column names.

'pl_insol'
teff_col str

Column names.

'pl_insol'
name_col str

Column holding planet names, used with labels.

'pl_name'
labels list of str

Planet names to annotate.

None
color_col str

Column used to colour the points (e.g. "esi_2p").

None
ax matplotlib Axes

Axes to draw on.

None

Returns:

Type Description
Axes

plot_mc_distribution

plot_mc_distribution(result: MCResult, bins: int = 60, label: str = 'ESI', ax: Optional[Any] = None) -> Any

Histogram of Monte Carlo samples with median and 68% / 95% intervals.

Parameters:

Name Type Description Default
result MCResult

Output of :func:exohab.compute_esi_mc or :func:exohab.compute_esi_2p_mc.

required
bins int

Number of histogram bins.

60
label str

x-axis label.

"ESI"
ax matplotlib Axes

Axes to draw on.

None

Returns:

Type Description
Axes