improve documentation

[nden]

This is a list of "desired" examples which came from Python in Astronomy meeting in Leiden.

• [ ] An example of separating optical distortion from atmospheric effects
• [ ] An example of “I have stars at pixel positions x, y (arrays), and I know they are at the SkyCoord(ra, dec). Give me the gWCS of the transformation to model that.”
• [ ] I have a FITS file with a header with FITS WCS - how do I read it in and inspect the gWCS object?
• [ ] I have a gWCS for a spectral cube, how do I check if the spectral axis is separable, and if so can I get a pure-spectral gWCS?
• [ ] Manual construction of a simple WCS pipeline.
• [ ] Augmenting (array) columns in FITS tables with WCS.
• [ ] I have a gWCS object for a time-dependent spectral cube, how do I find out what the order of the dimensions are? (e.g. longitude, time, latitude, spectral)
• [ ] Easily change WCS projections (automatic determination of new grid boundary, etc.)
• [ ] I have a gWCS object with distortions, how do I get one without distortions?
• [ ] A comparison of how to use gWCS versus FITS WCS (as implemented in astropy.wcs)
• [ ] I have a gWCS object for an image, and want to extract a cutout of the image, how do I get the gWCS of the cutout?
• [ ] I have a gWCS, how do I export it to a FITS file?
• [ ] Serialize a gWCS pipeline into yaml / asdf
• [ ] How to deal with different coordinate systems (J2000, B1950, Galactic, etc.)

[astrofrog]

I think this is one of the most important issues for 1.0. I would recommend that after doing these updates and before releasing, you let us know and some of us can go over the docs and say if anything is unclear.

As a side note, one comment that I had from reading the current documentation is that it's not clear why one needs to use cf.CelestialFrame rather than just specifying output_frame=ICRS() (maybe internally WCS could recognize astropy frames and wrap them in CelestialFrame?)

[eteq]

👍 to what @astrofrog said here. It's also worth considering whether someone other than @nden should try to write up some of this and have her essentially correct it. That's a fairly thankless task, but it might be the best way to get the docs for something this mind-twisting...?

[astrofrog]

I think the issue is finding someone who is not an expert yet knows how to do this. I feel like it would be better if @nden did a first pass and then others could go over and suggest improvements? I mean I'd have been happy to try and write something but I have no idea how to do these things!

[astrofrog]

A compromise would be that @nden could make available scripts to do these things to show how to do them and then ask someone else to write it up based on their understanding of the scripts.

[jdavies-st]

I can help @nden with this when we have some time. I've used gWCS a lot as a user, so might be able to help with documentation if needed.

[stscijgbot]

This ticket is now being tracked at AL-57