matplotlib-devel Mailing List for matplotlib

Mark Bakker wrote:
> I agree that the new logo looks nice, but I also think that
> Rob is right: When you see the logo you wouldn't know that
> we are talking about a general purpose plotting package.
> So the question is: are we going for looks over meaning?
> I guess the other way around would be terrible: choosing
> meaning over looks you are stuck with an ugly logo that
> carries the right message. So to me, looks it is,
I'm just happy the red-on-green is gone. My colorblind eyes thank whoever 
changed this.
-- 
Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
 -- Umberto Eco

Tony Yu skrev:
> 
> On Jun 3, 2008, at 4:18 PM, Jörgen Stenarson wrote:
>> using an empty mathtext "$$" in labels generates an exception. See
>> example and traceback below.
> 
> My guess is that this is a LaTeX error. If you enter $$ in a normal 
> LaTeX document, you will get:
> 
>
I don't think so. I'm using mathtext i.e. matplotlibs own latex 
interpreter. And I get the same error with $$ $$.
/Jörgen

Eric Firing wrote:
> Stephane Raynaud wrote:
> 
>> Hi,
>>
>> date2num and num2date perform conversion between datetime and 'days
>> since 0001年01月01日' and vice versa.
>> For such task, they strictly use ordinal dates for their numeric days,
>> 1 meaning '0001-01-01' by definition.
>> Thus, date2num(datetime.datetime(1,1,1,0,0,0)) return 1. which is
>> supposed to mean '1 days since 0001', which is wrong (because it
>> points to datetime.datetime(1,1,2,0,0,0)).
>>
>> Since year zero cannot be used (here for time units) because it
>> doesn't exist, don't you think that the ordinal date
>> (datetime.datetime(1,1,2,0,0,0).tordinal()) should not be strictly
>> used as a reference numeric time, but its value-1?
>> 
>
> Stephane, yes, what you say makes sense. Long ago I settled on a 
> convention of using "decimal days" referenced to the start of a 
> "yearbase" for time calculations and for plotting variables against 
> time. So if the yearbase is 2008, then noon on January 1 of 2008 is 
> 0.5. The more common convention in oceanography, though, was to label 
> days of the year with a 1-based count and then add the fraction of the 
> day, so what is 0.5 to me is 1.5 to many others. In this case, where 
> the time scale origin (the start of the yearbase) might be in the middle 
> of one's time series, the decimal day definition is clearly superior (at 
> least to me). But in the case of the matplotlib dates module the 
> distinction is less important, because the origin is quite arbitrary and 
> will almost always be far smaller than the minimum of the range plotted. 
> The datenum is mainly useful for calculations, not for direct display. 
> Note that the datetime module (and therefore mpl.dates) simply doesn't 
> work for BC dates.
>
> Personally, I would be perfectly happy to implement your suggestion so 
> that the reality would correspond to the dates module docstring; but 
> maybe this would break some user code, so others might prefer to modify 
> the docstring to reflect the present behavior instead.
>
> John, I suspect you wrote the dates module and use it heavily--what do 
> you think about the two methods of bringing the docstring and the 
> behavior into alignment? Any problem with fixing the behavior?
>
> Eric
>
> 
Eric:
There are alternate versions num2date and a date2num in basemap that 
handle arbitrary calendars (not just 'proleptic gregorian') and 
arbitrary reference times (not just 'days since 0001年01月01日 00:00:00'). 
The docstrings are at 
http://matplotlib.sourceforge.net/mpl_toolkits.basemap.basemap.html, 
down near the bottom of the page.
I don't know if this addresses the problem you're talking about though...
-Jeff
-- 
Jeffrey S. Whitaker Phone : (303)497-6313
Meteorologist FAX : (303)497-6449
NOAA/OAR/PSD R/PSD1 Email : Jef...@no...
325 Broadway Office : Skaggs Research Cntr 1D-113
Boulder, CO, USA 80303-3328 Web : http://tinyurl.com/5telg

Ted,
I agree entirely--we do need a better date-handling module than what can 
be built on the feeble and clumsy datetime standard module. It would be 
nice to have this as part of numpy, so it can be vectorized from the 
start. I have some code that I use; I will have to check to see what 
its limits are.
Eric
Ted Drain wrote:
> Just a note (that I realize will probably never get 'fixed'):
> 
> It would be nice if MPL could support more arbitrary date ranges (such as
> negative numeric dates). This comes up more often than you might think.
> Try writing a GUI w/ an embedded date plot - you can't switch a plot to date
> format until you reset the range so it doesn't contain a zero and you can't
> autoscale plots w/o data. In addition, we do plot things from a long time
> ago every once in awhile. It would be nice if you could switch an arbitrary
> plot to date format and not worry about the formatter throwing an exception
> because the plot range isn't quite to its liking. There are algorithms for
> handling numeric <-> calendar conversions that work for all time (at least
> from 0 Julian Date == -4700'ish BC).
> 
> http://en.wikipedia.org/wiki/Julian_date
> 
> A switch to Julian date format for the numeric value would 'fix' these
> problems though that would break existing data sets so I realize it's
> unlikely to happen.
> 
> At some point in the future, I'll put a little test case together to show
> how the problems w/ not supporting a zero date show up in embedded plots.
> 
> Ted
> 
>> -----Original Message-----
>> From: mat...@li...
>> [mailto:mat...@li...] On Behalf Of
>> Eric Firing
>> Sent: Tuesday, June 03, 2008 1:29 PM
>> To: Stephane Raynaud; John Hunter
>> Cc: Matplotlib
>> Subject: Re: [matplotlib-devel] date2num/num2date and ordinal date
>>
>> Stephane Raynaud wrote:
>>> Hi,
>>>
>>> date2num and num2date perform conversion between datetime and 'days
>>> since 0001年01月01日' and vice versa.
>>> For such task, they strictly use ordinal dates for their numeric
>> days,
>>> 1 meaning '0001-01-01' by definition.
>>> Thus, date2num(datetime.datetime(1,1,1,0,0,0)) return 1. which is
>>> supposed to mean '1 days since 0001', which is wrong (because it
>>> points to datetime.datetime(1,1,2,0,0,0)).
>>>
>>> Since year zero cannot be used (here for time units) because it
>>> doesn't exist, don't you think that the ordinal date
>>> (datetime.datetime(1,1,2,0,0,0).tordinal()) should not be strictly
>>> used as a reference numeric time, but its value-1?
>> Stephane, yes, what you say makes sense. Long ago I settled on a
>> convention of using "decimal days" referenced to the start of a
>> "yearbase" for time calculations and for plotting variables against
>> time. So if the yearbase is 2008, then noon on January 1 of 2008 is
>> 0.5. The more common convention in oceanography, though, was to label
>> days of the year with a 1-based count and then add the fraction of the
>> day, so what is 0.5 to me is 1.5 to many others. In this case, where
>> the time scale origin (the start of the yearbase) might be in the
>> middle
>> of one's time series, the decimal day definition is clearly superior
>> (at
>> least to me). But in the case of the matplotlib dates module the
>> distinction is less important, because the origin is quite arbitrary
>> and
>> will almost always be far smaller than the minimum of the range
>> plotted.
>> The datenum is mainly useful for calculations, not for direct
>> display.
>> Note that the datetime module (and therefore mpl.dates) simply doesn't
>> work for BC dates.
>>
>> Personally, I would be perfectly happy to implement your suggestion so
>> that the reality would correspond to the dates module docstring; but
>> maybe this would break some user code, so others might prefer to modify
>> the docstring to reflect the present behavior instead.
>>
>> John, I suspect you wrote the dates module and use it heavily--what do
>> you think about the two methods of bringing the docstring and the
>> behavior into alignment? Any problem with fixing the behavior?
>>
>> Eric
>>
>> -----------------------------------------------------------------------
>> --
>> This SF.net email is sponsored by: Microsoft
>> Defy all challenges. Microsoft(R) Visual Studio 2008.
>> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
>> _______________________________________________
>> Matplotlib-devel mailing list
>> Mat...@li...
>> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>> Checked by AVG.
>> Version: 8.0.100 / Virus Database: 269.24.6/1480 - Release Date:
>> 6/3/2008 7:00 AM
> 
> 
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2008.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

On Tue, Jun 3, 2008 at 3:41 PM, Ted Drain <ted...@jp...> wrote:
> At some point in the future, I'll put a little test case together to show
> how the problems w/ not supporting a zero date show up in embedded plots.
Actually, when you pass in python datetime objects to mpl, we use the
units converter infrastructure to convert these under the hood using
date2num. This is fairly easy to override in the units registry. If
you provide a registry to do conversions, locators and formatters for
julian dates, I can easily include it with an rc setting to make a
configurable default.
The date interface is setup in the matplotlib.dates module with the
following code -- all you have to do is provide a different converter
and we can provide a hook
 class DateConverter(units.ConversionInterface):
 def axisinfo(unit):
 'return the unit AxisInfo'
 if unit=='date':
 majloc = AutoDateLocator()
 majfmt = AutoDateFormatter(majloc)
 return units.AxisInfo(
 majloc = majloc,
 majfmt = majfmt,
 label='',
 )
 else: return None
 axisinfo = staticmethod(axisinfo)
 def convert(value, unit):
 if units.ConversionInterface.is_numlike(value): return value
 return date2num(value)
 convert = staticmethod(convert)
 def default_units(x):
 'return the default unit for x or None'
 return 'date'
 default_units = staticmethod(default_units)
 units.registry[datetime.date] = DateConverter()
 units.registry[datetime.datetime] = DateConverter()

On Jun 3, 2008, at 4:18 PM, Jörgen Stenarson wrote:
> using an empty mathtext "$$" in labels generates an exception. See
> example and traceback below.
My guess is that this is a LaTeX error. If you enter $$ in a normal 
LaTeX document, you will get:
pdflatex -interaction=nonstopmode -file-line-error-style exited with 
status 1
This error comes from the fact that double dollar signs ($$) are used 
to wrap display equations (single dollar signs are used to wrap inline 
equations). If you were to instead write "$ $" (or "$$ $$"), you 
shouldn't get an error.
-Tony

Just a note (that I realize will probably never get 'fixed'):
It would be nice if MPL could support more arbitrary date ranges (such as
negative numeric dates). This comes up more often than you might think.
Try writing a GUI w/ an embedded date plot - you can't switch a plot to date
format until you reset the range so it doesn't contain a zero and you can't
autoscale plots w/o data. In addition, we do plot things from a long time
ago every once in awhile. It would be nice if you could switch an arbitrary
plot to date format and not worry about the formatter throwing an exception
because the plot range isn't quite to its liking. There are algorithms for
handling numeric <-> calendar conversions that work for all time (at least
from 0 Julian Date == -4700'ish BC).
http://en.wikipedia.org/wiki/Julian_date
A switch to Julian date format for the numeric value would 'fix' these
problems though that would break existing data sets so I realize it's
unlikely to happen.
At some point in the future, I'll put a little test case together to show
how the problems w/ not supporting a zero date show up in embedded plots.
Ted
> -----Original Message-----
> From: mat...@li...
> [mailto:mat...@li...] On Behalf Of
> Eric Firing
> Sent: Tuesday, June 03, 2008 1:29 PM
> To: Stephane Raynaud; John Hunter
> Cc: Matplotlib
> Subject: Re: [matplotlib-devel] date2num/num2date and ordinal date
> 
> Stephane Raynaud wrote:
> > Hi,
> >
> > date2num and num2date perform conversion between datetime and 'days
> > since 0001年01月01日' and vice versa.
> > For such task, they strictly use ordinal dates for their numeric
> days,
> > 1 meaning '0001-01-01' by definition.
> > Thus, date2num(datetime.datetime(1,1,1,0,0,0)) return 1. which is
> > supposed to mean '1 days since 0001', which is wrong (because it
> > points to datetime.datetime(1,1,2,0,0,0)).
> >
> > Since year zero cannot be used (here for time units) because it
> > doesn't exist, don't you think that the ordinal date
> > (datetime.datetime(1,1,2,0,0,0).tordinal()) should not be strictly
> > used as a reference numeric time, but its value-1?
> 
> Stephane, yes, what you say makes sense. Long ago I settled on a
> convention of using "decimal days" referenced to the start of a
> "yearbase" for time calculations and for plotting variables against
> time. So if the yearbase is 2008, then noon on January 1 of 2008 is
> 0.5. The more common convention in oceanography, though, was to label
> days of the year with a 1-based count and then add the fraction of the
> day, so what is 0.5 to me is 1.5 to many others. In this case, where
> the time scale origin (the start of the yearbase) might be in the
> middle
> of one's time series, the decimal day definition is clearly superior
> (at
> least to me). But in the case of the matplotlib dates module the
> distinction is less important, because the origin is quite arbitrary
> and
> will almost always be far smaller than the minimum of the range
> plotted.
> The datenum is mainly useful for calculations, not for direct
> display.
> Note that the datetime module (and therefore mpl.dates) simply doesn't
> work for BC dates.
> 
> Personally, I would be perfectly happy to implement your suggestion so
> that the reality would correspond to the dates module docstring; but
> maybe this would break some user code, so others might prefer to modify
> the docstring to reflect the present behavior instead.
> 
> John, I suspect you wrote the dates module and use it heavily--what do
> you think about the two methods of bringing the docstring and the
> behavior into alignment? Any problem with fixing the behavior?
> 
> Eric
> 
> -----------------------------------------------------------------------
> --
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2008.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> Checked by AVG.
> Version: 8.0.100 / Virus Database: 269.24.6/1480 - Release Date:
> 6/3/2008 7:00 AM

On Tue, Jun 3, 2008 at 3:29 PM, Eric Firing <ef...@ha...> wrote:
> John, I suspect you wrote the dates module and use it heavily--what do you
> think about the two methods of bringing the docstring and the behavior into
> alignment? Any problem with fixing the behavior?
The only thing I am worried about is people who have saved the
date2num output in pickle files or other array storage formats.
Changing the offset by 1 will break this data. This argues for
changing the docstring to accurately reflect what the code does,
rather than changing the code to reflect the docstring.
But I could be persuaded otherwise.
JDH

Stephane Raynaud wrote:
> Hi,
> 
> date2num and num2date perform conversion between datetime and 'days
> since 0001年01月01日' and vice versa.
> For such task, they strictly use ordinal dates for their numeric days,
> 1 meaning '0001-01-01' by definition.
> Thus, date2num(datetime.datetime(1,1,1,0,0,0)) return 1. which is
> supposed to mean '1 days since 0001', which is wrong (because it
> points to datetime.datetime(1,1,2,0,0,0)).
> 
> Since year zero cannot be used (here for time units) because it
> doesn't exist, don't you think that the ordinal date
> (datetime.datetime(1,1,2,0,0,0).tordinal()) should not be strictly
> used as a reference numeric time, but its value-1?
Stephane, yes, what you say makes sense. Long ago I settled on a 
convention of using "decimal days" referenced to the start of a 
"yearbase" for time calculations and for plotting variables against 
time. So if the yearbase is 2008, then noon on January 1 of 2008 is 
0.5. The more common convention in oceanography, though, was to label 
days of the year with a 1-based count and then add the fraction of the 
day, so what is 0.5 to me is 1.5 to many others. In this case, where 
the time scale origin (the start of the yearbase) might be in the middle 
of one's time series, the decimal day definition is clearly superior (at 
least to me). But in the case of the matplotlib dates module the 
distinction is less important, because the origin is quite arbitrary and 
will almost always be far smaller than the minimum of the range plotted. 
 The datenum is mainly useful for calculations, not for direct display. 
Note that the datetime module (and therefore mpl.dates) simply doesn't 
work for BC dates.
Personally, I would be perfectly happy to implement your suggestion so 
that the reality would correspond to the dates module docstring; but 
maybe this would break some user code, so others might prefer to modify 
the docstring to reflect the present behavior instead.
John, I suspect you wrote the dates module and use it heavily--what do 
you think about the two methods of bringing the docstring and the 
behavior into alignment? Any problem with fixing the behavior?
Eric

Hi,
using an empty mathtext "$$" in labels generates an exception. See 
example and traceback below.
/Jörgen
from pylab import *
from numpy import *
x=arange(0,2*pi,0.1)
plot(x,sin(x))
title(r"$$")
show()
Exception in Tkinter callback
Traceback (most recent call last):
 File "C:\python25\lib\lib-tk\Tkinter.py", line 1403, in __call__
 return self.func(*args)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\backends\backend_tkagg.py", 
line 188, in resize
 self.show()
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\backends\backend_tkagg.py", 
line 191, in draw
 FigureCanvasAgg.draw(self)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\backends\backend_agg.py", 
line 255, in draw
 self.figure.draw(self.renderer)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\figure.py", 
line 796, in draw
 for a in self.axes: a.draw(renderer)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\axes.py", 
line 1494, in draw
 a.draw(renderer)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\text.py", 
line 295, in draw
 bbox, info = self._get_layout(renderer)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\text.py", 
line 195, in _get_layout
 line, self._fontproperties, ismath=self.is_math_text(line))
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\backends\backend_agg.py", 
line 134, in get_text_width_height_descent
 self.mathtext_parser.parse(s, self.dpi, prop)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\mathtext.py", 
line 2706, in parse
 box = self._parser.parse(s, font_output, fontsize, dpi)
 File 
"c:\python\external\matplotlib-trunk\build\lib.win32-2.5\matplotlib\mathtext.py", 
line 2186, in parse
 str(err)]))
ValueError:
$$
^
Expected end of text (at char 0), (line:1, col:1)

2008年6月3日 Darren Dale <dar...@co...>:
> On Sunday 01 June 2008 04:10:45 am Pierre Raybaut wrote:
>
 Sorry, I didn't mean to seem brusque. If there is a problem with
> matplotlib's
> qt4 support, I would prefer to have a chance to look into it before the
> problem is announced to the pyqt community.
>
No problem, I understand your concern and completely agree: I'll be more
cautious in the future.
>
> I tried putting some print statements in backend_qt4agg to see how long it
> was
> taking to draw the canvas:
>
> def draw( self ):
> """
> Draw the figure when xwindows is ready for the update
> """
>
> if DEBUG: print "FigureCanvasQtAgg.draw", self
> self.replot = True
> d0 = time.time()
> FigureCanvasAgg.draw(self)
> d = time.time()
> print d-d0, 'agg:draw'
> d0=d
> self.update()
> print time.time()-d0, 'qt4:update'
>
> FigureCanvasAgg.draw(self) takes about .02 seconds, and self.update() takes
> less than .0004 seconds. FigureCanvasAgg.draw is independent of qt/pyqt, so
> it look like panning/zooming is limited only by how fast matplotlib/agg can
> draw the canvas on my machine, which has qt-4.4.0 and PyQt4-4.4.2.
>
On my computer, FigureCanvasAgg.draw(self) takes 16 ms (basically the same
duration as yours), and self.update() takes 0 second, for both PyQt 4.3.3
and 4.4.2 - and there is still clearly a display performance issue with
release 4.4.2 (apparently, the draw and update features take the same time,
but on screen, panning/zooming refresh rate is clearly lower than with PyQt
4.3.3).
So it seems that it is not a good way to measure the display performance,
and honestly I don't know maplotlib enough to see how to do the right
benchmark.
Pierre

On Sunday 01 June 2008 04:10:45 am Pierre Raybaut wrote:
> > Hi Pierre,
> >
> > On Friday 30 May 2008 5:21:01 pm Pierre Raybaut wrote:
> >> > First, I would like to congratulate you for your work on Matplotlib. I
> >> > am using Matplotlib widgets in all my current projects, embedded in
> >> > PyQt graphical user interfaces.
> >> >
> >> > As you may know, PyQt 4.4.2 has been released a few days ago.
> >> > And I found out a performance bug when embedding a Matplotlib 0.91.2
> >> > canvas in a PyQt 4.4.2 object: the pan/zoom feature is very slow (with
> >> > PyQt 4.3.3, and the exact same scripts, pan/zoom is real-time).
> >
> > Would it be possible to post some benchmarks, something a little more
> > concrete, like specifically what calls are taking the most time, and how
> > they compare for the different versions of PyQt?
>
> Yes of course, I will send the requested informations as soon as I can.
>
> >> > I am posting this in PyQt mailing-list too, but I guess that you could
> >> > have more ideas on that matter (Matplotlib widgets may not be used
> >> > very often in PyQt).
> >
> > Please don't do that. Its not fair to the people who volunteer their time
> > on open source projects to try to draw so many people into the problem
> > before the problem is understood.
>
> Wow... I did not expect this reaction! :) The only reason that I posted
> on the two mailing-list was to be sure to inform everyone who was
> potentially interested by the topic. Otherwise, if I was really trying
> outrageously to draw many people into the problem, I wouldn't have
> mentioned the post on the other mailing-list, would I? Thanks for the
> warm welcome though ;)
Sorry, I didn't mean to seem brusque. If there is a problem with matplotlib's 
qt4 support, I would prefer to have a chance to look into it before the 
problem is announced to the pyqt community.
I tried putting some print statements in backend_qt4agg to see how long it was 
taking to draw the canvas:
 def draw( self ):
 """
 Draw the figure when xwindows is ready for the update
 """
 if DEBUG: print "FigureCanvasQtAgg.draw", self
 self.replot = True
 d0 = time.time()
 FigureCanvasAgg.draw(self)
 d = time.time()
 print d-d0, 'agg:draw'
 d0=d
 self.update()
 print time.time()-d0, 'qt4:update'
FigureCanvasAgg.draw(self) takes about .02 seconds, and self.update() takes 
less than .0004 seconds. FigureCanvasAgg.draw is independent of qt/pyqt, so 
it look like panning/zooming is limited only by how fast matplotlib/agg can 
draw the canvas on my machine, which has qt-4.4.0 and PyQt4-4.4.2.
Darren

Hi,
date2num and num2date perform conversion between datetime and 'days
since 0001年01月01日' and vice versa.
For such task, they strictly use ordinal dates for their numeric days,
1 meaning '0001-01-01' by definition.
Thus, date2num(datetime.datetime(1,1,1,0,0,0)) return 1. which is
supposed to mean '1 days since 0001', which is wrong (because it
points to datetime.datetime(1,1,2,0,0,0)).
Since year zero cannot be used (here for time units) because it
doesn't exist, don't you think that the ordinal date
(datetime.datetime(1,1,2,0,0,0).tordinal()) should not be strictly
used as a reference numeric time, but its value-1?
--
Stephane Raynaud

Hi all
I only read this thread today, and see that we have been battling many
of the same challenges in our documentation efforts. I am glad to see
that you are making such good progress!
2008年6月1日 John Hunter <jd...@gm...>:
>> I just realized, though, that I should probably be striving to conform with
>> the standard that the numpy and scipy folks put together:
>> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and
>> http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? I
>> think I have been relying too heavily on tables for the keyword arguments.
>
> I think that following their guidelines is a good idea for the most
> part, but we needn't adhere to them religiously. For one thing,
> matplotlib uses *a lot* more keyword args than either numpy or scipy,
> and what works for them for kwargs may not be best for us. In
> particular, if we use the format they suggest, I'm afraid our
> docstrings will simply take up too much space. For example, see
> http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-none
> . What if we formatted all the Line2d kwargs that way? It seems a
> bit bloated in terms of vertical space for the number of kwargs we
> need to handle, and so a ReST table may in fact be better.
I'd like to explain the rationale behind our approach. Our main focus
was to write produce documentation that is easy to read from a
text-based terminal. While designing our standard, we set aside all
other concerns, such as markup, compatibility with existing tools,
etc. After the standard was more-or-less finalised, we wrote a tool
which parses docstrings into logical units. For example,
In [5]: d = SphinxFunctionDoc(np.ravel)
In [6]: d['Parameters']
Out[6]:
[('a', '{array_like}', ['']),
 ('order',
 "{'C','F'}, optional",
 ["If order is 'C' the elements are taken in row major order. If order",
 "is 'F' they are taken in column major order."])]
In [7]: print d
**ravel(a, order='C')**
-----------------------
Return a 1d array containing the elements of a (copy only if needed).
[...]
Note that, when printing the docstring, it looks entirely different
from the original docstring, and contains customised markup. If you
wanted to use a table to describe keyword arguments, for example, it
would require only a few extra lines of code.
If you are interested in playing with the code, it is available at
https://code.launchpad.net/~stefanv/scipy/numpy-refguide
We also developed a web-framework that allows our community to write
documentation:
http://sd-2116.dedibox.fr/pydocweb
While it was written with NumPy in mind (we have some weird docstring
injection, not unlike yours), it should be trivial to modify for use
by another project.
Good luck!
Stéfan

Erik Tollerud wrote:
> While going through and updating some scripts to use the new features
> that were recently added to hist(), I found myself very confused by
> the align keywords - I had to go and look at Manuel Metz's post a
> couple weeks ago to believe it wasn't a typo in the documentation...
> "center" and "edge" are exactly the opposite of what one would have
> thought (as he noted)... I've attached a diff of my proposed solution
> - accepting the old keywords for backwards-compatibility, but have the
> documentation only mention two keywords that make more sense ('left'
> and 'mid').
> 
> I've added two other features as well - for some of the histograms I'm
> making, it makes sense to have plots that are cumulative from the left
> instead of the right - with this patch, that's allowed by passing in
> cumulative=-1 (or anything else that is less than 0 - True still
> operates the way it did before). To make this also easier from the
> perspective of how some might want the histogram to look, I've also
> added a 'right' option to the 'align' keyword.
> 
> Hopefully these changes will now satisfy all possible uses that anyone
> can imagine for a histogram. :)
> 
Hi Erik,
 yup - the keywords are currently _very_ misleading. I guess the 
original reason for these keywords was that they were just passed to the 
bar/barh method. Now that hist() was updated I thought about 
changing/adapting the align keyword, but didn't manage to get this in 
before 0.98 was released :-( Your suggestions look good to me ...
Manuel