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, whereas a conda environment may not. Alternatively, may be replaced with a path to a YAML file, for conda-like environment creation. Using the provided YAML for this workshop, you can create a kernel with all the packages you need for running workshop notebook content:

kernel-create rges-pit-dc env.yml "rges-pit-dc"  # This may take a while to solve the environment and download and install the packages. We will have an image available in the future to avoid this tedious process.

You can download the YAML here or clone the data-challenge-notebooks repo, which includes the YAML and all the RGES-PIT-provided assistive notebooks to help you with this challenge:

cd ~ # changes to the landing directory on the Nexus do not persist between updates
git clone https://github.com/rges-pit/data-challenge-notebooks.git
cd data-challenge-notebooks
kernel-create rges-pit-dc env.yml "rges-pit-dc"

For further instructions on Nexus setup and usage, see this STScI page or any of the helpful documentation pages in the landing directory on the Nexus. This content can also be found in the roman_notebooks repo when you are not on the Nexus.

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 a version-controlled workflow for managing, validating, and packaging your challenge submissions.

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 appropriate kernel in the Nexus-hosted notebook. If you wish to use these files anyway, refer to this README: AAS Workshop/README.md.

Nexus Specific Notebooks

Relevant notebooks to this session are:

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