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, |
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 |
None
|
Returns:
| Type | Description |
|---|---|
ESIResult
|
Named tuple |
Examples:
compute_esi_2p
¶
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 viaweights).
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 |
"earth"
|
weights
|
mapping
|
Weight exponents overriding those of the reference. |
None
|
Returns:
| Type | Description |
|---|---|
ESIResult
|
|
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 |
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
¶
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 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 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: |
"kashyap2017"
|
Returns:
| Type | Description |
|---|---|
(float, ndarray or Series)
|
Estimated surface temperature in K; NaN for non-positive or missing
|
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
¶
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: |
"runaway_greenhouse"
|
extrapolate
|
bool
|
If False, return NaN for |
False
|
Returns:
| Type | Description |
|---|---|
(float, ndarray or Series)
|
Effective flux |
hz_distance
¶
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 |
required |
seff
|
array - like
|
Effective flux from :func: |
required |
log_luminosity
|
bool
|
Interpret |
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 ofminus_erris ignored, so NASA Exoplanet Archiveerr1/err2pairs (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_validreports how many remain.truncate=True: they are redrawn (rejection sampling), i.e. each input follows the split normal truncated at zero andn_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: |
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. |
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 |
None
|
escape_velocity
|
float or tuple
|
In Earth units. Required unless |
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: |
None
|
truncate
|
bool
|
Redraw non-positive input draws instead of discarding them. |
False
|
Returns:
| Type | Description |
|---|---|
MCResult
|
Global-ESI summary; |
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. |
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_colis used as surface temperature unlesssurface_temp_methodis 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: |
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. |
None
|
chunk_size
|
int
|
Rows processed per vectorised batch (bounds memory use). |
500
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Same index as |
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 |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
split_normal_cdf
¶
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
|
|
parse_measurement
¶
Normalise a measurement to (nominal, plus_err, minus_err).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
float or sequence
|
|
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')
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: |
None
|
where
|
str
|
ADQL filter, e.g. |
None
|
cache_dir
|
str or Path
|
Cache location (default :func: |
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
|
timeout
|
float
|
HTTP timeout in seconds. |
120
|
add_metrics
|
bool
|
Append derived columns via :func: |
True
|
session
|
Session
|
Session to use for the HTTP request. |
None
|
surface_temp_method
|
str
|
Passed to :func: |
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**3when mass and radius exist, otherwisepl_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 whensurface_temp_methodis 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, |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Copy of |
build_query
¶
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 |
None
|
Returns:
| Type | Description |
|---|---|
str
|
ADQL query string. |
default_cache_dir
¶
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
|
|
True
|
keep_original
|
bool
|
If True, return the input columns followed by the new features. |
False
|
surface_temp_method
|
str
|
e.g. |
None
|
Notes
The transformer is stateless: fit only validates the input and
records column names. Input must be a pandas DataFrame.
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
|
'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 |
'pl_name'
|
labels
|
list of str
|
Planet names to annotate. |
None
|
color_col
|
str
|
Column used to colour the points (e.g. |
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: |
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
|
|