The obstools module stores tools for oberving (pre- and post-) as well as functioning as a module for various corrections and simple calculations that don’t have a better place to live.
Most implementations are for optical astronomy, as that is what the primary author does.
Note that throughout this module it is assumed that UTC as used in datetime is the same as UT1 (the UT used for calculations). This is only an issue if leapseconds stop being updated or if something such as daylight savings time calculations in datetime are important to be correct to less than DUT1 - otherwise, the “UTC” in datetime can simply by replaced with UT1 values when precision better than DUT1 is needed.
Also note that some of these functions require the dateutil package (it is installed by default with matplotlib)
See also
astropysics.coords.earth_rotation_angle() astropysics.coords.greenwich_sidereal_time()
Bases: astropysics.obstools.Extinction
This is the average extinction law derived in Calzetti et al. 1994: x=1/lambda in mu^-1 Q(x)=-2.156+1.509*x-0.198*x**2+0.011*x**3
Bases: astropysics.obstools._EBmVExtinction
Milky Way Extinction law from Cardelli et al. 1989
Bases: object
This is the base class for extinction-law objects. Extinction laws can be passed in as a function to the initializer, or subclasses should override the function f with the preferred law as f(self,lambda), and their initializers should set the zero point
Note that functions are interpreted as magnitude extinction laws ... if optical depth is desired, f should return (-2.5/log(10))*tau(lambda)
A0 is the normalization factor that gets multiplied into the reddening law.
determines the extinction for this extinction law in a given band or bands
band can be a wavelength or a string specifying a band
This derives the normalization of the Extinction function from provided ratios for theoretically expected fluxes. If multiple measurements are provided, the mean will be used
measured is the measured line ratio (possibly an array), while expected is either the expected line ratios, or a string specifying the appropriate balmer flux ratio as “Hab”,”Hde”,etc. (for Halpha/Hbeta or Hdelta/Hepsilon) to assume case B recombination fluxes (see e.g. Osterbrock 2007).
lambda1 and lambda2 are the wavelengths for the ratios F1/F2, or None if a string is provided
filterfunc is a function to be applied as the last step - it can either be used to contract an array to (e.g. np.mean), or filter out invalid values (e.g. lambda x:x[np.isfinite(x)]). Default does nothing
returns A0,standard deviation of measurements
Uses the supplied extinction law to correct a color (or array of colors) where the color is in the specified bands
bands is a length-2 sequence with either a band name or a wavelength for the band, or of the form ‘bandname1-bandname2’ or ‘E(band1-band2)’
Uses the extinction law to correct a magnitude (or array of magnitudes)
bands is either a string specifying the band, or a wavelength to use
Uses the supplied extinction law to correct a spectrum for extinction.
if newspec is True, a copy of the supplied spectrum will have the extinction correction applied
returns the corrected spectrum
Bases: astropysics.obstools._EBmVExtinction
Base class for Extinction classes that use the form from Fitzpatrick & Massa 90
Bases: astropysics.obstools.FMExtinction
LMC Extinction law from Gordon et al. 2003 LMC Average Sample
Bases: astropysics.obstools.FMExtinction
SMC Extinction law from Gordon et al. 2003 SMC Bar Sample
Bases: object
This class represents a location on Earth from which skies are observable.
lat/long are coords.AngularCoordinate objects, altitude in meters. latitude here is the geographic/geodetic latitude.
generate a site by specifying latitude and longitude (as coords.AngularCoordinate objects or initializers for one), optionally providing altitude (in meters), time zone (either as a timezone name provided by the system or as an offset from UTC), and/or a site name.
Altitude of the site in meters
computes the positions in horizontal coordinates of an object with the provided fixed coordinates at the requested time(s).
datetime can be a sequence of datetime objects or similar representations, or it can be a sequnce of JD’s. If None, it uses the current time or the value of the currentobsjd property.
If precess is True, the position will be precessed to the epoch of the observation (almost always the right thing to do)
If refraction is True, an added correction to the altitude due to atmospheric refraction at STP (formula from Meeus ch 16) is included. If refraction is a (non-0) float, it will be taken as the temperature at which to perform the refraction calculation. If it evaluates to False, no refraction correction is performed
returns a sequence of astropysics.coords.HorizontalCoordinates objects
Date and time to use for computing time-dependent values. If set to None, the jd at the instant of calling will be used. It can also be set as datetime objects or (yr,mon,day,hr,min,sec) tuples.
Generates a list of horizontal positions (or just one) from a provided equatorial position and local siderial time (or sequence of LSTs) in decimal hours and a latitude in degrees. If epoch is not None, it will be used to set the epoch in the equatorial system.
Note that this generally should not be used to compute the observed horizontal coordinates directly - apparentCoordinates() includes all the corrections and formatting. This method is purely for the coordinate conversion.
Geographic/Geodetic Latitude of the site as an AngularCoordinate object
Compute the local siderial time given an input civil time. The various input forms are used to determine the interpretation of the civil time:
current local siderial time for this Site or uses the value of the currentobsjd property.
input argument is julian date UT1
compute the local siderial time for midnight on the given date
the datetime object specifies the local time. If it has tzinfo, the object’s time zone will be used, otherwise the Site's
input arguments determine local time - time is in hours
local time - hours and minutes will be interpreted as integers
keywords
if True (default) the returned time will be local apparent sidereal time (i.e. nutation terms included), otherwise it will be local mean sidereal time
a string that determines the form of the returned LST as described below
returns the local siderial time in a format that depends on the returntype keyword. It can be:
LST in decimal hours
LST as a hh:mm:ss.s
a datetime.time object
Computes the local civil time given a particular local siderial time.
lsts are the input local times, and may be either a scalar or array, and must be in decimal hours. Althernatively, it can be a datetime.datetime object, in which case the date will be inferred from this object and the date argument will be ignored.
date should be a datetime.date object or a (year,month,day) tuple. If None, the current date will be assumed as inferred from Site.currentobsjd
if lsts is a datetime.datetime object, the object will be interpreted as the local siderial time with the corresponding date (any timezone info will be ignored), and the date argument will be ignored.
if apparent is True, the inputs are assumed to be in local apparent siderial time (i.e. nutation terms included), otherwise local mean siderial time.
returns the local time in a format that depends on the returntype keyword. It can be:
local time in decimal hours
local time as a hh:mm:ss.s
a datetime.time object with the appropriate tzinfo
If utc is True, the time will be converted to UTC before being returned.
Longitude of the site as an AngularCoordinate object
Get ‘next’ rise,set,transit for an equatorial position at a given datetime (see details).
If on-sky at the specified datetime, returns the rise / set times bracketing current transit, i.e. returns rise, set, transit such that rise < now < set; so rise and possibly transit will be in the past at specified time.
If the target is off-sky currently, then rise/transit/set will all be in the future, so now < rise < transit < set.
If circumpolar (always visible) rise/set are None, and next transit is returned. If never visible, rise / set / transit are all None.
NB The only dates checked for visibility are ‘today’ and ‘tomorrow’ (relative to given datetime). If the target is an edge case that’s below the horizon all day today, but is visible in 6 months, you will still get a None result.
See also: riseSetTransit
args alt` determines the altitude to be considered as risen or set in degrees. Default is for approximate rise/set including refraction.
dtime determines the datetime at which to do the computation. See calendar_to_jd() for acceptable formats. If None, the current datetime will be assumed as inferred from Site.currentobsjd
returns (rise,set,transit) as :class:datetime.datetime objects (UTC). If the object is circumpolar, rise and set are both None. If it is never visible, rise, set, and transit are all None.
Generates plots of important observability quantities for the provided coordinate objects for a single night.
coords should be a astropysics.coords.LatLongCoordinates, a sequence of such objects, or a dictionary mapping the name of an object to the object itself. These names will be used to label the plot.
plottype can be one of:
If onlynight is True, the plot will be shrunk to only show the times between sunset and sunrise. Otherwise, an entire day/night will be plotted.
If clf is True, the figure is cleared before the observing plot is made.
If utc is True, the times will be in UTC instead of local time.
colors should be a sequence of matplotlib color specifiers, or None to use the default color cycle.
plotkwargs will be provided as a keyword dictionary to matplotlib.pyplot.plot(), unless it is None
tabulates altitude, azimuth, and airmass values for the provided fixed position on a particular date, specified either as a datetime.date object, a (yr,mon,day) tuple, or a julain date (will be rounded to nearest)
if date is None, the current date is used
If localtime is True, the hours output (and input) will be in local time for this Site. Otherwise, it is UTC.
hrrange determines the size of the table - it should be a 3-tuple (starthr,endhr,n) where starthr is on the day specified in date and endhr is date + 1 day
if strtablename is True, a string is returned with a printable table of observing data. If strtable is a string, it will be used as the title for the table. Otherwise, a record array is returned with the hour(UTC), alt, az, and airmass
Checks if a target is on-sky at specified datetime.
NB on-sky means above minimum elevation as specifed by ‘alt’ parameter.
args eqpos Ra,Dec in equatorial co-ordinates.
dtime determines the datetime at which to do the computation. See calendar_to_jd() for acceptable formats. If None, the current datetime will be assumed as inferred from Site.currentobsjd
alt determines the altitude to be considered as risen or set in degrees. Default is for approximate rise/set including refraction.
Computes the rise, set, and transit times of a provided equatorial position in local time.
alt determines the altitude to be considered as risen or set in degrees. Default is for approximate rise/set including refraction.
date determines the date at which to do the computation. See calendar_to_jd() for acceptable formats. Note that this date is the date of the transit, so the rise and set times may be on the previous/following day.
returns (rise,set,transit) as :class:datetime.datetime objects if timeobj is True or if it is False, they are in decimal hours. If the object is circumpolar, rise and set are both None. If it is never visible, rise,set, and transit are all None
Plots the location transit and rise/set times of object(s) over ~year timescales.
coords should be a astropysics.coords.LatLongCoordinates, a sequence of such objects, or a dictionary mapping the name of an object to the object itself. These names will be used to label the plot.
startdate is a datetime.date object or a date tuple (year,month,day) that is used as the start of the plot.
n specifies the number of points to include of the objects
months is the number of months to draw the plot for.
If utc is True, the times will be in UTC instead of local time.
If clf is True, the figure is cleared before the observing plot is made.
colors should be a sequence of matplotlib color specifiers, or None to use the default color cycle.
Convert a calendar date and time to julian date.
| Parameters: |
|
|---|---|
| Returns: | JD as a float, or a sequence of JDs if sequences were input. |
Examples
>>> import datetime,dateutil
>>> calendar_to_jd((2010,1,1))
2455198.0
>>> calendar_to_jd(datetime.datetime(2000,12,21,3,0,0))
2451899.625
>>> calendar_to_jd([2004,3,(5,6)])
array([ 2453070., 2453071.])
>>> dates = [datetime.datetime(2004,3,5),datetime.datetime(2004,3,9)]
>>> calendar_to_jd(dates)
array([ 2453069.5, 2453073.5])
>>> tz = dateutil.tz.tzoffset('2',3*3600)
>>> calendar_to_jd((2010,1,1),tz)
2455197.875
Computes the difference between International Atomic Time (TAI) and UTC, known as delta(AT).
Note that this is not valid before UTC (Jan 1,1960) beganand it is not correct for future dates, as leap seconds are not predictable. Hence, warnings are issued if before UTC or >5 years from the date of the algorithm.
Implementation adapted from the matching SOFA algorithm (dat.c).
| Parameters: |
|
|---|---|
| Returns: | TAI - UTC in seconds as a float (or TT - UTC if usett is True) |
Converts a Julian or Besselian Epoch to a Julian Day.
| Parameters: |
|
|---|---|
| Returns: | The Julian Day as a float or array (if epoch is array-like) |
| Reference: |
Extinction correct a la Cardelli et al 89 from the supplied line data and a given E(B-V) along the sightline
inputs may be numpy arrays
linewl is in angstroms, lineflux in erg s^-1 cm^-2
if the input lineflux is None (or NaN but NOT False or 0) , Alambda is returned instead
frobs is the observed flux ratio f1/f2
frexpect is either a string code specifying a hydrogen transition (e.g. ‘Hab’ is Halpha/Hbeta, ‘Hde’ is Hdelta/Hepsilon, from Ostriker 2E) or a tuple of the form (expected f1/f2,lambda1,lambda2) wl in angstroms
outputs E(B-V) to a tolerance specified by tol if outlambda is 0/False/None, otherwise outputs Alambda (tol still determines E(B-V)) (outlambda can be UBVRI or ugriz as from B&M)
frobs can be an array, but other values cannot
Gets map values from Schlegel, Finkbeiner, and Davis 1998 extinction maps.
dustmap can either be a filename (if ‘%s’ appears in the string, it will be replaced with ‘ngp’ or ‘sgp’), or one of:
100-micron map in MJy/Sr
X-map, temperature-correction factor
Temperature map in degrees Kelvin for n=2 emissivity
E(B-V) in magnitudes
Mask values
For these forms, the files are assumed to lie in the current directory.
Input coordinates are in degrees of galactic latiude and logitude - they can be scalars or arrays.
if interpolate is an integer, it can be used to specify the order of the interpolating polynomial
Converts a julian date to a calendar date and time.
| Parameters: |
|
|---|---|
| Returns: | The calendar date and time in a format determined by the output parameter (see above). |
| Raises ValueError: | |
If rounding is larger than one second, or output is invalid. |
|
Examples
>>> jd_to_calendar(2451545)
datetime.datetime(2000, 1, 1, 12, 0, tzinfo=tzutc())
>>> jd_to_calendar(2305812.5)
datetime.datetime(1600, 12, 31, 0, 0, tzinfo=tzutc())
>>> jd_to_calendar([2415020.5,2305447.5],output='array')
array([[1900, 1, 1, 0, 0, 0, 0],
[1600, 1, 1, 0, 0, 0, 0]])
>>> jd_to_calendar(0.0,output='fracarray')
array([[ -4.71200000e+03, 1.00000000e+00, 1.50000000e+00]])
Converts a Julian Date to a Julian or Besselian Epoch expressed in decimal years.
| Parameters: |
|
|---|---|
| Returns: | The epoch as a string (or list of strings if jd was array-like) if asstring is True. If not, an int if a whole year, or a float (or array if jd was array-like). |
| Reference: |
Offset between Julian Date and Modified Julian Date - e.g. mjd = jd - mjdoffset