Add ooe_tbl function to get ELEMENTS tables (#40)

* Add ooe_tbl function to get ELEMENTS tables

* Bump version to 0.4.6

* Minor README.md tweak

* Add extra sanity check for ooe_tbl test

Compare the retrieved semi-major axis value (in AU) when the AU value
retrieved "manually" from the web interface for the same date
(2023-01-01).

Project.toml

@@ -2,7 +2,7 @@ name = "HORIZONS"
 uuid = "5a3ac768-beb4-554a-9c98-3342fe3377f5"
 repo = "https://github.com/PerezHz/HORIZONS.jl.git"
 authors = ["Jorge A. Pérez Hernández", "Luis Eduardo Ramírez Montoya"]
-version = "0.4.5"
+version = "0.4.6"
 
 [deps]
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"

README.md

@@ -54,7 +54,8 @@ Jon D. Giorgini for automated generation of small-body binary SPK files and tabl
 These scripts were originally written in `expect`, and can be found at the
 JPL's Solar System Dynamics group ftp server `ftp://ssd.jpl.nasa.gov/pub/ssd/SCRIPTS/`.
 Below, we describe these functions `smb_spk`, `smb_spk_ele`, and `vec_tbl`, as
-well as the *observer table* function `obs_tbl`.
+well as the *observer table* function `obs_tbl` and the *osculating orbital
+elements table* function `ooe_tbl`.
 
 #### `smb_spk`
 
@@ -197,6 +198,47 @@ values, and a brief description:
 | `MAKE_EPHEM::Bool`            | true         | Generate ephemeris           |
 | `OBJ_DATA::Bool`              | true         | Include object summary       |
 
+#### `ooe_tbl`
+
+`HORIZONS.jl` function `ooe_tbl` allows the user to generate osculating orbital
+elements tables for designated objects and save the output into a file:
+
+```julia
+# Date variables for start and stop times
+t_start = DateTime(2024,4,1)
+t_start = DateTime(2024,4,2)
+
+# Get data for a single interval (two points in time)
+δt = 1
+
+# Generate osculating orbital elements table for JWST relative to the solar
+# system barycenter and save output to jwst.csv in current directory:
+ooe_tbl("JWST", t_start, t_stop, δt; FILENAME = "jwst.csv", CENTER = "SSB", CSV_FORMAT = true)
+```
+
+More details about default values of keyword arguments are available in the
+`ooe_tbl` docstrings.  NB: The HORIZONS default value for `CENTER` is
+`Geocentric`, but for objects in a heliocentric orbit you probably want to use
+`CENTER="SSB"` (i.e. solar system barycenter) instead.
+
+If the output file is not specified, then `ooe_tbl` returns the output as a
+| Keyword::Type         | Default      | Description                     |
+|:----------------------|:------------:|:--------------------------------|
+| `FILENAME::String`    | ""           | Output filename                 |
+| `CENTER::String`      | "Geocentric" | Reference body/barycenter       |
+| `REF_PLANE::String`   | "ECLIPTIC"   | Ephemeris reference plane       |
+| `COORD_TYPE::String`  | "GEODETIC"   | Type of user coordinates        |
+| `SITE_COORD::String`  | "0,0,0"      | User coordinates for CENTER     |
+| `REF_SYSTEM::String`  | "ICRF"       | Astrometric reference frame     |
+| `OUT_UNITS::String`   | "KM-S"       | Output units (KM-S, KM-D, AU-D) |
+| `CAL_TYPE::String`    | "MIXED"      | Type of calendar                |
+| `TIME_DIGITS::String` | "MINUTES"    | Output time precision           |
+| `CSV_FORMAT::Bool`    | false        | Output in CSV format            |
+| `ELM_LABELS::Bool`    | true         | Include label for each element  |
+| `TP_TYPE::String`     | "ABSOLUTE"   | Type of periapsis time (Tp) .   |
+| `MAKE_EPHEM::Bool`    | true         | Generate ephemeris              |
+| `OBJ_DATA::Bool`      | true         | Include object summary          |
+
 ### Small-Body DataBase API
 
 `HORIZONS.jl` function `sbdb` fetchs data for a specific small-body in JPL's Small-Body

src/HORIZONS.jl

@@ -7,7 +7,7 @@ module HORIZONS
 using HTTP, JSON, Base64, Dates
 using HTTP: Messages.Response
 
-export horizons, smb_spk, smb_spk_ele, vec_tbl, obs_tbl, sbdb, sbradar, scout
+export horizons, smb_spk, smb_spk_ele, vec_tbl, obs_tbl, sbdb, sbradar, scout, ooe_tbl
 
 @doc raw"""
     horizons()
@@ -27,6 +27,7 @@ include("sbdb.jl")
 include("sbradar.jl")
 include("obstbl.jl")
 include("scout.jl")
+include("ooetbl.jl")
 
 function __init__()
 

src/ooetbl.jl

@@ -0,0 +1,103 @@
+@doc raw"""
+    ooe_tbl(COMMAND::ObjectName, START_TIME::StartStopTime, STOP_TIME::StartStopTime,
+            STEP_SIZE::StepSize; FILENAME::String = "", kwargs...) -> String
+
+Generate an osculating orbital elements table for object `COMMAND` from
+`START_TIME` to `STOP_TIME` with step `STEP_SIZE`. If `FILENAME` is empty,
+return the output as a `String`; otherwise, save the table to the corresponding
+file. For more information see [1], in particular the **Common Parameters** and
+**SPK File Parameters** sections; for a list of keyword arguments see the
+**Ephemeris-Specific Parameters** section.
+
+!!! reference
+    [1] https://ssd-api.jpl.nasa.gov/doc/horizons.html.
+
+# Examples
+```julia-repl
+# Date variables for start and stop times
+
+t_start = DateTime(2024,4,13)
+t_stop = Date(2024,4,14)
+
+# Step size (allowed types: Period, Int, String)
+
+δt = Hour(1) # 1 hour step size
+
+# Generate tables and save output to Voyager1.txt in current directory:
+
+julia> local_file = ooe_tbl("JWST", t_start, t_stop, δt;
+                            FILENAME = "JWST.txt", CENTER = "SSB", CSV_FORMAT = true)
+"JWST.txt"
+
+julia> isfile(local_file)
+true
+```
+
+# Extended help
+
+This table summarizes the available keyword argument names, types, default
+values, and a brief description:
+
+| Keyword::Type         | Default      | Description                     |
+|:----------------------|:------------:|:--------------------------------|
+| `FILENAME::String`    | ""           | Output filename                 |
+| `CENTER::String`      | "Geocentric" | Reference body/barycenter       |
+| `REF_PLANE::String`   | "ECLIPTIC"   | Ephemeris reference plane       |
+| `COORD_TYPE::String`  | "GEODETIC"   | Type of user coordinates        |
+| `SITE_COORD::String`  | "0,0,0"      | User coordinates for CENTER     |
+| `REF_SYSTEM::String`  | "ICRF"       | Astrometric reference frame     |
+| `OUT_UNITS::String`   | "KM-S"       | Output units (KM-S, KM-D, AU-D) |
+| `CAL_TYPE::String`    | "MIXED"      | Type of calendar                |
+| `TIME_DIGITS::String` | "MINUTES"    | Output time precision           |
+| `CSV_FORMAT::Bool`    | false        | Output in CSV format            |
+| `ELM_LABELS::Bool`    | true         | Include label for each element  |
+| `TP_TYPE::String`     | "ABSOLUTE"   | Type of periapsis time (Tp) .   |
+| `MAKE_EPHEM::Bool`    | true         | Generate ephemeris              |
+| `OBJ_DATA::Bool`      | true         | Include object summary          |
+"""
+function ooe_tbl(COMMAND::ObjectName, START_TIME::StartStopTime, STOP_TIME::StartStopTime,
+                 STEP_SIZE::StepSize; FILENAME::String = "",
+                 CENTER::String = "Geocentric", REF_PLANE::String = "ECLIPTIC",
+                 COORD_TYPE::String = "GEODETIC", SITE_COORD::String = "0,0,0",
+                 REF_SYSTEM::String = "ICRF", OUT_UNITS::String="KM-S",
+                 CAL_TYPE::String = "MIXED", TIME_DIGITS::String = "MINUTES",
+                 CSV_FORMAT::Bool = false, ELM_LABELS::Bool = true,
+                 TP_TYPE::String = "ABSOLUTE", MAKE_EPHEM::Bool = true,
+                 OBJ_DATA::Bool = true)
+
+    # HTTP response code and text
+    code, text = jplapi(
+        HORIZONS_API_URL,
+        "COMMAND" => jplstr(COMMAND),
+        "EPHEM_TYPE" => "ELEMENTS",
+        "START_TIME" => jplstr(Dates.format(DateTime(START_TIME), JPL_DATE_FORMAT)),
+        "STOP_TIME" => jplstr(Dates.format(DateTime(STOP_TIME), JPL_DATE_FORMAT)),
+        "STEP_SIZE" => jplstr(STEP_SIZE),
+        "CENTER" => jplstr(CENTER),
+        "REF_PLANE" => jplstr(REF_PLANE),
+        "COORD_TYPE" => jplstr(COORD_TYPE),
+        "SITE_COORD" => jplstr(SITE_COORD),
+        "REF_SYSTEM" => jplstr(REF_SYSTEM),
+        "OUT_UNITS" => jplstr(OUT_UNITS),
+        "CAL_TYPE" => jplstr(CAL_TYPE),
+        "TIME_DIGITS" => jplstr(TIME_DIGITS),
+        "CSV_FORMAT" => jplstr(CSV_FORMAT),
+        "ELM_LABELS" => jplstr(ELM_LABELS),
+        "TP_TYPE" => jplstr(TP_TYPE),
+        "MAKE_EPHEM" => jplstr(MAKE_EPHEM),
+        "OBJ_DATA" => jplstr(OBJ_DATA)
+    )
+    iszero(code) && return ""
+    # Parse JSON
+    dict = jsonparse(text)
+    # Return table as String
+    if isempty(FILENAME)
+        return dict["result"]
+    # Save table to FILENAME
+    else
+        open(FILENAME, "w") do file
+            write(file, dict["result"])
+        end
+        return FILENAME
+    end
+end

test/runtests.jl

@@ -95,6 +95,41 @@ end
     rm(local_file)
 end
 
+@testset "Osculating Orbital Elements table generation: ooe_tbl" begin
+    # Generate tables and save output to JWST.txt
+    t_start = DateTime(2023, 1, 1)
+    t_stop = Date(2023, 1, 2)
+    δt = Hour(1)
+    local_file = ooe_tbl("JWST", t_start, t_stop, δt; FILENAME = "jwst.csv",
+                         CSV_FORMAT = true, CENTER = "SSB", OUT_UNITS="AU-D")
+
+    @test isfile(local_file)
+
+    jwst = ooe_tbl("JWST", t_start, t_stop, δt;
+                   CSV_FORMAT = true, CENTER = "SSB", OUT_UNITS="AU-D")
+
+    x = readlines(local_file)
+    y = split(chomp(jwst), "\n")
+
+    @test length(x) == length(y)
+    # Find lines that differ
+    diffinds = findall(x .!= y)
+    # The only line(s) that should differ start with "Ephemeris / API_USER" and
+    # contain time of retrieval.
+    @test all(startswith("Ephemeris / API_USER"), y[diffinds])
+
+    # Test that A (semi-major axis) for t_start has expected value
+    soe = findfirst(==("\$\$SOE"), y)
+    a_fetched = parse(Float64, split(y[soe+1], ',')[12])
+    a_expected = 1.028281028256704E+00 # for 2023-01-01 (retrieved 2024-04-02)
+
+    # This test may fail if the "DEFINITIVE_EPHEMERIS" for past dates are ever
+    # updated/changed.
+    @test a_fetched ≈ a_expected
+
+    rm(local_file)
+end
+
 @testset "Small-Body DataBase API" begin
     # Search 433 Eros in three different ways
     eros_1 = sbdb("sstr" => "Eros")