astro

This project provides functions for converting between local IceCube coordinates and astronomical coordinates.

Maintainer: Kevin Meahger

Overview

All reconstructions of IceCube events calculate the direction in terms of IceCube coordinates which is a local coordinate system defined in reference to the geography at the South Pole, usually defined in terms of the zenith and azimuth angles. In order to perform astronomical analyses with IceCube data it is necessary to transform these coordinates into the standard astronomical coordinate systems: equatorial, galactic and supergalactic, which are defined with respect to the stars. Functions for locating the Sun and Moon are also provided. In a typical IceCube analysis, only a few astronomical coordinate transformations are needed to transform from local to equatorial. Astro only provides the coordinate transformations which are commonly used in IceCube analyses. Coordinate systems which are typically unneeded, such as current equatorial and multiple epochs, are intentionally omitted to avoid confusion.

This project provides functions in both C++ and python. In C++, structs for storing equatorial (J2000) and galactic coordinates are provided, and the function all use I3Direction for storing local coordinates. Many python functions are also provided, these will make use of the structs used in C++ as well as numpy array functions which take the coordinates separately. The following diagram gives an overview of the functions provided by this project:

../../_images/I3Astro.svg

Background

Astronomical objects are most commonly located in the celestial sphere by a coordinate system referred to as the equatorial coordinate system. This is the system in which the universe is ‘at rest’, aside from solar system objects, and stars near the solar system, astronomical objects do not move in equatorial coordinates. Equatorial coordinates are defined such that they have the same equator and poles as the Earth. The coordinates in this system are Right Ascension (commonly abbreviated RA or α) and Declination (commonly abbreviated Dec or δ). In addition, a galactic coordinate system is defined in which is centered a the the galaxy lies along the equator and is centered at longitude =0°. This coordinate system uses galactic longitude (abbreviated l) and galactic latitude (abbreviated b) as coordinates. Supergalactic coordinates which were designed to have their equator aligned with the supergalactic plane, a major structure in the local universe formed by the preferential distribution of nearby galaxy clusters, are also occasionally used as well.

A complete discussion of these coordinate systems is beyond the scope of this document. For those interested in an introduction to positional astronomy, a good introduction can be found here.

All reconstructions in icetray are performed in a local coordinate system defined for IceCube. This system is centered at the approximate center of the IceCube detector. The coordinates are aligned with the standard Antarctic grid coordinates with the x-axis pointing toward Grid East, the y-axis pointing toward Grid North, and the z-axis pointing toward the vertical. More information can be found on the wiki for the The IceCube Coordinate System.

Directional information in IceCube is almost always described using spherical coordinate system angles. Zenith angle is defined as angle to the vertical, and azimuth angle is defined as the angle along the xy-plane counter clockwise from the x-axis. so that the ordinal directions are: Grid East(0°) => Grid North(90°) => Grid West(180°) => Grid South(0°). This coordinate system is defined to be different than the local coordinate system typically used by astronomers. Astronomers typically use altitude as the angle above the horizon and azimuth defined as clockwise from North which will give ordinal directions North(0°) => East(90°) => South(180°) => West(270°). For the convenience of IceCubers who are used to the IceCube coordinate system and are likely to be confused by convert to standard astronomical local coordinates, astro does not deal with astronomical local coordinates and converts directly from IceCube coordinates to equatorial coordinates.

Unfortunately, the equatorial coordinate system can be ambiguous, although the direction of the Earth’s poles and equator is stable on the short term. The position of the poles slowly moves due to the torque of the sun and moon on the Earth’s equatorial bulge. To compensate for this RA and dec positions are accompanied by an epoch, since 1984 most astronomical catalogs have used the J2000 epoch, previous epoch were B1900 and B1950 (The J and B stand for Julian and Besselian respectively which are different ways of defining epochs.) Astro uses J2000 exclusively if another epoch becomes common, new function names can be added. Some times observations are given in coordinates of apparent or current epoch, these coordinates should be considered an intermediate calculation and no support is provided for them.

Python Array Interface

The most common way to use astro is in python using the numpy array interface. These function use numpy array broadcasting which can be used with both scalars and numpy arrays.

Forward Transformations

Convert from local coordinates to equatorial, galactic, and supergalactic:

  • icecube.astro.dir_to_equa() - Get the equatorial coordinates (right ascension and declination) of an IceCube event (zenith and azimuth) at a given time (mjd).

  • icecube.astro.equa_to_gal() - Get the Galactic coordinates l and b of an equatorial coordinate (Right Ascension and Declination).

  • icecube.astro.equa_to_supergal() - Get the supergalactic coordinates SGL and SGB from equatorial coordinates ra and dec

  • icecube.astro.gal_to_supergal() - Get the supergalactic coordinates SGL and SGB from galactic coordinates l and b

Note

Since the conversion from local to equatorial coordinates is rather complicated but the conversions between equatorial, galactic, and supergalactic are comparatively complicated, it is necessarily to first convert local to equatorial and then convert the results to galactic or supergalactic.

Sun and Moon

Analyses of the Sun and Moon are typically done in local coordinates, so the functions will return local coordinates for a given time:

  • icecube.astro.sun_dir() - Get the location of the Sun in IceCube local coordinates zenith and azimuth for a given time in mjd

  • icecube.astro.moon_dir() - Get the location of the Moon in IceCube local coordinates zenith and azimuth for a given time in mjd

Convenience Functions

These Functions are provided for convenience

  • icecube.astro.angular_distance() - calculate the angular distance along the great circle on the surface of a sphere between the points (lon1,`lat1`) and (lon2,`lat2`)

  • icecube.astro.tables_to_equa() - Get the equatorial coordinates (right ascension and declination) of IceCube’s Events from tables written by tableio. Works with hdf5 tables written by hdfwriter and read by pytables, h5py, or pandas

  • icecube.astro.fractional_mjd() - This is a convenience function to convert the MJD information provided by the standard tableio booking to a fractional MJD.

Reverse Transformations

Most analyses are performed in one of the celestial coordinate systems, however, it is sometimes necessary to transform back from a celestial coordinate systems back to local coordinate systems.

  • icecube.astro.equa_to_dir() - Get the IceCube zenith and azimuth of an equatorial coordinate (Right Ascension and Declination) at a given time mjd.

    Warning

    This function is significantly slower than dir_to_equa(), it is highly recommended that if you need to perform a significant number of calculations that you go from local to equatorial coordinates and perform the analyses in equatorial coordinates, rather than the reverse.

  • icecube.astro.gal_to_equa() - Get the equatorial coordinates (Right Ascension and Declination) from Galactic coordinates l and b

  • icecube.astro.supergal_to_equa() - Get the galactic coordinates ‘l’ and ‘b’ from supergalactic coordinates ‘SGL’ and ‘SGB’

  • icecube.astro.supergal_to_gal() - Get the equatorial coordinates ra and dec from supergalactic coordinates SGL and SGB

Examples

Simple transformation from zenith and azimuth to ra and dec and compare with the location of the Crab Nebula.

import tables
import numpy as np
from icecube import astro

with tables.openFile('tableio.h5') as f:

  mjd = (f.root.I3EventHeader.cols.time_start_mjd_day[:]+
         f.root.I3EventHeader.cols.time_start_mjd_sec[:]/86400.)
  zenith  = f.root.OnlineL2_BestFit.cols.zenith[:]
  azimuth = f.root.OnlineL2_BestFit.cols.azimuth[:]

  ra,dec = astro.dir_to_equa(zenith,azimuth,mjd)

  print np.degrees(ra)
  print np.degrees(dec)

  #calculate distance to the Crab Nebula
  print astro.angular_distance(ra,dec,
                               np.radians(83.6330
                               np.radians(22.01450)
                               )

These table functions are provided to make using astro with data written by tableio with I3HDFWriter as easy as possible. Tables read with pytables, h5py and pandas work equally well.

# using pytables
f = tables.openFile('foo.hdf5')
ra,dec= tables_to_equa(f.root.Particle,
                       f.root.I3EventHeader)

#using h5py
f= h5py.File('foo.hdf5')
ra,dec = tables_to_equa(f["Particle"],
                        f["I3EventHeader"])

#using pandas
p = pandas.read_hdf('foo.hdf5','Particle')
h = pandas.read_hdf('foo.hdf5','I3EventHeader')
ra,dec = tables_to_equa(p,h)

Python Dataclasses Interface

These function provided an the coordinate transformations through an icetray dataclasses interface which uses classes such as I3Direction to store coordinates.

Container Classes

These are the base classes used to store information and pass to functions:

  • icecube.dataclasses.I3Time - Store time, many different time formats are supported.

  • icecube.dataclasses.I3Direction - Store local coordinates, transformations to cartesian coordinates available.

  • icecube.astro.I3Equatorial - Struct to store Equatorial coordinates in the J2000 Epoch

  • icecube.astro.I3Galactic - Struct to store galactic coordinates

  • icecube.astro.I3SuperGalactic - Struct to store supergalactic coordinates

Forward Transformations

Convert from local coordinates to equatorial, galactic, and supergalactic:

  • icecube.astro.I3GetEquatorialFromDirection() - Convert an IceCube direction to J2000 equatorial coordinates system at a given time

  • icecube.astro.I3GetGalacticFromEquatorial() - Convert from Equatorial (J2000) to Galactic (IAU 1958) coordinate system

  • icecube.astro.I3GetSuperGalacticFromEquatorial() - Convert from Equatorial (J2000) to Supergalactic (de Vaucouleurs) coordinate system

Sun and Moon

  • icecube.astro.I3GetMoonDirection() - Returns the direction of the Moon in local IceCube coordinates at a given time

  • icecube.astro.I3GetSunDirection() - Returns the direction of the Sun in local IceCube coordinates at a given time

Time functions

  • icecube.astro.I3GetGMST() - Returns the Greenwich Mean Sidereal Time

  • icecube.astro.I3GetGMAST() - Returns the Greenwich Mean Anti Sidereal Time

  • icecube.astro.I3GetGMEST() - Returns the Greenwich Mean Extended Sidereal Time

Reverse Transformations

  • icecube.astro.I3GetDirectionFromEquatorial() -Convert an astronomical position in J2000 equatorial coordinates to local IceCube coordinates at a given time

  • icecube.astro.I3GetEquatorialFromGalactic() - Convert from Galactic (IAU 1958) to Equatorial (J2000) coordinate system

  • icecube.astro.I3GetEquatorialFromSuperGalactic() - Convert from Supergalactic (de Vaucouleurs) to Equatorial (J2000) coordinate system

  • icecube.astro.I3GetGalacticFromSuperGalactic() - Convert from Supergalactic (de Vaucouleurs) to Galactic (IAU 1958) coordinate system

  • icecube.astro.I3GetSuperGalacticFromGalactic() - Convert from Galactic (IAU 1958) to Supergalactic (de Vaucouleurs) coordinate system

Constants

  • icecube.astro.ICECUBE_LATITUDE - Latitude (WGS 84) of the origin of the IceCube coordinate system

  • icecube.astro.ICECUBE_LONGITUDE - Longitude (WGS 84) of the origin of the IceCube coordinate system

C++ Interface

I3Astro provides 3 container classes:

Tableio Converters

I3Astro provides 4 tableio converters:

  • I3AstroConverter - Books equatorial coordinates

  • I3GalacticConverter - Books galactic coordinates

  • I3SuperGalacticConverter - Books supergalactic coordinates

  • I3SunAndMoonConverter - Books the location of the Sun and moon for a timestamp provided by I3EventHeader

Example:

tray.Add(tableio.I3TableWriter,
         output="foo.hdf5",
         SubEventStreams=['in_ice'],
         keys = {'Particle': [ dataclasses.converters.I3ParticleConverter(),
                               astro.converters.I3AstroConverter(),
                               astro.converters.I3GalacticConverter(),
                               astro.converters.I3SuperGalacticConverter(),
                               ],
                 'I3EventHeader' : [ dataclasses.converters.I3EventHeaderConverter(),
                                     astro.converters.I3SunAndMoonConverter()]
                }

Accuracy

Positional astronomy calculations can be extremely accurate, standard software such as PAL can achieve milliarcsecond precision when all of the corrections are applied correctly. However for IceCube data, muon/cascade reconstruction error is the dominant source of angular uncertainty, this is typically O(1°) for muon neutrinos and higher for cascades. None of the corrections typically applied by these packages (save nutation) are necessary to achieve the necessary level of accuracy for an IceCube analysis. However, discussion of positional astronomy often lead to arguments about what corrections are appropriate to apply. The following table and discussion is intended to provide context to any future discussions about which corrections are appropriate to apply.

Effect

Magnitude

included in calculation

Remark

proper motion and parallax

source dependent

No

only affects stars close to the solar system

precession

50”/yr

Yes

relative to the year 2000

nutation

< 11”

Yes

annual aberration

< 20.5”

Yes

light deflection

< 1.74”

Yes

only near the sun limb

Sun positional uncertainty

5”

Moon positional uncertainty

30”

diurnal aberration

< 0.3”

Yes

refraction

< 0.5°

No

Cosmic Rays and Neutrinos are not refracted

polar motion

< 0.3”

No

UT1-UTC offset

< 13.5”

No

IceCube Not at Exact South Pole

32”

Yes

IceCube Size

< 16”

No

Glacial flow

0.3”/yr

No

relative to 2011

Nutation, annual aberration, and light deflection are included in the same function as precession so it is easier to include them than to exclude them. (Also if they are included the accuracy of the package can be compared with other high accuracy astronomy software.)

Parallax and proper motion only effect stars within O(10 parsecs) of the solar system. This can be ignored as there are no IceCube analyses which study objects at this distance. To calculate polar motion and UT1-UTC it is necessary to downloading data files from the International Earth Rotation and Reference System Service (IERS) which are updated on a monthly basis. Due to the hassle of downloading and making sure these files are up to date, these correction are omitted.

The quoted Sun and Moon uncertainties are the uncertainties of the algorithm used to predict the position of the moon and sun by PAL.

Astro uses geographic position 89°59’39.84” South, 62°36’29.16” West (-89.9944°N,-62.6081°E) as the location of IceCube observations. This value is taken from the 2011 position of the South Pole in IceCube coordinates system on the wiki. IceCube reconstructions calculate zenith and azimuth angles relative to a position near the center of gravity of the hits, which can be up to 500 m from the center of the detector. No effort is made to correct for this. In addition, the geographic location of IceCube move with the glacial flow of the antarctic ice at a rate 10 m/yr no effort is made to correct for this either.

Dependencies

Astronomical calculation are done using PAL. PAL is a reimplementation of SLALIB which is is an old Fortran library which was translated into c, it is no longer updated, has a weird license, and is hard to find. PAL is a newer library which is available on github and is licensed with LGPL. PAL is intended as a newer version of SLALIB and has an identical interface so it can function as a drop-in replacement. Instructions for downloading it can be found in the cmake tools documentation.

See Also