ASDCache¶

ASDCache is a Python project to retrieve data from the NIST Atomic Spectra Database (ASD), using caching for fast, efficient data handling.

To make the most use out of the cache, ASDCache is opinionated in the information it retrieves from the ASD; it always requests the same schema of information and locally computes additional fields, to provide a more 'machine-useable' experience.

It also coerces most of the retrieved data to be of a strictly numeric type, which strips out footnotes and annotations, but preserves e.g. bibliographic reference labels.

You should thus still be sure to check and attribute the NIST ASD when making use of ASDCache!

The main goals and benefits of ASDCache are:

Make the data from the NIST ASD locally accessible as a Dataframe for use in analysis of spectra
Retrieve a consistent schema of the data that represents the 'human readable' format, but enforce strictly numeric data for important columns
- This removes footnotes and other annotations, be sure to check the ASD itself as well for this information.
Use caching to dramatically speed up data retrieval, from minutes down to milliseconds in some cases
- Cache time-to-live is 1 week by default, meaning you still get updates to the ASD in a reasonable time frame
- The cache time-to-live can be adjusted
Cache data to allow working offline, or even transfering the ASD data to an offline system.
- The cache is only updated when a request for new data succeeds
Limit repeated queries for the same information, avoiding network overhead and server load.

ASDCache is not affiliated with NIST or the NIST ASD in any way, it simply tries to help make it more accessible.

Installing¶

ASDCache can be installed with pip.

pip install ASDCache

Further optional features can be installed by specifying the polars or docs feature flag, as defined in pyproject.toml.

To install all dependencies to locally serve and update the documentation for instance, you can run:

pip install ASDCache[docs]

Installing the polars feature is not required, in case polars is already installed in the active environment, it is possible to use polars instead of pandas as a Dataframe backend for ASDCache.

Documentation¶

Documentation for ASDCache is available on this page.

Example¶

A brief example below demonstrates how to use SpectraCache to query the NIST ASD for spectroscopic data for different species and plot their respective relative intensities.

Note that these relative intensities are in principle not comparable between different species or sources and merely serve as a guide.

More elaborate examples can be found in the example section of the documentation

from ASDCache import SpectraCache, BibCache
import matplotlib.pyplot as plt

nist = ASDCache()
lines_H_I = nist.fetch("H I")


plt.plot(lines_H_I['obs_wl_air(nm)'], lines_H_I['intens'], label=f"{lines_H_I['element'].unique()[0]} {lines_H_I['sp_num'].unique()[0]}")


nist.fetch("O I-III") # caches data from NIST but does not assign to a variable

# Oxygen I-III will still be plotted, each ionization state separately.
lines_all_cached = nist.get_all_cached()
for species,lines in lines_all_cached.groupby(["element","sp_num"]):
    plt.plot(lines['obs_wl_air(nm)'], lines['intens'], label=f"{species[0]} {species[1]}", marker='x', ls='none')
plt.legend()

Citing¶

Be sure to cite the NIST ASD when using ASDCache in your work, since it is the source of the data.

ASDCache itself can be cited using the following DOI provided via Zenodo: 10.5281/zenodo.14673488

License¶

ASDCache is licensed under the MIT license.