MUSE Pipeline Reference Manual  2.1.1
Functions
Astronomical tools

Functions

double muse_astro_compute_airmass (double aRA, double aDEC, double aLST, double aExptime, double aLatitude)
 Compute the effective airmass of an observation. More...
 
double muse_astro_airmass (cpl_propertylist *aHeader)
 Derive the effective airmass of an observation from information in a FITS header. More...
 
double muse_astro_posangle (const cpl_propertylist *aHeader)
 Derive the position angle of an observation from information in a FITS header. More...
 
double muse_astro_parangle (const cpl_propertylist *aHeader)
 Properly average parallactic angle values of one exposure. More...
 
double muse_astro_angular_distance (double aRA1, double aDEC1, double aRA2, double aDEC2)
 Compute angular distance in the sky between two positions. More...
 
double muse_astro_wavelength_vacuum_to_air (double aVac)
 Compute air wavelength for a given vacuum wavelength. More...
 
muse_astro_rvcorr muse_astro_rvcorr_compute (const cpl_propertylist *aHeader)
 Compute radial velocity corrections given the header of an exposure. More...
 

Detailed Description

Functions in this group are related to handling of astronomical properties. They are partly based on pilastroutils/giastroutils, and girvcorrection taken from the VIMOS and GIRAFFE pipelines (written by Carlo Izzo and Ralf Palsa, (C) 2000-2004 and 2002-2006 European Southern Observatory).

Function Documentation

double muse_astro_airmass ( cpl_propertylist *  aHeader)

Derive the effective airmass of an observation from information in a FITS header.

Parameters
aHeaderthe FITS header to use
Returns
The computed average airmass or -1 on error.

The function queries the necessary header keywords from the input propertylist and calls muse_astro_compute_airmass() to do the actual computation. It compares the result with the ESO.TEL.AIRM.START and ESO.TEL.AIRM.END keywords if they are found in the input header and gives a warning if the output is not in between those values (with a fuzzyness of 0.005).

Exceptions
set CPL_ERROR_ILLEGAL_INPUT, return -1aHeader is NULL

Definition at line 331 of file muse_astro.c.

References muse_astro_compute_airmass(), muse_pfits_get_airmass_end(), muse_pfits_get_airmass_start(), muse_pfits_get_dec(), muse_pfits_get_exptime(), muse_pfits_get_geolat(), muse_pfits_get_lst(), and muse_pfits_get_ra().

Referenced by muse_dar_correct(), muse_flux_calibrate(), muse_postproc_process_exposure(), and muse_resampling_euro3d().

double muse_astro_angular_distance ( double  aRA1,
double  aDEC1,
double  aRA2,
double  aDEC2 
)

Compute angular distance in the sky between two positions.

Parameters
aRA1RA [deg] of first position
aDEC1DEC [deg] of first position
aRA2RA [deg] of second position
aDEC2DEC [deg] of second position
Returns
The computed angular distance in degrees.

This function just implements the Vincenty formula from http://en.wikipedia.org/w/index.php?title=Great-circle_distance&oldid=599795109#Computational_formulas

Definition at line 496 of file muse_astro.c.

Referenced by muse_flux_response_compute(), and muse_postproc_load_nearest().

double muse_astro_compute_airmass ( double  aRA,
double  aDEC,
double  aLST,
double  aExptime,
double  aLatitude 
)

Compute the effective airmass of an observation.

Parameters
aRAright ascension in degrees
aDECdeclination in degrees
aLSTlocal sidereal time in seconds elapsed since siderial midnight
aExptimeintegration time in seconds
aLatitudelatitude of the observatory site in degrees
Returns
The computed average airmass or -1 on error.

The function calculates the average airmass for the line of sight given by the right ascension aRA and the declination aDEC. The latitude aLatitude in degrees of the observatory site and the local siderial time aLST at observation start has to be given, as well as the duration of the observation, i.e. the exposure time aExptime. If aExptime is zero then only one value of airmass is computed, instead of weighting beginning, middle, and end of exposure according to Stetson (Stetson P., 1987, PASP 99, 191).

This function uses the approximation given by Hardie (Hardie 1962, In: "Astronomical Techniques", ed. Hiltner, p. 184) to compute the airmass as a function of zenith distance.

Note
This function can be recompiled to use the formula of Young and Irvine (Young A. T., Irvine W. M., 1967, Astron. J. 72, 945) instead of the less widely used Hardie (1962). Then the range of trustworthy airmass outputs is only between 1 and 4.
This function can be recompiled to use the formula of Young (Young A. T., 1994 ApOpt, 33, 1108).
http://en.wikipedia.org/w/index.php?title=Airmass&oldid=358226579#Interpolative_formulas has an interesting collection of other approximations.
Exceptions
set CPL_ERROR_ILLEGAL_INPUT, return -1aRA, aDEC, aLST, or aLatitude values are not in a sensible range
set CPL_ERROR_ILLEGAL_INPUT, return -1aExptime is negative
output warning, set CPL_ERROR_ILLEGAL_OUTPUT, return -1the computed zenith distance is invalid

Definition at line 207 of file muse_astro.c.

Referenced by muse_astro_airmass().

double muse_astro_parangle ( const cpl_propertylist *  aHeader)

Properly average parallactic angle values of one exposure.

Parameters
aHeaderthe FITS header to use
Returns
The average parallactic angle or 0 on error.

The function queries the header keywords ESO.TEL.PARANG.START and ESO.TEL.PARANG.END, and if a large flip occurs between them (i.e. from ~-180 to ~+180) it properly averages them to a value with an absolute of ~180 not around zero.

Exceptions
set CPL_ERROR_NULL_INPUT, return 0.aHeader is NULL
output warning, propagate error from muse_pfits_get_parang_start()ESO.TEL.PARANG.START could not be found in the input aHeader
output warning, propagate error from muse_pfits_get_parang_end()ESO.TEL.PARANG.END could not be found in the input aHeader

Definition at line 449 of file muse_astro.c.

References muse_pfits_get_parang_end(), and muse_pfits_get_parang_start().

Referenced by muse_dar_correct(), and muse_resampling_euro3d().

double muse_astro_posangle ( const cpl_propertylist *  aHeader)

Derive the position angle of an observation from information in a FITS header.

Parameters
aHeaderthe FITS header to use
Returns
The computed position angle or 0 on error.

The function queries the header keyword INS.DROT.POSANG and INS.DROT.MODE. If INS.DROT.MODE is found to be "SKY", the sign found in POSANG is inverted, for "STAT" it is not. For all other cases, it's not clear what should happen, so output a warning and leave the original sign untouched.

Exceptions
set CPL_ERROR_NULL_INPUT, return 0.aHeader is NULL
propagate error from muse_pfits_get_drot_posang()INS.DROT.POSANG could not be found in the input aHeader
propagate error from muse_pfits_get_drot_mode()INS.DROT.MODE could not be found in the input aHeader

Definition at line 413 of file muse_astro.c.

References muse_pfits_get_drot_mode(), and muse_pfits_get_drot_posang().

Referenced by muse_dar_correct(), muse_geo_measure_spots(), muse_resampling_params_delete(), and muse_wcs_apply_cd().

muse_astro_rvcorr muse_astro_rvcorr_compute ( const cpl_propertylist *  aHeader)

Compute radial velocity corrections given the header of an exposure.

Parameters
aHeaderthe FITS header to use
Returns
the function returns a structure with the three velocity corrections, or zero for every component on error.

The function takes the information about the telescope location, the observation time and the epoch from aHeader and computes the barycentric, heliocentric and geocentric corrections for the telescope pointing. The motion of the observing site to the geocentric velocity is taken into account in the bary- and heliocentric corrections.

The computed corrections are in units of km/s.

Exceptions
set CPL_ERROR_NULL_INPUT, return zero for every componentaHeader is NULL
set CPL_ERROR_DATA_NOT_FOUND, propagate error codes, return zero for every componentaHeader does not contain all necessary info

Definition at line 1197 of file muse_astro.c.

References muse_astro_rvcorr::bary, muse_astro_rvcorr::geo, muse_astro_rvcorr::helio, muse_pfits_get_dec(), muse_pfits_get_equinox(), muse_pfits_get_exptime(), muse_pfits_get_geoelev(), muse_pfits_get_geolat(), muse_pfits_get_geolon(), muse_pfits_get_mjdobs(), and muse_pfits_get_ra().

Referenced by muse_rvcorrect().

double muse_astro_wavelength_vacuum_to_air ( double  aVac)

Compute air wavelength for a given vacuum wavelength.

Parameters
aVacwavelength in vacuum [Angstrom]
Returns
The computed wavelength in air [Angstrom]

According to http://www.sdss3.org/dr10/spectro/spectro_basics.php#vacuum the formula used comes from Morton 1991 ApJS 77, 119, and represents the IAU standard conversion relation.

http://www.iau.org/static/resolutions/IAU1991_French.pdf mentions Oosterhoff. P.T. 1957 Trans IAU Vol. IX pp. 69. 202 to be that standard reference, which Morton refers to as well.

Definition at line 534 of file muse_astro.c.

References muse_astro_rvcorr::bary, muse_astro_rvcorr::geo, and muse_astro_rvcorr::helio.

Referenced by muse_flux_reference_table_check().