exohab
How Earth-like is that exoplanet? exohab is a small, well-tested Python
toolkit for exploring that question with real data. It can:
- 🌍 compute published habitability metrics: the Earth Similarity Index (ESI), similarity to Mars, Venus or Titan, PHI, BCI, and Kopparapu habitable-zone limits;
- 🛰️ load live data from the NASA Exoplanet Archive, with no API key and with offline caching;
- 🎲 turn measurement error bars into probability distributions with Monte Carlo;
- 🤖 build scikit-learn-ready features; and
- 📊 plot results in one line.
Every formula comes from a peer-reviewed paper or an official data source and is cited in the docstring of the function that implements it. Where the literature has several variants, the exact one used is written down. Nothing is invented.
Installation
pip install exohab
Plots and machine-learning helpers need two optional extras (matplotlib and scikit-learn):
pip install "exohab[all]"
exohab needs Python 3.10 or newer. The core install depends only on numpy,
pandas and requests.
Quick start
🎓 For students: compare worlds to Earth
import exohab as eh
# Two-parameter ESI from radius (Earth radii) and stellar flux (Earth = 1)
print(eh.compute_esi_2p(radius=1.0, flux=1.0)) # Earth -> 1.0
print(eh.compute_esi_2p(radius=0.532, flux=0.431)) # Mars -> ~0.65
print(eh.compute_esi_2p(radius=1.12, flux=0.7005)) # Proxima b -> ~0.87
# Full four-parameter ESI, split into interior and surface parts (Mars)
res = eh.compute_esi_4p(radius=0.53, density=0.71, escape_velocity=0.45, surface_temp=240.0)
print(res.interior, res.surface, res.esi) # ~0.82, ~0.65, ~0.73
# How Mars-like is Earth? (Mars Similarity Index)
print(eh.compute_similarity(1.0, 1.0, 1.0, 288.0, reference="mars").esi) # ~0.68
# Every confirmed planet, plotted against the habitable zone
df = eh.load_nasa_exoplanets()
eh.plot_habitable_zone(df, color_col="esi_2p", labels=["Kepler-442 b", "TOI-700 d"])
🔬 For researchers: propagate asymmetric uncertainties
import exohab as eh
# Kepler-442 b: R = 1.34 +0.11/-0.18 R_E, S = 0.66 +0.23/-0.41 S_E (NASA Exoplanet Archive)
mc = eh.compute_esi_2p_mc(radius=(1.34, 0.11, -0.18), flux=(0.66, 0.23, -0.41),
n_samples=20_000, seed=42, truncate=True)
print(mc.median, mc.ci68, mc.ci95)
# TRAPPIST-1 e, 4-parameter ESI. Density and escape velocity are derived per
# draw from mass and radius, so their correlation is kept. The equilibrium
# temperature (249.7 +/- 2.4 K) is converted to a surface-temperature estimate.
ts = eh.estimate_surface_temp(249.7) # ~283.3 K
mc4 = eh.compute_esi_mc(radius=(0.920, 0.013, -0.012), mass=(0.692, 0.022, -0.022),
surface_temp=(ts, 1.096 * 2.4), n_samples=20_000, seed=42)
print(mc4.median, mc4.components["interior"].median, mc4.components["surface"].median)
eh.plot_mc_distribution(mc4, label="ESI (TRAPPIST-1 e)")
# Uncertainty for the whole catalogue, from the archive's own err1/err2 columns
df = eh.load_nasa_exoplanets(surface_temp_method="kashyap2017")
unc = eh.compute_esi_mc_catalog(df, method="2p", n_samples=2000, seed=0)
df.join(unc).nlargest(10, "esi_2p_mc_median")[
["pl_name", "esi_2p", "esi_2p_mc_median", "esi_2p_mc_ci68_low", "esi_2p_mc_ci68_high"]
]
🤖 For ML engineers: habitability features in a scikit-learn pipeline
import exohab as eh
from sklearn.cluster import KMeans
from sklearn.impute import SimpleImputer
from sklearn.pipeline import make_pipeline
df = eh.load_nasa_exoplanets()
features = eh.HabitabilityFeatureTransformer(surface_temp_method="kashyap2017")
X = features.fit_transform(df) # DataFrame with 15 engineered features
print(list(features.get_feature_names_out()))
model = make_pipeline(
eh.HabitabilityFeatureTransformer(surface_temp_method="kashyap2017"),
SimpleImputer(strategy="median"),
KMeans(n_clusters=4, n_init="auto", random_state=0),
)
df["cluster"] = model.fit_predict(df)
More examples:
examples/quickstart.ipynbis a runnable notebook walkthrough.examples/full_tour.pyis one script that runs and checks every public function.examples/try_exohab.pyis a short check of your installation against published values.
What is included
| Area | Functions | Definition used |
|---|---|---|
| Earth Similarity Index | compute_esi_4p |
Schulze-Makuch et al. (2011): ESI_x = (1 - abs(x-x0)/(x+x0))**w; weights are radius 0.57, density 1.07, escape velocity 0.70 and surface temperature 5.58; interior, surface and global indices are geometric means |
| Two-parameter ESI | compute_esi_2p |
Planetary Habitability Laboratory: 1 - sqrt(0.5*[((S-1)/(S+1))**2 + ((R-1)/(R+1))**2]) |
| Similarity to other bodies | compute_similarity |
Same form with another body's reference values. "mars" is the published Mars Similarity Index (Kashyap Jagadeesh et al. 2017). "venus" and "titan" use NASA fact-sheet values with the Earth ESI weights, because no body-specific weights have been published. Custom dicts also work. |
| Planetary Habitability Index | compute_phi |
(S*E*C*L)**(1/4) (Schulze-Makuch et al. 2011); you supply the factor scores in [0, 1] |
| Biological Complexity Index | compute_bci |
(S*E*T*G*A)**(1/5), optional BCI_rel = BCI/max (Irwin et al. 2014); you supply the factor scores in [0, 1] |
| Surface temperature | estimate_surface_temp |
T_s = 9.650 + 1.096*T_eq (Kashyap Jagadeesh 2017); rocky planets with atmospheres only |
| Habitable zone | kopparapu_seff, hz_distance |
Kopparapu et al. (2014) flux limits: recent Venus, runaway greenhouse (0.1/1/5 Earth masses), maximum greenhouse and early Mars; valid for 2600–7200 K; d = sqrt(L/S_eff) |
| Uncertainty | compute_esi_mc, compute_esi_2p_mc, compute_esi_mc_catalog, sample_split_normal, split_normal_cdf |
Two-piece (split) normal for quotes like x +a -b, with optional truncation at zero |
| Data | load_nasa_exoplanets, add_habitability_columns |
NASA Exoplanet Archive TAP service, pscomppars table |
| Machine learning | HabitabilityFeatureTransformer |
Derived density and escape velocity, ESI scores, interior/surface ratio, HZ fluxes and distances, and in-HZ flags |
| Plots | plot_esi_scatter, plot_habitable_zone, plot_mc_distribution |
matplotlib |
All metric functions accept scalars, lists, NumPy arrays and pandas Series. Series indices are kept. Missing or invalid values give NaN instead of an error, so you can process a whole catalogue in one call.
Scientific notes and limitations
Please read these before using the results in research:
- Surface vs. equilibrium temperature. The four-parameter ESI is defined
with the mean surface temperature (Earth: 288 K). Catalogues list the
equilibrium temperature instead (Earth: about 255 K).
- By default
pl_eqtis used as-is, which lowers the surface ESI of temperate planets. surface_temp_method="kashyap2017"applies an empirical fit to five Solar System bodies instead.- That fit is not valid for gas giants, and it extrapolates above about 255 K.
- By default
- Mass.
pl_bmasseis the archive's "best mass". For radial-velocity planets this may be a minimum mass (M sin i). - ESI measures similarity, not the probability of life. A high ESI means Earth-like bulk properties and insolation, nothing more.
- PHI and BCI need expert factor scores.
exohabimplements only the published formulas that combine those scores. It does not invent scores from raw data. - Monte Carlo inputs are sampled independently. The exception is mass
and radius, whose correlation is kept when you pass
mass.- Missing error bars are treated as zero and flagged in
*_errors_complete. - For those planets the intervals are lower limits on the true uncertainty.
- Missing error bars are treated as zero and flagged in
- Kopparapu habitable-zone limits are NaN outside 2600–7200 K unless you
pass
extrapolate=True.
Data source and acknowledgement
Live data comes from the
NASA Exoplanet Archive.
load_nasa_exoplanets caches each query in ~/.exohab/cache, so later calls
work offline. You can change the location with cache_dir= or the
EXOHAB_CACHE_DIR environment variable, and force a fresh download with
refresh=True.
If you publish results based on this data, the archive asks you to include this acknowledgement:
This research has made use of the NASA Exoplanet Archive, which is operated by the California Institute of Technology, under contract with the National Aeronautics and Space Administration under the Exoplanet Exploration Program.
Behind a corporate proxy or antivirus HTTPS scanning? If you see
SSL: CERTIFICATE_VERIFY_FAILED, install truststore with
pip install truststore. Then run
import truststore; truststore.inject_into_ssl() before loading data. This
uses your operating system's certificate store. Please do not disable
certificate verification.
References
- 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
- Planetary Habitability Laboratory, UPR Arecibo. Earth Similarity Index. https://phl.upr.edu/projects/earth-similarity-index-esi
- Kashyap Jagadeesh, M. (2017). Earth Similarity Index and Habitability Studies of Exoplanets. M.Phil. dissertation, Christ University. arXiv:1801.07101
- Irwin, L. N., Méndez, A., Fairén, A. G., Schulze-Makuch, D. (2014). Assessing the Possibility of Biological Complexity on Other Worlds. Challenges 5(1), 159–174. doi:10.3390/challe5010159
- Kopparapu, R. K. et al. (2013). Habitable Zones around Main-sequence Stars: New Estimates. ApJ 765, 131. arXiv:1301.6674
- Kopparapu, R. K. et al. (2014). Habitable Zones around Main-sequence Stars: Dependence on Planetary Mass. ApJL 787, L29. arXiv:1404.5292
- Wallis, K. F. (2014). The Two-Piece Normal, Binormal, or Double Gaussian Distribution. Statistical Science 29(1), 106–112.
Citing exohab
If exohab helps your work, please cite it:
@software{sivagnanam_exohab,
author = {Sivagnanam, Kailash},
title = {exohab: exoplanet habitability toolkit for Python},
version = {0.2.0},
year = {2026},
license = {MIT}
}
The same metadata is in CITATION.cff. GitHub reads that file
and shows a "Cite this repository" button. Please also cite the original
papers of the metrics you use, listed above.
Contributing and development
git clone https://github.com/kailash9342/exohab.git
cd exohab
pip install -e ".[dev,all]"
pytest
All tests run offline. Network calls to the NASA archive are mocked. Bug reports and suggestions are welcome on the issue tracker.
License
MIT. See LICENSE.
Metadata
Release files for exohab 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| exohab-0.2.0.tar.gz | 408.3 kB | Without provenance | Details for exohab-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| exohab-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for exohab-0.2.0-py3-none-any.whl |
Total release size: 442.9 kB
Release files / exohab-0.2.0.tar.gz
| Download URL | exohab-0.2.0.tar.gz |
|---|---|
| Size | 408.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
15533fcdae1825e84889725525165bc6315e6fb74c4b6d78ac4f5aad715629ef
|
|
BLAKE2b-256 checksum How to use checksums |
fcb1493a2afcc74a361044322b9b2e8609de14337e3940d273ce7d2ee181cb39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Release files / exohab-0.2.0-py3-none-any.whl
| Download URL | exohab-0.2.0-py3-none-any.whl |
|---|---|
| Size | 34.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f1f5d120c0029c080a7ccbfe96638ed1c68c5c97f4991567c5ba437c088320c
|
|
BLAKE2b-256 checksum How to use checksums |
2560dcd916d2ffbec87ce6153c1e6092d283f35743777448957c4c2372797e9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Security for exohab 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.