Introduction

XRADIO is an open-source Python package that leverages xarray to provide an interface for radio astronomy data. It includes converters from legacy formats and contains versioned schemas for each dataset type. A schema checker is also included to verify if a dataset conforms to the schema.

Data is organized into:

• xarray Datasets: A multi-dimensional, in-memory, array database of labeled n-dimensional arrays.

• XRADIO Processing Sets: XRADIO-specific data structure, based on a Python dictionary, that consists of a collection of xarray Datasets. We will be looking into replacing the processing set with xarray Datatree in the future.

XRADIO Schemas

XRADIO is actively developing support for various types of radio astronomy data:

Data Type	Description	Status
Measurement Set v4.0.0	Interferometer Data (Visibilities) and Single Dish data (Spectrum)	Under community review
Sky and Aperture Images	Representation of celestial objects and antenna patterns	Schema design in progress
Calibration Data	Information for instrument calibration	Schema design in progress
Aperture Models	Antenna dish models using Zernike polynomials	Work scheduled
Simulation Component Lists	Data for simulating radio astronomy observations	Work scheduled

Additional data types will be added based on community needs and contributions.

Schema Versioning

Each schema in XRADIO follows semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Changes to existing dimensions, coordinates, data variables, attributes, or measures. (This will not occur without wider community consultation.)

• MINOR: Addition of new datasets. (Backward compatible)

• PATCH: Addition of new coordinates, data variables, attributes, or measures to existing datasets. (Backward compatible)

For example:

• v4.0.0 to v5.0.0: Major change in the Measurement Set structure

• v4.0.0 to v4.1.0: Addition of a new dataset type

• v4.0.0 to v4.0.1: Addition of new attributes to an existing dataset

The Measurement Set schema will start at v4.0.0, building upon the work of Measurement Set V2 and Measurement Set v3 (which was never implemented).

An XRADIO release will be tied to specific versions of each available schema. All generated data will include both the XRADIO version and the schema version in the attribute section.

Installation

It is recommended to use the conda environment manager from miniforge to create a clean, self-contained runtime where XRADIO and all its dependencies can be installed:

conda create --name xradio python=3.12 --no-default-packages
conda activate xradio

📝 On macOS it is required to pre-install python-casacore using conda install -c conda-forge python-casacore.

XRADIO can now be installed using:

pip install xradio

This will also install the minimal dependencies for XRADIO. To install the minimal dependencies and the interactive components (JupyterLab) use:

pip install "xradio[interactive]"

Foundational Reading

The description and selection of data in XRADIO is based on xarray. To use XRADIO effectively, it’s crucial to understand the terminology and indexing methods used in xarray. Here are some important material to review:

• xarray terminology

• xarray indexing and selection guide

Contributing

We welcome contributions to XRADIO from the radio astronomy community and beyond!

Preparation

• Read the XRADIO Overview, Development, and the relevant schema section for example Measurement Set v4.0.0.

  • Pay special attention to the Foundational Reading subsection in the Overview.

• Complete the relevant tutorials (for example the measurement set tutorial), which demonstrates the schema and API usage.

Setting up Development Environment

• Install the conda environment manager from miniforge and create a clean, self-contained runtime where XRADIO and all its dependencies can be installed:

conda create --name xradio python=3.12 --no-default-packages
conda activate xradio

📝 On macOS it is required to pre-install python-casacore using conda install -c conda-forge python-casacore.

• Clone XRADIO repository, move into directory and install:

git clone https://github.com/casangi/xradio.git
cd xradio
 pip install -e ".[all]"

The -e ensures that the installation location is the same as the cloned repository (using pip list should show this), so that you can directly modify the cloned repo. The [all] ensures that all dependencies so that you can run the interactive Jupyter notebooks and build the documentation (the dependencies can be found in the pyproject.toml).

Building documentation

To build the documentation navigate to the docs folder, create a folder name build and run sphix:

cd docs
mkdir build
sphinx-build source build -v

Coding Standards

• Formatting: All code should be formatted using Black. A GitHub Action will trigger on every push and pull request to check if the code has been correctly formatted.

• Naming Conventions:

  • Use descriptive names. For example, use image_size instead of imsize.

  • Function names and variables should follow snake_case. Examples: my_function, my_variable.

  • Class names should follow CamelCase. Example: MyClass.

• Imports: Avoid relative imports; always use absolute imports to maintain clarity.

• Docstrings: All functions and classes should include NumPy-style docstrings. For guidelines, refer to the NumPy Documentation Guide.

• Compute-Intensive Code: Ensure that compute-intensive code is vectorized for performance. If vectorization is not feasible, consider using Numba. Use performance testing to verify that optimizations are effective.

• Testing: Write unit tests for all major functions and classes using pytest. The folder structure of xradio/tests/unit should mirror the source code structure.

• Error Handling & Logging: Use the toolviper logger for consistent logging.

Submitting Code

• Any code you submit is under the BSDv3 license and you will have to agree with our contributor license agreement that protects you and the XRADIO project from liability.

• Create an issue on github outlining what you would to contribute XRADIO GitHub repository.

• Once there is agreement on the scope of the contribution you can create a branch on github or in you clones repository:

git checkout -b feature-or-fix-name

(If you create the branch in your cloned repository remember to link it to the GitHub issue). - Make your code changes and add unit tests. - Run the tests locally using pytest. - After running Black add, commit and push your code changes to the GitHub branch:

git add -u :/ #This will add all changed files.
git commit -m 'A summary description of your changes.'
git pull origin main #Make sure you have all the latest changes in main.
git push

• If you are making many changes you can break up the work into multiple commits.

• If tests pass and you are satisfied open a pull request in GitHub. This will be reviewed by a member of the XRADIO team.