EROTICA is a Python package for analyzing star clusters using machine learning and Bayesian inference. Built for Gaia data, it uses unsupervised clustering to identify open star clusters and characterize their membership, ages, and structure.
📖 Documentation · Membership guide · API reference
pip install eroticagit clone https://github.com/notluquis/erotica.git
cd erotica
pip install -e ".[dev,docs]"- Python 3.13 or higher (this is
requires-python, not a recommendation — older versions cannot install the package) - See
pyproject.tomlfor the complete dependency list and the optional extras (bayes,selection,examples,docs,dev)
import erotica
# Load and preprocess
loader = erotica.DataLoader("your_gaia_catalog.ecsv")
data = loader.load_data(systems=["Gaia", "TMASS"])
preprocessor = erotica.DataPreprocessor(data)
preprocessor.apply_zero_point_correction()
good_data, bad_data = preprocessor.filter_data(fidelity_threshold=0.5)
# Membership: sweep min_cluster_size, score by recovery frequency x strength.
# `columns` IS the feature-space choice — 2D proper motion is the safe default.
# Mixing units (adding parallax) requires standardizing the columns first;
# see the membership guide for the trade-offs.
clusterer = erotica.Clustering(good_data, bad_data)
clusterer.search_pseudoprobability(columns=("pmra", "pmdec"))
clusterer.clustering_statistics()
summary = clusterer.get_cluster_summary()
clusterer.save_results("members.ecsv", format="ascii.ecsv")Downstream analysis (isochrone fitting, structure, dynamics) goes through
ClusterAnalyzer, which is constructed from a saved catalog — see the
quickstart.
erotica/
├── erotica/ # 📦 Main package
│ ├── core/ # 🔧 HDBSCAN clustering + membership
│ ├── io/ # 📊 Data loading and I/O
│ ├── preprocess/ # 🧹 Data preprocessing
│ ├── analysis/ # 📈 Isochrones, structure, dynamics, inference
│ │ ├── structure.py # radial profiles: King, EFF, Plummer, King+corona
│ │ ├── identifiability.py # is this parameter measured, or is the prior answering?
│ │ ├── synthetic.py # fractal cluster generation, for validation
│ │ └── provenance.py # git SHA, checksums, seeds, dependency versions
│ ├── selection.py # 🔭 Gaia DR3 selection function
│ ├── calibration.py # 🎯 Probability calibration
│ └── utils/ # 🛠️ Utility functions
├── docs/ # 📚 Sphinx documentation
│ ├── guides/ # User guides (membership, …)
│ ├── design-notes/ # Grounded method notes
│ └── api/ # Auto-generated API reference
├── tools/ # 🔧 Development + release tooling
│ └── validation/ # every quoted number has a script here
├── data/test/NGC6383/ # 🔬 Paper reproduction artifacts
└── tests/ # 🧪 Test suite
Profiles are fitted as an unbinned inhomogeneous Poisson point process, Σ log λ(rᵢ) − Λ, so
there is no bin width to choose and no Gaussian approximation to break in the sparse outer bins that
set the truncation radius. Four families share the machinery and are scored against each other by
SMC Bayes factor:
| model | when |
|---|---|
| King (1962) | the empirical standard. Note the additive background is not King's — see the docstring |
| EFF (Elson, Fall & Freeman 1987) | no tidal cutoff; the honest model when truncation is not locatable |
| Plummer | EFF(γ = 4) |
| King + uniform-sphere corona (Danilov & Putkov 2012; Seleznev 2016) | when the flat background is absorbing cluster structure rather than field |
Each carries a closed-form normalisation verified against quadrature, because the integral is evaluated at every leapfrog step.
erotica.analysis.identifiability answers "is this parameter measured, or is the prior answering for
it?" — before it is quoted. Four angles, because a parameter can pass one and fail another:
power-scaling prior sensitivity (Kallioinen et al. 2024), posterior geometry and condition number,
relative width, and the Muñoz et al. (2012) geometric criteria. It exists because this project
repeatedly reported numbers the data did not determine and found out late.
HDBSCAN with persistence thresholding and a hyperparameter sweep scored by recovery frequency × strength. The resulting pseudo-probability is calibrated against an external benchmark rather than assumed to be a probability, and a target–decoy construction measures the false-discovery proportion independently of the fit.
Gaia DR3 completeness via gaiaunlimited, foldable directly into the point-process normalisation, so
a radial completeness gradient enters the likelihood rather than being corrected afterwards.
fractal_cluster implements the Goodwin & Whitworth (2004) box-fractal construction — still the live
standard in 2026 — because drawing test data from a smooth profile begs the question when the thing
under test is a profile fit.
build_metadata records git SHA and dirty flag, input-data checksums, RNG seeds, sampler
configuration and dependency versions. A result without those is not reproducible, only repeatable.
Stated up front because the alternative is a referee stating it:
- A tidal radius is often prior-determined. For a footprint that does not contain the cluster,
R_tis unconstrained regardless of how well the sampler converged. AnyR_tmust name its prior. - The EFF slope is not recoverable at typical Gaia-census geometry. The controlling variable is the footprint-to-scale ratio, not the sample size.
- Circular symmetry is assumed and is the exception — median core axis ratio 0.71, computed here from Tarricq et al. (2022)'s published table, not quoted from their text (they report the distribution as peaking at 0.8–0.9).
- On a membership-selected sample the background term is not contamination. It absorbs the corona, and for one cluster it accounts for 56% of the sample against a 6.1% measured false-discovery rate.
Each of these is measured, scripted under tools/validation/, and written up in
docs/design-notes/.
Written once because three reviewers ask for it: pyOpenSci's review template asks for a comparison to similar packages, JOSS requires a State of the field section, and Astropy's affiliated criteria ask that a package avoid duplicating existing functionality.
Supported Python: 3.13+ (CI runs 3.13 and 3.14).
| package | what it does that EROTICA does not | overlap |
|---|---|---|
| ASteCA | The standard for photometric synthetic clusters and CMD fitting: IMF, mass-dependent binary fraction fitted to Offner et al. (2023), extinction with free R_V, differential reddening, errors calibrated on the observed cluster. Cite it; do not compete with it. |
membership; a private, unwired least-squares King fit |
| ocelot | Injects mock clusters into real Gaia DR3 with a two-stage selection function and error twin-resampling — 80,590 injection/retrievals behind the census completeness function. | radial profiles (it ships King62 only) |
| Kalkayotl | Bayesian cluster distances with parallax spatial correlations (Lindegren et al. 2020), which EROTICA does not model. The strongest error model in the Bayesian open-cluster set. | distance inference |
| gaiaunlimited | The Gaia DR3 selection function itself. EROTICA uses it rather than reimplementing it. | — |
| pyUPMASK / UPMASK | Membership by iterative clustering plus a random-field null. | membership |
| SPISEA | Stellar population synthesis: IMF, multiplicity, extinction, IFMR. No spatial structure. | — |
What is distinctive here, stated narrowly enough to survive checking:
- Radial profiles as an unbinned inhomogeneous Poisson point process, with King, EFF, Plummer and King-plus-corona compared by Bayes factor under one likelihood.
- A selection function folded into the normalisation rather than applied as an after-the-fact correction.
- An identifiability toolkit that asks whether a parameter is measured before it is quoted.
What is not distinctive, and is documented as such: Bayesian King fitting is not new — Pera et al. (2021, 2024) precede it. EFF fits to Galactic open clusters as a population are not new either; Cordoni et al. (2023) fit 78 and Pang et al. (2022) fit 82. Claims of novelty in this project have been falsified seven times, so they are checked before they are written.
Full documentation: erotica.readthedocs.io
Resolved 2026-08-03. This block used to warn that the Read the Docs slug was still
cosmic-clustersand thaterotica.readthedocs.iowould 404. That is no longer true, and the paragraph had also been corrupted by the rename pass — it printed the same URL on both sides of "while", so it read as a contradiction and then instructed future editors not to fix it. Measured directly:erotica.readthedocs.io/en/latest/→ HTTP 200,cosmic-clusters.readthedocs.io/en/latest/→ HTTP 404. The link above is correct; use it.
- Membership — which features to cluster on, error-aware membership, calibration, and the trade-offs of each choice
- API reference
- Design notes — grounded notes on the isochrone sampler, model grids, and HDBSCAN membership
Build the docs locally with pip install -e ".[docs]" && sphinx-build -b html docs docs/_build/html.
# Automated development environment setup
python tools/dev/setup_environment.py# Install in development mode
pip install -e ".[dev,docs]"
# Set up pre-commit hooks
pre-commit install
# Run tests
pytest
# Run comprehensive test suite
python tools/testing/run_comprehensive_tests.pyruff replaced black + isort + flake8. It is what .pre-commit-config.yaml actually runs,
so it is what gates a commit; the three tools this section used to name are no longer installed by
the dev extra.
# Lint and autofix, then format — the same two hooks pre-commit runs
ruff check --fix erotica/ tests/
ruff format erotica/ tests/
# Types (deliberately NOT a pre-commit hook — too slow for the commit loop)
mypy erotica/ --ignore-missing-imports
# Or just install the hooks and let them run on every commit
pre-commit installCurrent version: v0.1.0 — released 2026-08-03, tagged, published to
PyPI and archived on Zenodo
(10.5281/zenodo.21769959). This block claimed
"v0.0.1 (Alpha) — active development for v0.1.0" until 2026-08-04, when pyproject.toml,
CITATION.cff and CHANGELOG.md had all said 0.1.0 for a day.
Development status: v0.1.0 is the version the JOSS submission describes. The API is not yet frozen; see the roadmap below.
Tests: the full suite runs in CI on Python 3.13 and 3.14, plus a job that installs the bayes
extra so the sampler paths actually execute, and a docs job that builds the site. Audited by
mutation rather than by coverage. (No test count is quoted here on purpose — a count in prose is
stale by the next commit. Run pytest --collect-only -q for the current figure; paper/paper.md
quotes one pinned to the v0.1.0 tag, which is fixed and citable.)
Documentation: erotica.readthedocs.io — API reference, user guides and design notes.
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run the test suite:
pytest -q(what CI runs, and whatCONTRIBUTING.mdsays) - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
If EROTICA contributes to work you publish, please cite it. Machine-readable metadata is in
CITATION.cff, which GitHub renders as a "Cite this repository" button.
@software{erotica,
author = {Pulgar-Escobar, Lucas},
title = {{EROTICA}: Estimation, Recovery \& Optimization, together with Inference,
for Cluster Analysis},
version = {0.1.0},
year = {2026},
doi = {10.5281/zenodo.21769959},
url = {https://github.com/notluquis/erotica},
license = {AGPL-3.0-or-later}
}The DOI above is the concept DOI and always resolves to the latest version; use
10.5281/zenodo.21769960 to pin v0.1.0 exactly. The author field is spelled to match
CITATION.cff — it read Pulgar, Lucas M. until 2026-08-04, so the two files disagreed on the
family name and would have produced two different citations for one release.
A software paper is under review. Once it has a DOI,
CITATION.cff'spreferred-citationfield will redirect GitHub's citation button to it and supersede this entry.
Please also cite the methods you actually used, which are not ours: King (1962) or Elson, Fall &
Freeman (1987) for the profile you fitted, Hunt & Reffert (2024) for census cross-matches,
Cantat-Gaudin et al. (2023) via gaiaunlimited for the selection function, Kallioinen et al. (2024)
for the power-scaling diagnostics, and Goodwin & Whitworth (2004) for the synthetic generator. Each
is cited at the point of use in the API documentation.
EROTICA is licensed under the GNU Affero General Public License v3.0. This ensures that any modifications or derivative works remain open source.
Lucas Pulgar-Escobar — Universidad de Concepción, Chile (lescobar2019@udec.cl, ORCID 0009-0008-4359-2444)
Sole author, matching CITATION.cff and paper/paper.md. This
section read "Team" and listed two people until 2026-08-04, contradicting both — the kind of
discrepancy a JOSS editor queries. Every commit in the v0.1.0 release is from a single contributor,
and JOSS holds that financial and organizational contributions are not sufficient for co-authorship;
those who supported the work are acknowledged below instead.
I thank Nicolás Henríquez Salgado (Universidad de Concepción) for his contribution to the companion NGC 6383 science paper, and P. Cerulo for guidance on machine-learning methods and for discussions of Bayesian modelling with PyMC during the work that led to this package.
I gratefully acknowledge support from the ANID BASAL project FB210003 and the SOCHIAS GEMINI project 32230014, and financial support from the Dirección de Postgrado, Universidad de Concepción, through its MSc scholarship programme.
EROTICA builds upon excellent open-source libraries:
- HDBSCAN for density-based clustering
- Optuna for hyperparameter optimization
- Astropy for astronomical data handling
- scikit-learn for machine learning utilities
- Matplotlib for visualization
- Documentation: erotica.readthedocs.io
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: lescobar2019@udec.cl
- v0.0.1 — Initial alpha release with core functionality
- v0.1.0 — Comprehensive documentation, Zenodo archive, and PyPI distribution
(which this list had parked under v0.2.0;
pip install eroticaworks today) - v0.2.0 — Additional clustering algorithms; a frozen, deprecation-policed API
- v1.0.0 — Production-ready release with full validation suite
Citation: If you use EROTICA in your research, please cite our paper (in preparation) and acknowledge the underlying libraries.
Made with ❤️ for the astronomical community