Association files contain lists of data products that are related to each other. They are utilized by STScI Roman pipelines to process and combine Roman images, enabling groups of exposures to be treated as sets instead of individually. This article contains an overview to help users create and utilize association files. 

What are Associations? 

Association files are specially formatted JavaScript Object Notation (JSON) files that contain lists of related Roman data products and files. By grouping Roman images within an association file, these images can be treated as a set. This allows users to retrieve or process all the images of interest with a single command, without the need to configure special batch commands. Association files are often used as input for the various STScI Roman pipelines. For example, an association file is required by the mosaic level pipeline as input in order to run. This means that all images that should be combined into a mosaic need to be listed in the association file for the mosaic level pipeline to process them together into the output mosaic.

Association files have been used in HST and JWST missions in the past to group exposures, often by visit. The Roman association files produced by STScI are fairly similar to the JWST association files, although Roman may use associations differently than JWST in the data pipeline. Please visit JDox for more information about the JWST association files. 

Associations for Roman 

Association files for Roman will link together images and other Roman data files at different levels of the survey hierarchy, such as in a visit, or a pass, or a full-depth stack. See the APT Program Elements article for more information about the survey hierarchy.

The names of the associations provide information about the data they represent. See the Association Naming readthedocs article for the most up-to-date description of the Roman association file names. As of the publication of this article, Roman association file names follow this scheme: 

Associations and the STScI Roman Pipelines 

Multiple association files will be generated to keep track of various relationships between images. Here are some examples of how association files might be utilized by the pipeline:

• to identify the files corresponding to all 18 detectors of a single observation with Roman's field of view;
• to group engineering data with related images, such as a guide star data file with the corresponding observation;
• to sort data by type, such as all observations of the same filter and target, to be processed together;
• and to indicate exposures which are dependent upon one another. 

In addition to how the pipelines will use association files, users can create custom association files containing lists of any data files that the user wants to process or combine together using the STScI data pipelines for a given science goal. 

Creating Roman Association Files 

For anyone looking to reprocess Roman exposures with the STScI Roman pipelines, creating association files will likely be necessary. To run the STScI Roman pipelines on a custom list of Roman images not automatically grouped together by the STScI Roman pipelines, the user will need to generate an association file as they are the required input file for some pipelines, such as the mosaic level pipeline. It also can make retrieving, calibrating, reprocessing, and combining exposures more streamlined. 

The STScI Roman pipelines provide a utility function for creating association files called  asn_from_list which can be run from either a Python environment or the command line. The command line functionality is recommended at this time. More information can be found on the asn_from_list readthedocs page, and an example of the command line syntax is provided below. The simulations represent a single visit where only the exposure number is changing; please see the Data Levels and Products page for more information about how Roman filenames are formatted.

asn_from_list -o r00000-o9999_RDoxExampleName_ATYPE_001_asn.json --product-name=RDox-Example-Product *.asdf

The output JSON file has the name r00000-o9999_RDoxExampleName_ATYPE_001_asn.json and contains the following information, formatted appropriately for the STScI Roman pipeline: 

{
    "asn_type": "None",
    "asn_rule": "DMS_ELPP_Base",
    "version_id": null,
    "code_version": "0.14.1.dev208+gaaeb39f",
    "degraded_status": "No known degraded exposures in association.",
    "program": "noprogram",
    "constraints": "No constraints",
    "asn_id": "a3001",
    "target": "none",
    "asn_pool": "none",
    "products": [
        {
            "name": "RDox-Example-Product",
            "members": [
                {
                    "expname": "r0000901001001001001_01101_0001_WFI01_cal.asdf",
                    "exptype": "science"
                },
                {
                    "expname": "r0000901001001001001_01101_0002_WFI01_cal.asdf",
                    "exptype": "science"
                },
                {
                    "expname": "r0000901001001001001_01101_0003_WFI01_cal.asdf",
                    "exptype": "science"
                },
                {
                    "expname": "r0000901001001001001_01101_0004_WFI01_cal.asdf",
                    "exptype": "science"
                }
            ]
        }
    ]
}

The Roman simulated files and the resulting JSON output is publicly available and can be viewed and downloaded on Box at this link for those who would like to reproduce this example. 

This command allows Roman exposures to be grouped together as needed. Alternatively, users can create association files using their own methods to produce JSON files, but the formatting and filenames must conform to the requirements of the STScI Roman pipelines. 

To learn how association files will be used to process Roman data, please see the Roman STScI Data Pipelines. 

For additional questions not answered in this article, please contact the Roman Help Desk at STScI.

References

• Introducing JSON, accessed on 30 July 2024.
• Associations in Roman-Pipeline Readthedocs, maintained by Roman calibration pipeline developers at STScI, Revision cae1d648. Last updated on Jul 26, 2024.
• Associations Section of the JWST Science Data Overview, last updated 15 March 2024, JWST User Documentation (JDox).