ephessos 1.0.0__py3-none-any.whl

ephessos/__init__.py

@@ -0,0 +1,8 @@
+"""
+EPHESSOS: Ephemeris for Solar System Objects with JPL/Horizons
+
+Alejandro S. Borlaff
+NASA Ames Research Center, Moffett Field, 94035, California, USA.
+a.s.borlaff@nasa.gov
+"""
+import ephessos.core

ephessos/core.py

@@ -0,0 +1,198 @@
+from astropy.time import Time
+from astropy.table import vstack
+import astropy.units as u
+import numpy as np
+import pandas as pd
+
+def sso_query_to_horizons(designation, epoch=None, eccentricity=None, node=None, arg_perihelion=None, inclination=None, mean_anomaly=None, semimajor_axis=None, mean_motion=None, mjd_start=58849.0, mjd_end=61042.0, step_size="1d", verbose=False):
+    # Example of a HTTP API Request to Horizons: 
+    request_url = "https://ssd.jpl.nasa.gov/api/horizons.api?format=text&"
+    # request_url = "https://ssd.jpl.nasa.gov/api/horizons.api?"
+    # 00433   10.38  0.15 K25BL 310.55432  178.92978  304.27008   10.82847  0.2228360  0.55977529   1.4581210  0 E2025-YE5 16519  59 1893-2025 0.52 M-v 3Ek MPCORBFIT  1804    (433) Eros               20251222
+    """
+    OBJECT = df.iloc[0]["Designation"] # 	Name of user input object
+    EPOCH = df.iloc[0]["Epoch"] 	  	# Julian Day number (JDTDB) of osculating elements
+    ECLIP = "J2000" 	  	# Reference ecliptic frame of elements: J2000 or B1950. J2000 assumes the IAU76/80 J2000 obliquity of 84381.448 arcsec relative to the ICRF reference frame. B1950 assumes FK4/B1950 obliquity of 84404.8362512 arcsec.
+    EC =  str(df.iloc[0]["Eccentricity"]) # 	  	Eccentricity
+    # QR = 	# au 	Perihelion distance (see note above)
+    # TP = 	#   	Perihelion Julian Day number (see note above)
+    OM =  str(df.iloc[0]["Node"])	# deg 	Longitude of ascending node wrt ecliptic
+    W =   str(df.iloc[0]["Arg_Perihelion"])	# deg 	Argument of perihelion wrt ecliptic
+    IN =  str(df.iloc[0]["Inclination"])	# deg 	Inclination wrt ecliptic
+    MA =  str(df.iloc[0]["Mean_Anomaly"])	# deg 	Mean anomaly (see note above)
+    A =   str(df.iloc[0]["Semimajor_Axis"])	# au 	Semi-major axis (see note above)
+    N =	  str(df.iloc[0]["Mean_Motion"]) # deg/d 	Mean motion (see note above)
+    """
+    OBJECT = designation # 	Name of user input object
+    EPOCH = epoch 	  	# Julian Day number (JDTDB) of osculating elements
+    ECLIP = "J2000" 	  	# Reference ecliptic frame of elements: J2000 
+    EC =  str(eccentricity) # 	  	Eccentricity
+    # QR = 	# au 	Perihelion distance (see note above
+    # TP = 	#   	Perihelion Julian Day number (see note above)
+    OM =  str(node)	# deg 	Longitude of ascending node wrt ecliptic
+    W =   str(arg_perihelion)	# deg 	Argument of perihelion wrt ecliptic
+    IN =  str(inclination)    # deg 	Inclination wrt ecliptic
+    MA =  str(mean_anomaly)	# deg 	Mean anomaly (see note above)
+    A =   str(semimajor_axis)	# au 	Semi-major axis
+    N =	  str(mean_motion) # deg/d 	Mean motion (see note above)
+    
+    # HEOE = ';TEST,2460400.5,1.5,0.2,10.5,45.0,30.0,20240401,1.0,J2000'
+    
+    # Process time range for ephemeris query
+    from astropy.time import Time
+    t_start = Time(mjd_start, format='mjd')
+    t_end = Time(mjd_end, format='mjd')
+
+    if verbose: 
+        print("--designation="+designation+" --epoch="+str(epoch)+" --eccentricity="+str(eccentricity)+" --node="+str(node)+", --arg_perihelion="+str(arg_perihelion)+" --inclination="+str(inclination)+" --mean_anomaly="+str(mean_anomaly)+" --semimajor_axis="+str(semimajor_axis)+" --mean_motion="+str(mean_motion)+" --mjd_start="+str(mjd_start)+" --mjd_end="+str(mjd_end)+" --step_size="+step_size)
+
+    """
+    # request_url = request_url + "&COMMAND='1'"
+    """
+
+    if eccentricity is None and node is None and arg_perihelion is None and inclination is None and mean_anomaly is None and semimajor_axis is None:
+        request_url = request_url + "COMMAND='" + OBJECT + "'" 
+    else:
+        request_url = request_url + "COMMAND=';'" 
+    if designation is not None: request_url = request_url + "&OBJECT="+OBJECT
+    if epoch is not None: request_url = request_url + "&EPOCH=2461000.83333"#+EPOCH
+    request_url = request_url + "&ECLIP="+ECLIP
+    if eccentricity is not None: request_url = request_url + "&EC="+EC 
+    if node is not None: request_url = request_url + "&OM="+OM 
+    if arg_perihelion is not None: request_url = request_url + "&W="+W 
+    if inclination is not None: request_url = request_url + "&IN="+IN 
+    if mean_anomaly is not None: request_url = request_url + "&MA="+MA 
+    if semimajor_axis is not None: request_url = request_url + "&A="+A 
+    # request_url = request_url + "&N="+N 
+
+    # request_url = request_url + "&COMMAND='499'"
+    request_url = request_url + "&OBJ_DATA='YES'" 
+    request_url = request_url + "&MAKE_EPHEM='YES'" 
+    request_url = request_url + "&EPHEM_TYPE='OBSERVER'" 
+    request_url = request_url + "&CENTER='500@399'" 
+    request_url = request_url + "&START_TIME='" + t_start.isot + "'" 
+    request_url = request_url + "&STOP_TIME='"+ t_end.isot + "'" 
+    request_url = request_url + "&STEP_SIZE='" + step_size + "'"
+    request_url = request_url + "&CSV_FORMAT='YES'" 
+    request_url = request_url + "&QUANTITIES='1,2,3,4,5,6,7,8,9,10,20,23,24,25,27,29'"
+    # request_url = request_url.replace(",", "%3B")
+
+    import urllib.request
+    if verbose: print(request_url)
+    
+    request_url = request_url.replace(";","%3B")    
+
+    fp = urllib.request.urlopen(request_url)
+    mybytes = fp.read()
+
+    mystr = mybytes.decode("utf8")
+    fp.close()
+    
+    lines_horizons_query = np.array(mystr.split('\n'))
+    id_start_of_table = np.where(lines_horizons_query == '$$SOE')[0][0]
+    id_end_of_table = np.where(lines_horizons_query == '$$EOE')[0][0]
+    id_column_names = id_start_of_table - 2
+    horizons_column_names = lines_horizons_query[id_column_names]
+    horizons_data_table = lines_horizons_query[id_start_of_table+1:id_end_of_table]
+    n_rows = len(lines_horizons_query[id_start_of_table+1:id_end_of_table])
+
+    csv_table_list = []
+    # csv_table_list = csv_table_list + [horizons_column_names.split(',')]
+
+    for i in range(n_rows):
+        csv_table_list = csv_table_list + [horizons_data_table[i].split(',')]
+
+    # print(csv_table_list)
+
+    horizons_dataframe = pd.DataFrame(np.array(csv_table_list), columns=horizons_column_names.split(','))
+
+    ra_icrf = np.zeros(len(horizons_dataframe), dtype=object)
+    dec_icrf = np.zeros(len(horizons_dataframe), dtype=object)
+    date_hms = np.zeros(len(horizons_dataframe), dtype=object)
+    mjd = np.zeros(len(horizons_dataframe))
+
+    time_column_name = horizons_dataframe.columns[0]
+
+    for i in range(len(horizons_dataframe)):
+        ra_icrf[i] = horizons_dataframe[" R.A._(ICRF)"].iloc[i][1:].replace(" ",":")
+        dec_icrf[i] = horizons_dataframe[" DEC__(ICRF)"].iloc[i][1:].replace(" ",":")
+        date_hms[i] = translate_horizons_date_to_date_hms(horizons_dataframe[time_column_name].iloc[i])[1:]
+        mjd[i] = Time(date_hms[i], format='iso').mjd    
+
+    print(date_hms)
+
+    from astropy.coordinates import SkyCoord  # High-level coordinates
+    coords = SkyCoord(ra_icrf, dec_icrf, unit=(u.hourangle, u.deg))
+    horizons_dataframe["RA_deg_ICRF"] = coords.ra.deg
+    horizons_dataframe["DEC_deg_ICRF"] = coords.dec.deg
+    horizons_dataframe["MJD"] = mjd
+    return(horizons_dataframe)
+
+
+def translate_horizons_date_to_date_hms(horizons_date):
+    # Example input: "2025-Jan-22 00:00"
+    # Convert to ISO format: "2025-01-22T00:00:00"
+    date_hms = horizons_date.replace("Jan","01").replace("Feb","02").replace("Mar","03").replace("Apr","04").replace("May","05").replace("Jun","06").replace("Jul","07").replace("Aug","08").replace("Sep","09").replace("Oct","10").replace("Nov","11").replace("Dec","12")
+    return date_hms
+
+
+
+
+
+def read_mpc_nea_file(file_path):
+    # Define the exact character ranges based on the MPC schema
+    # Note: pandas uses 0-based indexing and the 'stop' value is exclusive
+    col_specification = [
+        (0, 7),     # Designation
+        (8, 13),    # H (Absolute Mag)
+        (14, 19),   # G (Slope Parameter)
+        (20, 25),   # Epoch
+        (26, 35),   # Mean Anomaly
+        (37, 46),   # Argument of Perihelion
+        (48, 57),   # Longitude of Ascending Node
+        (59, 68),   # Inclination
+        (70, 79),   # Eccentricity
+        (80, 91),   # Mean Daily Motion
+        (92, 103),  # Semimajor Axis
+        (105, 106), # Uncertainty (U)
+        (107, 116), # Reference
+        (117, 122), # Num observations
+        (123, 126), # Num oppositions
+        (127, 131), # First year / Arc
+        (132, 136), # Last year / 'days'
+        (137, 141), # r.m.s residual
+        (142, 145), # Perturbers (Coarse)
+        (146, 149), # Perturbers (Precise)
+        (150, 160), # Computer Name
+        (161, 165), # Flags (Hex)
+        (166, 174), # Numerical ID
+        (175, 194), # Readable Designation
+        (194, 202)  # Last Observation Date
+    ]
+
+    column_names = [
+        "Designation", "H", "G", "Epoch", "Mean_Anomaly", "Arg_Perihelion", 
+        "Node", "Inclination", "Eccentricity", "Mean_Motion", "Semimajor_Axis", 
+        "Uncertainty", "Ref", "Obs_Count", "Opp_Count", "First_Obs", "Last_Obs_Arc",
+        "RMS_Resid", "Pert_Coarse", "Pert_Precise", "Comp_Name", "Flags", "Num_ID",
+        "Full_Name", "Last_Obs_Date"
+    ]
+
+    # Read the file
+    # Replace 'NEA.txt' with the path to your downloaded file
+    df = pd.read_fwf(
+        file_path, 
+        colspecs=col_specification, 
+        names=column_names, 
+        header=None
+    )
+
+    # Optional: Convert numeric columns that might have been read as strings
+    df['H'] = pd.to_numeric(df['H'], errors='coerce')
+    df['Semimajor_Axis'] = pd.to_numeric(df['Semimajor_Axis'], errors='coerce')
+    #df[['ID', 'Name']] = df['Full_Name'].str.extract(r'(\(.*\))\s+(.*)')
+    df["Designation"] = df["Designation"].astype(str)
+
+    # Preview the first few rows
+    print(df.head())
+    return(df)

ephessos-1.0.0.data/scripts/ephessos

@@ -0,0 +1,59 @@
+#!python
+
+import ephessos as ep
+import argparse
+import yaml
+import glob
+from astropy.time import Time
+
+
+
+def go(args):
+
+    if (args.eccentricity is None):
+        print('Warning! Please input a some Heliocentric Ecliptic Osculating Elements. Check https://ssd-api.jpl.nasa.gov/doc/horizons.html for more information.')
+        print('EPHESSOS / Ephemeris for Solar System Objects with JPL/Horizons')
+        # print('EXAMPLE: ephessos --mjdstart 58849.0 --mjdend 61042.0')
+        return
+    
+    else:        
+        horizons_dataframe = ep.core.sso_query_to_horizons(designation=args.designation, 
+                      epoch=args.epoch, 
+                      eccentricity=args.eccentricity, 
+                      node=args.node, 
+                      arg_perihelion=args.arg_perihelion, 
+                      inclination=args.inclination, 
+                      mean_anomaly=args.mean_anomaly, 
+                      semimajor_axis=args.semimajor_axis, 
+                      mean_motion=args.mean_motion, 
+                      mjd_start=args.mjdstart, 
+                      mjd_end=args.mjdend, 
+                      step_size=args.step_size, 
+                      verbose=True)
+    
+    
+        horizons_dataframe.to_csv(args.output, index=False)
+        print(f"Ephemeris data saved to {args.output}") 
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description='EPHESSOS / Ephemeris for Solar System Objects with JPL/Horizons',
+        epilog='EXAMPLE: %(prog)s nea_database.txt',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+    parser.add_argument('--designation', type=str, default=None, help='Designation of the solar system object')
+    parser.add_argument('--epoch',   type=float, default=None, help='Julian Date of the osculating elements')
+    parser.add_argument('--eccentricity', type=float, default=None, help='Eccentricity of the orbit')
+    parser.add_argument('--node',   type=float, default=None, help='Longitude of the ascending node')
+    parser.add_argument('--arg_perihelion', type=float, default=None, help='Argument of perihelion')
+    parser.add_argument('--inclination',   type=float, default=None, help='Inclination of the orbit')
+    parser.add_argument('--mean_anomaly', type=float, default=None, help='Mean anomaly')
+    parser.add_argument('--semimajor_axis', type=float, default=None, help='Semimajor axis of the orbit')
+    parser.add_argument('--mean_motion', type=float, default=None, help='Mean motion')
+    parser.add_argument('--mjdstart', type=float, default=None, help='Modified Julian Date of the start of the ephemeris')
+    parser.add_argument('--mjdend',   type=float, default=None, help='Modified Julian Date of the end of the ephemeris')
+    parser.add_argument('--step_size',   type=str, default=None, help='Step size for the ephemeris. Example values: "1d" for 1 day, "12h" for 12 hours, "1h" for 1 hour, etc.')
+    parser.add_argument('--output',   type=str, default="horizons_ephemeris.csv", help='Output file for the ephemeris data. Default is "horizons_ephemeris.csv".')
+    parser.add_argument('--verbose',   type=float, default=None, help='Verbosity level')
+    args = parser.parse_args()
+
+    go(args)

ephessos-1.0.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: ephessos
+Version: 1.0.0
+Summary: Ephemeris for Solar System Objects with JPL/Horizons
+Author-email: "Alejandro S. Borlaff" <a.s.borlaff@nasa.gov>, Jessie Dotson <jessie.dotson@nasa.gov>
+License: BSD
+Project-URL: Homepage, https://github.com/Borlaff/EPHESSOS
+Project-URL: Repository, https://github.com/Borlaff/EPHESSOS
+Project-URL: Tracker, https://github.com/Borlaff/EPHESSOS/issues
+Project-URL: Documentation, https://ephessos.readthedocs.io/en/stable/
+Project-URL: Source Code, https://github.com/Borlaff/EPHESSOS
+Keywords: HWO,SSOs,Horizons,JPL
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: tqdm
+Requires-Dist: pandas
+Requires-Dist: astroquery
+Requires-Dist: matplotlib
+Requires-Dist: astropy
+Requires-Dist: pytest
+Requires-Dist: ipython
+Requires-Dist: sphinx
+Requires-Dist: sphinx-rtd-dark-mode
+Requires-Dist: sphinxcontrib-video
+Dynamic: license-file
+
+# EPHESSOS
+Ephemeris for Solar System Objects with JPL/Horizons
+
+[![PyPI version](https://badge.fury.io/py/ephessos.svg)](https://pypi.org/project/ephessos/)
+[![License: BSD](https://img.shields.io/badge/License-BSD-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+
+EPHESSOS is a Python library for querying ephemeris data of solar system objects from NASA's JPL Horizons system. It provides an easy interface to retrieve positional and observational data for asteroids, comets, and planets.
+
+## Features
+
+- Query JPL Horizons using orbital elements or object designations
+- Parse MPC NEA (Near-Earth Asteroid) data files
+- Retrieve comprehensive ephemeris data including RA, Dec, distance, and more
+- Support for custom time ranges and step sizes
+- Integration with Astropy for astronomical calculations
+
+## Installation
+
+Install EPHESSOS using pip:
+
+```bash
+pip install ephessos
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/Borlaff/EPHESSOS.git
+cd EPHESSOS
+pip install .
+```
+
+## Quick Start
+
+Here's a simple example showing how to query the ephemeris of asteroid (433) Eros:
+
+```python
+import ephessos as ep
+from astropy.time import Time
+
+# Define time range
+mjd_start = Time('2024-01-01T00:00:00', format='isot', scale='utc').mjd
+mjd_end = Time('2024-01-15T00:00:00', format='isot', scale='utc').mjd
+
+# Query Horizons for Eros (designation: 00433)
+eros_data = ep.core.sso_query_to_horizons(
+    designation="00433",
+    mjd_start=mjd_start,
+    mjd_end=mjd_end,
+    step_size="1d",
+    verbose=True
+)
+
+print(eros_data.head())
+```
+
+This will return a pandas DataFrame containing ephemeris data including:
+- Right Ascension (RA) and Declination (Dec) in degrees
+- Distance from observer
+- Magnitude and other observational quantities
+- Modified Julian Date (MJD)
+
+## Advanced Usage
+
+### Reading MPC Data Files
+
+EPHESSOS can parse MPC-formatted NEA files:
+
+```python
+# Read MPC NEA data
+nea_table = ep.core.read_mpc_nea_file("path/to/nea.txt")
+
+# Query ephemeris for the first object
+first_object = nea_table.iloc[0]
+data = ep.core.sso_query_to_horizons(
+    designation=first_object["Designation"],
+    epoch=first_object["Epoch"],
+    eccentricity=first_object["Eccentricity"],
+    node=first_object["Node"],
+    arg_perihelion=first_object["Arg_Perihelion"],
+    inclination=first_object["Inclination"],
+    mean_anomaly=first_object["Mean_Anomaly"],
+    semimajor_axis=first_object["Semimajor_Axis"],
+    mean_motion=first_object["Mean_Motion"],
+    mjd_start=mjd_start,
+    mjd_end=mjd_end,
+    step_size="1d"
+)
+```
+
+
+## Documentation
+
+Full documentation is available at: [https://ephessos.readthedocs.io/](https://ephessos.readthedocs.io/)
+
+## Contributing
+
+Contributions are welcome! Please see our [contributing guidelines](CONTRIBUTING.md) for details.
+
+## License
+
+EPHESSOS is licensed under the BSD 3-Clause License. See [LICENSE](LICENSE) for details.
+
+## Citation
+
+If you use EPHESSOS in your research, please cite:
+
+```
+Borlaff, A. S., & Dotson, J. (2026). EPHESSOS: Ephemeris for Solar System Objects with JPL/Horizons.
+```
+
+## Contact
+
+- **Authors**: Alejandro S. Borlaff, Jessie Dotson
+- **Email**: a.s.borlaff@nasa.gov, jessie.dotson@nasa.gov
+- **Repository**: [https://github.com/Borlaff/EPHESSOS](https://github.com/Borlaff/EPHESSOS)

ephessos-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ephessos/__init__.py,sha256=5IntFcOenbK4wEw10Bh8rpaQLuA_D2tb79OE7ZyF5xk,200
+ephessos/core.py,sha256=u5Roe09jWLGaiZ4cZfV6D_c5Jmul1Qi5maqy1LNRXWI,9624
+ephessos-1.0.0.data/scripts/ephessos,sha256=ksBN0XGLiSnH-J1fB1I5ANbWLP1bluTtbIvO8oTnWro,3218
+ephessos-1.0.0.dist-info/licenses/LICENSE,sha256=HS9fMXdi9KZPwco1Qz-4F7qeioX3GvaQVwpcGW5l5jI,1070
+ephessos-1.0.0.dist-info/METADATA,sha256=lLn1V_-4ynqy3mTzvgEnBGqatxL6KsebEyoymJ7_x1s,4715
+ephessos-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ephessos-1.0.0.dist-info/top_level.txt,sha256=dFGI6P84QZ_I9uIjONH9Xin-W9eGQTl1ZSLtyQ3PKwc,9
+ephessos-1.0.0.dist-info/RECORD,,

ephessos-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ephessos-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. S. Borlaff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ephessos-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ephessos