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 (59a8a49) to head (408c258).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #434      +/-   ##
==========================================
+ Coverage   81.81%   82.09%   +0.28%     
==========================================
  Files          53       53              
  Lines        4267     4335      +68     
==========================================
+ Hits         3491     3559      +68     
  Misses        776      776              

☔ 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.

[hhsieh00]

I didn't see any notable issues in the code changes and the functionality seems good after the various API and other changes to the previous way of doing things. My main comments are on the documentation:

• From the documentation, I was confused for a while about the relationship between SourceOrbit and source_orbit, and which the user was meant to use. The SourceOrbit class is mentioned but there is no example of its use in the documentation, while source_orbit (from SynGenerator) is the method used in the example to plot the object's orbit, so the need for a new SourceOrbit class was initially unclear. The change log makes it clearer that the source_orbit method produces a SourceOrbit object (so the SourceOrbit class mainly just enables backend functionality but is never directly called by name by the user?), but maybe this distinction should be made in the documentation itself? At the moment, in the documentation, under "Plotting syndynes and synchrones", it should probably say: "Syndynes, synchrones, and source_orbit have plot() methods to assist with this." since the example shows source_orbit.plot(), not SourceOrbit.plot().

• I'm not sure if this is a system-specific thing, but the synchrones in the syndyne-synchrone plot example in the documentation do not show up as dashed lines for me as in the example plot (shows up as all solid lines for me), so that plotting call should be "dust.synchrones()[4::5].plot(ax,ls="--")"

• It would probably be useful in the documentation to move the example where different syndynes are plotted with different line styles above the Spitzer example, because the variables get set to different values in the Spitzer example, whereas the sample output plot showing different line styles uses syndyne data from before the Spitzer example. Also, in that last example (plotting different line styles), while it probably shouldn't be too difficult for a user to figure out, it might still be better to write out the full code for generating the sample plot, rather than just showing the lines that are different from the original example code and leaving it to the user to fill in the blanks.

• At one point, "telescope" is incorrectly spelled as the "Spitzer Space Telesocpe"

[mkelley]

From the documentation, I was confused for a while about the relationship between SourceOrbit and source_orbit, and which the user was meant to use. The SourceOrbit class is mentioned but there is no example of its use in the documentation, while source_orbit (from SynGenerator) is the method used in the example to plot the object's orbit, so the need for a new SourceOrbit class was initially unclear. The change log makes it clearer that the source_orbit method produces a SourceOrbit object (so the SourceOrbit class mainly just enables backend functionality but is never directly called by name by the user?), but maybe this distinction should be made in the documentation itself?

Yeah, I see what you are saying. I'll move the orbit section to be contiguous with the syndyne and synchrone sections, and add some words before all this to clarify what is happening here: the SynGenerator object has methods syndynes(), synchrones(), and source_orbit() which produce Syndynes, Synchrones, and SourceOrbit objects.

At the moment, in the documentation, under "Plotting syndynes and synchrones", it should probably say: "Syndynes, synchrones, and source_orbit have plot() methods to assist with this." since the example shows source_orbit.plot(), not SourceOrbit.plot().

I think the above edits should help explain why this doesn't work. source_orbit is a function that produces the SourceOrbit object. source_orbit itself does not have a plot method. I think my attempt to be brief has confused things a bit, so I'll expand the example to help.

[mkelley]

I'm not sure if this is a system-specific thing, but the synchrones in the syndyne-synchrone plot example in the documentation do not show up as dashed lines for me as in the example plot (shows up as all solid lines for me), so that plotting call should be "dust.synchrones()[4::5].plot(ax,ls="--")"

fixed

[mkelley]

It would probably be useful in the documentation to move the example where different syndynes are plotted with different line styles above the Spitzer example, because the variables get set to different values in the Spitzer example, whereas the sample output plot showing different line styles uses syndyne data from before the Spitzer example.

That makes sense. Moved!

Also, in that last example (plotting different line styles), while it probably shouldn't be too difficult for a user to figure out, it might still be better to write out the full code for generating the sample plot, rather than just showing the lines that are different from the original example code and leaving it to the user to fill in the blanks.

Instead of repeating everything, I have enable the full "source code" link for the figure. Is that OK?

[mkelley]

At one point, "telescope" is incorrectly spelled as the "Spitzer Space Telesocpe"

And, done.

[mkelley]

@hhsieh00 ready for your reconsideration

[hhsieh00]

Finally went through all the changes and new documentation text. Looks good now!