[AstroPy] astropy.io.fits documentation, suggested rewording

[Erik Bray]

Agreed.  I actually have a bit in the recently added PyFITS FAQ that 
mentions that C/Python, and hence PyFITS use row-major order: 
https://github.com/iguananaut/PyFITS/blob/master/FAQ.txt

It should certainly read that way in the actual docs too.

On 05/12/2012 11:47 PM, Brian Kloppenborg wrote:
> Greetings,
>
> I was reading over the astropy.io.fits documentation
> (http://astropy.readthedocs.org/en/latest/fits/users_guide/users_tutorial.html)
> today and found the following phrase in the "Working with image data"
> section to be confusing:
>
>> "Note that, like C (and unlike FORTRAN), Python is 0-indexed and the
>> indices have the slowest axis first and fast axis last, i.e. for a 2-D
>> image, the fast axis (X-axis) which corresponds to the FITS NAXIS1
>> keyword, is the second index. Similarly, the 1-indexed sub-section of
>> x=11 to 20 (inclusive) and y=31 to 40 (inclusive) would be given in
>> Python as:"
>
> Perhaps we could rewrite this to refer to the indexing by it's name,
> "row-major order," instead? This would give interested parties a name by
> which to look it up.
>
> A drop-in replacement for the text and code sections could be:
>
> """
> "Note that Python, like C, is zero-indexed. The indicies follow
> row-major order (unlike FORTRAN and IDL which use column-major
> indexing). To access the ith row (FITS NAXIS0) and jth column (FITS
> NAXIS1) one specifies
>
> [code]
>  >>> scidata[i,j]
> [\code]
>
> When accessing a subarray of pixel data, rows =31 to 40 (inclusive) and
> columns = 11 to 10 (inclusive) it would be done by decrementing the
> starting index by one (to account for the zero-indexed nature of Python)
> and accessing the subarray using a range of rows and columns thusly:
>
> [code]
>  >>> scidata[30:40, 10:20]
> [\code]
> """
>
> We could also include a link to documentation for interested parties:
> http://en.wikipedia.org/wiki/Row-major_order
>
> I don't think the following bit is required, but if someone wanted to,
> we could write this too:
>
> """
> The index of the [i,j] entry of a 2D array of width 'w' is computed by:
>
> index = i * w + j
> """
>
> or something similar.
>
> Regards,
> Brian Kloppenborg
>
>
> _______________________________________________
> AstroPy mailing list
> AstroPy at scipy.org
> http://mail.scipy.org/mailman/listinfo/astropy