Conversion

Conversion functions between various physical values or representations.

kete.conversion.bin_data(data, bin_size=2, method='mean')

Bin data, reducing the size of a matrix.

Parameters:

data – 2 dimensional array of data to be reduced.
bin_size – Binning size, binning of data is applied to both directions of the data. If the bin size is not a multiple of the shape of the data, the data is trimmed until it is.
method – Which function is used to produce a single final value from the bins. This includes ‘mean’, ‘median’, ‘min’, ‘max’. NANs are ignored.

kete.conversion.compute_airmass(zenith_angle)

Compute the approximate air-mass above the observer given the zenith angle.

Algorithm from: Andrew T. Young, “Air mass and refraction,” Appl. Opt. 33, 1108-1110 (1994)

Parameters:: zenith_angle (float) – True zenith angle in degrees.
Return type:: float

kete.conversion.compute_albedo(diameter, h_mag, c_hg=1329.0)

Compute the albedo of the object given the diameter in km and H magnitude.

Parameters:

diameter (NDArray) – The diameter of the object in Km.
h_mag (NDArray) – The H magnitude of the object.

Return type:

ndarray

kete.conversion.compute_aphelion(peri_dist, ecc)

Calculate aphelion, returning nan when it cannot be computed.

Parameters:

peri_dist (NDArray) – Perihelion distance in units of AU.
ecc (NDArray) – Eccentricity of the orbit.

Return type:

ndarray

kete.conversion.compute_diameter(albedo, h_mag, c_hg=1329.0)

Compute the diameter of the object in km given the albedo and H magnitude.

Parameters:

albedo (NDArray) – The albedo of the object.
h_mag (NDArray) – The H magnitude of the object.

Return type:

ndarray

kete.conversion.compute_earth_radius(geodetic_latitude)

Compute the effective Earth’s radii at the specified geodetic latitude assuming that the Earth is an oblate spheroid.

Returns the radii in units of AU.

Parameters:: geodetic_latitude (float) – The geodetic latitude in degrees.
Return type:: float

kete.conversion.compute_eccentric_anomaly(eccentricity, mean_anomaly, peri_dist=None)

Solve Kepler’s equation for the eccentric anomaly.

For eccentricity up to and including 1 the result is the eccentric anomaly in degrees, in [0, 360). At eccentricity 1 this is the limit of the elliptical solution. For a hyperbolic orbit the result is the hyperbolic anomaly in degrees. Invalid inputs give NaN.

Parameters:

eccentricity (float or numpy.ndarray) – The eccentricity of the orbit, greater than or equal to 0.
mean_anomaly (float or numpy.ndarray) – The mean anomaly of the orbit in degrees.
peri_dist (float or numpy.ndarray, optional) – Not used by the calculation. It is accepted for compatibility. Defaults to None.

Returns:

The eccentric or hyperbolic anomaly in degrees.

Return type:

numpy.ndarray

kete.conversion.compute_h_mag(diameter, albedo, c_hg=1329.0)

Compute the H magnitude of the object given the diameter in km and the albedo.

Parameters:

diameter (NDArray) – The diameter of the object in Km.
albedo (NDArray) – The albedo of the object.

Return type:

ndarray

kete.conversion.compute_obliquity(time)

Compute the mean obliquity of the ecliptic of date.

The expression is the IAU 2006 obliquity, equation (39) of the paper cited on earth_precession_rotation(). Use it within several centuries of J2000.

Parameters:: time (float) – Time in TDB scaled Julian Days.
Returns:: Mean obliquity in degrees.
Return type:: float

kete.conversion.compute_semi_major(peri_dist, ecc)

Calculate semi major axis, returning nan when it cannot be computed.

Parameters:

peri_dist (NDArray) – Perihelion distance in units of AU.
ecc (NDArray) – Eccentricity of the orbit.

Return type:

ndarray

kete.conversion.compute_tisserand(semi_major, ecc, inclination, perturbing_semi_major=5.2038)

Compute Tisserand’s Parameter, the default perturbing body is set to Jupiter.

See: https://en.wikipedia.org/wiki/Tisserand%27s_parameter

Note that if the inclination is not computed with respect to the perturbing body that this computation will not be correct. However, Jupiter only has an inclination of 1.3 degrees with respect to the Ecliptic plane, which will only introduce a very small error if the input inclination is w.r.t. the Ecliptic plane.

Parameters:

semi_major (float) – Semi Major axis of small body, in units of AU.
ecc (float) – Eccentricity of the small body.
inclination (float) – Inclination of the small body with respect to the perturbing body, in units of Degrees.
perturbing_semi_major (float) – Semi major axis of the parent body, in units of AU.

kete.conversion.dec_degrees_to_dms(dec)

Convert a declination in degrees to a “degrees arcminutes arcseconds” string.

Arcseconds are rounded to 2 decimals.

Parameters:: dec – Declination in decimal degrees.
Raises:: ValueError – If a value is not finite or is outside [-90, 90].

kete.conversion.dec_dms_to_degrees(dec)

Convert a declination from “degrees arcminutes arcseconds” string to degrees.

Terms may be separated by spaces, commas, colons, or semicolons. Missing trailing terms are zero. The sign of the degrees applies to the whole angle.

Parameters:: dec – Declination in degrees-arcminutes-arcseconds.
Raises:: ValueError – If the string cannot be parsed, arcminutes or arcseconds are outside [0, 60), or the declination is outside [-90, 90].

kete.conversion.earth_precession_rotation(time)

Compute the precession rotation from the J2000 epoch to a date.

The matrix transforms a vector in the J2000 Equatorial frame to the mean equator and equinox of the date. The equinox precesses by about 50 arcseconds per year, which is about 20 arcminutes from 2000 to 2025. The matrix does not include the frame bias.

The angles are the P03 precession angles of equation (40), which the IAU adopted as the IAU 2006 precession. Use them within a few centuries of 2000. The source is:

"Expressions for IAU 2000 precession quantities"
Capitaine, N. ; Wallace, P. T. ; Chapront, J.
Astronomy and Astrophysics, v.412, p.567-586 (2003)
doi:10.1051/0004-6361:20031539

This paper defines the IAU 1976 model, which JPL Horizons uses. It discusses the same angles:

"Precession matrix based on IAU (1976) system of astronomical constants."
Lieske, J. H.
Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284.

Parameters:: time (Time or float) – Time, as a Time or in TDB scaled Julian Days.
Returns:: The 3x3 rotation matrix.
Return type:: list of list of float

Examples

Convert a vector in the Equatorial J2000 frame to the mean equator and equinox of 2025. The result is not an Equatorial vector as kete defines it, because kete defines that frame at the J2000 epoch.

import kete
import numpy as np

jd = kete.Time.from_ymd(2025, 1, 1).jd
rotation = np.array(kete.conversion.earth_precession_rotation(jd))
new_vec = rotation @ kete.Vector.from_ra_dec(20, 10)

kete.conversion.flux_to_mag(flux, zero_point=3631)

Convert flux in Jy to AB Magnitude, assuming it is a single frequency source. Note that this assumes that the band is infinitely narrow.

See: https://en.wikipedia.org/wiki/AB_magnitude

Parameters:

flux (float) – Flux in Jy.
zero_point – Flux in Jy where the magnitude is zero.

Return type:

float

kete.conversion.hill_radius(body, central_body='Sun', jd=None)

Compute the Hill radius of a body orbiting a more massive central body.

r_H = a (1 - e) (m / (3 M))^(1/3)

The orbital elements are looked up from the loaded SPICE kernels at the given epoch.

Parameters:

body (str | int) – Name or NAIF ID of the orbiting body (e.g. "Earth" or 399).
central_body (str | int) – Name or NAIF ID of the central body. Defaults to "Sun".
jd (float | None) – Epoch at which to evaluate the orbit (JD, TDB). Defaults to J2000.

Returns:

Hill radius in AU.

Return type:

float

kete.conversion.mag_to_flux(mag, zero_point=3631)

Convert AB Magnitude to flux in Jy, assuming it is a single frequency source. Note that this assumes that the band is infinitely narrow.

See: https://en.wikipedia.org/wiki/AB_magnitude

Parameters:

mag (float) – AB Magnitude.
zero_point – Flux in Jy where the magnitude is zero.

Return type:

float

kete.conversion.ra_degrees_to_hms(ra)

Convert a Right Ascension in decimal degrees to an “hours minutes seconds” string.

The angle is wrapped into [0, 24) hours, and seconds are rounded to 3 decimals.

Parameters:: ra – Right Ascension in decimal degrees.
Raises:: ValueError – If a value is not finite.

kete.conversion.ra_hms_to_degrees(ra)

Convert a right ascension from “hours minutes seconds” string to degrees.

Terms may be separated by spaces, commas, colons, or semicolons. Missing trailing terms are zero.

Parameters:: ra – Right ascension in hours-minutes-seconds.
Raises:: ValueError – If the string cannot be parsed, minutes or seconds are outside [0, 60), or the right ascension is outside [0, 24) hours.

kete.conversion.sphere_of_influence(body, central_body='Sun', jd=None)

Compute the Laplace sphere-of-influence radius.

r_SOI = a (m / M)^(2/5)

The semi-major axis is looked up from the loaded SPICE kernels at the given epoch.

Parameters:

body (str | int) – Name or NAIF ID of the orbiting body (e.g. "Earth" or 399).
central_body (str | int) – Name or NAIF ID of the central body. Defaults to "Sun".
jd (float | None) – Epoch at which to evaluate the orbit (JD, TDB). Defaults to J2000.

Returns:

Sphere of influence radius in AU.

Return type:

float

kete.conversion.table_to_states(orbit_dataframe)

Load kete.State from a dataframe provided by either kete.mpc.fetch_known_orbit_data() or kete.horizons.fetch_known_orbit_data().

import kete

# Load all MPC orbits
orbits = kete.mpc.fetch_known_orbit_data()

# Subset the table to be only NEOs
neos = kete.population.neo(orbits.peri_dist, orbits.ecc)
neo_subset = orbits[neos]

# load the state object from this table
state = kete.conversion.table_to_states(neo_subset)

Parameters:: orbit_dataframe – Pandas Dataframe as provided by the fetch_known_orbit_data function.