Star Name Database Walkthrough - HypatiaOrg/HySite GitHub Wiki
One of the problems that needed to be solved to create the Hypatia Catalog was how to associate data across different sources that used a variety of names to refer to the same stars. We called this the star name problem. We got our best results when we stopped trying to solve the problem ourselves and instead leveraged the work already done by SIMBAD. It is a pillar of the astronomy database community and a key resource that compiles most star names.
The first time we run the Hypatia Catalog pipeline, we get the star name information from SIMBAD and we save it locally in our database. The next time we run the pipeline, we can use our database to make name associations for star names the pipeline has already encountered. This way, we only query SIMBAD when encountering new star names from new data (such as newly discovered exoplanet host stars). This keeps us from spamming SIMBAD while also dramatically increasing the speed of name associations without our pipeline. At the time of writing, we have 46,055 star name records in the Hypatia Catalog star names database.
Overall, we find this tool very helpful and other astronomers or scientists might also find it useful! This guide aims to help others create their own star names database and leverage the public Hypatia Catalog code we use to take any star name and return the default SIMBAD name for a given star. This simplifies the process of cross-matching stars across multiple datasets and can help people avoid potential target list duplicates where the same star is listed twice under different names.
This guide uses Docker to deploy a MongoDB database and Python environment. However, this process will also work if you manage and install MongoDB and Python locally on your computer. Our install guides are linked below.
-
Docker: container management software.
-
MongoDB Compass: an optional graphical user interface for viewing and querying MongoDB data.
-
HySite is the HypataCatalog's public code repository.
- Option 1: Clone using Git
git clone https://github.com/HypatiaOrg/HySite.git
- Option 2: Download from the GitHub website https://github.com/HypatiaOrg/HySite using the code button to select a zip file download.
*Option 3: For a comprehensive guide on the developer setup of the HySite repository, refer to our wiki page Initial Setup Git and GitHub.
To configure HySite containers and hold secrets, we use a non-versioned plain text file named .env
. Since this file is not versioned, you must create it and add the variables in the example below, but change the values to create your username and passwords.
Note
If you do not create this file, the defaults below are used.
MONGO_USERNAME=admin
MONGO_PASSWORD=super-not-secure
JUPYTER_TOKEN=docker
Note
The first time you start the MongoDB container is when the username and password are set. For more information, see the section persistent storage for MongoDB database section of the Directory and File Structure wiki page.
With Docker installed and started, use a terminal program and change directory to the HySite folder. From here you can use the following Docker command to start the MongoDB and iPython containers:
docker compose up --build mongo-db ipython
Use control-C
to stop the containers.
Alternatively, if you set up your own Python environment and installed the HySite requirements, you can start only the MongoDB container with:
docker compose up --build mongo-db
Tip
More Docker commands and tips for deleting container files are found on our Docker Wiki page.
The example Jupyter notebook can be found at (paste this into your favorite browser):
http://127.0.0.1:8888/notebooks/examples/db/stars/star_names.ipynb
You will be prompted to enter a password or token
the first time you do this. This is either the default (docker
) or what you configured in .env (see the section .env file configuration for passwords above) for the variable JUPYTER_TOKEN
.

Note
You can see the star_names.ipynb notebook on GitHub in read-only mode.
A graphical user interface (GUI) for a database can be an excellent tool for testing new commands, queries, or searches before implementing them in our Python-Django API. Setup for the MongoDB Compass GUI is discussed in the section MongoDB Compass in our Recommended Software wiki page.
Before navigating to that page, you must understand a few configuration settings. These configurations can be set in the .evn
file. In this walk-through, we are setting up a MongoDB database in a container accessible on your computer as localhost
on port 27017
, which is often written as localhost:27017
for a connection string.