0
# Spectroscopic Databases
1

2
Specialized databases for atomic, molecular, and spectroscopic data used in astronomical spectroscopy and laboratory astrophysics. These services provide essential reference data for identifying spectral lines, understanding molecular processes, and interpreting astronomical spectra.
3

4
## Capabilities
5

6
### Splatalogue - Spectroscopy Database
7

8
Splatalogue provides access to spectral line data for radio, millimeter, and submillimeter astronomy, containing molecular transition frequencies and quantum numbers essential for spectral analysis.
9

10
```python { .api }
11
from astroquery.splatalogue import Splatalogue
12

13
def query_lines(min_frequency: Union[float, Quantity], max_frequency: Union[float, Quantity],
14
               chemical_name: str = None, molecular_tag: int = None, 
15
               line_lists: List[str] = None, line_strengths: List[str] = None,
16
               energy_max: float = None, energy_type: str = 'eu_k',
17
               transition: str = None, version: str = 'v3.0',
18
               exclude: List[str] = None, only_NRAO_recommended: bool = None,
19
               export: bool = True, export_limit: int = 10000,
20
               noHFS: bool = False, displayHFS: bool = False, 
21
               show_upper_degeneracy: bool = False) -> Table:
22
    """
23
    Query Splatalogue for spectral lines in a frequency range.
24
    
25
    Parameters:
26
    - min_frequency: Minimum frequency (Hz, MHz, GHz) 
27
    - max_frequency: Maximum frequency (Hz, MHz, GHz)
28
    - chemical_name: Chemical formula or name to search
29
    - molecular_tag: Molecular identification tag number
30
    - line_lists: List of line list names to include
31
    - line_strengths: Minimum line strength categories
32
    - energy_max: Maximum upper state energy
33
    - energy_type: Energy unit type ('eu_k', 'eu_cm', 'el_cm')
34
    - transition: Specific transition to search
35
    - version: Splatalogue version
36
    - exclude: Line lists to exclude
37
    - only_NRAO_recommended: Include only NRAO recommended frequencies
38
    - export: Export results
39
    - export_limit: Maximum number of results to export
40
    - noHFS: Exclude hyperfine structure
41
    - displayHFS: Display hyperfine structure
42
    - show_upper_degeneracy: Show upper state degeneracy
43
    
44
    Returns:
45
    Table with spectral line data
46
    """
47

48
def get_species_table() -> Table:
49
    """
50
    Get table of available molecular species.
51
    
52
    Returns:
53
    Table with species names, molecular tags, and metadata
54
    """
55

56
def query_lines_async(min_frequency: Union[float, Quantity], 
57
                     max_frequency: Union[float, Quantity], **kwargs) -> JobResults:
58
    """
59
    Submit asynchronous query for spectral lines.
60
    
61
    Parameters:
62
    - min_frequency: Minimum frequency
63
    - max_frequency: Maximum frequency  
64
    - **kwargs: Additional query parameters
65
    
66
    Returns:
67
    JobResults object for retrieving results
68
    """
69

70
# Configuration
71
from astroquery.splatalogue import conf
72
conf.server: str              # Splatalogue server URL
73
conf.timeout: int = 60        # Connection timeout
74
```
75

76
Usage examples:
77

78
```python
79
from astroquery.splatalogue import Splatalogue
80
import astropy.units as u
81

82
# Query CO lines in 3mm band
83
co_lines = Splatalogue.query_lines(80*u.GHz, 120*u.GHz, 
84
                                  chemical_name='CO')
85
print(f"Found {len(co_lines)} CO transitions")
86
print(co_lines['Species', 'Freq', 'Transition'])
87

88
# Search for methanol lines with energy constraints
89
ch3oh_lines = Splatalogue.query_lines(200*u.GHz, 250*u.GHz,
90
                                     chemical_name='CH3OH',
91
                                     energy_max=50.0,
92
                                     line_strengths=['ls1', 'ls2'])
93

94
# Get all available species
95
species = Splatalogue.get_species_table()
96
organic_species = species[species['Species'].str.contains('C')]
97
print(f"Found {len(organic_species)} carbon-bearing species")
98

99
# Query specific molecular tag (for H2O)
100
h2o_lines = Splatalogue.query_lines(100*u.GHz, 200*u.GHz,
101
                                   molecular_tag=18003,
102
                                   only_NRAO_recommended=True)
103
```
104

105
### LAMDA - Leiden Atomic and Molecular Database
106

107
LAMDA provides collisional excitation data for atoms and molecules used in non-LTE radiative transfer modeling and molecular astrophysics calculations.
108

109
```python { .api }
110
from astroquery.lamda import Lamda
111

112
def query(molecule: str = None, **kwargs) -> Table:
113
    """
114
    Query LAMDA database for molecular data.
115
    
116
    Parameters:
117
    - molecule: Molecule name or formula
118
    - **kwargs: Additional query parameters
119
    
120
    Returns:
121
    Table with molecular data and collision rates
122
    """
123

124
def get_datafile(molecule: str, cache: bool = True) -> str:
125
    """
126
    Download LAMDA data file for a molecule.
127
    
128
    Parameters:
129
    - molecule: Molecule name
130
    - cache: Enable file caching
131
    
132
    Returns:
133
    Path to downloaded data file
134
    """
135

136
def list_molecules() -> List[str]:
137
    """
138
    Get list of available molecules in LAMDA.
139
    
140
    Returns:
141
    List of molecule names
142
    """
143

144
# Configuration
145
from astroquery.lamda import conf
146
conf.server: str              # LAMDA server URL
147
conf.timeout: int = 60        # Connection timeout
148
```
149

150
Usage examples:
151

152
```python
153
from astroquery.lamda import Lamda
154

155
# Query CO molecule data
156
co_data = Lamda.query(molecule='co')
157
print(f"CO has {len(co_data)} energy levels")
158

159
# Download full data file for detailed analysis
160
co_file = Lamda.get_datafile('co')
161
print(f"Downloaded CO data to: {co_file}")
162

163
# List all available molecules
164
molecules = Lamda.list_molecules()
165
print(f"LAMDA contains {len(molecules)} molecules")
166
sulfur_molecules = [m for m in molecules if 'S' in m]
167
print(f"Sulfur-bearing molecules: {sulfur_molecules}")
168

169
# Query specific molecule for radiative transfer modeling
170
h2co_data = Lamda.query(molecule='h2co-h2')
171
```
172

173
### NIST - Atomic Spectral Lines
174

175
NIST Atomic Spectra Database provides comprehensive atomic spectral line data including wavelengths, transition probabilities, and energy levels for all elements.
176

177
```python { .api }
178
from astroquery.nist import Nist
179

180
def query(linename: str, wavelength_range: Tuple[float, float] = None,
181
         wavelength_type: str = 'vacuum', wavelength_unit: str = 'Angstrom',
182
         energy_level_unit: str = 'eV', output_order: str = 'wavelength',
183
         get_query_payload: bool = False) -> Table:
184
    """
185
    Query NIST atomic spectral line database.
186
    
187
    Parameters:
188
    - linename: Element name or ion (e.g., 'H I', 'Fe II', 'Ca')
189
    - wavelength_range: Wavelength range as (min, max) tuple
190
    - wavelength_type: 'vacuum' or 'air'  
191
    - wavelength_unit: Wavelength unit ('Angstrom', 'nm', 'um')
192
    - energy_level_unit: Energy unit ('eV', 'cm-1', 'Ry')
193
    - output_order: Sort order ('wavelength', 'multiplet')
194
    - get_query_payload: Return query parameters instead of executing
195
    
196
    Returns:
197
    Table with atomic spectral line data
198
    """
199

200
def query_async(linename: str, **kwargs) -> JobResults:
201
    """
202
    Submit asynchronous query for atomic spectral lines.
203
    
204
    Parameters:
205
    - linename: Element name or ion
206
    - **kwargs: Additional query parameters
207
    
208
    Returns:
209
    JobResults object for retrieving results
210
    """
211

212
# Configuration  
213
from astroquery.nist import conf
214
conf.server: str              # NIST server URL
215
conf.timeout: int = 60        # Connection timeout
216
```
217

218
Usage examples:
219

220
```python
221
from astroquery.nist import Nist
222
import astropy.units as u
223

224
# Query hydrogen Balmer lines
225
h_lines = Nist.query('H I', wavelength_range=(3000, 7000),
226
                    wavelength_unit='Angstrom')
227
print(f"Found {len(h_lines)} hydrogen lines")
228
print(h_lines['Wavelength', 'Aki', 'Lower Level', 'Upper Level'])
229

230
# Query iron lines in specific wavelength range
231
fe_lines = Nist.query('Fe II', wavelength_range=(4000, 5000),
232
                     wavelength_type='air')
233
strong_fe = fe_lines[fe_lines['Aki'] > 1e8]  # Strong transitions
234
print(f"Found {len(strong_fe)} strong Fe II lines")
235

236
# Query calcium lines with energy level information
237
ca_lines = Nist.query('Ca I', wavelength_range=(3900, 4500),
238
                     energy_level_unit='cm-1')
239
```
240

241
### Hitran - Molecular Absorption Database
242

243
HITRAN provides high-resolution molecular absorption data essential for atmospheric and stellar spectroscopy, containing line parameters for greenhouse gases and other molecules.
244

245
```python { .api }
246
from astroquery.hitran import Hitran
247

248
def query_lines(molecule_number: int, isotopologue_number: int,
249
               min_frequency: float, max_frequency: float,
250
               **kwargs) -> Table:
251
    """
252
    Query HITRAN molecular absorption lines.
253
    
254
    Parameters:
255
    - molecule_number: HITRAN molecule number
256
    - isotopologue_number: Isotopologue number  
257
    - min_frequency: Minimum frequency (cm-1)
258
    - max_frequency: Maximum frequency (cm-1)
259
    - **kwargs: Additional line parameters
260
    
261
    Returns:
262
    Table with molecular absorption line data
263
    """
264

265
def query_lines_async(molecule_number: int, isotopologue_number: int,
266
                     min_frequency: float, max_frequency: float,
267
                     **kwargs) -> JobResults:
268
    """
269
    Submit asynchronous query for molecular lines.
270
    
271
    Parameters:
272
    - molecule_number: HITRAN molecule number
273
    - isotopologue_number: Isotopologue number
274
    - min_frequency: Minimum frequency (cm-1)
275
    - max_frequency: Maximum frequency (cm-1)
276
    - **kwargs: Additional parameters
277
    
278
    Returns:
279
    JobResults object for retrieving results
280
    """
281

282
def get_molecule_identifier(molecule_name: str) -> Dict[str, int]:
283
    """
284
    Get HITRAN molecule and isotopologue numbers.
285
    
286
    Parameters:
287
    - molecule_name: Molecule name (e.g., 'CO2', 'H2O')
288
    
289
    Returns:
290
    Dictionary with molecule and isotopologue numbers
291
    """
292

293
# Configuration
294
from astroquery.hitran import conf  
295
conf.server: str              # HITRAN server URL
296
conf.timeout: int = 60        # Connection timeout
297
```
298

299
Usage examples:
300

301
```python
302
from astroquery.hitran import Hitran
303

304
# Query CO2 absorption lines (molecule_number=2, isotopologue=1)
305
co2_lines = Hitran.query_lines(molecule_number=2, isotopologue_number=1,
306
                              min_frequency=2000.0, max_frequency=2100.0)
307
print(f"Found {len(co2_lines)} CO2 lines")
308
print(co2_lines['nu', 'sw', 'gamma_air'])  # frequency, intensity, broadening
309

310
# Query water vapor lines  
311
h2o_lines = Hitran.query_lines(molecule_number=1, isotopologue_number=1,
312
                              min_frequency=1500.0, max_frequency=1600.0)
313

314
# Get molecule identifiers
315
molecule_ids = Hitran.get_molecule_identifier('CH4')
316
print(f"Methane: molecule={molecule_ids['molecule']}, "
317
      f"isotopologue={molecule_ids['isotopologue']}")
318
```
319

320
### Atomic Line Database - AtomDB
321

322
Additional atomic and ionic line databases for X-ray and UV spectroscopy, particularly useful for hot plasma diagnostics and stellar atmosphere modeling.
323

324
```python { .api }
325
from astroquery.atomic import AtomicLineList
326

327
def query_lines(wavelength_range: Tuple[float, float] = None,
328
               element: str = None, minimal_abundance: float = None,
329
               wavelength_unit: str = 'Angstrom', wavelength_type: str = 'air') -> Table:
330
    """
331
    Query atomic line databases for spectral lines.
332
    
333
    Parameters:
334
    - wavelength_range: Wavelength range as (min, max) tuple
335
    - element: Element symbol or name
336
    - minimal_abundance: Minimum abundance threshold
337
    - wavelength_unit: Wavelength unit
338
    - wavelength_type: 'air' or 'vacuum'
339
    
340
    Returns:
341
    Table with atomic line data
342
    """
343

344
# Configuration
345
from astroquery.atomic import conf
346
conf.server: str              # Atomic database server URL
347
conf.timeout: int = 60        # Connection timeout
348
```
349

350
Usage examples:
351

352
```python
353
from astroquery.atomic import AtomicLineList
354

355
# Query UV lines of various elements
356
uv_lines = AtomicLineList.query_lines(wavelength_range=(1000, 3000),
357
                                     wavelength_unit='Angstrom')
358
print(f"Found {len(uv_lines)} UV atomic lines")
359

360
# Query specific element lines
361
oxygen_lines = AtomicLineList.query_lines(element='O',
362
                                         wavelength_range=(5000, 6000))
363
```
364

365
## Common Types
366

367
```python { .api }
368
from astropy.table import Table
369
from astropy.units import Quantity
370
from typing import Union, List, Tuple, Dict, Optional
371

372
# Input types
373
min_frequency: Union[float, Quantity]       # Minimum frequency
374
max_frequency: Union[float, Quantity]       # Maximum frequency  
375
wavelength_range: Tuple[float, float]       # Wavelength range
376
chemical_name: str                          # Chemical formula/name
377
molecule_number: int                        # HITRAN molecule ID
378
isotopologue_number: int                    # Isotopologue ID
379

380
# Query parameters
381
energy_max: float                           # Maximum energy
382
line_strengths: List[str]                   # Line strength categories
383
wavelength_unit: str = 'Angstrom'          # Wavelength unit  
384
wavelength_type: str = 'vacuum'            # Air or vacuum wavelengths
385
energy_level_unit: str = 'eV'              # Energy unit
386

387
# Return types
388
Table                                       # Spectral line data
389
JobResults                                  # Asynchronous results
390
List[str]                                  # Available molecules/species
391
Dict[str, int]                             # Molecule identifiers
392
str                                        # Downloaded file path
393
```