Skip to main content

exohab

CI PyPI Python License: MIT

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:

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_eqt is 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.
  • Mass. pl_bmasse is 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. exohab implements 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.
  • 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)

Source distribution for exohab 0.2.0
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)

Table of built distributions (wheels) for exohab 0.2.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page