How to Access and Utilize Built-in Data Files and Test Data within ExoJAX

Use the get_testdata_filename() function from exojax.test.data to resolve bundled test assets to absolute paths via importlib.resources, ensuring reliable access regardless of whether ExoJAX is installed from source, a wheel, or a compressed archive.

ExoJAX ships with a self-contained collection of reference spectra, molecular line lists, collision-induced absorption (CIA) tables, and photometric filter curves under the exojax/data/ hierarchy. The get_testdata_filename() helper, defined in src/exojax/test/data.py, provides the primary entry point for accessing these resources, making them discoverable without manual path management or external downloads.

Locating the Test Data API

The central helper for retrieving bundled assets is implemented in src/exojax/test/data.py. This module exposes get_testdata_filename(), which converts a relative filename into an absolute pathlib.Path object using Python's importlib.resources API.

from exojax.test.data import get_testdata_filename

Under the hood, the function constructs paths relative to the package root:

TESTDATA_DIR = "data/testdata/"

def get_testdata_filename(filename):
    """
    get the full path of the test data file
    """
    from importlib.resources import files
    return files('exojax').joinpath(TESTDATA_DIR + filename)

This design guarantees that data files are located correctly even when ExoJAX is installed as a compressed wheel, eliminating dependency on a specific working directory.

Available Built-in Data Assets

All test assets reside in src/exojax/data/testdata/ and are mapped to human-readable constants in exojax.test.data. Key resources include:

• SAMPLE_SPECTRA_CO: Sample CO emission spectrum (spectrum_co.txt) used extensively in unit tests
• TESTDATA_CO_EXOMOL_MODIT_XS_REF: Reference MODIT cross-section for CO from ExoMol (modit_test_ref.txt)
• TESTDATA_CO_EXOMOL_PREMODIT_TRANSMISSION_REF: Reference PRE-MODIT transmission spectrum (premodit_trans_test_ref.txt)
• TESTDATA_FILTER_SDSS_G: SDSS-g filter transmission curve (filter_sdss_g.csv) for photometric calculations
• TESTDATA_H2_H2_CIA: Sample H₂–H₂ collision-induced absorption data (H2-H2_TEST.cia)

Because these files are packaged with the library, you do not need to download or manage external dependencies. Simply pass the appropriate constant to get_testdata_filename() and feed the resulting path into ExoJAX's readers or opacity generators.

Practical Usage Examples

Loading a Reference Spectrum for Validation

To quickly inspect a reference CO emission spectrum:

import numpy as np
import matplotlib.pyplot as plt
from exojax.test.data import get_testdata_filename, SAMPLE_SPECTRA_CO

# Resolve the full path

spec_path = get_testdata_filename(SAMPLE_SPECTRA_CO)

# The file contains two columns: wavenumber (cm⁻¹) and flux

wn, flux = np.loadtxt(spec_path, unpack=True)

plt.plot(wn, flux)
plt.xlabel("Wavenumber (cm⁻¹)")
plt.ylabel("Flux")
plt.title("Reference CO Emission Spectrum")
plt.show()

The data file lives at src/exojax/data/testdata/spectrum_co.txt, while the loader logic resides in src/exojax/test/data.py.

Integrating CIA Tables into Radiative Transfer

Use bundled CIA data to compute collision-induced absorption coefficients:

from exojax.database.cia import CdbCIA
from exojax.test.data import get_testdata_filename, TESTDATA_H2_H2_CIA

cia_path = get_testdata_filename(TESTDATA_H2_H2_CIA)

# Load CIA data for the wavenumber range 4050–4150 cm⁻¹

cia = CdbCIA(str(cia_path), nurange=[4050.0, 4150.0])

# cia.kappa contains the absorption coefficient array ready for RT

print("CIA shape:", cia.kappa.shape)

The CIA loader implementation is found in src/exojax/database/cia/api.py, while the test data file is located at src/exojax/data/testdata/H2-H2_TEST.cia.

Applying Photometric Filters to Synthetic Spectra

Convolve a synthetic spectrum with the built-in SDSS-g filter:

from exojax.postproc.specop import convolve_spectrum
from exojax.test.data import get_testdata_filename, TESTDATA_FILTER_SDSS_G
import numpy as np

# Load the filter transmission curve (wavelength in nm, throughput)

filter_path = get_testdata_filename(TESTDATA_FILTER_SDSS_G)
lam, throughput = np.loadtxt(filter_path, unpack=True, delimiter=',')

# Convert wavenumber to wavelength (nm) for convolution

# Assuming wn from previous example (cm⁻¹)

lam_spec = 1e7 / wn  # cm⁻¹ → nm

# Convolve spectrum with the filter

flux_filt = convolve_spectrum(lam_spec, flux, lam, throughput)

print("Band-integrated flux:", flux_filt)

The filter file is stored at src/exojax/data/testdata/filter_sdss_g.csv, and the convolution utility is implemented in src/exojax/postproc/specop.py.

Validating Opacity Calculations with MODIT References

Retrieve pre-computed MODIT cross-sections for unit testing or algorithm validation:

import numpy as np
from exojax.test.data import get_testdata_filename, TESTDATA_CO_EXOMOL_MODIT_XS_REF

xs_path = get_testdata_filename(TESTDATA_CO_EXOMOL_MODIT_XS_REF)

# MODIT reference files contain wavenumber and cross-section columns

wn, sigma = np.loadtxt(xs_path, unpack=True)

print("MODIT cross-section shape:", sigma.shape)

This reference data is stored in src/exojax/data/testdata/modit_test_ref.txt.

Summary

• get_testdata_filename() in src/exojax/test/data.py is the canonical interface for locating bundled assets using importlib.resources.files('exojax').
• Test data constants like SAMPLE_SPECTRA_CO and TESTDATA_H2_H2_CIA map to specific files in src/exojax/data/testdata/, ensuring type-safe references.
• The importlib.resources approach guarantees path resolution works across source installations, wheels, and zip archives without manual path manipulation.
• Built-in files cover reference spectra, CIA tables, filter curves, and opacity benchmarks, supporting reproducible radiative-transfer workflows.

Frequently Asked Questions

Where are the built-in data files physically located?

All bundled data resides within the src/exojax/data/testdata/ directory of the repository. When installed, these files are packaged inside the exojax Python package under exojax/data/testdata/. You should never hardcode these paths; instead, use get_testdata_filename() to resolve them dynamically according to the installation layout.

Do I need to download test data separately?

No. ExoJAX includes all test data as package data, meaning it ships with the library itself. Whether you install via pip install exojax or from a GitHub checkout, the get_testdata_filename() helper automatically locates the files without requiring separate downloads or environment variables.

Can I use get_testdata_filename() for my own custom data files?

No. This function is specifically designed for the bundled test assets under exojax/data/testdata/. For your own data, use standard Python path handling or pathlib. The function relies on importlib.resources.files('exojax') which only traverses the package namespace and cannot access arbitrary filesystem locations.

What file formats are supported by the built-in data loaders?

The built-in files include plain-text tables (.txt, .csv) for spectra and filters, and specialized formats like .cia for collision-induced absorption data. The expected format depends on the specific ExoJAX module consuming the file: CdbCIA expects HITRAN-style CIA files, while spectral loaders typically expect two-column wavenumber-flux arrays.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}