Add jonathan's examples to the repo

[adrn]

Jonathan Foster made a tutorial on editing FITS headers -- I'm adding it to the repository.

[kelle]

do it!

[adrn]

Here and anywhere else we should use the astropy standard:

from astropy.io import fits

instead of pyfits.

[astrofrog]

I usually use the following approach for editing a FITS file (data or header) which I think is cleaner because you don't need to keep track of data and header separately:

from astropy.io import fits
hdu = fits.open('some_file.fits')[0]  # [0] gets first HDU only
hdu.header['OBJECT'] = "M31"
hdu.writeto('new_file.fits')

but that's just a personal preference 😄

If you are editing a file with multiple HDUs, it's definitely worth it, because you can do

from astropy.io import fits
hdulist = fits.open('some_file.fits')
hdulist[0].header['OBJECT'] = "M31"
hdulsit[1].data *= 2  # edit data in HDU 1
hdulist.writeto('new_file.fits')

which is quite convenient. Generally speaking, this will be a lot more convenient when editing FITS files with multiple HDUs (it's much harder to do the same with getdata).

[adrn]

Totally agree @astrofrog -- I'm working on the example in my branch now, just wanted to check in what Jonathan had written so I could show @kelle the github workflow.

[jfoster17]

Probably there's a discussion somewhere for the rational in using
from astropy.io import fits
instead of
from astropy.io import pyfits
? If so, I've been unable to find it.

From my point-of-view, the vast majority of documentation about accessing FITS files that exists on the web is based on the old model of calling it pyfits. This is going to be a point of great confusion to python novices, who will try to use examples from the web and find that they just don't work (the error message for such a mistake is not immediately useful to a new user).

Tom, while I agree that your method is the best for files with multiple HDUs, my experience is that people find it conceptually less straight-forward. If nothing else, everyone coming from and IDL background will be more comfortable with the procedure-like example I provide than the object-like example you list.

I think the best solution is to have a series of tutorials of increasing depth/complexity. For astropy.io.fits, the full in-depth tutorial already exists in the documentation. Mine is the dead-simple 5 minute lesson. There might logically be space for an intermediate tutorial as well.

[astrofrog]

I'm not sure that there was ever any debate about having pyfits become astropy.io.fits, as everyone agreed that seemed sensible at the time. I do see that it may confuse users slightly, but I think this is only a transition phase. This is similar to asciitable -> astropy.io.ascii, and pywcs -> astropy.wcs - we aren't preserving the original package names, but choosing what makes most sense in the new hierarchy.

Multiple levels of tutorials are fine for me, and you can interlink them (i.e. 'if you need to edit FITS files with multiple HDUs, you might want to check this out instead').

One basic question though - what form are the tutorials going to take? Do you want to have them on a website that looks like the docs? Or ipython notebooks? or another form?

[perrygreenfield]

While it is good to provide guidance to IDL users (e.g., "everyone coming from an IDL background will be more comfortable with the procedure-like example"), we want to be clear that this is not necessarily the recommended approach when using Python tools. There's a balance of making them comfortable in transitioning, but not distorting Python libraries to look like IDL ones, or fostering a usage pattern along those lines. (For pyfits we've always advocated having both functional and object approaches to FITS files; the functional approach is often more convenient in interactive analysis, but for multi-extension files, the object approach is almost always better.)

On Mar 22, 2013, at 2:58 PM, Jonathan Foster wrote:

Tom, while I agree that your method is the best for files with multiple HDUs, my experience is that people find it conceptually less straight-forward. If nothing else, everyone coming from and IDL background will be more comfortable with the procedure-like example I provide than the object-like example you list.

I think the best solution is to have a series of tutorials of increasing depth/complexity. For astropy.io.fits, the full in-depth tutorial already exists in the documentation. Mine is the dead-simple 5 minute lesson. There might logically be space for an intermediate tutorial as well.

—
Reply to this email directly or view it on GitHub.

[adrn]

FWIW, I agree with you guys -- @jfoster17 are you ok with me making changes? Alternatively, you could:

• create a fits-header branch on your own fork of this repo
• merge in my changes (from [email protected]:adrn/astropy-tutorials.git on branch fits-header)
• make any changes you want
• let me know, and I can merge them back in here

[jfoster17]

Okay, fair enough. I approve of import as fits over import as pyfits with appropriate explanation. I still maintain that functional approaches are more appropriate for introductory tutorials, so I think having both explanations is they way to go. @adrn, I'll fork your repo just to get experience doing that.

To answer @astrofrog, I think we decided to try writing some tutorials before settling on a final format, but we were leaning towards a documentation-like website with Sphinx.

[adrn]

@astrofrog @jfoster17 RE: format, that's right -- we're going to write a few tutorials first and then explore using Sphinx to auto-build the examples.

[adrn]

OK @jfoster17 -- your changes have been added to this PR...