Introduction to the Roman Research Nexus (The Nexus)

Log In to Nexus Sign Up for MyST Get Help

The Roman Research Nexus (aka “the Nexus”) is a JupyterHub service with public, shared compute resources, intended for Roman-related data analysis.

Creating Nexus accounts

Creating a MyST account is required to log in to the Nexus. Click the “Sign Up for MyST” button above to navigate to the sign-up page.

How to access the Nexus

1. Go to the Nexus login page (see the “Log In to Nexus” button at the top of the page).

2. Sign in with your MyST account.

3. Launch a server.
   

   • Choose from the dropdown list:

   Server Type	vCPU	RAM
   Small	2	16 GB
   Medium	8	16 GB
   Large - CPU optimized	32	64 GB
   Large - Memory optimized	16	128 GB

   • Choose an image: e.g., roman-17.1.1 (June 2025 patched).

That’s all. You might have to wait a few minutes for the server to start. When it does, an instance of JupyterLab will automatically launch in your browser.

Named servers

You might decide to open more than one server at a time or simply create a more organized setup. Create multiple or named servers by clicking Home on the top navigation bar instead of launching a server immediately when you log in.

Type in a name for your new server (e.g. “test-server”) and select the smaller blue button Add new server.

That’s it. You should be greeted with a “Welcome to the Roman Research Nexus!” page in a JupyterLab instance.

Stopping a server

The virtual server that runs your personal instance of the Nexus will shut down after approximately an hour of inactivity. You can restart this virtual server the next time you access the Nexus.

You can stop a server instance using the Hub Control Panel, which is accessed from the JupyterLab UI by clicking File -> Hub Control Panel.

Teams

Creating teams

To create a team, put in a request with the Nexus helpdesk.

Shared files

Team storage can be accessed through /teams/<your team name>/ (see teams.md).

Environments

There is robust documentation on creating environments on the Nexus, in software.md, which you can reach by clicking the “Installing extra software” link on the welcome page.

TL;DR Environments are created, listed, activated, exported, and removed using:

# Create
kernel-create <environment-name> [<python-version>] [<lab-display-name>]

# List
kernel-list

# Activate
source kernel-activate <environment-name>

# Export
kernel-export <environment-name> <output-file-name.yaml>

# Remove
kernel-delete <environment-name>

These environments persist between sessions.

Using the Nexus with local tools

VS Code (or Cursor)

Here’s a step-by-step guide to using the Nexus with VS Code, through Jupyter notebooks.

1. Log in to the Nexus
   See above.

2. Create a named server (trust me — it’s easier)
   See above.

3. Open the terminal and Create an Environment
   See above; kernel-create <environment-name> [<python-version>] [<lab-display-name>].

4. Reopen the Hub Control Panel
   See above.

5. Get your secret token:
   • Click on Token, which is in the navigation bar at the top of the page.
   • Fill out the form:
     • Note: Give it a name that reminds you what it’s for.
     • Expiry: Shorter is more secure, but requires more maintenance.
     • Permissions: leave blank (full permissions) or specify a subset — your choice.
   • Request a new API token.
   • Copy the token. Treat it like a password.
6. Build the URL:
   • Take your server’s base URL (like https://roman.science.stsci.edu).
   • Add your specific server path (like /user/<user-name>/<server-name>/). This is where having a sensibly named server is helpful. You can find this on the Token page in the Hub Control Panel, under “Authorized Applications” → “Application” → “Server at ”.
   • Tack on ?token= and then paste your secret token at the end.

   TL;DR
   server-URL: https://roman.science.stsci.edu/user/<user-name>/<server-name>/?token=<token>

7. Connect VS Code to the kernel:
   • Ensure you have the Jupyter extension pack (by Microsoft) installed.
   • In VS Code, with a notebook open, click Select Kernel or the current kernel name (if one is already selected). Then choose:
     • “Select Another Kernel…”
     • “Existing Jupyter Server…”
     • “Enter the URL of the running Jupyter Server…”
     • Paste your server-URL into the box and hit Enter.
     • Select your created kernel/environment. If your kernel doesn’t show up, it is likely due to a missing IPython. Run pip install ipython in a terminal on the Nexus (with your environment activated) and try again.

Note:
If you are using AI agents in your workflow, ensure you have selected one with notebook editing capabilities. E.g. Claude Sonnet with GitHub Copilot.

Microlensing Data Challenge Tools

The RGES-PIT Microlensing Data Challenge uses the microlens-submit toolkit - a stateful submission tool that provides version-controlled workflow for managing, validating, and packaging your challenge submissions. The general recommended challenge workflow and modeling guides are the contents of

The official challenge repositories and documentation are hosted at:

Notebook and Informational Repository: https://github.com/rges-pit/data-challenge-notebooks

Duplicates of most of these notebooks exist pre-loaded on the Nexus.

Submission Tool Repository: https://github.com/rges-pit/microlens-submit

Submission Documentation and Guides: https://microlens-submit.readthedocs.io/en/latest/

Data Challenge Submissions

The microlens-submit documentation includes detailed specifications for how to create a submission. Strict adherence to the submission criteria is required, as much of the evaluation process is automated.

A comprehensive tutorial notebook is available in the microlens-submit repository:

• Tutorial: docs/Submission_Tool_Tutorial.ipynb
• Manual Submission Format: https://microlens-submit.readthedocs.io/en/latest/submission_manual.html

Nexus notebook content

The Nexus JupyterLab session comes preloaded with useful pages and notebooks. These live inside the reference/ directory. tutorials.md lists all the reference notebooks and links to access them.

Note:
The notebooks in this directory are read-only, but the file system itself is not, so the reference notebooks can execute. You should not create and save notebooks in this directory. It is regularly replaced with the contents of its source repository, and any changes you make here will be lost.

In the notebook directory (notebooks/microlensing-data-challenge/) you will find the aforementioned notebooks and additional environment files (env.yaml and requirements.txt). Included in these environment files are the dependencies for the notebooks and packages we anticipate you may need for the data challenge.

Using the Environment Files

You should not need to use the provided environment file; you only need to select the rges-pit-kernel in the Nexus hosted notebook. Should you wish to use them anyway, you can refer to this readme README.md for instructions on how.

Nexus Specific Notebooks

Relevant notebooks to this session are:

• Accessing data using s3fs (reference/content/notebooks/data_discovery_and_access/data_discovery_and_access.ipynb).

  View on GitHub View Docs Download

• Data challenge workflow and creating data challenge submissions (microlens-submit) (reference/content/notebooks/rmdc2025_workflow/rmdc2025_workflow.ipynb).

  View on GitHub Download Open

• Alternate workflow with the submission command line tool, for non-Python users.

  View on RtD View Docs Open

FAQ

How do I use the terminal?

Use “+” button on the far right of the document tabs, then select terminal, which is sorted under “Other”.

How do I select an environment?

In a notebook session, click the select kernel text at the top right of the embedded window (between the hamburger and the bug). If an environment or kernel has already been selected, it might say something like Python 3 (ipykernel). Simply click that kernel name to change to a new kernel.

How do I open the Hub Control Panel from inside the JupyterLab instance?

Click File -> Hub Control Panel