astropy/astropy-api — pull request #3 by adrn (2012-10-10 20:06:11+00:00)
Title: Adding plot API for discussion

(Sorry, ignore two corrective commits...)

The idea is to discuss how to handle plotting within the AstroPy package. This means:
* How to enforce consistent plotting API's amongst objects
* What does the interface look like?

**Discussion point:** What name do we choose? _plot()_, _show()_, _display()_?

**Conclusion:** I think plot() is the most natural and is probably what most people with expect, but we will ask for community feedback.

**Discussion point:** Do we make it matplotlib agnostic and enable other backends?

**Conclusion:** For now, we write the code so that the access to the API is generic but defaults to using matplotlib. In the future, if someone wants to implement a way to register other plotting backends or packages, our API won't have to change.

**Discussion point:** What do we do with NDData objects? Should they have a plot() method?

**Conclusion:** An argument *for* the plot() method is that it encourages subclasses to implement this method. An argument *against* the method is that it is really hard to make something generic enough to be useful in many cases. The decision for NDData is to only plot when the number of dimensions <= 2. For more than 2 dimensions, the user is expected to either sum over the other dimensions or slice it however they want to get the object down to 2 dimensions. Then they can use the .plot() method to view the data.

**Discussion point:** How do we incorporate other keyword arguments for customizing the plot?

**No conclusion:** One solution is to not accept any kwargs, and to force the user to use the object-oriented "Axis" object that is returned to retroactively change parameters. The other option is to accept any other keyword arguments, but the problem here is, taking matplotlib as an example, plotting one-dimensional data will use the matplotlib plot() function whereas plotting two-dimensional data will use imshow(), but the user never sees this distinction. I don't think we came to a conclusion, but I implemented one just so we have something to discuss.