Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LauraSilRu/exoplanet-profiler/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through setting up ExoProfiler from a clean environment, downloading the source dataset from the NASA Exoplanet Archive, running each pipeline stage in order, and launching the interactive Streamlit application to explore the discovered planetary families.

​
Prerequisites

ExoProfiler requires Python 3.9 or later. All dependencies are listed in requirements.txt and can be installed in a single step. Jupyter Notebook or JupyterLab is required to execute the pipeline notebooks (it is not in requirements.txt but is available via pip or your preferred environment manager).

​
Installation

1

Clone the repository

git clone https://github.com/LauraSilRu/exoplanet-profiler.git
cd exoplanet-profiler
2

Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate        # macOS / Linux
.venv\Scripts\activate           # Windows
3

Install dependencies

pip install -r requirements.txt
The following packages are installed:
PackagePurpose
PandasTabular data loading and feature engineering
NumPyNumerical array operations and transformations
MatplotlibStatic plots: scree charts, loading heatmaps, distributions
SeabornStatistical visualization and correlation matrices
Scikit-learnPreprocessing pipeline, PCA, K-Means, Silhouette, DBSCAN
PlotlyInteractive 2D/3D PCA scatter plots colored by cluster
StreamlitInteractive web app for exploring planetary families

​
Download the Dataset

ExoProfiler uses the NASA Exoplanet Archive — Planetary Systems (PS) table, filtered to confirmed TESS discoveries with a single default flag per planet. Navigate to the archive URL and export the result as a CSV file named exoplanets.csv, then place it in the data/raw/ directory: 
data/raw/exoplanets.csv
Direct archive URL (TESS confirmed planets, default flag): 
https://exoplanetarchive.ipac.caltech.edu/cgi-bin/TblView/nph-tblView?app=ExoTbls&config=PS&constraint=default_flag=1&constraint=disc_facility+like+%27%25TESS%25%27
The raw file contains 910 rows and 355 columns. After the completeness filter applied during preprocessing, 731 exoplanets (80.33%) are retained for analysis.

​
Feature Configuration

The pipeline operates on exactly 12 feature columns — 7 planetary and 5 stellar variables. These are defined in data/processed/preprocessing_metadata.json and must be present in the downloaded CSV. 
FEATURE_COLUMNS = [
    "pl_orbper",    # Orbital period (days)
    "pl_orbsmax",   # Semi-major axis (AU)
    "pl_rade",      # Planet radius (Earth radii)
    "pl_bmasse",    # Planet mass (Earth masses)
    "pl_orbeccen",  # Orbital eccentricity
    "pl_insol",     # Insolation flux (Earth flux)
    "pl_eqt",       # Equilibrium temperature (K)
    "st_teff",      # Stellar effective temperature (K)
    "st_rad",       # Stellar radius (Solar radii)
    "st_mass",      # Stellar mass (Solar masses)
    "st_met",       # Stellar metallicity [Fe/H]
    "st_logg",      # Stellar surface gravity (log g)
]
Six of these columns are positively skewed and receive a log1p transformation before scaling: 
LOG1P_FEATURES = ["pl_orbper", "pl_orbsmax", "pl_rade", "pl_bmasse", "pl_insol", "st_rad"]
The remaining six are scaled linearly. All 12 are then normalized with RobustScaler and imputed with KNNImputer(n_neighbors=5, weights="distance").

​
Running the Pipeline

Open each notebook in order inside Jupyter Notebook or JupyterLab and run all cells. Each notebook serializes its outputs to data/processed/ for the next stage to consume. 
jupyter notebook
StepNotebookKey output
101_data_understanding.ipynbVariable audit, null-rate report
202_eda.ipynbDistribution and correlation analysis
303_preprocessing.ipynbexoplanets_preprocessed.csv, preprocessing_pipeline.joblib
404_pca_and_cluster_profiling.ipynbpca/pca_model.joblib, pca/pca_scores.csv, cluster profiles
505_clustering_and_evaluation.ipynbclustered_exoplanets.csv, evaluation metrics
Notebooks 4 and 5 are interdependent. Notebook 4 runs PCA and produces the component scores; notebook 5 applies K-Means clustering on those scores and evaluates the result. Run them in order.
See the individual notebook pages for a detailed walkthrough of each stage:

Preprocessing Notebook

Log transforms, RobustScaler, KNNImputer, and completeness filtering that retains 731 of 910 planets.

PCA Notebook

Dimensionality reduction to 4 principal components capturing 90.35% of total variance.

​
Artifact Outputs

After running all five notebooks, the following files are written to data/processed/:
FilePathDescription
Preprocessed feature matrixdata/processed/exoplanets_preprocessed.csv731 × 12 scaled and imputed feature matrix
Preprocessing pipelinedata/processed/preprocessing_pipeline.joblibFitted log1p + RobustScaler + KNNImputer pipeline for reuse on new data
PCA modeldata/processed/pca/pca_model.joblibFitted 4-component PCA model (90.35% retained variance)
PCA scoresdata/processed/pca/pca_scores.csv731 × 4 principal component scores for each planet
Clustered planetsdata/processed/clustered_exoplanets.csv731 planets with Cluster_K2 label and Familia_Planeta family name

​
Applying the Pipeline to New Data

The fitted preprocessing pipeline can be loaded and applied to new planet records without re-running the notebooks: 
import joblib
import pandas as pd

# Load the fitted pipeline
pipeline = joblib.load("data/processed/preprocessing_pipeline.joblib")

# Load the fitted PCA model
pca = joblib.load("data/processed/pca/pca_model.joblib")

# Apply to new data (must contain all 12 FEATURE_COLUMNS)
new_data = pd.read_csv("path/to/new_planets.csv")
X_scaled = pipeline.transform(new_data[FEATURE_COLUMNS])
X_pca = pca.transform(X_scaled)

​
Launch the Streamlit App

Once the pipeline has been run and clustered_exoplanets.csv exists, launch the interactive exploration app: 
streamlit run app/app.py
The app opens at http://localhost:8501 and lets you explore the two discovered planetary families, view cluster profiles, and inspect individual exoplanet records.
The Streamlit app reads from data/processed/clustered_exoplanets.csv. Run all five pipeline notebooks before launching the app, or the app will not find its required input file.

Build docs developers (and LLMs) love

Get started for freeTalk to us