[Numpy-discussion] concatenate, doc-string

[Arnd Baecker]

On Wed, 26 Apr 2006, David M. Cooke wrote:

> Arnd Baecker <arnd.baecker at web.de> writes:
>
> > Hi,
> >
> > the doc-string of concatentate is pretty short:
> >
> > numpy.concatenate?
> > Docstring:
> >     concatenate((a1,a2,...),axis=None).
> >
> > Would the following be better:
> > """
> > concatenate((a1, a2,...), axis=None) joins the tuple  `(a1, a2, ...)` of
> > sequences (or arrays) into a single numpy array.
> >
> > Example::
> >
> >   print concatenate( ([0,1,2], [5,6,7]))
> > """
> >
> > ((The ``(or arrays)`` could be omitted if sequences include array by
> > default, though it might not be obvious to beginners ...))
>
> Here's what I just checked in:
>
>     concatenate((a1, a2, ...), axis=None) joins arrays together
>
>     The tuple of sequences (a1, a2, ...) are joined along the given axis
>     (default is the first one) into a single numpy array.
>
>     Example:
>
>     >>> concatenate( ([0,1,2], [5,6,7]) )
>     array([0, 1, 2, 5, 6, 7])

Great -  many thanks!!

There are some further routines which might benefit
from some more explanation/examples -
so if you don't mind I will try to suggest some additions
(I could check them in directly, I think, but as I am not
a native speaker I feel better to post them here for
review/improvement).

> > I was also tempted to suggest a dtype argument,
> >   concatenate( ([0,1,2], [5,6,7]), dtype=numpy.Float)
> > but I am not sure if that would be a good idea ...
>
> Well, that would require more code, so I didn't do it :-)

;-) It might also be problematic, when one of the sequence
elements would not fit into the output type.

Best, Arnd