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

> Access ExoJAX built-in data files and test data reliably use get_testdata_filename() for absolute paths. Learn how to utilize these assets easily.

- Repository: [Hajime Kawahara/exojax](https://github.com/hajimekawahara/exojax)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/hajimekawahara/exojax/blob/main/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`](https://github.com/hajimekawahara/exojax/blob/main/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.

```python
from exojax.test.data import get_testdata_filename

```

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

```python
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`](https://github.com/hajimekawahara/exojax/blob/main/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`](https://github.com/hajimekawahara/exojax/blob/main/modit_test_ref.txt))
- **`TESTDATA_CO_EXOMOL_PREMODIT_TRANSMISSION_REF`**: Reference PRE-MODIT transmission spectrum ([`premodit_trans_test_ref.txt`](https://github.com/hajimekawahara/exojax/blob/main/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:

```python
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`](https://github.com/hajimekawahara/exojax/blob/main/src/exojax/data/testdata/spectrum_co.txt), while the loader logic resides in [`src/exojax/test/data.py`](https://github.com/hajimekawahara/exojax/blob/main/src/exojax/test/data.py).

### Integrating CIA Tables into Radiative Transfer

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

```python
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`](https://github.com/hajimekawahara/exojax/blob/main/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:

```python
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`](https://github.com/hajimekawahara/exojax/blob/main/src/exojax/postproc/specop.py).

### Validating Opacity Calculations with MODIT References

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

```python
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`](https://github.com/hajimekawahara/exojax/blob/main/src/exojax/data/testdata/modit_test_ref.txt).

## Summary

- **`get_testdata_filename()`** in [`src/exojax/test/data.py`](https://github.com/hajimekawahara/exojax/blob/main/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.