API Reference

obsplanning.GMST(datetime_in_UTC, dms=True)

For an input UT time, output the GMST.

Parameters:

• datetime_in_UTC (datetime.datetime) – dt object in UTC

• dms (bool) –

  Whether to return in sexagesimal components or decimal format.

  True (default) returns GMST in [int degrees, int minutes, float seconds]

  False returns GMST in decimal degrees

Returns:

GMST_24 – GMST time in 24-hr format

Return type:

list, or float

obsplanning.HA(LMST_hms, RA_in_decimal)

Compute hour angle from LMST and RA.

Hour Angle = L(M)ST - Right Ascension

Parameters:

• LMST_hms (list) – LMST in [H,M,S] format

• RA_in_decimal (float) – Right Ascension in decimal format

Returns:

HA_hms – Hour angle, in [H,M,S] format

Return type:

list

obsplanning.JD(time_in, string_format='%Y/%m/%d %H:%M:%S')

Converts a date/time to Julian Date

Parameters:

• time_in (datetime.datetime, ephem.Date, or string) – The input time. If given as a string, specify the format using string_format.

• string_format (str) – The format of time_in when it’s given as a string. Passed to dt.datetime.strptime to parse the input values.

Returns:

jd

Return type:

float

Notes

Equivalent output to pyephem.julian_date

Time since noon Universal Time on Monday, January 1, 4713 BC.

Algorithm from L. E. Doggett, Ch. 12, “Calendars”, p. 606, in Seidelmann 1992

obsplanning.LMST(GMST_in_hours, longitude_east_deg)

Compute LMST for GMST and longitude.

LMST = GMST + (observer’s east longitude)

Parameters:

• GMST_in_hours (list) – GMST in [int h, int m, float s]

• longitude_east_deg (float) – East longitude, in degrees

Returns:

LMST_hours

Return type:

float

obsplanning.LST_from_local(datetime_in_local, longitude_east_deg)

Compute Local Sidereal Time from timezone-aware datetime. See http://www.stargazing.net/kepler/altaz.html

Parameters:

• datetime_in_local (datetime.datetime) – Timezone-aware dt.datetime object (pytz.timezone included)

• longitude_east_deg (float) – East longitude, in degrees

Returns:

LST_hms – Local Sidereal Time in [H,M,S format]

Return type:

list

obsplanning.MJD(time_in, string_format='%Y/%m/%d %H:%M:%S')

Converts a date/time to Modified Julian Date

Parameters:

• time_in (datetime.datetime, ephem.Date, or string) – The input time. If given as a string, specify the format using string_format.

• string_format (str) – The format of time_in when it’s given as a string. Passed to dt.datetime.strptime to parse the values.

Returns:

mjd – The Modified Julian Date

Return type:

float

Notes

Definition of MJD relative to Julian Date: MJD = JD - 2400000.5

class obsplanning.Observer_with_timezone

A lightly-decorated version of a pyephem Observer object, which now includes a timezone attribute. This timezone can be set to a string name (Olson database) of the timezone corresponding to the Observer’s location (longitude/latitude).

obsplanning.VLBA_freq_minimum_sun_separation(frequency_GHz)

Calculates the recommended minimum source separation (in degrees) from the Sun for pointings in VLBA observations at a specified radio frequency in GHz.

The minimum separations vs frequency trend very cleanly follows a line in log space, so arbitrary frequencies (beyond the exact defined values) are calculated by interpolating from the defined NRAO list accordingly.

Parameters:

frequency_GHz (float) – The radio frequency of interest, in GHz

Returns:

minsep – The minimum separation from the Sun recommended for VLBA observations at the given frequency

Return type:

float

Note

Following the definitions in Table 17.1:

https://science.nrao.edu/facilities/vlba/docs/manuals/oss/referencemanual-all-pages

Example

obs.VLBA_freq_minimum_sun_separation(6.5) #–> 19.74 (degrees minimum here at C band)

obsplanning.add_sizebar(axin, length_pixels, label, loc=4, sep=5, borderpad=0.8, frameon=False, path_effects=[<matplotlib.patheffects.withStroke object>], color=None, **kwargs)

Add a sizebar to the specified matplotlib axis.

Parameters:

• axin (matplotlib axes object (Axes,AxesSubplot...)) –

• length_pixels (float) – The length of the sizebar, in pixels

• label (str) – The label for the bar annotation

• loc (int or str) – matplotlib location specifier

• sep (float) – matplotlib AnchoredSizeBar separation pad value

• borderpad (float) – matplotlib AnchoredSizeBar border pad value

• frameon (bool) – Whether to make the AnchoredSizeBar frame visible

• path_effects (list or matplotlib PathEffects) –

• color (str or matplotlib color specifier) –

• kwargs (various) – Optional keyword args for AnchoredSizeBar

Returns:

asb

Return type:

matplotlib AnchoredSizeBar

obsplanning.airmass2alt(airmass)

Secant(z) = 1/cos(z). z = 90-altitude(elevation)

Parameters:

airmass (float (or numpy.array of floats)) – Airmass along the telescope pointing LOS

Returns:

altitude – The altitude/elevation in degrees corresponding to the airmass

Return type:

float (or numpy.array of floats)

obsplanning.alt2airmass(altitude)

Secant(z) = 1/cos(z). z = 90-altitude(elevation)

Parameters:

altitude (float (or numpy.array of floats)) – The altitude/elevation in degrees

Returns:

airmass – The airmass at the specified altitude

Return type:

float (or numpy.array of floats)

obsplanning.angulardistance(coords1_deg, coords2_deg, pythag_approx=False, returncomponents=False, input_precision=<class 'numpy.float64'>)

Calculate the angular distance between [RA1,DEC1] and [RA2,DEC2] given in decimal (not sexagesimal). This function uses coordinate values directly for inputs; to use ephem objects as inputs instead, use obs.skysep_fixed_single(ephemsource1, ephemsource2)

Parameters:

• coords1_deg (float) – [RA,DEC] coordinates in degrees for the first object (decimal, not sexagesimal)

• coords2_deg (float) – [RA,DEC] coordinates in degrees for the second object (decimal, not sexagesimal)

• pythag_approx (bool) – If True, use the pythagorean approximation for the distance. (WARNING! only approximately valid for very small distances, such as for small fits images. Likely to be deprecated in a future release.)

• returncomponents (bool or str) –

  Valid options are

  1.)False or True (True defaults to option 2 below)

  2.) ‘cartesian’ or ‘RAcosDEC’

  3.) ‘spherical’ or ‘orthogonal’

  When set to False, only the total separation is returned. The other options will additionally return the component angular separations specified. ‘cartesian’ or ‘RAcosDEC’ will return the angular separations strictly following the longitude and latitude lines. i.e., the longitude component will be along constant lat lines, but will be modified by the cosine(DEC) term. ‘spherical’ or ‘orthogonal’ will return the orthogonal components in spherical coordinates (i.e. when viewed from directly above) – angles along great circles in EACH direction. The longitude/RA component here will not follow lines of constant DEC!

• input_precision (numpy precision dtype) – The precision to use for the calculation. Lower precision will consume less memory, but obviously at the expense of precision and potential for rounding errors. For VERY small angles, if you are getting results smaller than your desired precision, try increasing to np.float128.

Returns:

totalseparation_deg – Separation in degrees

Return type:

float

Notes

This assumes coords1 and coords2 are in the SAME coordinate system/equinox/etc.! Don’t mix ICRS and FK5 for example. For small separations (<~1deg), can approximate the result with a small correction to the pythagorean formula:

delta_RA=(RA1-RA2)*cos(DEC_average)

delta_DEC=(DEC1-DEC2)

total_sep=sqrt(delta_RA^2+delta_DEC^2)

Otherwise must use the full equation for arbitrary angular separation (central angle of great-circle distance) – for RA mapped to [0,2pi], DEC to [-pi/2,+pi/2]):

ang.dist.=arccos( sin(DEC1)sin(DEC2)+cos(DEC1)COS(DEC2)cos(RA1-RA2) )

However, this standard equation may suffer from rounding errors at small angles. For the particular case of equal major & minor axes (perfect sphere), a form that is accurate for all angles and positions, including antipodes, is angle =

( SQRT( (cos(DEC2)sin(RA1-RA2))^2 + (cos(DEC1)sin(DEC2)-sin(DEC1)cos(DEC2)cos(RA1-RA2))^2 ) )

arctan( —————————————————————————————— )

( sin(DEC1)sin(DEC2)+cos(DEC1)cos(DEC2)cos(RA1-RA2) )

Examples

obs.angulardistance([146.4247680, -14.3262771], [150.4908485, 55.6797891]) #–> 70.08988039585651

obs.angulardistance([146.0, -14.0], [146.0 - 1e-12, -14.0 + 1e-11], input_precision=np.float128) #–> 1.0045591516529160856e-11

obs.angulardistance([180., -10.], [160., 30.], returncomponents=True) #–> (44.38873913031471, -19.696155060244166, 40.0)

### But note carefully the effect of cos(DEC)

obs.angulardistance([120., 60.], [120., 0.], returncomponents=’cartesian’) #–> (59.999999999999986, 0.0, -59.99999999999999)

obs.angulardistance([120., 60.], [100., 60.], returncomponents=’cartesian’) #–> (9.961850643857742, -9.99999999999999, 0.0)

obs.angulardistance([120., 60.], [100., 60.], returncomponents=’spherical’) #–> (9.961850643857744, 9.961850643857813, 0.0) # DEC=60deg -> reduces ‘simple’ longitude diff of 20deg by ~ cos(pi/3)=0.5

### And note how a simple pythagorean approximation would give erroneous values # for the total separation.

obs.angulardistance([120., 60.], [100., 60.], returncomponents=True, pythag_approx=True) #–> array([ 10., -10., 0.])

obsplanning.autocalculate_observer_timezone(observer)

Determine the local timezone from a pyephem Observer object, using timezonefinder (previous tzwhere implementation now deprecated).

Parameters:

observer (ephem.Observer) – The pyephem Observer object which includes the site latitude & longitude

Returns:

timezone – The name of the local timezone (from the Olson database)

Return type:

str

Example

wht = obs.create_ephem_observer(‘WHT’, ‘-17 52 53.8’, ‘28 45 37.7’, 2344)

obs.autocalculate_observer_timezone(wht)

# –> ‘Atlantic/Canary’

obsplanning.band_from_freq(query_freq_GHz, print_table=False)

Takes an input frequency in GHz, and returns the radio band name string it corresponds to.

Parameters:

• query_freq_GHz (float) – The radio frequency to query, in GigaHertz. Current definitions span [0.054,50.0] GHz (Band ‘4’ through Q-band).

• print_table (bool) – Set to True to also print the entire table of radio band definitions (band name, frequency range, wavelength range) to screen

Returns:

resultband – The common name of the radio band corresponding to the input frequency

Return type:

str

Example

obs.band_from_freq(7.3)

#–> ‘C’

obsplanning.bgpars2pix(arrin, headerin, precise=True)

Calculate ellipse region params in terms of image/pixel coordinates – takes array

[RA (dec), DEC (dec), Rmaj (deg), Rmin (deg), PA (deg., N from W)].

Converts these angular (degree) RA,DEC,Rmaj,Rmin values to pixel values using the supplied fits header. Note the position angle follows the math definition (CCW from x=0) not the astronomical convention (CCW from N).

Parameters:

• arrin (list) – [RA (degrees), DEC (degrees), Rmaj (deg), Rmin (deg), PA (deg., N from W)]

• headerin (astropy.io.fits.Header) –

• precise (bool) – Whether to apply sub-pixel precision for coordinate conversion

Returns:

arrout – [Center_xpix, Center_ypix, Rmaj_pix, Rmin_pix, P.A.(CCW from x=0)]

Return type:

list

obsplanning.calc_optimal_slew_loop(targets, optimize_by='separation', verbose=False, repeat_loop=True, sortloops=False, return_format='names', AZ_deg_min=90.0, EL_deg_min=30.0, set_first=None, drop_wrap_repeats=True)

For an input list of input target ephem objects, generate all slew order permutations and calculate the total distance slewed (cumulative separations). Return the minimum.

Parameters:

• targets (array-like) – List or array of the ephem target sources to consider

• optimize_by (str) – ‘separation’ (shortest angular separation) or ‘time’ (uses specified motor slew speeds)

• repeat_loop (bool) – False optimize for single pass. True optimizes for repeat loops.

• sortloops (bool) – True sorts the list of permutations by cumulative separation. Currently only applies to verbose output.

• return_format (str) –

  Valid options are

  • ’names’ for only the list of source names

  • ’values’ for the cumulative slew angles/times

  • ’ephem’ for list of ephem objects

• AZ_deg_min (float) – Slew speed in telescope Azimuth axis, in degrees per minute. Defaults to 90 deg/min, the nominal VLBA value in AZ.

• float (EL_deg_min) – Slew speed in telescope Elevation axis, in degrees per minute. Defaults to 30 deg/min, the nominal VLBA value in EL.

• set_first (None or string or ephem source.) – If specified (other than None), only use permutations that start from that source.

• drop_wrap_repeats (bool) – If True and repeat_loop=True, wrap permutations and remove those that contain duplicate orderings (and reverses). For example, if [A,B,C] exists, then would drop [B,C,A] and [C,A,B] ( but not [A,C,B] )

Returns:

optimum_slew_loop – Depending on what is specified in return_format, the list will either contain ephem objects, a list of strings for the names, or floats for the slew loop durations.

Return type:

list

Examples

ngc6240 = obs.create_ephem_target(‘NGC 6240’, ‘16:52:58.90’, ‘02:24:03.6’)

J17353371p2047470 = obs.create_ephem_target(‘2MASX J17353371+2047470’, ‘17:35:33.76’, ‘20:47:47.0’)

CGCG341m006= obs.create_ephem_target(‘CGCG341-006’, ‘18:45:26.15’, ‘72:11:01.6’)

groupC = [ngc6240, J17353371p2047470, CGCG341m006, obs.SRC_3C345]

# Optimize purely by angular separation (not telescope slew speed)

calc_optimal_slew_loop(groupC, verbose=True, repeat_loop=True, sortloops=True, optimize_by=’sep’)

## printed to screen:

#Permutations (repeating the loop)

# [‘NGC 6240’, ‘2MASX J17353371+2047470’, ‘CGCG341-006’, ‘3C345’]: cumulative distance = 146.7 deg

# [‘NGC 6240’, ‘3C345’, ‘CGCG341-006’, ‘2MASX J17353371+2047470’]: cumulative distance = 146.7 deg

# [‘NGC 6240’, ‘2MASX J17353371+2047470’, ‘3C345’, ‘CGCG341-006’]: cumulative distance = 150.9 deg

# [‘NGC 6240’, ‘CGCG341-006’, ‘3C345’, ‘2MASX J17353371+2047470’]: cumulative distance = 150.9 deg

# [‘NGC 6240’, ‘CGCG341-006’, ‘2MASX J17353371+2047470’, ‘3C345’]: cumulative distance = 183.9 deg

# [‘NGC 6240’, ‘3C345’, ‘2MASX J17353371+2047470’, ‘CGCG341-006’]: cumulative distance = 183.9 deg

##returned output:

#[‘NGC 6240’, ‘2MASX J17353371+2047470’, ‘CGCG341-006’, ‘3C345’]

#

# Now optimize by the time it takes to slew the telescope, using supplied

# slew rates

calc_optimal_slew_loop(groupC, verbose=True, repeat_loop=True, sortloops=True, optimize_by=’time’, set_first=obs.SRC_3C345, AZ_deg_min=90., EL_deg_min=30.)

## printed to screen:

#Permutations (repeating the loop)

# [‘3C345’, ‘NGC 6240’, ‘2MASX J17353371+2047470’, ‘CGCG341-006’]: 4.65 min. (146.7 deg)

# [‘3C345’, ‘2MASX J17353371+2047470’, ‘NGC 6240’, ‘CGCG341-006’]: 4.65 min. (150.9 deg)

# [‘3C345’, ‘CGCG341-006’, ‘2MASX J17353371+2047470’, ‘NGC 6240’]: 4.65 min. (146.7 deg)

# [‘3C345’, ‘CGCG341-006’, ‘NGC 6240’, ‘2MASX J17353371+2047470’]: 4.65 min. (150.9 deg)

# [‘3C345’, ‘2MASX J17353371+2047470’, ‘CGCG341-006’, ‘NGC 6240’]: 5.92 min. (183.9 deg)

# [‘3C345’, ‘NGC 6240’, ‘CGCG341-006’, ‘2MASX J17353371+2047470’]: 5.92 min. (183.9 deg)

##returned output:

#[‘3C345’, ‘NGC 6240’, ‘2MASX J17353371+2047470’, ‘CGCG341-006’]

obsplanning.calculate_VLBA_dynamic_starttime_range(target, approximate_time, duration_hours, weights=None, return_fmt='%Y/%m/%d %H:%M:%S', elevation_limit_deg=15.0, LST_PT=False, mode='nearest', plotresults=False)

Estimate sensible time range to start VLBA observation for a given target, based on the specified observation duration. This is quite useful, for example, for helping to quickly determine a sensible LST_PT range to put in your .key file for dynamic scheduling.

This process for estimating this range starts by first calculating the mean source transit over all VLBA antennae, and subtracting half the duration as a starting point.

If not all stations remain up for the duration, it returns this mean transit minus half the duration for both start & end times.

If all stations are up for at least the full duration though, it returns the time range between MK rising and SC setting.

If all stations are always up (circumpolar source), it returns the start & end of the day.

Parameters:

• target (ephem.FixedBody()) – The sky source of interest

• approximate_time (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – UTC date/time, not local time

• duration_hours (float) – The desired duration of the full VLBA observation session, in hours

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. The order of stations is alphabetical: [BR,FD,HN,KP,LA,MK,NL,OV,PT,SC].

• return_fmt (str ['ephem', 'mjd', 'dt', or dt strftime format string]) –

  The format in which the start time will be returned. Options are:

  ’ephem’: return times as pyephem.Date objects [NOTE: these floats are Dublin JD, not MJD]

  ’mjd’: return times as float Modified Julian Dates

  ’dt’: return times as datetime.datetime objects

  String with strptime % formatting: return string dates (e.g., ‘%Y/%m/%d %H:%M:%S’ [default])

• elevation_limit_deg (float [degrees]) – The elevation limit at the observatory to use for rise/set calculations, in degrees

• LST_PT (bool) – True returns the time in PieTown LST (e.g., used for VLBA dynamic scheduling)

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• plotresults (bool) – Set to True to plot MK/SC elevations and starttimes. [NOT YET IMPLEMENTED]

Returns:

dynamic_starttime_range

Return type:

list [dynamic_obs_range_start, dynamic_obs_range_end]

Example

mrk348=obs.create_ephem_target(‘Mrk348’,’00:48:47.14’,’31:57:25.1’)

dynamicobs_starttime_range = obs.calculate_VLBA_dynamic_starttime_range(mrk348,ephem.Date(‘2021/07/15 20:36:00’), 3.5, weights=None, return_fmt=’%Y/%m/%d %H:%M:%S’, elevation_limit_deg=10., LST_PT=True, plotresults=False)

#–> [‘2021/07/14 21:57:04’, ‘2021/07/15 00:22:53’]

obsplanning.calculate_VLBA_mean_transit_time(target, approximate_time, weights=None, mode='nearest')

Calculates the mean transit time of a single target for the VLBA stations, for a specified approximate date+time. This is a convenience function which calls calculate_vlbi_mean_transit_time() for all VLBA antennae.

Parameters:

• target (ephem.FixedBody()) – Sky target of interest.

• approximate_time (str, formatted as 'YYYY/MM/DD HH:MM:SS.s') – String UTC date/time, to use for calculating the transit times with ephem

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. The order of stations is alphabetical: [BR,FD,HN,KP,LA,MK,NL,OV,PT,SC].

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

Returns:

mean_transit_time – The mean of the transit times of the target at the various VLBA stations

Return type:

str

Notes

Weighted mean = Sum(w_i*x_i)/Sum(w_i)

Example

mrk348=obs.create_ephem_target(‘Mrk348’,’00:48:47.14’,’31:57:25.1’)

obs.calculate_VLBA_mean_transit_time(mrk348,’2025/09/15 12:00:00’)

obsplanning.calculate_antenna_visibility_limits(target, station, referenceephemtime, plusminusdays=1.0, elevation_limit_deg=15.0, interpsteps=100, alwaysup_fmt='nan', timeformat='ephem', LST_PT=False, verbose=False)

Calculate the previous and next time within e.g. 24hrs when a target reaches a specified elevation for the given antenna

e.g., 10deg or 15deg for VLBA stations…

(sometimes ‘always up’ targets might still go below 10deg)

Parameters:

• ephem.FixedBody() (target =) – The sky source of interest

• ephem.Sun() – The sky source of interest

• ephem.Moon() (or) – The sky source of interest

• station (ephem.Observer()) – Telescope/station/observer location from which the observation calculation will be made

• referenceephemtime (ephem.Date()) – Reference observation time. Can be any time, but expected use is ~ a (mean) transit time.

• plusminusdays (float) – The number of days to span before/after the reference time

• elevation_limit_deg (float) – The minimum telescope elevation limit to be considered visible/up

• inerpsteps (int) – The number of steps over which to calculate elevations between the reference time and plusminusdays

• alwaysup_fmt (str ('nan','limits')) –

  The option for handling output when a target is ‘always up’ with respect to a specified elevation limit

  ’nan’= return np.nan for the rise/set times

  ’limits’ = return the limits – the beginning of the day (-plusminusdays) for previous rise/set, and the end of the day (+plusminusdays) for next rise/set

• timeformat (str ('ephem', 'mjd', 'dt', or dt strptime format)) –

  String specifying the format for the returned times

  ’ephem’: return times as pyephem.Date objects (default) [NOTE: these floats are Dublin JD, not MJD]

  ’mjd’: return times as float Modified Julian Dates

  ’dt’: return times as datetime.datetime objects

  String with strptime % formatting: return string dates (e.g., ‘%Y/%m/%d %H:%M:%S’)

• LST_PT (bool) – True to return times in LST at Pietown instead of in the default UTC

Returns:

previous_setrise,next_setrise – [previous set, previous rise], [next set, next rise]

Return type:

list, list

Example

ngc3147=obs.create_ephem_target(‘NGC3147’,’10:16:53.65’,’73:24:02.7’)

prev_setrise,next_setrise = obs.calculate_antenna_visibility_limits(ngc3147,obs.vlbaSC, ephem.Date(‘2021/08/01 20:36:31’), elevation_limit_deg=15., verbose=False)

obsplanning.calculate_current_utcoffset(local_timezone)

Calculate the current UTC offset for a timezone string (standard Olson database name, e.g. ‘America/Chicago’)

Parameters:

local_timezone (pytz.timezone, or string) – Local timezone, either as a pytz.timezone object, or a standard Olson database name string

Returns:

utcoffset – Number of hours the timezone is (currently) offset from UTC

Return type:

float

Example

dt.datetime.utcnow() #–> datetime.datetime(2021, 9, 9, 3, 20, 7, 791748) obs.calculate_current_utcoffset(‘America/Chicago’) #–> -5.0

obsplanning.calculate_dt_utcoffset(datetime_aware)

Calculate the UTC offset for a specific dt object that is timezone-aware (tzinfo already included).

Parameters:

datetime_in (datetime.datetime) – dt.datetime format time in the local desired timezone. (If the tzinfo=’UTC’, the offset will naturally be 0)

Returns:

utc_offset – Number of hours the supplied aware datetime object is offset from UTC

Return type:

float

Example

obs.calculate_dt_utcoffset( obs.dt_naive_to_dt_aware(dt.datetime.now(),’US/Eastern’) )

obsplanning.calculate_dtnaive_utcoffset(datetime_naive, local_timezone)

Calculate the UTC offset for a specific time and timezone string

Parameters:

• datetime_naive (datetime.datetime) –

  naive dt.datetime format time in the local desired timezone

  If your dt.datetime object already has the correct tzinfo (it’s “aware”), then you can just use utcofffset=datetime_aware.utcoffset().total_seconds()/3600.

• local_timezone (pytz.timezone, or str) – pytz.timezone object, or string of a standard Olson database timezone name (e.g. ‘US/Pacific’)

Returns:

utc_offset – Number of hours the supplied datetime object with timezone is offset from UTC

Return type:

float

obsplanning.calculate_moon_times(obsframe, startdate, outtype='dec', verbose=False)

Calculates the moonrise/moonset – takes into account when sunset/sunrise occur

Parameters:

• obsframe (ephem.Observer()) – pyephem Observer() frame

• startdate (str, formatted as e.g., 'YYYY/MM/DD 23:00:00') – The starting date/time (the evening at the beginning observations, for classical night sessions)

• outtype (str ('decimal', 'tuple', or 'dt')) –

  Desired output format:

  ’decimal’ ephem.Date() format (e.g., 43489.99976096985)

  ’tuple’ (e.g., (2019, 1, 26, 11, 59, 39.34779482893646) )

  ’dt’ datetime format (e.g., [datetime.datetime(2021, 4, 15, 14, 56, 33), …] )

• verbose (bool) – Set to True to print the previous moonrise / next moonset info to screen

Returns:

moonriseset – The [moonrise,moonset] times in the specified format

Return type:

list

obsplanning.calculate_optimal_VLBAstarttime(target, approximate_time, duration_hours, weights=None, return_fmt='%Y/%m/%d %H:%M:%S', LST_PT=False, mode='nearest')

Calculate the optimal VLBA observation start time (to maximize station uptime), for a given target and desired observation duration.

This is estimated from the mean transit time for the full array, minus half the specified duration.

Calls calculate_VLBA_mean_transit_time()

Parameters:

• target (ephem.FixedBody()) – Sky target of interest

• approximate_time (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – UTC date/time

• duration_hours (float) – The desired duration of the full VLBA observation session, in hours

• weights (array-like [list, np.array...]) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. The order of stations is alphabetical: [BR,FD,HN,KP,LA,MK,NL,OV,PT,SC].

• return_fmt (str ['ephem', 'dt', or dt strftime format string]) –

  The format in which the start time will be returned. Options are:

  ’ephem’ : ephem.Date format

  ’dt’ or ‘datetime’ : dt.datetime

  strftime format code : return a string of the date, using the format code to convert from dt.datetime using dt.datetime.strftime(). Default is ‘%Y/%m/%d %H:%M:%S’, which prints as ‘YYYY/MM/DD hh:mm:ss’

• LST_PT (bool) – True returns the time in PieTown LST (e.g., used for VLBA dynamic scheduling)

• mode (str) –

  Specifies which transit time to use. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

Returns:

start_time

Return type:

ephem.Date, datetime.datetime, or str

Example

# Observing quasar on 2025/09/15 for a duration of 5.5 hours

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

obs.calculate_optimal_VLBAstarttime(ngc1052,’2025/09/15’,5.5)

#–> ‘2025/09/15 07:19:27’

obs.calculate_optimal_VLBAstarttime(ngc1052,’2025/09/15’,5.5,LST_PT=True)

#–> ‘2025/09/14 23:45:01’

obsplanning.calculate_rise_set_times_single(target, observer, time_in, mode='nearest', return_fmt='str', verbose=True)

Calculate a target source’s rise/set times near a specified observation time. Depending on the specified ‘mode’, determine the previous rise and previous set, the next rise next set, or the rise/set corresponding to the nearest transit (default).

Parameters:

• ephem.FixedBody() (target =) – The sky source of interest

• ephem.Sun() – The sky source of interest

• ephem.Moon() (or) – The sky source of interest

• observer (ephem.Observer()) – Telescope/observer location from which the observation calculation will be made

• time_in (ephem.Date(), or str in 'YYYY/MM/DD HH:MM:SS.s' format) – approximate date/time (UTC, not local!) for which to compute the nearest transit time

• mode (str) –

  Specifies how to determine the rise/set times. Options are

  ’previous’/’before’ = calculate the rise/set times before the input time

  ’next’/’after’ = calculate the rise/set times after the input time

  ’nearest’/’transit’ = calculate the nearest transit to the input time, and the corresponding rise/set times

• return_fmt (str ('str', 'ephem', or 'dt')) – The desired the output format. ‘str’ for string output, ‘ephem’ for ephem.Date format, ‘dt’ for datetime.

• verbose (bool) – Set to True to print extra warnings to terminal

Returns:

risesettimes – [Previous rise time, Next set time]

Return type:

list

Examples

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

obs.calculate_rise_set_times_single(ngc1052,obs.vlbaLA,’2025/09/15 12:00:00’,return_fmt=’str’)

#–> [‘2025/9/15 04:30:38’, ‘2025/9/15 15:47:02’]

obsplanning.calculate_target_darktime_singlenight(target, observer, night_time, darklevel='astro')

Calculate the available dark time for a given target on a given night. Dark time here is defined from a specified level: between sunset/sunrise, civil, nautical, or astronomical twilight. Does not consider light from the moon, only the Sun.

Parameters:

• target (ephem.FixedBody(), ephem.Moon(), or ephem.Sun()) – pyephem target source

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer object

• night_time (ephem.Date(), dt.datettime, or string in format 'YYYY/MM/DD HH:MM:SS') – A reference time during the night for the observations. A safe bet is midnight of the desired day, since the calculation is for the previous rise and next set relative to that time. ** Important: do not give a time before sunset or after sunrise, or it will be off by a day.

• darklevel (str) – The level of darkness to consider. Should be one of ‘sunrise’/’sunset’, or one of the twilight levels ‘civil’, ‘nautical’, ‘astronomical’

Returns:

darktime_singlenight – The number of hours of darktime in the specified night

Return type:

float

Examples

crab = obs.create_ephem_target(‘Crab Nebula’,’05:34:31.94’,’22:00:52.2’)

wht = obs.create_ephem_observer(‘WHT’, ‘-17 52 53.8’, ‘28 45 37.7’, 2344)

obs.calculate_target_darktime_singlenight(crab, wht, ‘2025/10/31 23:59:59’)

# –> 8.867340195807628 [hours]

obs.calculate_target_darktime_singlenight(ephem.Jupiter(), wht, ‘2025/10/31 23:59:59’)

# –> 6.645513419411145 [hours]

obsplanning.calculate_target_times(target, observer, obstime, outtype='dec')

Compute a target’s rise and set times, from a specified observer site and for a given obstime

Parameters:

• target (ephem.FixedBody(), ephem.Moon(), or ephem.Sun()) – pyephem target source

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer object

• obstime (ephem.Date(), or string in format 'YYYY/MM/DD HH:MM:SS') – A relevant time for the observations, from which to calculate the rise/set times

• outtype (str ('decimal', 'tuple', or 'dt')) –

  Desired output format:

  ’decimal’ ephem.Date() format (e.g., 43489.99976096985)

  ’tuple’ (e.g., (2019, 1, 26, 11, 59, 39.34779482893646) )

  ’dt’ datetime format (e.g., [datetime.datetime(2021, 4, 15, 14, 56, 33),…] )

Returns:

target_riseset – [target_rise,target_set] times in the specified format

Return type:

list

obsplanning.calculate_targets_mean_transit_time(target_list, observer, approximate_time, weights=None, mode='nearest')

Calculates the mean transit time of multiple targets at the supplied single observatory, for a specified approximate date+time

Parameters:

• target_list (list [ elements being ephem.FixedBody(), ephem.Sun(), or ephem.Moon() ]) – Sky targets of interest

• observer (ephem.Observer()) – The observatory in ephem.Observer() format

• approximate_time (str, formatted as 'YYYY/MM/DD HH:MM:SS.s') – String UTC date/time, to use for calculating the transit times with ephem

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance.

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

Returns:

mean_transit_time – The mean of the transit times of the mutliple specified targets

Return type:

str

Notes

Weighted mean = Sum(w_i*x_i)/Sum(w_i)

Examples

mrk348=obs.create_ephem_target(‘Mrk348’,’00:48:47.14’,’31:57:25.1’)

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

ngc1068=obs.create_ephem_target(‘NGC1068’,’02:42:40.71’,’-00:00:47.81’)

obs.calculate_targets_mean_transit_time([mrk348,ngc1052,ngc1068],obs.vlbaFD,’2025/09/15 12:00:00’)

## Now, upweight ngc1052 and ngc1068

obs.calculate_targets_mean_transit_time([mrk348,ngc1052,ngc1068],obs.vlbaFD,’2025/09/15 12:00:00’,weights=[1,5,2]) #–> ‘2025/9/15 09:46:05’

obsplanning.calculate_transit_time_single(target, observer, approximate_time, mode='nearest', return_fmt='str')

Calculates the transit time of a sky target for the supplied observer(telescope/station), for a single specified approximate date+time. Use keyword “mode” to specify the transit previous to the input time, the next transit, or the nearest (default, whether it’s before or after the input time)

Parameters:

• target (ephem.FixedBody(), ephem.Sun(), or ephem.Moon()) – The source of interest on the sky

• observer (ephem.Observer()) – Telescope/observer location from which the observation calculation will be made

• approximate_time (ephem.Date(), or str in 'YYYY/MM/DD HH:MM:SS.s' format) – approximate date/time (UTC, not local!) for which to compute the nearest transit time

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• return_fmt (str ('str', 'ephem', or 'dt')) – The desired the output format. ‘str’ for string output, ‘ephem’ for ephem.Date format, ‘dt’ for datetime.

Returns:

t_transit

Return type:

str, ephem.Date, or datetime.datetime

Example

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

obs.calculate_transit_time_single(ngc1052,obs.vlbaBR,’2020/09/15 12:00:00’,return_fmt=’str’)

#–> ‘2020/9/15 11:01:22’

obsplanning.calculate_twilight_times(obsframe, startdate, verbose=False)

Calculate the sunset/sunrise and various twilight times for a classical night observing session. The expected startdate (date/time) is expected to be in the night, between sunset and sunrise, to calculate previous_setting and next_rising

Parameters:

• obsframe (ephem.Observer()) – pyephem Observer() frame

• startdate (str, formatted as e.g., 'YYYY/MM/DD 23:00:00') – The starting date/time (the evening at the beginning observations, for classical night sessions)

• verbose (bool) – Set to True to print the sunrise/sunset/twilights info to screen

Returns:

sunsetrise,t_civil,t_naut,t_astro – Numpy arrays of the sunset/sunrise, Civil twilights, Nautical twilights, and Astronomical twilights. All values are in pyephem.Date format.

Return type:

np.array,np.array,np.array,np.array

Notes

Definitions for the various levels of twilight:

Civil: for horizon = -6 degrees, Nautical: -12 deg, Astronomical: -18 deg

Example

# Print times for the Crab Nebula observed from WHT on 2025/01/01 at 23:59:00

wht = ephem.Observer()

wht.lat=’28 45 37.7’; wht.lon=’-17 52 53.8’; wht.elevation=2344

obstime=’2025/01/01 23:59:00’

sunset,twi_civil,twi_naut,twi_astro = obs.calculate_twilight_times(wht,obstime)

obsplanning.calculate_vlbi_mean_transit_time(target, observer_list, approximate_time, weights=None, force_after_observer_i=None, wrap_date=False, mode='nearest')

Calculates the mean transit time of a single target for the supplied antennae, for a specified approximate date+time

Parameters:

• target (ephem.FixedBody(), ephem.Sun(), or ephem.Moon()) – Sky target of interest

• observer_list (list (elements of ephem.Observer() type)) – A list of the ephem.Observer() objects for all the stations to calculate for

• approximate_time (ephem.Date(), or str, formatted as 'YYYY/MM/DD HH:MM:SS.s') – String UTC date/time, to use for calculating the transit times with ephem

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance.

• force_after_observer_i (None or int) – If set to an integer, force the computation of the next transit to be after the transit time at this observer/station index in the supplied observer_list. i.e., useful for forcing all times to be after the St. Croix station transit for VLBA calculations.

• wrap_date (bool) – Set to True to wrap the mean transit time to restrict it to the same day as the supplied “approximate_time”. Useful when a calculation requires a specific date. (e.g., if mean transit is 03:24 the following day, forces it to return 03:24 on the same day)

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

Returns:

mean_transit_time – The mean of the transit times of the target at the various stations. The output is produced by calling the ephem.Date object as a string

Return type:

str

Notes

Weighted mean = Sum(w_i*x_i)/Sum(w_i)

Examples

ngc3079=obs.create_ephem_target(‘NGC3079’,’10:01:57.80’,’55:40:47.24’)

obs.calculate_vlbi_mean_transit_time(ngc3079,[obs.vlbaBR,obs.vlbaMK,obs.vlbaSC],’2021/09/15 12:00:00’)

#To upweight MK and SC over BR, given them higher values in this list

obs.calculate_vlbi_mean_transit_time(ngc3079,[obs.vlbaBR,obs.vlbaMK,obs.vlbaSC],’2021/09/15 12:00:00’,weights=[1,5,2])

obsplanning.compute_moon_tracks(observer, obsstart, obsend, nsteps=100)

Compute the altitudes & azimuths (visibility tracks) for the Moon from a given observer(telescope/station)

Parameters:

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer() object

• obsstart (ephem.Date() or datetime.datetime()) – The start time for the array calculations

• obsend (ephem.Date() or datetime.datetime()) – The end time for the array calculations

• nsteps (int) – The number of elements in the final array, inclusive of obsstart and obsend

Returns:

moon_altaz – The array of altitude/azimuth calculations spanning obsstart to obsend, over nsteps.

Return type:

np.array (moon_altaz.shape = [2,nsteps])

obsplanning.compute_moonphase(obstime, return_fmt='perc')

Compute the phase of the moon, as a fraction or percent, at a specific time.

Parameters:

• obstime (emphem.Date(), or str in 'YYYY/MM/DD hh:mm:ss' format) – date/time at which to calculate the moon phase

• return_fmt (str ('perc', 'frac', or 'name')) – ‘perc’ (default) to return moon phase as a percent, or ‘frac’ to return fraction. ‘name’ returns the colloquial name of the moon phase, such as ‘Waxing Gibbous’

Returns:

moonphase – The fractional or percent phase of the moon

Return type:

float

obsplanning.compute_sidereal_time(observer, t1, as_type='datetime')

Compute the sidereal time corresponding to an input time t1, at a specified observer location.

Parameters:

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer() object

• t1 (ephem.Date() or datetime.datetime()) – The input time

• as_type (str -- 'datetime', 'dms', 'angle_rad', 'angle_deg', or 'string') – The desired output format of the computed LST

Returns:

LST_out

Return type:

datetime.datetime, [D,M,S], float, or str

obsplanning.compute_sidereal_times(observer, t1, t2, nsteps=1000, as_type='datetime')

Compute an array of sidereal times between times t1 and t2 over nsteps, at a specified observer location.

Parameters:

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer() object

• t1 (ephem.Date() or datetime.datetime()) – The start time for the array calculations

• t2 (ephem.Date() or datetime.datetime()) – The end time for the array calculations

• nsteps (int) – The number of elements/steps in the array for calculating times

• as_type (str -- 'datetime', 'dms', 'angle_rad', 'angle_deg', or 'string') – The desired output format of the computed LST values

Returns:

LST_arr

Return type:

list (with elements of type datetime.datetime, [D,M,S], float, or str)

obsplanning.compute_sun_tracks(observer, obsstart, obsend, nsteps=100)

Compute the altitudes & azimuths (visibility tracks) for the Sun from a given observer(telescope/station)

Parameters:

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer() object

• obsstart (ephem.Date() or datetime.datetime()) – The start time for the array calculations

• obsend (ephem.Date() or datetime.datetime()) – The end time for the array calculations

• nsteps (int) – The number of elements in the final array, inclusive of obsstart and obsend

Returns:

sun_altaz – The array of altitude/azimuth calculations spanning obsstart to obsend, over nsteps.

Return type:

np.array (sun_altaz.shape = [2,nsteps])

obsplanning.compute_target_altaz(target, observer, t1, t2, nsteps=1000)

Compute a range of target altitude and azimuth values, using the supplied observer location

Parameters:

• target (ephem.FixedBody(), ephem.Moon(), or ephem.Sun()) – pyephem target source

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer() object

• t1 (ephem.Date() or datetime.datetime()) – The start time for the array calculations

• t2 (ephem.Date() or datetime.datetime()) – The end time for the array calculations

• nsteps (int) – The number of elements in the final array, inclusive of t1 and t2

Returns:

target_altaz – The array of altitude/azimuth calculations spanning t1 to t2, over nsteps.

Return type:

np.array (target_altaz.shape = [2,nsteps])

Examples

tstart=ephem.Date(‘2025/01/01 00:00:00’); tend=ephem.Date(‘2025/01/01 23:59:59’);

ngc3079=obs.create_ephem_target(‘NGC3079’,’10:01:57.80’,’55:40:47.24’)

obs.compute_target_altaz(ngc3079,obs.vlbaLA,tstart,tend,nsteps=100)

obs.compute_target_altaz(ephem.Sun(),obs.vlbaLA,tstart,tend,nsteps=100)

obsplanning.compute_target_altaz_single(target, observer, obstime)

Compute a target’s altitude and azimuth at a single obstime, using the supplied observer location

Parameters:

• target (ephem.FixedBody(), ephem.Moon(), or ephem.Sun()) – pyephem target source

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer() object

• obstime (ephem.Date(), or string in format 'YYYY/MM/DD HH:MM:SS') – The desired time at which to calculate the observer alt/az

Returns:

target_altaz – Array of the target altitude and azimuth, each in degrees

Return type:

np.array

obsplanning.compute_yearly_target_data(target, observer, obsyear, timezone='auto', time_of_obs='night', peak_alt=False, local=True, mode='nearest')

Computes a target source’s transit & rise/set times from a specific observer site, over the course of a calendar year.

Parameters:

• target (an ephem.FixedBody()) – Target observation source of interest

• observer (ephem.Observer()) – Observatory/antenna/location object to use for the calculations

• obsyear (ephem.Date(), datetime.datetime, or str formatted as 'YYYY') – Year in which to calculate the source transit & rise/set times

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] – use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• time_of_obs (str ['noon', 'night', 'midnight', 'peak' or 'HH:MM:SS']) –

  Denotes how to generate the times to use for each day. Options:

  ’noon’ = calculate the values at 12:00 local time each day

  ’night’ or ‘midnight’ = use 23:59:59 local time each day (for night obs. 00:00:00 would be for the previous night.)

  ’peak’ = return values during daily peak altitude

  #’exact’ = use the exact timesteps as np.linspace returns them

• peak_alt (bool) – True also returns the daily peak altitudes

• local (bool) – True returns times in the local observer site time. False returns in UTC time.

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

Returns:

transit_times,rise_times,set_times,obstime_alts

Return type:

np.array,np.array,np.array,np.array

Example

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’) TRS_alts_2021=obs.compute_yearly_target_data(ngc1052, obs.vlbaBR, ‘2021’, local=True, timezone=’US/Pacific’)

obsplanning.construct_datetime(listin, dtformat='time', timezone=None)

Convenience utility to construct a dt.datetime() object from a list of components, including an optional timezone.

Parameters:

• listin (list (or other array-like)) –

  List of [H,M,S(.SS)] (for ‘time’), [Y,M,D] (for ‘date’), or [Y,M,D,H,M,S(.S)] (datetime)

  Strings also accepted in format ‘H:M:S(.s)’, ‘Y/M/D’, or ‘Y/M/D H:M:S(.s)’

• dtformat (str) – ‘time’, ‘date’, or ‘datetime’/’dt’. Denotes desired format.

• timezone (pytz.timezone, or datetime timezone string) – Accepts timezones in pytz.timezone format or datetime string format (standard Olson database names such as ‘US/Eastern’, which will then be formed with pytz)

Returns:

dt_out – dt.time, dt.date, or dt.datetime object

Return type:

datetime object

Examples

obs.construct_datetime([2021,9,15,16,0,0.0],’dt’,timezone=’US/Pacific’) obs.construct_datetime(‘2021/09/15 16:00:00’,’dt’,timezone=’US/Pacific’)

#–> datetime.datetime(2021, 9, 15, 16, 0, tzinfo=<DstTzInfo ‘US/Pacific’ PDT-1 day, 17:00:00 DST>)

obsplanning.convert_ephem_datetime(ephem_date_in)

Converts naive UTC pyephem Date() object into formatted datetime.datetime object with pytz UTC timezone

Parameters:

ephem_date_in (ephem.Date) – ephem.Date() object with no timezone info (naive)

Returns:

obstime_dt – datetime.datetime object with UTC pytz timezone

Return type:

datetime.datetime

obsplanning.convert_ephem_observer_datetime(obsin)

Converts pyephem Observer().date object into formatted datetime.datetime object with pytz UTC timezone

Not currently used; better to just use ephem.Date().datetime()

Parameters:

obsin (ephem.Observer()) –

Returns:

obstime_dt – datetime.datetime object with UTC pytz timezone

Return type:

datetime.datetime

obsplanning.create_ephem_observer(namestring, longitude, latitude, elevation, decimal_format='deg', timezone=None)

Convenience function to create a (lightly modified) ephem.Observer() object for a telescope location. A timezone attribute has been added to Observers created with this function.

Parameters:

• namestring (str) – The name/identifier to attach to the observatory (e.g., ‘JCMT’, ‘GBT’, …)

• longitude (str or float) – Pyephem longitudes are +E, or (increasing) East coords (pygeodesy may print coords as +West, if the +E are negative). String coordinates can be delimited by spaces or colons. Note that decimal coordinates are accepted by pyephem objects, but it expects decimal coordinates to be in radians, not degrees.

• latitude (str or float) – String coordinates can be delimited by spaces or colons. Note that decimal coordinates are accepted by pyephem objects, but it expects decimal coordinates to be in radians, not degrees.

• elevation (int or float) – The elevation of the telescope / observer site, in meters

• decimal_format (str) – Specifies the format of the input longitude & latitude when they are given as floats – ‘deg’/’degrees’ if the inputs are in degrees, or ‘rad’/’radians’ if the inputs are in radians (which are the native float input format for pyephem Observer type)

• timezone (str, None) – The name of the timezone (from the Olson database) corresponding to the Observer’s location. The timezone can be calculated automatically, using timezonefinder/tzwhere, from the latitude and longitude, though this option can taka a few seconds.

Returns:

tmpobserver – A pyephem Observer() instance – lightly modified with Observer_with_timezone() to include a timezone attribute

Return type:

ephem.Observer

Examples

wht = obs.create_ephem_observer(‘WHT’, ‘-17 52 53.8’, ‘28 45 37.7’, 2344)

wht = obs.create_ephem_observer(‘WHT’, ‘-17:52:53.8’, ‘28:45:37.7’, 2344)

wht = obs.create_ephem_observer(‘WHT’, -17.88161, 28.760472, 2344)

wht = obs.create_ephem_observer(‘WHT’, -0.31209297, 0.50196493, 2344, decimal_format=’rad’)

### Attach timezone info by specifying the name manually, and by calculating from coordinates:

wht = obs.create_ephem_observer(‘WHT’, ‘-17 52 53.8’, ‘28 45 37.7’, 2344, timezone=’Atlantic/Canary’)

wht = obs.create_ephem_observer(‘WHT’, ‘-17 52 53.8’, ‘28 45 37.7’, 2344, timezone=’calculate’)

Notes

This Observer object’s internal values can be accessed and displayed in a number of ways. By default, calling a pyephem object property returns its numerical value, while using print() on that property returns a more common human-readable format, such as sexagesimal coordinates.

wht.lat,wht.lon #–> (0.501964934706148, -0.3120929894500905) [radians]

print(wht.lat,wht.lon) #–> 28:45:37.7 -17:52:53.8

See the pyephem documentation for more details.

https://rhodesmill.org/pyephem/quick.html#observers

obsplanning.create_ephem_target(namestring, RA, DEC, decimal_format='deg')

Convenience function to create an ephem.FixedBody() object for a sky source target

Parameters:

• namestring (str) – The name/identifier to attach to the object (e.g., ‘NGC1275’)

• RA (string, or float) – Right Ascension coordinate. If string, must be in sexagesimal H:M:S form (separated by : ). If float, must be in RADIANS (which is what pyephem assumes internally)

• DEC (string, or float) – Declination coordinate. If string, must be in sexagesimal D:M:S form (separated by : ). If float, must be in RADIANS (which is what pyephem assumes internally)

• decimal_format (str) – Specifies the format of the input RA & DEC when they are given as floats – ‘deg’/’degrees’ if the inputs are in degrees, or ‘rad’/’radians’ if the inputs are in radians (which are the native float input format for pyephem FixedBody type)

Returns:

ephemobj – A pyephem FixedBody() instance

Return type:

ephem.FixedBody

Examples

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

# obs.sex2dec(‘02:41:04.7985’,’-08:15:20.751’) #–> [40.269994, -8.255764]

ngc1052=obs.create_ephem_target(‘NGC1052’, 40.269994 * np.pi/180, -8.255764 * np.pi/180)

#in radians: np.array([40.269994, -8.255764])*np.pi/180 #–> [ 0.70284399, -0.14409026]

ngc1052=obs.create_ephem_target(‘NGC1052’, 0.70284399, -0.14409026, decimal_format=’rad’)

Notes

This FixedBody object’s internal values can be accessed and displayed in a number of ways. By default, calling a pyephem object property returns its numerical value, while using print() on that property returns a more common human-readable format, such as sexagesimal coordinates.

ngc1052.a_ra,ngc1052.a_dec #–> (0.7075167104622412, -0.142444748709817) [radians]

print(ngc1052.a_ra,ngc1052.a_dec) #–> 2:42:09.05 -8:09:41.3

Information depending on time, such as altitude & azimuth from an Observer, can be computed using the FixedBody.compute(Observer) method. See the pyephem documentation for more details.

https://rhodesmill.org/pyephem/quick.html#bodies

Input coordinates are assumed to be apparent topocentric position.

See https://rhodesmill.org/pyephem/radec for more details on pyephem RA & DEC coordinates.

obsplanning.create_local_time_object(time_in, timezone, string_format='%Y/%m/%d %H:%M:%S', return_fmt='dt')

Take an input naive time (no timezone explicitly attached yet) in the desired local time, and use the supplied timezone to return a time object in the specified format: datatime, ephem.Date, or string representation. First converts input time from specified input format to tz-aware dt object, then returns in the specified output format. Timezone-aware dt objects are now also accepted as input, and will be localized from their attached tzinfo to the specified timezone.

Parameters:

• time_in (ephem.Date(), datetime.datetime, MJD (float), or str formatted as 'YYYY/MM/DD HH:MM:SS') – The desired clock time in the local timezone. Can be input as a string formatted for ephem.Date, or as a naive datetime.datetime object (with no timezone attached yet). If a tz-aware dt.datetime is used, it will use its attached tzinfo and the input timezone to localize. Users may also input ephem.Date objects, that were previously created from a string corresponding to a local time (and not UTC as pyephem assumes), because this tz-unaware pyephem time will merely be converted to a naive datetime object.

• timezone (str, or pytz.timezone) – The local timezone to use. Olson database names or pytz timezones are accepted.

• string_format (str) – The format of time_in when it’s given as a string. Passed to dt.datetime.strptime to parse the input values. Default is ‘%Y/%m/%d %H:%M:%S’, which corresponds to input as ‘YYYY/MM/DD hh:mm:ss’

• return_fmt (str ['dt', 'MJD', or 'str']) –

  The format in which the start time will be returned. Options are:

  ’dt’ or ‘datetime’ : dt.datetime

  ’str’return a string of the date, using the format code specified

  in string_format to convert from dt.datetime using dt.datetime.strftime().

  ’ephem’ : ephem.Date format.

Returns:

local_time_formatted – Returns the time in format specified by return_fmt – datetime, ephem.Date, MJD (float), or string representation

Return type:

datetime.datetime, ephem.Date, float, or str

Examples

obs.create_local_time_object(‘2021/10/31 23:59:59’,’US/Pacific’)

obs.create_local_time_object( dt.datetime(2021,10,31,23,59,59,

tzinfo=pytz.timezone(‘US/Eastern’)),’US/Pacific’)

obsplanning.create_obstime_array(timestart, timeend, timezone_string='UTC', output_as_utc=False, n_steps=100)

Takes start & end times in either dt or string format, to create an array of datetime times. Does this by converting the input date/time string to datetime format, then calculating the increments with obs.date_linspace()

Parameters:

• timestart (str, or datetime.datetime) – Start time, either in string format as ‘YYYY/MM/DD HH:MM:SS’ or in naive datetime format

• timeend (str, or datetime.datetime) – End time, either in string format as ‘YYYY/MM/DD HH:MM:SS’ or in naive datetime format

• timezone_string (str) – Standard timezone string for use with pytz. ‘UTC’, ‘GMT’, ‘US/Mountain’, ‘Atlantic/Canary’, etc..

• output_as_utc (bool) – Set to True to receive output in UTC

• n_steps (int) – number of elements in the final array, including start/end values (as in np.linspace usage)

Returns:

times_arr – Datetime objects in regular increments between start/end point

Return type:

list

Example

obs.create_obstime_array(‘2020/09/15 00:00:00’,’2020/09/15 23:59:59’,timezone_string=’UTC’,n_steps=10)

obsplanning.daily_moonseps(target, observer, tstart, tend, every_N_days=1, verbose=True)

Calculate the Moon separations for a given target, ever N days for the period between the specified start and end.

Parameters:

• target (ephem.FixedBody()) – Target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• tstart (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The start date/time for determining the Sun separations

• tend (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The latest date/time for determining the Sun separations

• every_N_days (int) – The interval in days to use for determining and printing the Sun separations.

• verbose (bool) – Whether or not to print the Sun separations to terminal.

Example

#Print Moon separations at midnight for NGC6240 every 14 days in October 2023.

# Note that even though “tend” was given as 10/31, the final printed entry

# is (14+14)=28 days after “tstart” on Oct.1, or 10/29.

ngc6240 = obs.create_ephem_target(‘NGC 6240’,’16:52:58.90’,’02:24:03.6’)

obs.daily_moonseps(ngc6240, obs.vlbaBR, ‘2023/10/01 00:00:00’, ‘2023/10/31 00:00:00’, every_N_days=14)

#NGC 6240

# On 2023/10/1 00:00:00, Sun separation = 132.3 deg

# On 2023/10/15 00:00:00, Sun separation = 52.9 deg

# On 2023/10/29 00:00:00, Sun separation = 138.5 deg

obsplanning.daily_sunseps(target, observer, tstart, tend, every_N_days=1, verbose=True)

Calculate the Sun separations for a given target, ever N days for the period between the specified start and end.

Parameters:

• target (ephem.FixedBody()) – Target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• tstart (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The start date/time for determining the Sun separations

• tend (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The latest date/time for determining the Sun separations

• every_N_days (int) – The interval in days to use for determining and printing the Sun separations.

• verbose (bool) – Whether or not to print the Sun separations to terminal.

Example

#Print Sun separations at noon for NGC6240 every 14 days in October 2023.

# Note that even though “tend” was given as 10/31, the final printed entry

# is (14+14)=28 days after “tstart” on Oct.1, or 10/29.

ngc6240 = obs.create_ephem_target(‘NGC 6240’,’16:52:58.90’,’02:24:03.6’)

obs.daily_sunseps(ngc6240, obs.vlbaBR, ‘2023/10/01 12:00:00’, ‘2023/10/31 12:00:00’, every_N_days=14)

#NGC 6240

# On 2023/10/1 12:00:00, Sun separation = 66.3 deg

# On 2023/10/15 12:00:00, Sun separation = 54.3 deg

# On 2023/10/29 12:00:00, Sun separation = 42.8 deg

obsplanning.date_linspace(start_dt, end_dt, n_elements)

From start & end dt times, generate an array of datetime objects, similar to np.linspace. Useful for, e.g., making an array of times for calculating ephemeris.

Parameters:

• start_dt (datetime.datetime) –

• end_dt (datetime.datetime) –

• n_elements (int) – number of elements in the final array, including start/end values (as in np.linspace usage)

Returns:

dt_array – Datetime objects in regular increments between start/end point

Return type:

list

Example

a=dt.datetime.strptime(‘2020/09/15 00:00:00’,’%Y/%m/%d %H:%M:%S’) b=dt.datetime.strptime(‘2020/09/15 23:59:59’,’%Y/%m/%d %H:%M:%S’) obs.date_linspace(a,b,10)

obsplanning.dec2sex(longin, latin, as_string=False, decimal_places=2, str_format=':', RAhours=True, order='radec')

Convert from decimal coordinate pairs to sexagesimal format.

Parameters:

• longin (float) – Longitude coordinate in degrees (e.g., Long on Earth or Right Ascension on sky)

• latin (float) – Latitude coordinate in degrees (e.g., Lat on Earth or Declination on sky )

• as_string (bool) – False (default) = return as lists of floats True = return as a string

• decimal_places (int) – Return the result with this number of decimal places

• str_format (str) –

  The format in which to return the coords when as_string is True.

  Options are ‘:’, ‘ ‘, ‘DMS’, ‘dms’, ‘HMS’, ‘hms’, or user supplied list

  of six delimiter strings:

  ’:’ : separate all coordinates by colons. e.g., [‘05:19:00.54’,’-23:07:31.10’]

  ’ ‘ : separate all coordinates by spaces. e.g., [‘05 19 00.54’,’-23 07 31.10’]

  ’DMS’,’dms’: separate RA&DEC coords by letters (upper or lower case)

  e.g., [‘05d19m00.54s’,’-23d07m31.10s’]

  ’HMS’,’hms’: same as DMS/dms, but RA uses hours instead of degrees

  e.g., [‘05h19m00.54s’,’-23d07m31.10s’]

  user supplied list of 6 delimiters.

  e.g. [‘hr’,’min’,’sec’,’deg’,’min’,’sec’] – [‘05hr19min00.54sec’,..]

• RAhours (bool) –

  True (default) specifies that the longitude coordinate is in RA hours

  (and will be divided by 360/24=15)

  False specifies that the longitude coordinate is not in hours

• order (str) –

  The order of the coordinates: longitude then latitude or vice versa.

  Options: ‘lonlat’,’latlon’,’radec’,’decra’

  For example, dec2sex(loncoord,latcoord) – returns [lonstring,latstring]

  or dec2sex(latcoord,loncoord, order=’latlon’) – returns [latstring,lonstring]

Returns:

LatMinSec – The sexagesimal versions of the input coorinates.

Return type:

list, or string

Examples

obs.dec2sex(146.50, -14.25) #–> RAhours=True, so ([9, 46, 0.0], [-14, 15, 0.0])

obs.dec2sex(146.50, -14.25, RAhours=False) #–> ([146, 30, 0.0], [-14, 15, 0.0])

obs.dec2sex(0.,90., as_string=True)

obs.dec2sex(0., 90., as_string=True, str_format=’hms’) #–> [‘00h00m00.00s’, ‘90d00m00.00s’]

obs.dec2sex(5.1111, 80.2222, as_string=True, decimal_places=8, str_format=’:’)

#–> [‘00:20:26.66400000’, ‘80:13:19.92000000’]

obsplanning.deg2dms(valin)

Converts decimal degrees to a list of [ Degrees (int), Minutes (int), Seconds (decimal)]

Parameters:

valin (float) – Input value in degrees

Returns:

DMS – [ Degrees (int), Minutes (int), Seconds (decimal)]

Return type:

list

Example

# e.g., 123.456789 degrees corresponds to 123 deg, 27 min, 24.4404 sec

obs.deg2dms(123.456789) #–> [123, 27, 24.440400000002]

obsplanning.deg2hour(valin)

Converts decimal degrees to a HMS list of [ Hours (int), Minutes (int), Seconds (decimal)].

Parameters:

valin (float) – Input value in degrees

Returns:

HMS – [ Hours (int), Minutes (int), Seconds (decimal)]

Return type:

list

Example

# e.g., 180 degrees corresponds to 12 hours, 0 min, 0 sec

obs.deg2hour(180.0) #–> [12, 0, 0]

obsplanning.dms2deg(valin)

Converts DMS input to decimal degrees. Input can be either a string delimeted by : or spaces, or a list of [D,M,S] numbers.

Parameters:

valin (float) –

Input value in DMS. Can be either:

• a string delimeted by : or spaces

• a list of [D,M,S] numbers (floats or ints)

Returns:

valout – Degrees corresponding to the DMS value

Return type:

float

Examples

# e.g., ‘-78:12:34.56’ corresponds to -77.7904 deg

obs.dms2deg(‘-78:12:34.56’) #–> -77.79039999999999

obs.dms2deg(‘-78 12 34.56’) #–> -77.79039999999999

obs.dms2deg([-78,12,34.56]) #–> -77.79039999999999

obsplanning.download_2mass_cutouts(coords, boxwidth, savepathstem, boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False)

Convenience function to download cutouts of the three 2MASS images, in J,H,K bands.

Calls download_cutouts() with GALEX bands being passed to surveybands.

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_2MASS<band>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

Example

obs.download_2mass_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.download_cutout(coords, boxwidth, savepath, survey='DSS2 Red', boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False)

Downloads and saves a single fits image. If multiple surveys given, only first will be saved. SkyView.get_images() requires size in pixels.

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepath (str) – The path for saving the downloaded file, including the filename and desired filetype (.fits, .FIT, etc.)

• survey (str) –

  The survey to download from. E.g., ‘SDSSr’,’2MASS-J’,’WISE 3.4’ …

  List all available surveys with:

  from astroquery.skyview import SkyView; SkyView.list_surveys()

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) –

  Set to True to overwrite the existing file at the specified savepath

  If you have deleted a fits file and the old one keeps reappearing, try deleting the contents of your astroquery download cache, ~/.astopy/cache/download/url/

• search_name (bool) – Set to True to query SkyView by a common name, rather than by coordinates. In this case, coords should be the name (string)

Examples

obs.download_cutout([83.63725, 22.0145], 10., ‘Crab_2massJ_10arcmin.fits’, survey=’2MASS-J’, boxwidth_units=’arcmin’) #Crab Nebula, M1

obs.download_cutout( obs.sex2dec(‘05:34:32.94’,’22:00:52.2’), 10., ‘Crab_2massJ_10arcmin.fits’, survey=’2MASS-J’, boxwidth_units=’arcmin’)

obs.download_cutout(‘NGC1275’, 90., ‘./NGC1275_SDSSr_90asec.fits’, survey=’SDSSr’, search_name=True, boxwidth_units=’asec’)

obsplanning.download_cutouts(coords, boxwidth, savepathstem, surveybands=['DSS2 Blue', 'DSS2 Red', 'DSS2 IR'], boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False)

Downloads and saves multiple cutout fits images using astroquery.skyview. Useful for, e.g., collecting images to make 3-color plots, or to quickly assemble plots in different bands.

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_<surveyband>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

Example

obs.download_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.download_dss_cutouts(coords, boxwidth, savepathstem, boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False)

Convenience function to download cutouts of the DSS2 images: B, R, IR.

Calls download_cutouts() with DSS2 bands being passed to surveybands.

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_DSS2<band>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

Example

obs.download_dss_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.download_galex_cutouts(coords, boxwidth, savepathstem, boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False)

Convenience function to download cutouts of the GALEX NUV and FUV files.

Calls download_cutouts() with GALEX bands being passed to surveybands.

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_GALEX<band>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

Example

obs.download_galex_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.download_sdss_cutouts(coords, boxwidth, savepathstem, boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False, SDSSbands=['SDSSg', 'SDSSi', 'SDSSr'])

Convenience function to download multiple SDSS cutout images.

Calls download_cutouts() with SDSS bands being passed to surveybands.

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_SDSS<band>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

• SDSSbands (list) – The list of SDSS bands to download. ‘SDSSg’,’SDSSi’,’SDSSr’,’SDSSu’,’SDSSz’, ‘SDSSdr7g’,’SDSSdr7i’,…

Example

obs.download_sdss_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.download_ukidss_cutouts(coords, boxwidth, savepathstem, boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False)

Downloads cutouts of the three UKIDSS bands: J,H,K

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_UKIDSS<band>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

Example

obs.download_ukidss_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.download_ukidss_cutouts2(coords, boxwidth_asec, savepathstem, overwrite=False)

Alternative method to download UKIDSS images using astroquery.ukidss instead of astroquery.skyview

Downloads cutouts of the three UKIDSS bands: J,H,K

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_UKIDSS<band>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

Example

obs.download_ukidss_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.download_wise_cutouts(coords, boxwidth, savepathstem, boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False)

Convenience function to download cutouts of the four WISE band images.

Calls download_cutouts() with GALEX bands being passed to surveybands.

Parameters:

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• savepathstem (str) – The path string stem to use for saving the downloaded files. Filenames will be appended with ‘_WISE<band>.fits’

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) – Set to True to overwrite the existing file at the specified savepath

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

Example

obs.download_wise_cutouts(‘M104’, 90., ‘./M104_90asec’, search_name=True, boxwidth_units=’arcsec’)

obsplanning.dt_naive_to_dt_aware(datetime_naive, local_timezone)

Convert a naive dt object (no tzinfo attached) to an aware dt object.

Parameters:

• datetime_naive (datetime.datetime) – naive datetime object – e.g. dt.datetime(2021, 4, 15, 23, 59, 59)

• local_timezone (pytz.timezone, or str) – pytz.timezone object, or string of a standard Olson database timezone name (e.g. ‘US/Pacific’)

Example

obs.dt_naive_to_dt_aware(dt.datetime.strptime(‘2021/04/15 23:59:59’,’%Y/%m/%d %H:%M:%S’),’US/Pacific’)

obsplanning.dtaware_to_ephem(dt_in)

Converts timezone-aware dt object into ephem.Date() [UTC time] object

Parameters:

dt_in (datetime.datetime) –

Returns:

ephem_out

Return type:

ephem.Date

obsplanning.eph2c(target, style='sex', apparent=False, **kwargs)

Convenience function to return equatorial (RA,DEC) coordinates from the ephem target source in the specified style: sexagesimal string, degrees, or radians. To return coordinates at specific epochs or other coordinate systems such as Galactic, use the formal ephem functionality, e.g. ephem.Galactic(target, epoch=ephem.J2000)

Parameters:

• target (ephem.FixedBody(), ephem.Sun(), or ephem.Moon()) – The source of interest on the sky. Object must already be instantiated and coordinates computed with .compute().

• style (str) –

  Style of output coordinates.

  ’sex’ = sexagesimal coordinates from obs.dec2sex (can optionally specify kwargs)

  ’deg’ = decimal degrees.

  ’hour’ = decimal hours for RA, degrees for DEC

  ’rad’ = radians

• apparent (bool) – Whether to use apparent coordinates from the pre-computed epoch instead of the absolute/astrometric coordinates. Default is False (use absolute coords). If True, uses [target.ra, target.dec] instead of [target.a_ra, target.a_dec] Note - for objects like Sun and Moon, must use apparent=True

• kwargs (bool, in, or str) – Keyword args for obs.dec2sex: as_string, decimal_places, str_format

Returns:

coords – The output coordinates, in the format specified by style

Return type:

list, str, or astropy.coordinates.SkyCoord

obsplanning.ephemeris_report(target, observer, obstime)

For a specified Observer, astronomical target, and observation time, print to screen various ephemeris information about the target.

Parameters:

• target (ephem.FixedBody(), ephem.Moon(), or ephem.Sun()) – pyephem target source

• observer (ephem.Observer()) – The observer/telescope/station as a pyephem Observer object

• obstime (ephem.Date(), or string in format 'YYYY/MM/DD HH:MM:SS') – A relevant time for the observations, from which to calculate the rise/set times

obsplanning.fill_twilights(axin, obsframe, startdate, offsetdatetime=0.0, timetype='offset', bgcolor='k')

Fills a matplotlib axis with shading for twilight.

Parameters:

• axin (matplotlib.axes._subplots.AxesSubplot) – The matplotlib axis object to plot to, created with plt.subplot(), plt.axis() etc.

• obsframe (ephem.Observer()) – pyephem Observer() frame

• startdate (ephem.Date or str, formatted as e.g., 'YYYY/MM/DD hh:mm:ss') – The starting date/time (the evening at the beginning observations, for classical night sessions)

• offsetdatetime (datetime.datetime) – Reference time to use for plotting offset times

• timetype (str, 'offset' or 'abs') – String denoting the style to use for displaying the time: either ‘abs’ for absolute time, or ‘offset’ for offset/delta time from speccified offsetdatetime.

• bgcolor (str, or valid matplotlib color) – Base color to use for plot background fill shading.

obsplanning.fill_twilights_light(axin, obsframe, startdate, plottimerange, offsetdatetime=0.0, bgcolor='#95D0FC', timetype='offset')

Fills a matplotlib axis with shading for twilight – alternate variant for light colors.

Parameters:

• axin (matplotlib.axes._subplots.AxesSubplot) – The matplotlib axis object to plot to, created with plt.subplot(), plt.axis() etc.

• obsframe (ephem.Observer()) – pyephem Observer() frame

• startdate (ephem.Date or str, formatted as e.g., 'YYYY/MM/DD hh:mm:ss') – The starting date/time (the evening at the beginning observations, for classical night sessions)

• plottimerange (array-like [list, tuple, ...]) – The beginning and end times (dt.datetime format) use for the plot x-range span

• offsetdatetime (datetime.datetime) – Reference time to use for plotting offset times

• timetype (str, 'offset' or 'abs') – String denoting the style to use for displaying the time: either ‘abs’ for absolute time, or ‘offset’ for offset/delta time from speccified offsetdatetime.

• bgcolor (str, or valid matplotlib color) – Base color to use for plot background fill shading.

obsplanning.fill_twilights_split(axin, obsframe, startdate, enddate, bgcolor='k')

Fill a matplotlib axis with shading for twilight; for daytime observations, so centered in the daylight hours with twilight shading split into two parts.

Parameters:

• axin (matplotlib.axes._subplots.AxesSubplot) – The matplotlib axis object to plot to, created with plt.subplot(), plt.axis() etc.

• obsframe (ephem.Observer()) – pyephem Observer() frame

• startdate (ephem.Date or str, formatted as e.g., 'YYYY/MM/DD hh:mm:ss') – The starting date/time (the morning at the beginning of observations, for daytime sessions)

• enddate (ephem.Date or str, formatted as e.g., 'YYYY/MM/DD hh:mm:ss') – The ending date/time (the evening at the end of observations, for daytime sessions)

• bgcolor (str, or valid matplotlib color) – Base color to use for plot background fill shading.

Notes

Civil, Nautical, and Astronomical twilight defined as when Sun is > [6,12,18] deg below horizon.

obsplanning.get_VLBA_sensitivity_table_info(query_freq_GHz)

Takes a nominal observation frequency in GHz and returns the relevant VLBA sensitivity calculation values from:

https://science.nrao.edu/facilities/vlba/docs/manuals/oss/bands-perf

(LBA Frequency Bands & Performance. Table 5.1. )

Parameters:

query_freq_GHz (float) – The frequency of interest, in GHz.

Returns:

• VLBA_sensitivity_info (list) – [receiver_name, zenith_SEFD(Jy), peak_gain(K/Jy), baseline_sensitivity(60min), image_sensitivity(8hrs)]

• Example – obs.get_VLBA_sensitivity_table_info(5.) #Returns –> [‘6 cm’, 210, 0.119, 2.1, 5]

obsplanning.get_visible_targets_from_source_list(observer, time_start, time_end, source_list, elevation_limit=15.0, decbin_limits_deg=[-90, 90], minimum_observability_minutes='full', coord_format='dec', skip_header=0, delimiter=',', nsteps=100, decimal_format='deg')

For a specified observatory location, determine the observable targets from a list of sources. Observability here means the targets will be above the specified telescope elevation limit for the full (or partial, if specified) duration. Targets can be restricted to a certain declination range using a list of min/max limits.

Note

The format of the input source list is three columns:

source name (string), RA, DEC

The coordinates can be in decimal (default) or sexagesimal, to be specified by the user.

Sparse lists (missing elements in a row) are not supported.

Querying positions by name is not yet implemented within this function – do this beforehand, e.g., with obs.query_object_coords_simbad()

Parameters:

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• time_start (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The observation start date/time, in UTC

• time_end (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The observation end date/time, in UTC

• source_list (array-like sequence (list, tuple, ...)) – The list of candidate sources and coordinates, of shape Nx3: each row/element consisting of [Sourcename,RA,DEC]

• elevation_limit (float [degrees]) – The elevation limit at the observatory to use for visibility calculations, in degrees

• decbin_limits_deg (sequence (list, tuple, np.array...)) – The [minimum, maximum] declination limits for returned targets, in degrees.

• minimum_observability_minutes (float, int, or str) – The minimum time (in minutes, as a float or int) that the source targets must be observable in the specified observation window. If set to ‘full’ (default), only returns source targets that are observable for the entire duration of the specified observation window.

• coordinates (coord_format = 'dec'/'decimal' or 'sex'/'sexagesimal'. Specifies the format of the source_list) –

• skip_header (int) – The number of header lines to skip when loading a source list from file, passed to np.genfromtxt

• delimiter (str) – The delimiter to use when loading a source list from file, passed to np.genfromtxt

• nsteps (int) – The number of steps over which to calculate altitudes for the visibility checks

• decimal_format (str) – ‘deg’ or ‘rad’ – The format of the source list coordinates (degrees or radians), when they are supplied as decimal (floats) instead of strings. Passed to obs.create_ephem_target.

Returns:

observable_targets – A list of the sources that satisfy the minimum observability duration within the specified observing window.

Return type:

list

Example

obs.get_visible_targets_from_source_list([obs.vlbaMK], dt.datetime(2021,10,31,10,0,0), dt.datetime(2021,10,31,10,45,0), ‘special_sources.txt’, elevation_limit=15., minimum_observability_minutes=30., minimum_mutual_vis_observers=’full’, coord_format=’sex’)

obsplanning.get_visible_targets_from_source_list_VLBA(time_start, time_end, source_list, elevation_limit=15.0, decbin_limits_deg=[-90, 90], minimum_observability_minutes='full', minimum_mutual_vis_observers='full', fast_mode=True, coord_format='dec', skip_header=0, delimiter=',', nsteps=100, decimal_format='deg')

Determine the observable targets for the VLBA from a list of sources. Observability here means the targets will be above the specified telescope elevation limit for the full (or partial, if specified) duration, and concurrently visible across at least the specified number of stations.

Parameters:

• time_start (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The observation start date/time, in UTC

• time_end (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The observation end date/time, in UTC

• source_list (array-like sequence (list, tuple, ...)) – The list of candidate sources and coordinates, of shape Nx3: each row/element consisting of [Sourcename,RA,DEC]

• elevation_limit (float [degrees]) – The elevation limit at the observatory to use for visibility calculations, in degrees

• decbin_limits_deg (sequence (list, tuple, np.array...)) – The [minimum, maximum] declination limits for returned targets, in degrees.

• minimum_observability_minutes (float, int, or str) – The minimum time (in minutes, as a float or int) that the source targets must be observable in the specified observation window. If set to ‘full’ (default), only returns source targets that are observable for the entire duration of the specified observation window.

• minimum_mutual_vis_observers (int, or str) – The minimum number of stations across which a target must be concurrently visible. If set to ‘full’ (default), only returns source targets that are observable over the entire array, for the specified duration.

• fast_mode (bool) – If set to True, will perform calculations for the four outermost N,E,S,W stations (MK,BR,HN,SC) instead of the full array of 10 stations

• coordinates (coord_format = 'dec'/'decimal' or 'sex'/'sexagesimal'. Specifies the format of the source_list) –

• skip_header (int) – The number of header lines to skip when loading a source list from file, passed to np.genfromtxt

• delimiter (str) – The delimiter to use when loading a source list from file, passed to np.genfromtxt

• nsteps (int) – The number of steps over which to calculate altitudes for the visibility checks, and times for the duration checks

• decimal_format (str) – ‘deg’ or ‘rad’ – The format of the source list coordinates (degrees or radians), when they are supplied as decimal (floats) instead of strings. Passed to obs.create_ephem_target.

Returns:

observable_targets – A list of the sources that satisfy the minimum observability duration within the specified observing window, with mutual visibility among at least the minimum number of stations.

Return type:

list

Example

obs.get_visible_targets_from_source_list_VLBA(‘2021/10/31 10:00:00.0’, ‘2021/10/31 10:45:00.0’, ‘./spooky_halloween_sources.txt’, elevation_limit=15., minimum_observability_minutes=’full’, minimum_mutual_vis_observers=’full’, fast_mode=True, coord_format=’dec’)

obsplanning.get_visible_targets_from_source_list_multistation(observerlist, time_start, time_end, source_list, elevation_limit=15.0, decbin_limits_deg=[-90, 90], minimum_observability_minutes='full', minimum_mutual_vis_observers='full', coord_format='dec', skip_header=0, delimiter=',', nsteps=100, decimal_format='deg')

For a specified list of observatory locations, determine the observable targets from a list of sources. Observability here means the targets will be above the specified telescope elevation limit for the full (or partial, if specified) duration, and concurrently visible across at least the specified number of stations.

Parameters:

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• time_start (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The observation start date/time, in UTC

• time_end (ephem.Date(), datetime.datetime, or str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The observation end date/time, in UTC

• source_list (array-like sequence (list, tuple, ...)) – The list of candidate sources and coordinates, of shape Nx3: each row/element consisting of [Sourcename,RA,DEC]

• elevation_limit (float [degrees]) – The elevation limit at the observatory to use for visibility calculations, in degrees

• decbin_limits_deg (sequence (list, tuple, np.array...)) – The [minimum, maximum] declination limits for returned targets, in degrees.

• minimum_observability_minutes (float, int, or str) – The minimum time (in minutes, as a float or int) that the source targets must be observable in the specified observation window. If set to ‘full’ (default), only returns source targets that are observable for the entire duration of the specified observation window.

• minimum_mutual_vis_observers (int, or str) – The minimum number of stations across which a target must be concurrently visible. If set to ‘full’ (default), only returns source targets that are observable over the entire array, for the specified duration.

• coordinates (coord_format = 'dec'/'decimal' or 'sex'/'sexagesimal'. Specifies the format of the source_list) –

• skip_header (int) – The number of header lines to skip when loading a source list from file, passed to np.genfromtxt

• delimiter (str) – The delimiter to use when loading a source list from file, passed to np.genfromtxt

• nsteps (int) – The number of steps over which to calculate altitudes for the visibility checks, and times for the duration checks

• decimal_format (str) – ‘deg’ or ‘rad’ – The format of the source list coordinates (degrees or radians), when they are supplied as decimal (floats) instead of strings. Passed to obs.create_ephem_target.

Returns:

observable_targets – A list of the sources that satisfy the minimum observability duration within the specified observing window, with mutual visibility among at least the minimum number of stations.

Return type:

list

Example

obs.get_visible_targets_from_source_list_multistation([obs.vlbaMK,obs.vlbaHN], dt.datetime(2021,10,31,10,0,0), dt.datetime(2021,10,31,10,45,0), ‘special_sources.txt’, elevation_limit=15., minimum_observability_minutes=30., minimum_mutual_vis_observers=’full’, coord_format=’sex’)

obsplanning.hour2deg(valin)

Converts hours or HMS input to decimal degrees.

Parameters:

valin (float) –

Input value in HMS. Can be either:

• a string delimeted by : or spaces

• a list of [H,M,S] numbers (floats or ints)

Returns:

valout – Degrees corresponding to the HMS value

Return type:

float

Examples

# e.g., ‘09:30:15’ corresponds to 142.5625 deg

obs.hour2deg(‘09:30:15’) #–> 142.5625

obs.hour2deg(‘09 30 15.000’) #–> 142.5625

obs.hour2deg([9,30,15.]) #–> 142.5625

obsplanning.info_from_idifits(idifits_path, print_style='short')

Prints and returns info about the contents of an idifits file, in either long or short form.

Parameters:

• idifits_path (str) – The path to the idifits file (relative & absolute paths OK)

• print_style (str ('short' or 'long')) – Specifies the level of detail to print to screen/terminal

Returns:

OBSCODE, DATE_OBS, SOURCE, sourcecoordlist, REF_FREQ, totalBW, NR_BANDS, BAND_FREQS

Return type:

str, str, list, list, float, float, int, np.array

Examples

obs.info_from_idifits(‘myVLBAquasar_Kband.idifits’,print_style=’long’);

obs.info_from_idifits(‘/home/observerdude/data/NGC3079_Kband.idifits’,print_style=’short’);

for f in sorted(glob(‘/some/directory/with/idifits/’)):

obs.info_from_idifits(f,print_style=’short’);

#Note the semicolon at the end, to suppress the return output in ipython…

obsplanning.is_dt_tzaware(dt)

Simple check for whether a dt.datetime object is timezone-aware or not

Parameters:

dt (datetime.datetime) –

Returns:

dt_is_tzaware

Return type:

bool

Examples

dt_naive = dt.datetime.strptime(‘2021/10/31 23:59:59’,’%Y/%m/%d %H:%M:%S’)

obs.is_dt_tzaware(dt_naive) #–> False

obs.is_dt_tzaware(dt_naive.replace(tzinfo=pytz.UTC)) #–> True

obsplanning.is_target_always_up(target, observer, approximate_time)

Checks whether a target is always above the observing horizon (circumpolar) for a specified observer on a specified date.

Parameters:

• ephem.FixedBody() (target =) – The sky source of interest

• ephem.Sun() – The sky source of interest

• ephem.Moon() (or) – The sky source of interest

• observer (ephem.Observer()) – Telescope/observer location from which the observation calculation will be made

• approximate_time (ephem.Date(), or str in 'YYYY/MM/DD HH:MM:SS.s' format) – approximate date/time (UTC, not local!) of the calculation

Returns:

alwaysup – True if target is always up on that day, False if not.

Return type:

bool

obsplanning.is_target_never_up(target, observer, approximate_time)

Checks whether a target is always below the observing horizon for a specified observer on a specified date.

Parameters:

• ephem.FixedBody() (target =) – The sky source of interest

• ephem.Sun() – The sky source of interest

• ephem.Moon() (or) – The sky source of interest

• observer (ephem.Observer()) – Telescope/observer location from which the observation calculation will be made

• approximate_time (ephem.Date(), or str in 'YYYY/MM/DD HH:MM:SS.s' format) – approximate date/time (UTC, not local!) of the calculation

Returns:

alwaysup – True if target is never up on that day, False if not.

Return type:

bool

obsplanning.local_to_local(dt_aware_in, timezone_out)

Converts/localizes a tz-aware datetime to another specified timezone.

Parameters:

• dt_aware_in (datetime.datetime) – Timezone-aware dt.datetime object (tzinfo is attached)

• timezone_out (pytz.timezone or str) – The desired output timezone, in either pytz.timezone format or a string from the Olson timezone name database

Returns:

dt_aware_out – A timezone-aware datetime object in the new timezone

Return type:

datetime.datetime

Examples

dt_pacific = dt.datetime(2025,12,31,23,59,59,tzinfo=pytz.timezone(‘US/Pacific’))

dt_eastern = obs.local_to_local(dt_pacific,’US/Eastern’)

dt_utc = obs.local_to_local(dt_pacific,pytz.UTC)

obsplanning.local_to_utc(datetime_local_aware)

Convert an aware dt object (correct tzinfo already present) to UTC

Parameters:

datetime_local_aware (datetime.datetime) – Timezone-aware datetime object

Returns:

datetime_utc

Return type:

datetime.datetime

Example

#using pytz.localize to account for DST

tz = pytz.timezone(‘US/Mountain’)

t = tz.localize(dt.datetime.strptime(‘2021/04/15 23:59:59’,’%Y/%m/%d %H:%M:%S’))

obs.local_to_utc(t)

obsplanning.localnaive_to_utc(datetime_local_naive, local_timezone)

Convert a naive (no tzinfo attached) datetime from the local timezone to UTC.

Parameters:

• datetime_local_naive (datetime.datetime) – datetime object with values reflecting the time in the local timezone

• local_timezone (pytz.timezone, or str) – pytz.timezone object, or string of a standard Olson database timezone name (e.g. ‘US/Eastern’)

Returns:

datetime_utc

Return type:

datetime.datetime

Example

obs.localnaive_to_utc(dt.datetime.now(),’US/Mountain’)

obsplanning.make_finder_plot_multicolor(targetname, coords, boxwidth, surveyscolors=[['DSS2 IR', '#C11B17'], ['DSS2 Red', '#FFFD74'], ['DSS2 Blue', '#1569C7']], boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False, refregs=None, scalefuncs=['sqrt', 'sqrt', 'sqrt'], dpi=200, tickcolor='0.2', mfc='r', mec='w', bs_amin=0.0, surveytitle=False, savepathstem='./', filetype='jpg')

Downloads cutout images (with astroquery.skyview, if not already on disk) of the specified survey bands, and creates a multicolor image finder plot. Optional refregs can be specified to plot reference positions on the plot (notable guide stars, etc).

Parameters:

• targetname (str) – The name of the target, to use in filenames and the plot title

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• surveyscolors (list) – Each element in this list is a pair of a [‘surveyname’,’#hexcolor’], a string astroquery.skyview survey name, and a hex/html color to apply to that image. (E.g., ‘SDSSr’, ‘2MASS-J’, ‘WISE 3.4’ …) This list can include as many or as few images as desired – not limited to exactly 3 colors.

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) –

  Set to True to overwrite the existing file at the specified savepath

  If you have deleted a fits file and the old one keeps reappearing, try deleting the contents of your astroquery download cache, ~/.astopy/cache/download/url/

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

• refregs (list) – refregs = list of reference position points in format [RA,DEC,’Name’]

• scalefuncs (list) – List of the scaling functions from multicolorfits to use for scaling in the various images: ‘linear’, ‘sqrt’, ‘log’, ‘asinh’

• dpi (int) – The raster resolution (dots per inch) to apply to the saved image

• tickcolor (str or matplotlib color specifier) – The color to use for the tick marks

• mfc (str or matplotlib color specifier) – Marker face color

• mec (str or matplotlib color specifier) – Marker edge color

• bs_amin (float) – The (angular) bar size to plot, in arcmin

• surveytitle (bool) – Set to True to include the surveys used for the background image

• savepathstem (str) – The path string stem to use for saving the downloaded file.

• filetype (str) – The filetype to use for the saved image. ‘jpg’,’png’,’pdf’,’svg’,’eps’…

Example

refstars=[[‘5:34:42.3’,’22:10:34.5’,’HD 244988’], [‘5:34:36.6’,’21:37:19.9’,’HD 36707’],] obs.make_finder_plot_multicolor(‘M1’, obs.sex2dec(‘05:34:31.94’,’22:00:52.2’), 50., [[‘DSS2 Red’,’#A83C09’], [‘DSS2 Blue’,’#336699’]], boxwidth_units=’arcmin’, refregs=refstars, scalefuncs=[‘linear’,’linear’], dpi=200, tickcolor=’0.8’, mfc=’#C11B17’,mec=’w’,bs_amin=10., filetype=’jpg’)

obsplanning.make_finder_plot_simpleRGB(targetname, coords, boxwidth, surveyR, surveyG, surveyB, boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False, refregs=None, Rscalefunc='sqrt', Gscalefunc='sqrt', Bscalefunc='sqrt', dpi=200, tickcolor='0.2', mfc='r', mec='w', bs_amin=0.0, surveytitle=False, savepathstem='./', filetype='jpg')

Downloads a cutout image (with astroquery.skyview, if not already on disk) of the specified survey band, and creates a simple R,G,B stacked image finder plot. Optional refregs can be specified to plot reference positions on the plot (notable guide stars, etc).

Parameters:

• targetname (str) – The name of the target, to use in filenames and the plot title

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• surveyR (str) –

  The Red-channel survey to download from. E.g., ‘SDSSr’, ‘2MASS-J’, ‘WISE 3.4’ …

  List all available surveys with:

  from astroquery.skyview import SkyView; SkyView.list_surveys()

• surveyG (str) – The Green-channel survey to download from. E.g., ‘SDSSr’, ‘2MASS-J’,’ WISE 3.4’ …

• surveyB (str) – The Blue-channel survey to download from. E.g., ‘SDSSr’, ‘2MASS-J’, ‘WISE 3.4’ …

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) –

  Set to True to overwrite the existing file at the specified savepath

  If you have deleted a fits file and the old one keeps reappearing, try deleting the contents of your astroquery download cache, ~/.astopy/cache/download/url/

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

• refregs (list) – refregs = list of reference position points in format [RA,DEC,’Name’]

• Rscalefunc (str) – The scaling function from multicolorfits to use for scaling in the Red channel: ‘linear’, ‘sqrt’, ‘log’, ‘asinh’

• Gscalefunc (str) – The scaling function from multicolorfits to use for scaling in the Green channel: ‘linear’, ‘sqrt’, ‘log’, ‘asinh’

• Bscalefunc (str) – The scaling function from multicolorfits to use for scaling in the Blue channel: ‘linear’, ‘sqrt’, ‘log’, ‘asinh’

• dpi (int) – The raster resolution (dots per inch) to apply to the saved image

• tickcolor (str or matplotlib color specifier) – The color to use for the tick marks

• mfc (str or matplotlib color specifier) – Marker face color

• mec (str or matplotlib color specifier) – Marker edge color

• bs_amin (float) – The (angular) bar size to plot, in arcmin

• surveytitle (bool) – Set to True to include the surveys used for the background image

• savepathstem (str) – The path string stem to use for saving the downloaded file.

• filetype (str) – The filetype to use for the saved image. ‘jpg’,’png’,’pdf’,’svg’,’eps’…

Example

refstars=[[‘5:34:42.3’,’22:10:34.5’,’HD 244988’], [‘5:34:36.6’,’21:37:19.9’,’HD 36707’],] obs.make_finder_plot_simpleRGB(‘M1’, obs.sex2dec(‘05:34:31.94’,’22:00:52.2’), 50., ‘DSS2 IR’,’DSS2 Red’,’DSS2 Blue’, boxwidth_units=’arcmin’, refregs=refstars, Rscalefunc=’linear’, Gscalefunc=’linear’, Bscalefunc=’linear’, dpi=200, tickcolor=’0.8’, mfc=’#C11B17’,mec=’w’,bs_amin=10., filetype=’jpg’)

obsplanning.make_finder_plot_singleband(targetname, coords, boxwidth, survey='DSS2 Red', boxwidth_units='pix', frame='icrs', overwrite=False, search_name=False, refregs=None, cmap='gist_yarg', dpi=200, tickcolor='0.2', mfc='r', mec='w', bs_amin=0.0, surveytitle=False, savepathstem='./', filetype='jpg')

Downloads a cutout image (with astroquery.skyview, if not already on disk) of the specified survey band, and creates a finder plot. Optional refregs can be specified to plot reference positions on the plot (notable guide stars, etc).

Parameters:

• targetname (str) – The name of the target, to use in filenames and the plot title

• coords (list or str) –

  The list of target [RA,DEC] coordinates to use in astroquery.skyview.SkyView.get_images, in decimal (not sexagesimal).

  If search_name is True, this is a string name for the target source, to use with astroquery.

• boxwidth (int or float) – The width of the box sides of the desired image. Units (e.g., pixels or arcminutes) specified with boxwidth_units

• boxwidth_units (str) – The units of the specified box width. Options: ‘pixels’/’pix’, ‘degree’,’deg’, ‘arcmin’/’amin’, ‘arcsec’/’asec’

• survey (str) –

  The survey to download from. E.g., ‘SDSSr’, ‘2MASS-J’, ‘WISE 3.4’ …

  List all available surveys with:

  from astroquery.skyview import SkyView; SkyView.list_surveys()

• frame (str) – The coordinate reference frame. Defaults to ‘icrs’. Other options include ‘galactic’,’fk5’, …

• overwrite (bool) –

  Set to True to overwrite the existing file at the specified savepath

  If you have deleted a fits file and the old one keeps reappearing, try deleting the contents of your astroquery download cache, ~/.astopy/cache/download/url/

  Or, astropy.utils.data.clear_download_cache()

• search_name (bool) – Set to True to query SkyView by a common name (e.g., ‘M33’). Specify this name with the coords parameter instead of a list of [RA,DEC] coordinates.

• refregs (list) – refregs = list of reference position points in format [RA,DEC,’Name’]

• cmap (str or matplotlib LinearSegmentedColormap) – The matplotlib colormap (or cmap specifier string) to apply to the image.

• dpi (int) – The raster resolution (dots per inch) to apply to the saved image

• tickcolor (str or matplotlib color specifier) – The color to use for the tick marks

• mfc (str or matplotlib color specifier) – Marker face color

• mec (str or matplotlib color specifier) – Marker edge color

• bs_amin (float) – The (angular) bar size to plot, in arcmin

• surveytitle (bool) – Set to True to include the survey used for the background image

• savepathstem (str) – The path string stem to use for saving the downloaded file.

• filetype (str) – The filetype to use for the saved image. ‘jpg’,’png’,’pdf’,’svg’,’eps’…

Example

refstars=[[‘5:34:42.3’,’22:10:34.5’,’HD 244988’], [‘5:34:36.6’,’21:37:19.9’,’HD 36707’],] obs.make_finder_plot_singleband(‘Crab Nebula’, ‘M1’, 50., boxwidth_units=’arcmin’, survey=’DSS2 Red’, search_name=True, refregs=refstars, cmap=’gist_yarg’, dpi=200, tickcolor=’0.2’, mfc=’r’, mec=’w’, bs_amin=10., )

obsplanning.moonsep_VLBAminmax(target, obstime, verbose=False, return_names=False)

Convenience function to call moonsep_arrayminmax() for the VLBA stations.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• obstime (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The time at which the separation should be determined

• verbose (bool) – True prints results to terminal

• return_names (bool) – Setting to True will also return the station names where the min/max occur

Returns:

minmaxlist – The min/max target separation from the Moon, in degrees

Return type:

list [minsep,maxsep]

obsplanning.moonsep_arrayminmax(target, observer_list, obstime, verbose=False, return_names=False)

Calculate the Moon separation from the target, observed from a specified obstime, and each supplied telescope/station, to determine the minimum/maximum separation

Parameters:

• target (ephem.FixedBody()) – The target observation source

• observer_list (array-like [list, np.array, ...]) – The list of ephem.Observer() antenna location objects to use for the calculations

• obstime (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The time at which the separation should be determined

• verbose (bool) – True prints results to terminal

• return_names (bool) – Setting to True will also return the station names where the min/max occur

Returns:

minmaxlist – The min/max target separation from the Moon, in degrees

Return type:

list [minsep,maxsep]

obsplanning.moonsep_single(target, observer, obstime)

Calculate the angular separation between the Moon and a target, observed from a specified telescope/station and obsdate

Parameters:

• target (ephem.FixedBody()) – Target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obstime (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The time at which the separation should be determined

Returns:

moonsep – The angular separation between the Moon and the source, in degrees

Return type:

float

obsplanning.moonsep_timearray(target, observer, obstime_array)

Calculate an array of angular separations between the Moon and a target, observed from a specified telescope/station at multiple obsdate/times. Useful, for example, for determining moon separation at each point in a night’s observations.

Parameters:

• target (ephem.FixedBody()) – Target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obstime_array (array-like [list,np.array...]) – A series of date+times, in ephem.Date, dt.datetime, or string (‘YYYY/MM/DD HH:MM:SS.s’)

Returns:

moonseps – The target separations from the Moon, in degrees, at each time in the series

Return type:

np.array

obsplanning.nearest_from_target_list(obstarget, reference_source_list, verbose=False, stat='median', return_format='name')

For a given observation target (or list of targets), determine the nearest from among a list of reference sky targets.

Parameters:

• obstarget (ephem.FixedBody(), or array-like of ephem.FixedBody()) – The sky source(s) of interest.

• reference_source_list (array-like [list, tuple, np.array...]) – The list of reference objects, in ephem.FixedBody() format

• verbose (bool) – Set to True to print out the distance to each source in reference_source_list

• stat (str) – The statistic to use for calculating the nearest, when multiple obstargets are input: ‘median’ or ‘mean’/’average’

• return_format (str) – The type of object to return: ‘name’ returns only the nearest source name, ‘source’ returns the nearest ephem target object, ‘separations’ returns the array of separations

Returns:

src_nearest – The name (ephem.FixedBody().name string) of the nearest Fringe Finder to the target

Return type:

str

Examples

obs.nearest_from_target_list(obstarget,[obs.SRC_3C84,obs.SRC_3C286,obs.SRC_3C273],verbose=True)

obsplanning.nearest_standard_fringefinder(obstarget, verbose=False, stat='median', return_format='name')

For a given observation target, determine the nearest fringe finder, and optionally print the distance to standard fringe finders.

Parameters:

• obstarget (ephem.FixedBody()) – The sky source of interest.

• verbose (bool) – Set to True to print out the distance to each fringe finder

• stat (str) – The statistic to use for calculating the nearest, when multiple obstargets are input: ‘median’ or ‘mean’/’average’

• return_format (str) – The type of object to return: ‘name’ returns only the nearest source name, ‘source’ returns the nearest ephem target object, ‘separations’ returns the array of separations

Returns:

src_nearest – The name (ephem.FixedBody().name string) of the nearest Fringe Finder to the target

Return type:

str

Examples

ngc3079=obs.create_ephem_target(‘NGC3079’,’10:01:57.80’,’55:40:47.24’)

obs.nearest_standard_fringefinder(ngc3079) #–> ‘4C39.25’

obs.nearest_standard_fringefinder(ngc3079,verbose=True) #–> prints individual seps

###

# You can do this for the Sun/Moon as well, which first requires coords at some time

suncoords=obs.compute_target_altaz_single(ephem.Sun(),obs.vlbaBR,’2021/01/01 00:00:00’)

obs.nearest_standard_fringefinder(suncoords)

obsplanning.optimal_visibility_date(target, observer, obsyear, extra_info=True, verbose=False, return_fmt='str', timezone='auto', time_of_obs='night', peak_alt=True, local=True)

Returns the optimal day/time to observe a specified target from a specified observer site, for the given year. (Based on the peak altitude at the time specified by time_of_obs.)

Parameters:

• target (ephem.FixedBody()) – The target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obsyear (int, float, str, ephem.Date, or datetime.datetime) – The year to consider for the calculations. Use 4-digit format ‘YYYY’ if given as a string.

• extra_info (bool) – Set to True to also return a list of [rise time, set time, peak altitude] on that date

• verbose (bool) – Set to True to also print results to screen

• return_fmt (str ['string', 'dt', or 'ephem']) – The desired output format for the returned date.

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• time_of_obs (str ['noon', 'night', 'midnight', 'peak' or 'HH:MM:SS']) –

  Denotes how to generate the times to use for each day. Options:

  ’middark’ = calculate the altitudes at each night’s middle-dark time

  ’noon’ = calculate the values at 12:00 local time each day

  ’night’ or ‘midnight’ = use 23:59:59 local time each day (for night obs. 00:00:00 would be for the previous night.)

  ’peak’ = return values during daily peak altitude

Returns:

outdates – Returns the optimal observing date/time in the format specified by return_fmt. Optionally also returns a list of extra info comprised of [rise time, set time, peak altitude]

Return type:

same as return_fmt, or np.array if extra_info=True

Example

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

obs.optimal_visibility_date(ngc1052,obs.vlbaBR,’2021’,verbose=True,time_of_obs=’12:00:00’)

#–> ‘2021/09/19 03:46:38’

obsplanning.plot_VLBA_visibility_tracks(target, obsstart, obsend, weights=None, mode='nearest', duration_hours=0, figsize=(14, 8), dpi=200, savepath='', showplot=False)

Plot visibility tracks for the VLBA stations, for a given target and obsdate. Creates the figure and axis, calls plot_VLBA_visibility_tracks_toaxis() to do the plotting, then saves/shows.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• obsstart (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation start time

• obsend (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation end time

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. Passed to calculate_VLBA_mean_transit_time(). The order of stations is alphabetical: [BR,FD,HN,KP,LA,MK,NL,OV,PT,SC].

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• duration_hours (float) – The desired duration of observations, for calculating the optimal start time. If greater than zero, calculate start time and plot a vertical line denoting it.

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

obsplanning.plot_VLBA_visibility_tracks_toaxis(target, obsstart, obsend, axin, weights=None, mode='nearest', duration_hours=0, xaxisformatter=<matplotlib.dates.DateFormatter object>)

Plot visibility tracks for the VLBA stations, for a given target and obsdate. Includes the mean of the transit times from each station in the full VLBA array. Plots onto a user-supplied matplotlib/pyplot axis (useful for creating the plot & allowing further manual editing).

Parameters:

• target (ephem.FixedBody()) – The target observation source

• obsstart (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation start time

• obsend (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation end time

• axin (matplotlib/pyplot axis object) – The axis on which to plot

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. Passed to calculate_VLBA_mean_transit_time(). The order of stations is alphabetical: [BR,FD,HN,KP,LA,MK,NL,OV,PT,SC].

• mode (str) –

  Specifies which transit time to return. (passed to calculate_VLBA_mean_transit()) Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• duration_hours (float) – The desired duration of observations, for calculating the optimal start time. If greater than zero, calculate start time and plot a vertical line denoting it.

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis times. Default obs.hourformat [mdates.DateFormatter(‘%H:%M’)] prints the hour and minute.

Example

fig1=plt.figure(1,figsize=(14,8))

ax1=fig1.add_subplot(111)

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

obs.plot_VLBA_visibility_tracks_toaxis(ngc1052,ephem.Date(‘2021/04/15 00:00:00’),ephem.Date(‘2021/04/15 23:59:59’),ax1)

plt.savefig(‘ngc1052_fullVLBA_april15.jpg’); plt.clf(); plt.close(‘all’)

obsplanning.plot_day_observing_tracks(target_list, observer, obsstart, obsend, weights=None, mode='nearest', plotmeantransit=False, toptime='local', timezone='auto', n_steps=1000, simpletracks=False, azcmap='rainbow', bgcolor='k', xaxisformatter=<matplotlib.dates.DateFormatter object>, figsize=(14, 8), dpi=200, savepath='', showplot=False)

Convenience function to call obs.plot_observing_tracks(…, light_fill=True) for daytime observations.

Plot visibility tracks of an astronomical target on the sky, over a specified period - like a classic ‘staralt’ plot.

Parameters:

• target_list (ephem.FixedBody(), or array-like [list, tuple, np.array...]) – List of pyephem FixedBody sky sources. Can also input a single target source.

• observer (ephem.Observer()) – Observatory/antenna/location object to use for the calculations

• obsstart (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation start time

• obsend (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation end time

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. Passed to calculate_targets_mean_transit_time()

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• plotmeantransit (bool) – Set to True to plot a vertical line denoting the mean of the target transit times

• toptime (str ['local', 'LMST', 'none']) – Type of time to plot on the top axis: local time, LMST, or nothing

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• n_steps (int) – The number of positions to calculate in the altitude tracks

• simpletracks (bool) –

  Whether to plot the visibility tracks as simple lines (True) or with a colormap (False).

  colormap option only works for a single target…

• azcmap (str, or matplotlib.colors.LinearSegmentedColormap) – The colormap to use for azimuth, passed to plt.scatter(). Any valid matplotlib colormap should work (including strings for builtin cmaps such as ‘inferno’).

• light_fill (bool, or 'none') – Whether to fill the background with light (True) color, dark (False, default) color, or nothing (‘none’)

• bgcolor (str, or valid matplotlib color) – Base color to use for plot background fill shading.

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. Default mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

Example

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

mrk348=obs.create_ephem_target(‘Mrk348’,’00:48:47.14’,’+31:57:25.1’)

obsstart=obs.dtaware_to_ephem(obs.construct_datetime(‘2021/09/15 16:00:00’,’dt’,timezone=’US/Pacific’))

obsend=obs.dtaware_to_ephem(obs.construct_datetime(‘2021/09/16 10:00:00’,’dt’,timezone=’US/Pacific’))

obs.plot_observing_tracks([ngc1052,mrk348],obs.vlbaBR,obsstart,obsend, plotmeantransit=False, simpletracks=True, toptime=’local’, timezone=’calculate’, n_steps=1000, azcmap=’rainbow’, light_fill=True, savepath=’test.jpg’, showplot=False) obs.plot_day_observing_tracks([ngc1052,mrk348], obs.vlbaBR, obsstart, obsend, simpletracks=True, savepath=’test.jpg’, showplot=False)

obsplanning.plot_night_observing_tracks(target_list, observer, obsstart, obsend, weights=None, mode='nearest', plotmeantransit=False, toptime='local', timezone='auto', n_steps=1000, simpletracks=False, azcmap='rainbow', bgcolor='k', xaxisformatter=<matplotlib.dates.DateFormatter object>, figsize=(14, 8), dpi=200, savepath='', showplot=False)

Convenience function to call obs.plot_observing_tracks(…, light_fill=False) for nighttime observations.

Plot visibility tracks of an astronomical target on the sky, over a specified period - like a classic ‘staralt’ plot.

Parameters:

• target_list (ephem.FixedBody(), or array-like [list, tuple, np.array...]) – List of pyephem FixedBody sky sources. Can also input a single target source.

• observer (ephem.Observer()) – Observatory/antenna/location object to use for the calculations

• obsstart (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation start time

• obsend (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation end time

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. Passed to calculate_targets_mean_transit_time()

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• plotmeantransit (bool) – Set to True to plot a vertical line denoting the mean of the target transit times

• toptime (str ['local', 'LMST', 'none']) – Type of time to plot on the top axis: local time, LMST, or nothing

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• n_steps (int) – The number of positions to calculate in the altitude tracks

• simpletracks (bool) –

  Whether to plot the visibility tracks as simple lines (True) or with a colormap (False).

  colormap option only works for a single target…

• azcmap (str, or matplotlib.colors.LinearSegmentedColormap) – The colormap to use for azimuth, passed to plt.scatter(). Any valid matplotlib colormap should work (including strings for builtin cmaps such as ‘inferno’).

• light_fill (bool, or 'none') – Whether to fill the background with light (True) color, dark (False, default) color, or nothing (‘none’)

• bgcolor (str, or valid matplotlib color) – Base color to use for plot background fill shading.

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. Default mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

Example

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

mrk348=obs.create_ephem_target(‘Mrk348’,’00:48:47.14’,’+31:57:25.1’)

obsstart=obs.dtaware_to_ephem(obs.construct_datetime(‘2021/09/15 16:00:00’,’dt’,timezone=’US/Pacific’))

obsend=obs.dtaware_to_ephem(obs.construct_datetime(‘2021/09/16 10:00:00’,’dt’,timezone=’US/Pacific’))

obs.plot_observing_tracks([ngc1052,mrk348],obs.vlbaBR,obsstart,obsend, plotmeantransit=False, simpletracks=True, toptime=’local’, timezone=’calculate’, n_steps=1000, azcmap=’rainbow’, light_fill=True, savepath=’test.jpg’, showplot=False) obs.plot_night_observing_tracks([ngc1052,mrk348], obs.vlbaBR, obsstart, obsend, simpletracks=True, savepath=’test.jpg’, showplot=False)

obsplanning.plot_observing_tracks(target_list, observer, obsstart, obsend, weights=None, mode='nearest', plotmeantransit=False, toptime='local', timezone='auto', n_steps=1000, simpletracks=False, azcmap='rainbow', light_fill=False, bgcolor='k', xaxisformatter=<matplotlib.dates.DateFormatter object>, figsize=(14, 8), dpi=200, savepath='', showplot=False)

Plot visibility tracks of an astronomical target on the sky, over a specified period - like a classic ‘staralt’ plot.

Parameters:

• target_list (ephem.FixedBody(), or array-like [list, tuple, np.array...]) – List of pyephem FixedBody sky sources. Can also input a single target source.

• observer (ephem.Observer()) – Observatory/antenna/location object to use for the calculations

• obsstart (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation start time

• obsend (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation end time

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. Passed to calculate_targets_mean_transit_time()

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• plotmeantransit (bool) – Set to True to plot a vertical line denoting the mean of the target transit times

• toptime (str ['local', 'LMST', 'none']) – Type of time to plot on the top axis: local time, LMST, or nothing

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• n_steps (int) – The number of positions to calculate in the altitude tracks

• simpletracks (bool) –

  Whether to plot the visibility tracks as simple lines (True) or with a colormap (False).

  colormap option only works for a single target…

• azcmap (str, or matplotlib.colors.LinearSegmentedColormap) – The colormap to use for azimuth, passed to plt.scatter(). Any valid matplotlib colormap should work (including strings for builtin cmaps such as ‘inferno’).

• light_fill (bool, or 'none') – Whether to fill the background with light (True) color, dark (False, default) color, or nothing (‘none’)

• bgcolor (str, or valid matplotlib color) – Base color to use for plot background fill shading.

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. Default mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

Example

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

mrk348=obs.create_ephem_target(‘Mrk348’,’00:48:47.14’,’+31:57:25.1’)

obsstart=obs.dtaware_to_ephem(obs.construct_datetime(‘2021/09/15 16:00:00’,’dt’,timezone=’US/Pacific’))

obsend=obs.dtaware_to_ephem(obs.construct_datetime(‘2021/09/16 10:00:00’,’dt’,timezone=’US/Pacific’))

obs.plot_observing_tracks([ngc1052,mrk348],obs.vlbaBR,obsstart,obsend, plotmeantransit=False, simpletracks=True, toptime=’local’, timezone=’calculate’, n_steps=1000, azcmap=’rainbow’, light_fill=True, savepath=’test.jpg’, showplot=False)

obsplanning.plot_sunseps_year(target, observer, year, min_sep_val=8.4, min_sep_type='freq', savepath='./sunsep_over_year.jpg', moon=True)

Make a plot of the Sun (and Moon, if specified) separations from a target over the course of a year. Also denote the minimum separation value

Parameters:

• target (ephem.FixedBody()) – Target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• year (int) – The year over which to calculate the Sun separations

• min_sep_val (float) – The minimum desired/required separation from the Sun. Depending on what is set by min_sep_type, can either be the number of degrees, or the frequency (GHz) of the observations - in which case the minimum separation in degrees will be calculated by the internal table of values for the VLBA.

• min_sep_type (str) – What the min_sep_val corresponds to - ‘degrees’ or ‘frequency’

• savepath (str (path)) – The path, including filename and file extension, to save the plot.

• moon (bool) – whether or not to include Moon separations in the plot.

Note

The minor ticks on the x (time) axis are 7-day increments past the first day of each month, to aid easy by-eye estimations.

obsplanning.plot_visibility_tracks(target_list, observer, obsstart, obsend, weights=None, mode='nearest', duration_hours=0, plotmeantransit=False, timezone='auto', xaxisformatter=<matplotlib.dates.DateFormatter object>, figsize=(14, 8), dpi=200, savepath='', showplot=False)

Plot visibility tracks for targets observed from a single observer station, for a given start and end time. Creates the figure and axis, calls plot_visibility_tracks_toaxis() to do the plotting, then saves/shows.

Parameters:

• target_list (ephem.FixedBody(), or array-like [list, tuple, np.array...]) – List of pyephem FixedBody sky sources. Can also input a single target source.

• observer (ephem.Observer()) – Observatory/antenna/location object to use for the calculations

• obsstart (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation start time

• obsend (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation end time

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance.

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• duration_hours (float) – The desired duration of observations, for calculating the optimal start time. If greater than zero, calculate start time and plot a vertical line denoting it.

• plotmeantransit (bool) – Set to True to plot a vertical line denoting the mean of the target transit times

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. Default mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

obsplanning.plot_visibility_tracks_toaxis(target_list, observer, obsstart, obsend, axin, weights=None, mode='nearest', duration_hours=0, plotmeantransit=False, timezone='auto', xaxisformatter=<matplotlib.dates.DateFormatter object>)

Plot visibility tracks for the given targets, for a given ephem observer (telescope location) and obstimes. Includes the mean of the transit times from each target. Plots onto a specified existing matplotlib/pyplot axis – useful for creating the plot & allowing further manual editing. The Moon separation and Sun separation at the target transit times are included in the legend entries.

Parameters:

• target_list (ephem.FixedBody(), or array-like [list, tuple, np.array...]) – List of pyephem FixedBody sky sources. Can also input a single target source.

• observer (ephem.Observer()) – Observatory/antenna/location object to use for the calculations

• obsstart (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation start time

• obsend (emphem.Date() or str [formatted as 'YYYY/MM/DD HH:MM:SS.s']) – Observation end time

• axin (matplotlib/pyplot axis object) – The axis on which to plot

• weights (np.array, list, or other array-like) – Optional (float) weights to give to certain stations. (e.g. to prioritize certain baselines) Larger values give higher importance. Passed to calculate_targets_mean_transit_time()

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• duration_hours (float) – The desired duration of observations, for calculating the optimal start time. If greater than zero, calculate start time and plot a vertical line denoting it.

• plotmeantransit (bool) – Set to True to plot a vertical line denoting the mean of the target transit times

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. Default mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

Example

fig1=plt.figure(1,figsize=(14,8))

ax1=fig1.add_subplot(111)

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

mrk348=obs.create_ephem_target(‘Mrk348’,’00:48:47.14’,’+31:57:25.1’)

obs.plot_visibility_tracks_toaxis([ngc1052,mrk348],vlbaBR, ephem.Date(‘2021/04/15 00:00:00’),ephem.Date(‘2021/04/15 23:59:59’), ax1, timezone=’US/Pacific’)

plt.savefig(‘ngc1052_fullVLBA_april15.jpg’); plt.clf(); plt.close(‘all’)

obsplanning.plot_year_RST(target, observer, obsyear, timezone='auto', time_of_obs='night', local=True, showsun=True, showmoon=False, figsize=(14, 8), dpi=200, savepath='', showplot=False, xaxisformatter=<matplotlib.dates.DateFormatter object>, yaxisformatter=<matplotlib.dates.DateFormatter object>)

For a specified target source and observer site, plot the time of day the target rises, sets, and transits over the year.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obsyear (int, float, str, ephem.Date, or datetime.datetime) – The year to consider for the calculations. Use 4-digit format ‘YYYY’ if given as a string.

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• time_of_obs (str ['noon', 'night', 'midnight', 'peak' or 'HH:MM:SS']) –

  Denotes how to generate the times to use for each day. Options:

  ’noon’ = calculate the values at 12:00 local time each day

  ’night’ or ‘midnight’ = use 23:59:59 local time each day (for night obs. 00:00:00 would be for the previous night.)

  ’peak’ = return values during daily peak altitude

• local (bool) – True returns times in the local observer site time. False returns in UTC time.

• showsun (bool) – Set to True to include a track on the plot for the Sun

• showmoon (bool) – Set to True to include a track on the plot for the Moon

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. Default mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

• yaxisformatter (mdates.DateFormatter) – Formatter object for the yaxis times. Default mdates.DateFormatter(‘%H:%M’) will print the hour and minute.

Example

wht = ephem.create_ephem_observer(‘WHT’, ‘-17 52 53.8’, ‘28 45 37.7’, 2344);

crab = obs.create_ephem_target(‘Crab Nebula’,’05:34:31.94’,’22:00:52.2’) #’M1’

obs.plot_year_RST(crab, wht, ‘2021’, showplot=True)

obsplanning.plot_year_darktime(target, observer, obsyear, timezone='auto', time_of_obs='night', local=True, showmoon=True, figsize=(14, 8), dpi=200, savepath='', showplot=False, xaxisformatter=<matplotlib.dates.DateFormatter object>, yaxisformatter=<matplotlib.dates.DateFormatter object>)

Plot the dark time over the course of a year, from a specified observing site, and plot the target altitude track.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obsyear (int, float, str, ephem.Date, or datetime.datetime) – The year to consider for the calculations. Use 4-digit format ‘YYYY’ if given as a string.

• timezone (str or None) –

  Timezone (standard Olson names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• time_of_obs (str ['noon', 'night', 'midnight', 'peak' or 'HH:MM:SS']) –

  Denotes how to generate the times to use for each day. Options:

  ’noon’ = calculate the values at 12:00 local time each day

  ’night’ or ‘midnight’ = use 23:59:59 local time each day (for night obs. 00:00:00 would be for the previous night.)

  ’peak’ = return values during daily peak altitude

• local (bool) – True returns times in the local observer site time. False returns in UTC time.

• showmoon (bool) – Set to True to include a track on the plot for the Moon

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. Default mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

• yaxisformatter (mdates.DateFormatter) – Formatter object for the yaxis times. Default mdates.DateFormatter(‘%H:%M’) will print the hour and minute.

Example

wht = ephem.Observer(); wht.name=’WHT’

wht.lon=’-17 52 53.8’; wht.lat=’28 45 37.7’; wht.elevation=2344;

crab=obs.create_ephem_target(‘Crab Nebula’,’05:34:31.94’,’22:00:52.2’) #’M1’

obs.plot_year_darktime(crab, wht, ‘2021’, showplot=True)

obsplanning.plot_year_observability(target, observer, obsyear, timezone='auto', time_of_obs='midnight', local=True, figsize=(14, 8), dpi=200, savepath='', showplot=False, xaxisformatter=<matplotlib.dates.DateFormatter object>)

Plot the daily peak visibility (altitude) track for a target source over the course of a year, from a given observer site. Similar to a classic ‘starobs’ plot.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obsyear (int, float, str, ephem.Date, or datetime.datetime) – The year to consider for the calculations. Use 4-digit format ‘YYYY’ if given as a string.

• timezone (str or None) –

  Timezone (standard Olson database names) for local time on upper x-axis. Options:

  ’none’ or None : Do not add local time info to the upper axis string of a standard Olson database name [e.g., ‘US/Mountain’ or ‘America/Chicago’] : use this directly for dt calculations

  ’auto’ or ‘calculate’ : compute the timezone from the observer lat/lon using module timezonefinder.

• time_of_obs (str ['noon', 'night', 'midnight', 'peak' or 'HH:MM:SS']) –

  Denotes how to generate the times to use for each day. Options:

  ’middark’ = calculate the altitudes at each night’s middle-dark time

  ’noon’ = calculate the values at 12:00 local time each day

  ’night’ or ‘midnight’ = use 23:59:59 local time each day (for night obs. 00:00:00 would be for the previous night.)

  ’peak’ = return values during daily peak altitude

• local (bool) – True returns times in the local observer site time. False returns in UTC time.

• figsize (tuple) – matplotlib Figure size

• dpi (int) – matplotlib image resolution (dpi = dots per inch)

• savepath (str) – The path for saving the figure, including the filename and extension.

• showplot (bool) – Set to True to invoke plt.show() and display the interactive plot

• xaxisformatter (mdates.DateFormatter) – Formatter object for the xaxis dates. mdates.DateFormatter(‘%b’) will print abbreviated month names, ‘%B’ will print full month names.

Example

crab=obs.create_ephem_target(‘Crab Nebula’,’05:34:31.94’,’22:00:52.2’) #’M1’

obs.plot_year_observability(crab, obs.vlbaMK, ‘2021’, showplot=True)

obsplanning.print_VLBA_observability_between_dates(obstarget, duration_hrs, ephemdatestart, ephemdateend, obstypestring='[]-Band', outtimefmt='%Y/%m/%d %H:%M:%S', mode='nearest', every_N_days=1)

Prints out optimal VLBA observing start time (in UT and PT_LST) for each day between two given dates.

Parameters:

• ephem.FixedBody() (obstarget =) – The sky target of interest. Initialize, e.g., as a create_ephem_target() object

• duration_hrs (float) – Duration of total observation session in hours

• ephemdatestart (ephem.Date()) – The starting date/time to print results for

• ephemdateend (ephem.Date()) – The end date/time to print results for

• obstypestring (str) – Label denoting observation type, for printout. (e.g., ‘K-band’)

• outtimefmt (str) – The dt.datetime.strftime format to use for the output times

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• every_N_days (int) – Print out the observability details every N days

Example

ngc2992=obs.create_ephem_target(‘NGC2992’,’09:45:42.05’,’-14:19:34.98’)

obs.print_VLBA_observability_between_dates(ngc2992, 7.5, ephem.Date(‘2021/08/01 00:00:00’), ephem.Date(‘2021/08/31 23:59:59’), obstypestring=’K-Band’, every_N_days=1) # –>

# Aug 01 – 2021/08/01 16:19:42 UTC, 2021/08/01 05:49:11 LST

# Aug 02 – 2021/08/02 16:15:46 UTC, 2021/08/02 05:49:11 LST

# …

obsplanning.print_VLBA_observability_summary(target, tstart, tend, every_N_days, t_middle, obs_dur_hrs, obs_freq_GHz, outtimefmt='%Y/%m/%d %H:%M:%S', weights=None, mode='after', elevation_limit_deg=10.0, LST_PT=True, plotresults=False)

Prints out optimal VLBA observing start times for multiple days in the specified scheduling window, displaying lines for every N days.

Parameters:

• ephem.FixedBody() (target =) – The sky target of interest. Initialize, e.g., as a create_ephem_target() object

• tstart (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The start date/time for determining the Sun separations

• tend (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The latest date/time for determining the Sun separations

• every_N_days (int) – The interval in days to use for determining and printing the Sun separations.

• t_middle – The date/time somewhere in the middle of the range, to use for estimating the dynamic schedule start times (with calculate_VLBA_dynamic_starttime_range)

• obs_dur_hrs (float) – Duration of total observation session in hours

• obs_freq_GHz (float) – The frequency of the observations, in GHz

• outtimefmt (str) – The dt.datetime.strftime format to use for the output times

• weights (array-like) – Array of the numerical weights to apply to each VLBA station

• mode (str) –

  Specifies which transit time to return. Options are

  ’previous’/’before’ = calculate the last transit before the input time

  ’next’/’after’ = calculate the next transit after the input time

  ’nearest’ = calculate the nearest transit to the input time

• elevation_limit_deg (float [degrees]) – The elevation limit at the observatory to use for rise/set calculations, in degrees

• LST_PT (bool) – True returns the time in PieTown LST (e.g., used for VLBA dynamic scheduling)

• plotresults (bool) – Set to True to plot MK/SC elevations and starttimes. [NOT YET IMPLEMENTED]

Example

ngc2992=obs.create_ephem_target(‘NGC2992’,’09:45:42.05’,’-14:19:34.98’)

# For 4 hour duration obs at 22GHz, print every 10 days for August 2021

obs.print_VLBA_observability_summary(ngc2992, ephem.Date(‘2021/08/01 00:00:00’),

ephem.Date(‘2021/08/31 23:59:59’), 10, ephem.Date(‘2021/08/15 00:00:00’),

4.00, 22.0)

# –>

#Optimal VLBA observation start times between 2021 August 01 and 2021 August 31,

#for 4.00 hr duration K-band obs. of NGC2992:

#—————————————————————–

# Aug 01 – 2021/08/01 18:04:42 UTC, 2021/08/01 07:34:28 LST

# Aug 11 – 2021/08/11 17:25:23 UTC, 2021/08/11 07:34:29 LST

# Aug 21 – 2021/08/21 16:46:04 UTC, 2021/08/21 07:34:29 LST

# Aug 31 – 2021/08/31 16:06:45 UTC, 2021/08/31 07:34:29 LST

#

#Estimated dynamical scheduling start times in PT_LST for 2021/8/15 :

#[‘2021/08/15 07:34:29’, ‘2021/08/15 07:34:29’]

obsplanning.pytz_timezones_from_utc_offset(tz_offset, common_only=True)

Determine timezone strings corresponding to the given timezone (UTC) offset

Parameters:

• tz_offset (int, or float) – Hours of offset from UTC

• common_only (bool) – Whether to only return common zone names (True) or all zone names (False)

Returns:

results – List of Olson database timezone name strings

Return type:

list

Examples

obs.pytz_timezones_from_utc_offset(-7) obs.pytz_timezones_from_utc_offset(-7.62, common_only=False)

obsplanning.query_object_coords(stringname, service='astropy', return_fmt='dec', results_ind=0, **kwargs)

Query online service for coordinates of a named target.

Note

Internet connection required to complete the query.

Parameters:

• stringname (str) – The common name of the desired query target. e.g., ‘NGC1275’. To query the coordinates

• service (str) – The service to query. Current options are ‘astropy’, or ‘simbad’

• return_fmt (str) – The desired format of the returned coordinates. ‘dec’/’decimal’,’sex’/’sexagesimal’, or ‘SkyCoord’/’astropy’.

• results_ind (int) – The index of the queried results to return, when there are multiple results. Default is 0 (the first result)

• kwargs – Optional keyword arguments to pass to the query service. e.g., for ‘simbad’: wildcard(bool), verbose(bool) for astropy: frame(str), parse(bool), cache(bool)

Returns:

targetcoords – List of the [RA,DEC] of the queried target, or SkyCoord object

Return type:

list, or astroopy.coordinates.SkyCoord

Example

obs.query_object_coords(‘M1’, service=’astropy’, return_fmt=’dec’)

# –> –> [83.63308333333333, 22.0145]

obs.query_object_coords_simbad(‘NGC1275’,return_fmt=’sex’)

# –> [‘03 19 48.1597’, ‘+41 30 42.114’] # ## Example using keyword args from astroquery Simbad docs, and returning the # resulting table entry index 2 (the third entry): obs.query_object_coords_simbad(“m [1-9]”, wildcard=True, verbose=True, results_ind=2)

obsplanning.query_object_coords_simbad(stringname, return_fmt='dec', results_ind=0, **kwargs)

Query Simbad for coordinates of a named target.

Note

Internet connection required to complete the query.

Parameters:

• stringname (str) –

  The common name of the desired query target. e.g., ‘NGC1275’.

  To query the coordinates

• return_fmt (str) –

  The desired format of the returned coordinates.

  ’dec’/’decimal’,’sex’/’sexagesimal’, or ‘ap’/’astropy’.

• results_ind (int) –

  The index of the queried results to return, when there are multiple results.

  Default is 0 (the first result)

• kwargs –

  Optional keyword arguments to pass to astroquery.Simbad. Currently, the valid ones are

  wildcard = bool, default False. When True it means the object stringname has wildacards.

  For example, “m [1-9]” returns M1 through M9.

  verbose = bool, default False. True prints query results to terminal.

Returns:

targetcoords – List of the [RA,DEC] of the queried target

Return type:

list

Example

obs.query_object_coords_simbad(‘M1’, return_fmt=’dec’)

# –> –> [83.63308333333333, 22.0145]

obs.query_object_coords_simbad(‘NGC1275’,return_fmt=’sex’)

# –> [‘03 19 48.1597’, ‘+41 30 42.114’] # ## Example using keyword args from astroquery Simbad docs, and returning the # resulting table entry index 2 (the third entry): obs.query_object_coords_simbad(“m [1-9]”, wildcard=True, verbose=True, results_ind=2)

obsplanning.sex2dec(longin, latin, RAhours=True, order='radec')

Convert from sexagesimal coordinate pairs to decimal format.

Parameters:

• longin (string, or array_like (list, tuple, numpy.array)) – Longitude coordinate in sexagesimal format (e.g., Long on Earth or Right Ascension on sky)

• latin (string, or array_like (list, tuple, numpy.array)) – Latitude coordinate in sexagesimal format (e.g., Lat on Earth or Declination on sky )

• RAhours (bool) –

  True (default) = the longitude coordinate will be RA hours (to be multiplied by 360/24=15)

  False = the longitude coordinate will NOT be in RA hours

• order (str) –

  The order of the coordinates: longitude then latitude or vice versa.

  Options: ‘lonlat’,’latlon’,’radec’,’decra’

  For example, sex2dec(lonstring,latstring) – returns [loncoord,latcoord]

  or sex2dec(latstring,lonstring, order=’latlon’) – returns [latcoord,loncoord]

Returns:

[latout,longout] – The decimal versions of the input coorinates.

Return type:

list

Examples

obs.sex2dec(‘23:59:59.9999’,’-30:15:15.0’) #–> [359.9999995833333, -30.254166666666666]

obs.sex2dec(‘23h59m59.9999s’,’-30d15m15.0s’) #–> [359.9999995833333, -30.254166666666666]

obs.sex2dec([23,59,59.9999],[-30,15,15.0]) #–> [359.9999995833333, -30.254166666666666]

obsplanning.skysep_fixed_single(source1, source2, returncomponents=False, componentframe='equatorial')

Calculate the angular separation on the sky (in degrees), for fixed pyephem objects source1 and source2. To calculate the angular distance between a source and the Sun or moon, use sunsep_single() or moonsep_single() functions instead.

To input simple coordinate values instead of pyephem objects, use function angulardistance([lon1,lat1],[lon2,lat2]) instead.

Parameters:

• source1 (ephem.FixedBody()) –

• source2 (ephem.FixedBody()) –

• returncomponents (bool) –

  Optinally also returns the component separations, to go from source1 to source2. Valid options are

  1.)False or True (True defaults to option 2 below)

  2.) ‘cartesian’ or ‘RAcosDEC’

  3.) ‘spherical’ or ‘orthogonal’

  When set to False, only the total separation is returned. The other options will additionally return the component angular separations specified. ‘cartesian’ or ‘RAcosDEC’ will return the angular separations strictly following the longitude and latitude lines. i.e., the longitude component will be along constant lat lines, but will be modified by the cosine(DEC) term. ‘spherical’ or ‘orthogonal’ will return the orthogonal components in spherical coordinates (i.e. when viewed from directly above) – angles along great circles in EACH direction. The longitude/RA component here will not follow lines of constant DEC!

• componentframe (str, one of ['equatorial','galactic','ecliptic']) – If returncomponents is set to True, this determines the components to return – [RA,DEC] for ‘equatorial’, [longitude,latitude] otherwise

Returns:

• angsep (float) – The angular separation between the sources, in degrees

• Optional, if returncomponents=True – longitude and latitude components (float), in degrees

Example

ngc1052=obs.create_ephem_target(‘NGC1052’,’02:41:04.7985’,’-08:15:20.751’)

ngc3079=obs.create_ephem_target(‘NGC3079’,’10:01:57.80’,’55:40:47.24’)

obs.skysep_fixed_single(ngc1052,ngc3079) #–> 108.13770035565858 [degrees]

## Some examples for sources falling along a line of constant DEC

src1 = obs.create_ephem_target(‘src1’,’01:00:00.0’,’-60:00:00.0’) #[15.0,-60.0] in decimal

src2 = obs.create_ephem_target(‘src2’,’23:00:00.0’,’-60:00:00.0’) #[345.0,-60.0] in decimal

obs.skysep_fixed_single(src1,src2, returncomponents=’RAcosDEC’) #or ‘cartesian’ gives same

#–> (14.871642464356663, -14.999999999999986, 0.0)

## Now return components in Ecliptic [lon,lat] angles – noting slight difference in

# returned longitude values between ‘spherical’ and ‘cartesian’

obs.skysep_fixed_single(src1,src2, returncomponents=’spherical’, componentframe=’equatorial’)

#–> (14.871642464356663, -14.870944452263702, 0.0)

obs.skysep_fixed_single(src1,src2, returncomponents=’cartesian’, componentframe=’equatorial’)

#–> (14.871642464356663, -14.999999999999986, 0.0)

## Now return components in Galactic [l,b] angles

src1 = obs.create_ephem_target(‘src1’,’01:00:00.0’,’-30:00:00.0’) #[15.0,-30.0] in decimal

src2 = obs.create_ephem_target(‘src2’,’23:00:00.0’,’-30:00:00.0’) #[345.0,-30.0] in decimal

obs.skysep_fixed_single(src1,src2, returncomponents=’cartesian’, componentframe=’galactic’)

#–> (25.90621437229111, 45.489777798143976, 21.14372563906864)

# The components might ‘seem’ too high, but look at the Galactic coordinates of src1, src2:

# [270.22743381 -86.56783073], [ 19.60461978 -65.4241051 ]

obsplanning.sources_within_radius(src_list, ref_pos, sep_deg, direction='inside', return_format='sources')

Determine which ephem target sources fall within (or, alternatively, outside of) a separation radius from specified reference target/position. Essentially a simple cone search.

Parameters:

• src_list (array-like of ephem target sources) – Table of sources with columns for RA and DEC being in decimal degrees format

• ref_pos (ephem target source, array-like of floats, or astropy.coordinates.SkyCoord) – Reference position for obs.angulardistance calculation, either [RA,DEC] values in decimal degrees, an ephem target source, or a SkyCoord object.

• sep_deg (float) – The separation radius to use, in degrees

• direction (str) – ‘inside’/’outside’. Return sources inside/outside of this separation radius.

• return_format (str) – Determines what to return. ‘mask’ for the boolean array mask, ‘inds’ for the indices, or ‘sources’ for the source table slice

Returns:

output – Sliced table, indices, or mask for sources that fall within the specified separation radius.

Return type:

pandas/astropy table slice, or array-like

Examples

virgo_targets = [ obs.create_ephem_target(n,*obs.query_object_coords_simbad(n))

for n in [‘m87’, ‘m85’, ‘m60’, ‘m49’, ‘m90’, ‘m98’] ]

# Which of these sources are within 3 degrees of the Virgo cluster center?

obs.sources_within_radius(virgo_targets, [‘12:27:00’,’12:43:00’], 3.0,

direction=’inside’, return_format=’names’)

#–> [‘m87’, ‘m90’]

# Which of these Virgo sources are further than 4 degrees from M87?

obs.sources_within_radius(virgo_targets[1:], virgo_targets[0], 4.0,

direction=’outside’, return_format=’names’)

#–> [‘m85’, ‘m49’, ‘m98’]

obsplanning.srctable_within_radius(src_table, ref_coords, sep_deg, RAlabel='RA', DEClabel='DEC', direction='inside', return_format='sources')

For a pandas or astropy table of sources with columns for RA,DEC coordinates decimal degrees, determine which sources fall within (or, alternatively, outside of) a separation radius from specified reference coordinates. Essentially a simple cone search. The sources are first filtered by a crude RA/DEC cut to speed things up considerably.

Parameters:

• src_table (pandas or astropy table) – Table of sources with columns for RA and DEC being in decimal degrees format

• ref_coords (array-like of floats, or astropy.coordinates.SkyCoord) – Reference coordinates for obs.angulardistance calculation, either [RA,DEC] values in decimal degrees or a SkyCoord object.

• sep_deg (float) – The separation radius to use, in degrees

• RAlabel (str) – The source table column name for RA, which has values in decimal degrees

• DEClabel (str) – The source table column name for DEC, which has values in decimal degrees

• direction (str) – ‘inside’/’outside’. Return sources inside/outside of this separation radius.

• return_format (str) – Determines what to return. ‘mask’ for the boolean array mask, ‘inds’ for the indices, or ‘sources’ for the source table slice

Returns:

output – Sliced table, indices, or mask for sources that fall within the specified separation radius.

Return type:

pandas/astropy table slice, or array-like

obsplanning.sunsep_VLBAminmax(target, obstime, verbose=False, return_names=False)

Convenience function to call sunsep_arrayminmax() for the VLBA stations.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• obstime (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The time at which the separation should be determined

• verbose (bool) – True prints results to terminal

• return_names (bool) – Setting to True will also return the station names where the min/max occur

Returns:

minmaxlist – The min/max target separation from the Sun, in degrees

Return type:

list [minsep,maxsep]

obsplanning.sunsep_VLBAminmax_timearray(target, obstime_array, verbose=False, return_names=False)

Calculate the min & max Sun separation for the VLBA stations, across an array of obstimes.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• obstime_array (array-like [list,np.array...]) – A series of date+times, in ephem.Date, dt.datetime, or string (‘YYYY/MM/DD HH:MM:SS.s’)

• verbose (bool) – True prints results to terminal

• return_names (bool) – Setting to True will also return the station names where the min/max occur

Returns:

minmaxlist – The min/max target separation from the Sun from among the specified times, in degrees

Return type:

list [minsep,maxsep]

obsplanning.sunsep_allVLBA(target, obstime, verbose=False, return_names=False)

Calculates the angular separation from the sun for a given target and obsdate, for all VLBA stations.

Parameters:

• target (ephem.FixedBody()) – The target observation source

• obstime (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The time at which the separation should be determined

• verbose (bool) – True prints results to terminal

• return_names (bool) – Setting to True will also return the station names where the min/max occur

Returns:

sunseps – List of the Sun separations (in degrees) as observed from all VLBA stations

Return type:

list

obsplanning.sunsep_arrayminmax(target, observer_list, obstime, verbose=False, return_names=False)

Calculate the angular separation of the Sun from the target, observed from a specified obsdate, and each supplied telescope/station to get the minimum/maximum separation

Parameters:

• target (ephem.FixedBody()) – The target observation source

• observer_list (array-like [list, np.array, ...]) – The list of ephem.Observer() antenna location objects to use for the calculations

• obstime (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The time at which the separation should be determined

• verbose (bool) – True prints results to terminal

• return_names (bool) – Setting to True will also return the station names where the min/max occur

Returns:

minmaxlist – The min/max target separation from the Sun, in degrees

Return type:

list [minsep,maxsep]

obsplanning.sunsep_single(target, observer, obstime)

Calculate the angular separation of the Sun from the target, observed from a specified telescope/station and obsdate+time

Parameters:

• target (ephem.FixedBody()) – Target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obstime (ephem.Date, datetime.datetime, str formatted as 'YYYY/MM/DD HH:MM:SS.s') – The time at which the separation should be determined

Returns:

sunsep – The angular separation between the Sun and the source, in degrees

Return type:

float

obsplanning.sunsep_timearray(target, observer, obstime_array)

Calculate the angular sky separation of the Sun from the target, observed from a specified telescope/station at each obstime. Useful, for example, for determining Sun separation at each point in an observing session.

Parameters:

• target (ephem.FixedBody()) – Target observation source

• observer (ephem.Observer()) – Observatory/antenna location object to use for the calculations

• obstime_array (array-like [list,np.array...]) – A series of date+times, in ephem.Date, dt.datetime, or string (‘YYYY/MM/DD HH:MM:SS.s’)

Returns:

sunseps – The target separations from the Sun, in degrees, at each time in the series

Return type:

np.array

obsplanning.theoretical_VLBA_image_integration_time(freq_GHz, BW_total_GHz, Sensitivity_uJybm, eta=0.8, Nstations=10, pol='dual', return_fmt='hours')

Calculate the the theoretical integration time to achieve a certain sensitivity level with the VLBA. Calls theoretical_vlbi_integration_time_homogeneous() using values relevant to the VLBA.

Parameters:

• freq_GHz (float) – The nominal frequency of the observations, in GHz. SEFD estimated from this value.

• BW_total_GHz (float) – The total bandwidth of the receiver setup, in GHz, for a single polarization. Default is 0.512 (= 512 MHz per polarization)

• Sensitivity_uJybm (float) – Desired image sensitivity level, in microJy/beam

• eta (float) – The system (in)efficiency value, eta_s. NRAO uses 0.8, the EVN calculator uses 0.7.

• Nstations (int) – Number of stations to use for the calculation. [default = 10, for the full array]

• pol (str) – Polarization descriptor. [‘single’,’r’,’l’,’x’,’y’,’1’] for single polarization, [‘dual’,’full’,’rl’,’lr’,’xy’,’yx’,’2’] for dual polarization.

• return_fmt (str ['sec', 'min', or 'hours']) – Format for the returned integration time

Example

#Goal = 25uJy/bm at 5.0 GHz in dual polarization, 512MHz BW per pol., eta=0.8, full array

obs.theoretical_VLBA_image_integration_time(5.0, 0.512, 25.0, eta=0.8, Nstations=10, pol=’dual’, return_fmt=’hours’)

# –> 0.3323025173611111 [hours]

obsplanning.theoretical_VLBA_image_sensitivity(freq_GHz, BW_total_GHz, t_int_hr, eta=0.8, Nstations=10, pol='dual')

Calculate the theoretical image sensitivity for VLBA observations of duration t_int_hr hours. Calls vlbi_image_sensitivity_homogeneous() using values relevant to VLBA.

Parameters:

• freq_GHz (float) – The nominal frequency of the observations, in GHz. SEFD estimated from this value.

• BW_total_GHz (float) – The total bandwidth of the receiver setup, in GHz, for a single polarization. Default is 0.512 (= 512 MHz per polarization)

• t_int_hr (float) – Integration time, in hours

• eta (float) – The system (in)efficiency value, eta_s. NRAO uses 0.8, the EVN calculator uses 0.7.

• Nstations (int) – Number of stations to use for the calculation. [default = 10, for the full array]

• pol (str) – Polarization descriptor. [‘single’,’r’,’l’,’x’,’y’,’1’] for single polarization, [‘dual’,’full’,’rl’,’lr’,’xy’,’yx’,’2’] for dual polarization.

Returns:

Sensitivity_Jybm – Image sensitivity, in Jy/beam

Return type:

float

Example

# 5.0 GHz obs in dual polarization, 512MHz BW per pol., 1 hr obs, eta=0.8, full array

obs.theoretical_VLBA_image_sensitivity(5.0,0.512,1.0,eta=0.8,Nstations=10,pol=’dual’)

# –> 1.4411421628371519e-05 or 14.41 microJy/beam

obsplanning.theoretical_vlbi_integration_time_homogeneous(Sensitivity_Jybm, SEFD_Jy, eta, Nstations, BW_total_Hz, pol='dual')

Calculates the integration time required to achieve a given image sensitivity, for homogeneous antennae. Essentially inverting the equation in vlbi_image_sensitivity_homogeneous():

t_int_sec = (SEFD_Jy/(sqrt(#polarizations)*Sensitivity_Jybm*eta))^2 * 1./(N*(N-1)*BW_total_Hz)

Parameters:

• Sensitivity_Jybm (float) – Image sensitivity, in Jy/beam

• SEFD_Jy (float) – System equivalent flux density, in units of Jansky

• eta (float) – System inefficiency, in range [0,1]

• Nstations (int) – Number of homogeneous observing stations in the array

• BW_total_Hz (float) – Bandwidth in Hz in a single polarization

• pol (str) – Polarization descriptor. [‘single’,’r’,’l’,’x’,’y’,’1’] for single polarization, [‘dual’,’full’,’rl’,’lr’,’xy’,’yx’,’2’] for dual polarization.

Returns:

t_int_sec – The total integration time on source in seconds

Return type:

float

Example

#To achieve 25 uJy/bm for VLBA obs at 5.0GHz (C-band,SEFD=210Jy), dual pol, 512MHz/pol, for eta=0.8:

#t_int = (210/(np.sqrt(2)*25e-6*0.8))**2 / (10*(10-1)*512e6) = 1196sec, or 0.33 hrs or 20 min

obs.theoretical_vlbi_integration_time_homogeneous(25e-6,210,0.8,10,512e6,pol=’dual’) #–> 1196.29

obsplanning.tz_from_observer(observer)

Determine the local timezone from a pyephem Observer object - if the timezone attribute is already set (not None), use that. If it’s set to None, calculate the local timezone with autocalculate_observer_timezone().

Parameters:

observer (ephem.Observer) – The pyephem Observer object which includes the site latitude & longitude

Returns:

timezone – The name of the local timezone (from the Olson database)

Return type:

str

obsplanning.utc_to_local(utc_dt, local_timezone, verbose=True)

Convert a datetime object in UTC (or other timezone) to a dt in a specified timezone

Parameters:

• utc_dt (datetime.datetime) – dt.datetime object (naive or aware)

• local_timezone (pytz.timezone, or str) – pytz.timezone object, or string of a standard Olson database timezone name (e.g. ‘US/Eastern’)

• verbose (bool) – True = print warning in case supplied dt_utc is NaN

Returns:

datetime_local – Timezone-aware dt object in a localized timezone

Return type:

datetime.datetime

Example

obs.utc_to_local(dt.datetime.utcnow(),’US/Eastern’)

obsplanning.vincenty_sphere(lon1, lat1, lon2, lat2, units='rad', input_precision=<class 'numpy.float64'>)

Full great-circle angle separation between two positions, from Vincenty ellipsoid equation. This formulation (special case of equal major and minor axes = perfect sphere) is valid for all angles and positions including antipodes, and doesn’t suffer from rounding errors at small angles and antipodes that the standard Vincenty ellipsoid and haversine formulae do. See https://en.wikipedia.org/wiki/Great-circle_distance For the particular case of equal major & minor axes (perfect sphere), a form that is accurate for all angles and positions, including antipodes, is angle =

( SQRT( (cos(DEC2)sin(RA1-RA2))^2 + (cos(DEC1)sin(DEC2)-sin(DEC1)cos(DEC2)cos(RA1-RA2))^2 ) )

arctan( —————————————————————————————— )

( sin(DEC1)sin(DEC2)+cos(DEC1)cos(DEC2)cos(RA1-RA2) )

Parameters:

• lon1 (float) – The longitude (e.g. RA, l) component of the first coordiante position

• lat1 (float) – The latitude (e.g. DEC, b) component of the first coordiante position

• lon2 (float) – The longitude (e.g. RA, l) component of the second coordiante position

• lat2 (float) – The latitude (e.g. DEC, b) component of the second coordiante position

• units (str) – ‘rad’ if the input values are supplied as radians, ‘deg’ if they are in degrees

• input_precision (numpy precision dtype) – The precision to use for the calculation. Lower precision will consume less memory, but obviously at the expense of precision and potential for rounding errors. For VERY small angles, if you are getting results smaller than your desired precision, try increasing to np.float128.

Returns:

totalseparation – Angular separation. Output units will match input units.

Return type:

float

Example

obs.vincenty_sphere(0.,0., np.pi,0.) #–> 3.141592653589793

obs.vincenty_sphere(0.,0., 180,-45., units=’deg’) # –> 135.0

obs.vincenty_sphere(0.,0., 1e-16,-1e-5, units=’deg’) # –> 1e-05

obs.vincenty_sphere(0.,0., 1e-16,-1e-5, units=’deg’, input_precision=np.float128)

# –> 1.0000000000000000847e-05

obsplanning.vlbi_image_sensitivity_homogeneous(SEFD_Jy, eta, Nstations, BW_total_Hz, t_int_sec, pol='dual')

Calculate radio image sensitivity for arrays with homogeneous antennae, following:

https://science.nrao.edu/facilities/vlba/docs/manuals/oss/imag-sens

Parameters:

• SEFD_Jy (float) – System equivalent flux density, in units of Jansky

• eta (float) – System inefficiency, in range [0,1]

• Nstations (int) – Number of homogeneous observing stations in the array

• BW_total_Hz (float) – Bandwidth in Hz in a single polarization

• t_int_sec (float) – Total integration time, in seconds

• pol (str) – Polarization descriptor. [‘single’,’r’,’l’,’x’,’y’,’1’] for single polarization, [‘dual’,’full’,’rl’,’lr’,’xy’,’yx’,’2’] for dual polarization.

Returns:

Sensitivity_total – The estimated image sensitivity, in Jy/beam

Return type:

float

Notes

For a single polarization:

Sensitivity (Jy/beam) = SEFD / [ eta*(N*(N−1)*BW*t_int)^1/2 ]

SEFD or “system equivalent flux density” is the system noise expressed in Janskys.

Values: https://science.nrao.edu/facilities/vlba/docs/manuals/oss/bands-perf#Table%205.1

eta <= 1 accounts for the VLBI system inefficiency (primarily quantization in the data recording).

Walker (1995) and Kogan (1995b) provide the combination of scaling factors and inefficiencies appropriate for VLBA visibility data. The sensitivity values presented in table 5.1 were calculated using eta=0.8, while the EVN Sensitivity Calculator uses eta=0.7.

The bandwidth in Hz is BW (for a single polarization).

For a continuum target, use the channel bandwidth or the full recorded bandwidth, depending on the fringe-fitting mode; for a line target, use the channel bandwidth divided by the number of spectral points that span the channel.

N is the number of observing stations

t_int is the total integration time on source in seconds.

For simultaneous dual polarization, the image sensitivity for Stokes I, Q, U, or V is:

Sensitivity_total = Sensitivity_singlePol/sqrt(2)

Returns:

Sensitivity_total – Estimated image sensitivity, in Jy/beam

Return type:

float

Examples

#VLBA vc_b setting (6cm, SEFD=210 Jy) for 1 hour, dual pol.

#(512MHz each pol), with NRAO eta = 0.8

#Sensitivity = 210. / (0.8*(10*(10-1)*512e6*3600)**.5) / np.sqrt(2)

# = 1.44e-5 = 14.4 uJy/bm

obs.vlbi_image_sensitivity_homogeneous(210.,0.8,10,512e6,60*60,pol=’dual’) # 1.44e-5

obsplanning.wrap_24hr(timein, component=False)

Wraps a time (float) in hours to a 24-hour time. Can be used, e.g., to determine the hour of day after adding/subtracting some number of hours.

Parameters:

• timein (float) – Decimal number of hours

• component (bool) – If True, input timein in H:M:S components will be converted to decimal

Returns:

timeout – The number of hours on a 0–24 hour scale

Return type:

float

Examples

# e.g.: 49.5 hours is 1.5 hours (after 2x24); -2 corresponds to 22.0

obs.wrap_24hr(49.5) #–> 1.5

obs.wrap_24hr(-2) #–> 22.0

obs.wrap_24hr(some_amount_of_seconds/3600.)

obs.wrap_24hr(LMST_reference_hour+offset_hours)

obs.wrap_24hr(‘49:30:00’,component=True) #–> 1.5

obsplanning.wrap_360(valin)

Wraps a value (float) to a 0–360 degree range.

Parameters:

valin (float) – Input value in degrees

Returns:

valout

Return type:

float

Example

# e.g., 370 degrees is equivalent to 10 degrees.

obs.wrap_360(370) #–> 10.

Note

Essentially equivalent to calculating as (valin % 360) .

obsplanning.wrap_center_pmrange(valin, center_val, pm_range)

Wraps values (scalar/floats or array-likes) to a specified range surrounding a specified center value. [(value + centershift)%(newrange)] Useful specifying like this for, e.g., all-sky rotations. [Taken from skyplothelper ]

Parameters:

• valin (float, or array-like of floats) – The input values to be wrapped to the new range

• center_val (float) – The new range center value

• pm_range (float) – The half-range amount – the plus and minus from the center_val

Returns:

valout – The values wrapped to the new range

Return type:

float, or array-like of floats

Examples

#A.) 271 mapped to 90 +/- 180 ([-90,270] range) –> -89

obs.wrap_center_pmrange(271, 90, 180) #-89

#B.) Map values [45, 200, 359] to the range [-180,180] or 0 +/- 180

obs.wrap_center_pmrange([45, 200, 359], 0, 180) #np.array([45, -160, -1])

obsplanning.wrap_pm180(valin)

Wraps a value (float) to a -180 to 180 degree range.

Parameters:

valin (float) – Input value in degrees

Returns:

valout

Return type:

float

Example

# e.g., 200 degrees corresponds to -160 degrees when limited to [-180,180]

obs.wrap_pm180(200) #–> -160.0

Note

Similar to (valin % 180.).

obsplanning.wrap_pmPI(valin)

Wraps a value (float) to a -PI to PI radian range.

Parameters:

valin (float) – Input value in radians

Returns:

valout

Return type:

float

Example

obs.wrap_pmPI(-0.5*np.pi) #–> -1.5707963267948966 (-pi/2)

obs.wrap_pmPI(1.5*np.pi) #–> -1.5707963267948966

Note

Similar to (valin % (2*np.pi))