rvs_desi_fit¶

The rvs_desi_fit command fits DESI spectra using the rvspecfit pipeline to determine radial velocities and stellar atmospheric parameters. This is the main interface for processing DESI spectroscopic data.

Purpose¶

This command is specifically designed for the Dark Energy Spectroscopic Instrument (DESI) survey data and provides:

Automated fitting of stellar spectra from DESI coadded files
Radial velocity and stellar parameter determination
Integration with DESI data formats and metadata
Support for parallel processing and MPI
Quality control and warning flags
Integration with redrock/zbest results

The command processes DESI coadd FITS files and produces tables with fitted parameters, quality metrics, and optional diagnostic plots.

Basic Usage¶

rvs_desi_fit --config config.yaml --output_dir ./results/ spectrum.fits

Command Line Options¶

Input Files and Selection¶

Positional Arguments

input_files: Space-separated list of DESI coadd FITS files to process.

File Input Options

--input_file_from FILENAME: Read the list of spectral files from a text file (one filename per line).
--queue_file: Treat the input file list as a queue where entries are deleted as soon as they’re processed. Useful for distributed processing.

Target Selection¶

--targetid TARGETID: Fit only a specific target ID. Useful for debugging or focused analysis.
--targetid_file_from FILENAME: Fit only target IDs listed in the specified file (one target ID per line).
--minsn THRESHOLD: Fit only spectra with signal-to-noise ratio larger than this threshold. Default: -1e9 (no filtering)
--minexpid EXPID: Process only exposures with exposure ID >= this value.
--maxexpid EXPID: Process only exposures with exposure ID <= this value.
--objtypes TYPES: Comma-separated list of object types to fit. Examples: 'MWS_ANY,SCND_ANY,STD_*'. Uses DESI target selection bitmasks.

Redrock Integration¶

--zbest_select: Use the zbest/redrock file to fit only potentially interesting targets (e.g., stars vs galaxies).
--zbest_include: Include zbest/redrock information in the output table without using it for target selection.

Processing Options¶

--config FILENAME: Path to the YAML configuration file specifying template library location and fitting parameters.
--nthreads N: Number of threads for parallel processing. Default: 1
--npoly N: Number of polynomial coefficients for continuum fitting. Overrides config file setting if specified.
--fitarm ARMS: Comma-separated list of spectral arms to fit. Options: 'b', 'r', 'z', or combinations like 'b,r,z'.
--param_init METHOD: Method for initializing fit parameters and radial velocity. Default: 'CCF' (cross-correlation function)

Resolution Matrix¶

--resolution_matrix: Use DESI resolution matrix in fitting for more accurate results.
--no-resolution_matrix: Do not use resolution matrix (faster but less accurate). Default behavior.

Output Control¶

--output_dir PATH: Output directory for result tables. Default: '.'
--output_tab_prefix PREFIX: Prefix for output table files. Default: 'rvtab'
--output_mod_prefix PREFIX: Prefix for output model files. Default: 'rvmod'
--subdirs / --no_subdirs: Create/don’t create subdirectories in output directory. Default: create subdirectories

File Handling¶

--overwrite: Overwrite existing output products. Otherwise, attempt to update/append.
--skipexisting: Skip processing if output products already exist.

Diagnostics and Plotting¶

--doplot: Generate diagnostic plots showing spectral fits.
--figure_dir PATH: Directory for fit figures. Default: './'
--figure_prefix PREFIX: Prefix for figure filenames. Default: 'fig'

Cross-Correlation Options¶

--ccf_continuum_normalize / --no_ccf_continuum_normalize: Enable/disable continuum normalization during cross-correlation. Default: enabled

Logging and Monitoring¶

--log FILENAME: Write log messages to specified file. For MPI runs, use %d to include rank in filename.
--log_level LEVEL: Set logging level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL. Default: WARNING
--process_status_file FILENAME: File to record successfully processed files for monitoring progress.

Advanced Options¶

--mpi: Use MPI for distributed processing across multiple nodes.
--throw_exceptions: Don’t protect against exceptions inside rvspecfit (useful for debugging).
--version: Display software version and exit.

Examples¶

Basic DESI Fitting¶

Process a single DESI coadd file:

rvs_desi_fit --config desi_config.yaml \
             --output_dir ./desi_results/ \
             coadd-sv1-bright-10378.fits

Batch Processing¶

Process multiple files with parallel processing:

rvs_desi_fit --config desi_config.yaml \
             --output_dir ./desi_results/ \
             --nthreads 8 \
             --process_status_file processing.log \
             coadd-*.fits

High S/N Stars Only¶

Fit only high signal-to-noise stellar targets:

rvs_desi_fit --config desi_config.yaml \
             --output_dir ./stellar_results/ \
             --minsn 10 \
             --objtypes 'MWS_ANY,SCND_ANY' \
             --zbest_select \
             coadd-sv1-bright-10378.fits

Specific Target Analysis¶

Analyze specific targets with diagnostic plots:

echo "39628422527323686" > targets.txt
echo "39628422531515839" >> targets.txt

rvs_desi_fit --config desi_config.yaml \
             --output_dir ./target_analysis/ \
             --targetid_file_from targets.txt \
             --doplot \
             --figure_dir ./plots/ \
             --log_level DEBUG \
             coadd-sv1-bright-10378.fits

Single Arm Processing¶

Fit only the blue arm spectra:

rvs_desi_fit --config desi_config.yaml \
             --output_dir ./blue_arm_results/ \
             --fitarm b \
             --resolution_matrix \
             coadd-sv1-bright-10378.fits

Queue-Based Processing¶

Use a file queue for distributed processing:

ls /data/desi/coadd-*.fits > file_queue.txt

rvs_desi_fit --config desi_config.yaml \
             --output_dir ./queue_processing/ \
             --input_file_from file_queue.txt \
             --queue_file \
             --mpi \
             --nthreads 4

Configuration File¶

The command requires a YAML configuration file specifying template library paths and fitting parameters:

# desi_config.yaml
template_lib: '/path/to/desi_templates/'
min_vel: -1000      # km/s
max_vel: 1000       # km/s
min_vel_step: 0.2   # km/s
vel_step0: 5        # km/s
min_vsini: 0.1      # km/s
max_vsini: 500      # km/s

Output Files¶

Result Tables¶

rvtab_<filename>.fits (or custom prefix)

Main results table with columns:

TARGETID: DESI target identifier
VRAD: Radial velocity [km/s]
VRAD_ERR: Radial velocity uncertainty [km/s]
TEFF: Effective temperature [K]
TEFF_ERR: Temperature uncertainty [K]
LOGG: Surface gravity [dex]
LOGG_ERR: Surface gravity uncertainty [dex]
FEH: Metallicity [Fe/H] [dex]
FEH_ERR: Metallicity uncertainty [dex]
ALPHA: Alpha enhancement [α/Fe] [dex]
ALPHA_ERR: Alpha enhancement uncertainty [dex]
VSINI: Rotational velocity [km/s]
VSINI_ERR: Rotational velocity uncertainty [dex]
CHISQ_TOT: Total χ² of the fit
RVS_WARN: Quality warning bitmask
Additional DESI metadata columns

Model Spectra¶

rvmod_<filename>.fits (or custom prefix): Best-fit model spectra for comparison with observations.

Quality Flags¶

The RVS_WARN bitmask indicates potential issues:

1 (CHISQ_WARN): χ² vs continuum is suspiciously large
2 (RV_WARN): Radial velocity too close to search boundaries
4 (RVERR_WARN): Radial velocity uncertainty too large
8 (PARAM_WARN): Stellar parameters too close to grid boundaries
16 (VSINI_WARN): v sin i value suspiciously large
32 (BAD_SPECTRUM): Problem with spectrum itself
64 (BAD_HESSIAN): Issue with error estimation (Hessian matrix)

DESI Data Integration¶

File Format Support¶

Reads DESI coadd FITS files with standard extensions
Handles DESI fibermap information for target metadata
Supports DESI spectral resolution matrices
Compatible with DESI data model conventions

Target Selection¶

Uses DESI target selection bitmasks:

MWS_ANY: Milky Way Survey targets
SCND_ANY: Secondary targets
STD_*: Standard stars (various types)

Object types are filtered using DESI OBJTYPE and DESI_TARGET information.

Redrock Integration¶

When --zbest_select or --zbest_include are used:

Reads redrock/zbest files associated with input spectra
Can filter targets based on redrock classifications
Includes redrock redshifts and spectral types in output

Performance Considerations¶

Single Node Processing: - Use --nthreads to parallelize across CPU cores - Typical performance: ~10-100 spectra per minute per core - Memory usage: ~1-2 GB per thread

Multi-Node Processing: - Use --mpi for distributed processing - Requires MPI-enabled environment - Use --queue_file with shared file system for work distribution - Log files should include MPI rank: --log logfile_%d.log

Resolution Matrix: - --resolution_matrix improves accuracy but increases compute time by ~2-3x - Recommended for final science analysis - May not be necessary for initial target screening

Troubleshooting¶

File Access Issues: Ensure DESI files are accessible and properly formatted. Check file permissions and paths.
Template Library Problems: Verify config file points to correct template library. Ensure all required template files (ccf, interp, etc.) are present.
Memory Issues: Reduce --nthreads or process smaller batches. High-resolution fits require substantial memory.
MPI Problems: Check MPI installation and network configuration. Ensure shared filesystem access across nodes.
Target Selection Issues: Verify --objtypes matches DESI target selection. Check that zbest files exist if using zbest options.
Quality Warnings: High RVS_WARN values indicate potential fit issues. Check individual spectra and consider filtering criteria.

Integration with DESI Pipeline¶

The command integrates with DESI data processing workflows:

Input: DESI coadd spectra from spectroscopic pipeline
Processing: rvspecfit analysis with DESI-specific adaptations
Output: FITS tables compatible with DESI data model
Quality: Warning flags following DESI conventions

Results can be ingested into DESI databases or used for science analysis following DESI data access protocols.

rvs_desi_fit¶

Purpose¶

Basic Usage¶

Command Line Options¶

Input Files and Selection¶

Target Selection¶

Redrock Integration¶

Processing Options¶

Resolution Matrix¶

Output Control¶

File Handling¶

Diagnostics and Plotting¶

Cross-Correlation Options¶

Logging and Monitoring¶

Advanced Options¶

Examples¶

Basic DESI Fitting¶

Batch Processing¶

High S/N Stars Only¶

Specific Target Analysis¶

Single Arm Processing¶

Queue-Based Processing¶

Configuration File¶

Output Files¶

Result Tables¶

Model Spectra¶

Quality Flags¶

DESI Data Integration¶

File Format Support¶

Target Selection¶

Redrock Integration¶

Performance Considerations¶

Troubleshooting¶

Integration with DESI Pipeline¶

See Also¶

rvspecfit

Navigation

Related Topics