Using OSA in ESA Datalabs (EDL)

A practical guide to preparing the environment, mounting the required data volumes, selecting science windows, creating observation groups, and running OSA analyses from ESA DataLabs.

This is a web and more extended version of the quick reference guide: Open the INTEGRAL OSA quick-start PDF

OSA in EDL

You need a Cosmos account for workflows that select data in ISLA and send that selection to EDL.
For security reasons, access to ISLA can only be granted to registered users, and it is thus necessary to sign-in with a Cosmos account. Registration can be done via the XMM-Newton Science Archive (XSA) registration tool: https://www.cosmos.esa.int/web/xsa/self-registration. Get familiar with both ISLA and EDL before following this guide.

After registering at https://datalabs.esa.int, you can work with OSA through two main Datalab configurations:

  • Use the INTEGRAL OSA VNC Datalab when you need a graphical desktop session. This is useful for opening terminals, running OSA binaries with their GUI parameter dialogs, and using tools such as XSPEC that benefit from a graphical environment.
  • Use the INTEGRAL OSA JL Datalab when you want to work from terminals with OSA GUIs disabled, or from Python notebooks using OSAhelper to drive the analysis workflow. This is the option that can be linked directly from ISLA.

Starting a Datalab

Be sure you are logged in both in ISLA and EDL.
The first step is to create or start the Datalab that matches your workflow (VNC or JL): for python notebook-driven analysis, choose the JupyterLab-based OSA environment. For interactive command-line plus OSA GUI work, choose the VNC environment.

Keep the session layout simple: use a project folder for notebooks and scripts, and use the mounted INTEGRAL data volume as the read-only data source. We recommend to work /media/user by default, it is linked to /home/your_datalab_user_name/my_workspace and it is a permanent storage space.

Launching OSA JL or VNC

  1. Log in to EDL and click the beaker icon in the top menu bar ().
  2. Choose Launch new and search for Integral.
  3. Select INTEGRAL OSA JL or INTEGRAL OSA VNC, according to your needs, and wait until the Datalab is ready (green color on the vertical bar on the left of the datalab button).

Mounting the Required Volumes

Before running an analysis, make sure the INTEGRAL data volume is mounted in the Datalab, aswell as the ESDC ASSETS volume. To check mounted volumnes or access the search and mount utility in EDL, look for the cloud button in the topbar of the EDL interface ().

At the top level of the Datalab filesystem you should normally see folders for mounted data, your private workspace, and shared team workspaces.

  • /data contains read-only shared volumes.
  • /my_workspace is the area where you keep notebooks, scripts, and local edits. It is also accessed via /media/user/.
  • /team_workspaces is intended for collaboration with other users.

The shared /data area should include int_data_datalabs for INTEGRAL data, and esdc_datalabs_assets for ESDC notebook templates.

Before starting we need the right set of folders in order to let OSA find all the files and info it needs. Check the OSA User's manual for details.

If you are using the JL datalab, the osahelper.setup_osa_workspace helper sets up the workspace in /media/user:

import osahelper
osahelper.setup_osa_worskapce()

If your Datalab uses different mount points, pass explicit paths to setup_osa_workspace(media_user=..., data_root=...).

If you are using the VNC version instead, provided ima.sh, lcr.sh, and spe.sh scripts will also create the folder structure if it does not exists. For a manual set up check the OSA User's manual.

Sending an ISLA Selection to EDL

ISLA can send the currently selected search results to an existing OSA JL Datalab. Open ISLA in another browser tab, sign in with your Cosmos account, run a search, and select the rows you want to process.

  1. In ISLA, use the checkboxes in the results table to select the data.
  2. Click the cloud action labelled Send current search to ESA Datalabs.
  3. In the EDL tab, copy the Datalab ID from the last part of the URL.
  4. Paste that ID in the ISLA dialog and open the linked ESA Datalab.

For a URL such as https://datalabs.esa.int/datalab-viewer/566b8892ee42a468, the Datalab ID is 566b8892ee42a468. The linked code block contains the query needed to fetch the selected data.

VNC Session with Analysis Scripts

In an OSA VNC session, you can run the usual OSA commands from a terminal and interact with graphical parameter dialogs. This mode is a good fit when you are validating an analysis manually, inspecting intermediate products, or using GUI-oriented tools, for example:

cd /media/user
source osa_init.sh
ibis_science_analysis

The GUI version of OSA analysis scripts is available for parameter selection. FITS file inspection, and interactive plotting with HEASOFT tools is also possible. 

Scripts ima.sh, ima.sh, and ima.sh, not using GUI mode, are available for a quick ISGRI or JEM-X analysis setup, and can be used in this datalab.

JupyterLab Session with OSAhelper

In an OSA JL session, the recommended workflow is to prepare the OSA workspace from the first notebook cell, initialize the OSA environment, and then use OSAhelper widgets to select inputs and launch the analysis.

This approach is especially convenient for reproducible analysis: notebook cells document the selected science windows, analysis parameters, generated observation groups, and quick-look plots.

The official quick-start PDF is useful when you need the EDL and ISLA click-path rather than the notebook code: open the PDF guide.

Prepare the Workspace

Run this cell at the beginning of the notebook. The helper creates in /media/user links to the data folders ic, idx, scw, aux, cat, and adp, it also copies pfiles and syspfiles, and finally it creates the obs folder.

from osahelper import setup_osa_workspace, osa_init

ready = setup_osa_workspace()
if not ready:
    raise RuntimeError("Mount the INTEGRAL data volume first")

osa_init()

Running setup_osa_workspace() is intentionally safe to repeat. Existing correct links and folders are detected and unchanged.

Analysis Workflow

1. Select SCWs Use an existing local list, upload one from your computer, or generate it from an ISLA query.
2. Configure Parameters Choose the instrument, final analysis level, and energy bands.
3. Create the Observation Group Run og_create from the notebook interface.
4. Run OSA Execute osa and inspect the generated products in /media/user/obs.
 

Minimal Notebook

For examples of complete and more detailed data analysis, check the tutorials.

A minimal set up would be:

from osahelper import setup_osa_workspace, osa_init, setup_analysis

if setup_osa_workspace():
    osa_init()
    setup_analysis()
else:
    print("Mount the INTEGRAL data volume and run the cell again")

Using an ISLA Query

From ISLA a JL notebook can be created directly into your datalab. It will contain a cell similar to this one:


from astroquery.esa.integral import IntegralClass
isla = IntegralClass()
query = "select * from ila.cons_pub_obs where 1=CONTAINS(POINT('ICRS',ra,dec),CIRCLE('ICRS',83.63320922851562,22.01447105407715,14)) AND starttime <= '2026-07-02 19:55:43.9213' AND endtime >= '2001-10-09 22:18:09.5787' and obsid in ('06200370001') order by obsid"
result = isla.query_tap(query)

and a set of intructions on how to set up and run de analysis.

Copy that notebook to your /medua/user folder and follow the instructions.

Using an previously created scw list

Open a notebook and insert inthe first cell:

from osahelper import setup_osa_workspace, osa_init, setup_analysis

setup_osa_workspace()
osa_init()
setup_analysis()

You will be able to select your previously prepared science window list file from the datalab workspace of from your own PC.

Resources