From 34dda890eca2e54ab0e3f7f5804b9bd3a04d2b05 Mon Sep 17 00:00:00 2001 From: Joey Carpinelli Date: Wed, 27 Mar 2024 22:39:58 -0400 Subject: [PATCH] Finished draft of common documentation --- .vscode/ltex.dictionary.en-US.txt | 1 + docs/Project.toml | 1 + docs/make.jl | 6 ++- docs/src/examples/horizons/index.md | 57 +++++++++++++++++++++++++++++ docs/src/examples/index.md | 9 ++++- docs/src/examples/spice/index.md | 52 ++++++++++++++++++++++++++ docs/src/index.md | 2 +- docs/src/quick-start/index.md | 56 ---------------------------- 8 files changed, 124 insertions(+), 60 deletions(-) create mode 100644 .vscode/ltex.dictionary.en-US.txt delete mode 100644 docs/src/quick-start/index.md diff --git a/.vscode/ltex.dictionary.en-US.txt b/.vscode/ltex.dictionary.en-US.txt new file mode 100644 index 00000000..82850134 --- /dev/null +++ b/.vscode/ltex.dictionary.en-US.txt @@ -0,0 +1 @@ +ephemeris diff --git a/docs/Project.toml b/docs/Project.toml index 1c0e048a..47ccefd2 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,4 +1,5 @@ [deps] +DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" HorizonsAPI = "c15253bb-5e94-4b8b-9a02-579bb6c8e3ce" HorizonsEphemeris = "05ee1981-f730-42d8-b713-4f42d99733dc" diff --git a/docs/make.jl b/docs/make.jl index 299153ca..34f4bb5c 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,8 +6,10 @@ makedocs( pages = [ "Overview" => [ "About Ephemeris" => "index.md", - "Quick Start" => "quick-start/index.md", - "Examples" => "examples/index.md", + "Quick Start" => [ + "SPICE" => "examples/spice/index.md", + "HORIZONS" => "examples/horizons/index.md", + ], ], ], ) diff --git a/docs/src/examples/horizons/index.md b/docs/src/examples/horizons/index.md index e69de29b..dadd7efe 100644 --- a/docs/src/examples/horizons/index.md +++ b/docs/src/examples/horizons/index.md @@ -0,0 +1,57 @@ +# HORIZONS Ephemeris Examples + +The JPL HORIZONS platform provides ephemeris data as Cartesian state vectors, +osculating orbital elements, and other representations. The precise +[REST API](https://ssd-api.jpl.nasa.gov/doc/horizons.html) +accepted by the JPL HORIZONS servers is implemented in Julia with `HorizonsAPI.jl`. + +```@repl horizons-examples +using HorizonsAPI + +fetch_vectors(399; format="text") # Earth's position w.r.t. the solar system barycenter +``` + +The `CENTER` parameter specifies the ephemeris reference position. + +```@repl horizons-examples +fetch_vectors(499; format="text", CENTER="@399") # Mars' position w.r.t. Earth +``` + +The response from the HORIZONS API contains a lot of information! To more simply +fetch and inspect ephemeris data from JPL HORIZONS servers, use the `ephemeris` +method in `HorizonsEphemeris.jl`. + +```@repl horizons-examples +using Dates, HorizonsEphemeris + +ephemeris("earth", now()) +``` + +The output of `ephemeris` is a `NamedTuple`, so you can easily pass it along to +`DataFrames.jl` for convenient inspection & data processing. Note the `wrt` +keyword argument as well; it is a simplified interface to the HORIZONS API +`CENTER` argument. + +```@repl horizons-examples +using DataFrames + +data = DataFrame( + ephemeris("earth", now() - Year(50), now() + Year(5), Day(1); wrt="jupiter") +) +``` + +This example wouldn't be complete without some plotting! + +```@repl horizons-examples +using Plots + +figure = plot( + data.x, data.y; + xlabel="X (KM)", ylabel="Y (KM)", label=:none, + title="Earth's Position w.r.t. Jupiter" +); +``` + +```@example horizons-examples +figure # hide +``` diff --git a/docs/src/examples/index.md b/docs/src/examples/index.md index 1b976a9b..fb09b75b 100644 --- a/docs/src/examples/index.md +++ b/docs/src/examples/index.md @@ -1 +1,8 @@ -# Examples \ No newline at end of file +# Ephemeris Package Examples + +Navigating ephemeris platforms — and processing ephemeris data — can sometimes +have a steep learning curve. For simple blocks of code to get you up and running +with loading and plotting ephemeris data, check out the +[SPICE](spice/index.md) or [HORIZONS](horizons/index.md) +examples, or the documentation pages for each individual package in the +drop-down menu above. diff --git a/docs/src/examples/spice/index.md b/docs/src/examples/spice/index.md index e69de29b..54012b66 100644 --- a/docs/src/examples/spice/index.md +++ b/docs/src/examples/spice/index.md @@ -0,0 +1,52 @@ +# SPICE Ephemeris Examples + +The `SPICEBodies.KernelBody` type allows us to idiomatically query information +from the SPICE kernel pool. First, download some common generic kernels (such as +`de432s` below) and load them into the kernel pool with `SPICE.furnsh`. If you +want more information about what's in each kernel, inspect each kernel's +docstring; for example, `@doc de432s`, or `help?> de432s` in Julia's REPL. + +```@repl quickstart +using SPICE, SPICEKernels, SPICEBodies + +return furnsh( + de432s(), # position and velocity data for nearby planets + latest_leapseconds_lsk(), # timekeeping, parsing epochs + gm_de440(), # mass parameters for major solar system bodies + pck00011(), # physical properties of major solar system bodies +) + +earth = KernelBody("earth") +``` + +We can now call the `earth` variable like a function of time, and get back the +positions (and velocities) interpolated by `CSPICE` from the data in the kernel +pool. + +```@repl quickstart +using Dates + +timepoints = DateTime(1950,1,1) : Month(1) : DateTime(2049,1,1) + +states = earth.(timepoints) +``` + +Finally, let's plot the data we just collected. + +```@repl quickstart +using Plots + +figure = let x = map(u -> u[begin], states), y = map(u -> u[begin+1], states) + scatter( + x, y; + label=nothing, markersize=1, + xlabel="X (KM)", ylabel="Y (KM)", zlabel="Z (KM)", + title="Earth's Position w.r.t. SSB", + aspect_ratio=1, + ); +end +``` + +```@example quickstart +figure # hide +``` diff --git a/docs/src/index.md b/docs/src/index.md index c00f962a..8f87d573 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -46,4 +46,4 @@ These two ephemeris platforms — HORIZONS and SPICE — are both free to use, and have been incredibly helpful to students and researchers around the world. The Julia packages above — and others — available to help you fetch and parse ephemeris data. For more information on how to use these packages, continue on -to [**Quick Start**](quick-start/index.md). +to the documentation [**examples**](examples/index.md). diff --git a/docs/src/quick-start/index.md b/docs/src/quick-start/index.md deleted file mode 100644 index 18b14732..00000000 --- a/docs/src/quick-start/index.md +++ /dev/null @@ -1,56 +0,0 @@ -# Quick Start - -Navigating ephemeris platforms — and processing ephemeris data — can sometimes -have a steep learning curve. This page will help you get up and running with -loading and plotting ephemeris. For more detailed information, check out the -documentation [**examples**](../examples/index.md), or documentation pages -for each individual package in the drop-down menu. - -The `SPICEBodies.KernelBody` type allows us to idiomatically query information -from the SPICE kernel pool. First, download some common generic kernels (such as -`de432s` below) and load them into the kernel pool with `SPICE.furnsh`. If you -want more information about what's in each kernel, inspect each kernel's -docstring; for example, `@doc de432s`, or `help?> de432s` in Julia's REPL. - -```@repl quickstart -using SPICE, SPICEKernels, SPICEBodies - -return furnsh( - de432s(), # position and velocity data for nearby planets - latest_leapseconds_lsk(), # timekeeping, parsing epochs - gm_de440(), # mass parameters for major solar system bodies - pck00011(), # physical properties of major solar system bodies -) - -earth = KernelBody("earth") -``` - -We can now call the `earth` variable like a function of time, and get back the -positions (and velocities) interpolated by `CSPICE` from the data in the kernel -pool. - -```@repl quickstart -using Dates - -timepoints = [DateTime(year, month, 1) for year in 1950:2049, month in 1:12] - -states = earth.(timepoints) -``` - -Finally, let's plot the data we just collected. This is why we need leap days! - -```@repl quickstart -using Plots - -figure = let x = [u[begin] for u in states], y = [u[begin+1] for u in states] - scatter( - x, y; - label=nothing, color=:black, xlabel="X (KM)", ylabel="Y (KM)", - title="Earth's Position w.r.t. the Solar System Barycenter" - ) -end; -``` - -```@example quickstart -figure # hide -```