expand documentation for `hvncat`

[matthias314]

I would like to suggest that the documentation says more about about the shape variant of the recently added function hvncat. I've been mulling for quite some time over the explanation and the example, but I still don't see how the tuple of tuples shape is related to the output shape. Maybe other users have the same problem.

Also, at present all examples for hvncat concatenate numbers. I think it would be instructive to illustrate that one can apply hvncat to arrays. (This applies to hvcat as well.)

Finally, there exists a method for hvncatwhere the first argument is an Int. Should this also be documented, or is it a private method?

[BioTurboNick]

Sure.

I was thinking these wouldn't typically be used directly, but worth doing. Realized this morning I hadn't expanded the documentation for the int form, as it was a late addition.

Quick example of the shape method.

[a b ; c d e ;;;; f ; g h]
 ___   _____      _   ___
 2     3          1   2    : elements in each row
 ___________      _______  
 5                3        : elements in each column
 ________________________
 8                         : elements in each 3rd dimension slice
 ________________________
 8                         : elements in each 4th dimension slice

shape = (
(2, 3, 1, 2),
(5, 3),
(8,),
(8,)
)

row_first = false inverts the first two elements of shape:

[a ; b ;; c ; d ; e ;;;; f ;; g ; h]
 _____    _________      _    _____
 2        3              1    2     : elements in each column
 __________________      __________  
 5                       3          : elements in each row
 __________________________________
 8                                  : elements in each 3rd dimension slice
 __________________________________
 8                                  : elements in each 4th dimension slice

shape = (
(2, 3, 1, 2),
(5, 3),
(8,),
(8,)
)

Like hvcat's rows argument, they are describing the input shape, not the output shape. The output shape is determined by the input shape and the sizes of the inputs.

[matthias314]

Thanks, that clarifies a lot! I think it would be very useful if something like that goes into the docstring.

I have some more comments about hvncat -- not regarding the documentation, but how the function itself behaves. What's the best way to post them? Shall I continue within this issue (maybe with a revised title), open a new one or hook into some other issue or PR?

[BioTurboNick]

You're welcome!

I just opened an issue #41111 for that purpose, thanks for the prompt!