Syndynes plots and fixes

[mkelley]

Summary

• Add plot() methods to syndyne and synchrone classes
• New SourceOrbit class to encapsulate a collection of states that make up an orbit.
• Update SynGenerator.source_orbit to use the new SourceOrbit class.
• Add a new documentation subsection to show how to get State objects from Horizons via Ephem.from_horizons.
• Ephem.from_horizons is populated with masked quantities, but WCS can crash trying to convert masked coordinates to pixels. Added a new sbpy.utils._unmasked function which will return an unmasked object using an astropy 7.0 function (or fall back on an internal method for astropy < 7).
• Add an example of plotting syndynes on an image.
• State.to_ephem was in the documentation, but not the code! Added this function.

.plot() methods

Syndyne and synchrone plotting is simplified. Previously one might have written:

coords0 = observer.observe(comet)
def plot(ax, coords, **kwargs):
    dRA = coords.ra - coords0.ra
    dDec = coords.dec - coords0.dec
    ax.plot(dRA.arcsec, dDec.arcsec, **kwargs)

for syndyne in dust.syndynes():
    plot(ax, syndyne.coords, label=f"$\\beta={syndyne.beta:.2g}$")

for synchrone in dust.synchrones():
    plot(ax, synchrone.coords, ls="--", label=f"$\Delta t={synchrone.age.to(u.d):.2g}$")

Now, much of that is incorporated into sbpy:

dust = SynGenerator(comet, betas, ages, observer=observer)
dust.syndynes().plot()
dust.synchrones().plot()

See the documentation for more examples.

API changes with SourceOrbit

SynGenerator.source_orbit returned a tuple including the states and coordinates of the orbit at the requested times. But these can be collected into a single object, just like Syndyne and Synchrone include their own particle states and coordinates. Furthermore, it would be great to use the new plot() approach that Syndyne and Synchrone use. To that end, I've created the new SourceOrbit class.

Previously:

states, coords = dust.source_orbit(dt)
coords0 = observer.observe(comet)
dRA = coords.ra - coords0.ra
dDec = coords.dec - coords0.dec
ax.plot(dRA.arcsec, dDec.arcsec,  color="k", ls=":", label="Orbit")

Now with SourceOrbit the same machinery behind Syndynes and Synchrones can be used:

dust.source_orbit(dt).plot(color="k", ls=":", label="Orbit")

API changes with Syndynes and Synchrones

Indexing with int, slice, or tuple

Indexing Syndynes or Synchrones would return single Syndyne / Synchrone objects, or a list thereof:

>>> syndynes = dust.syndynes()
>>> type(syndynes[0])
sbpy.dynamics.syndynes.Syndyne
>>> type(syndynes[:2])
list

This behavior was OK, but with the new .plot() methods, returning a list drops the fancy machinery behind, e.g., Synchrones.plot(). As a result we would have to use the individual plot methods, which also means the label needs to be specified to achieve the same behavior:

# plot every 5th synchrone
for syn in dust.synchrones()[::5]:
    syn.plot(label="$\\Delta t = {age}$".format(syn.age))

Now indexing with a slice (or tuple) will return a Syndynes or Synchrones object, and we can immediately plot the results:

# plot every 5th synchrone
dust.synchrones()[::5].plot()

Drop "coords" from to_ephem() result

The heliocentric ecliptic IAU76 reference frame needs observation time. When creating an Ephem object from Synchrones in that frame, the coordinates of each synchrone could not be concatenated. I think it is because the observation times in the reference frame did not match, so astropy thought the reference frames were different, and in a way that is right. Rather than hack something here, just drop the coords column. RA, Dec, etc. are already included as separate columns, so there is no loss of information.

[github-actions]

Thank you for your contribution to sbpy, an Astropy affiliated package! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• Do the proposed changes actually accomplish desired goals?
• Do the proposed changes follow the sbpy coding guidelines?
• Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
• Did the CI pass? If no, are the failures related?
• Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label.
• Is a milestone added?

[mkelley]

Keeping this a draft until #427 is done.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.09%. Comparing base (162139f) to head (4786e0c).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #434      +/-   ##
==========================================
- Coverage   84.72%   82.09%   -2.63%     
==========================================
  Files          92       53      -39     
  Lines        8459     4335    -4124     
==========================================
- Hits         7167     3559    -3608     
+ Misses       1292      776     -516     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mkelley]

Updated comment with API-breaking change in to_ephem.