bugGNU Octave - Bugs: bug #48088, document that issquare, iscolumn,...

 
 

bug #48088: document that issquare, iscolumn, isempty, etc operate on cell arrays

Submitter:  Francesco Potortì <pot>
Submitted:  Thu 02 Jun 2016 11:26:40 AM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  3 - Low Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  9.1.0 Planned Release:  9.1.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 16 Feb 2024 05:59:11 AM UTC, comment #16: 

That should have a hyphen:

"...is a single-element object of any type..."

changed in https://hg.savannah.gnu.org/hgweb/octave/rev/388c87433483

Nicholas Jankowski <nrjank>
Group Member
Fri 16 Feb 2024 05:27:25 AM UTC, comment #15: 

(Not a native speaker)
Is "element object" commonly understood in English?

> A scalar is a single element object of any type for which @code{size (@var{x})}
> returns @w{@code{[1, 1]}}.

Markus Mützel <mmuetzel>
Group administrator
Fri 16 Feb 2024 02:45:49 AM UTC, comment #14: 

ok, you're right. object array is pretty awkward.  "a 2-D array of any type for which size returns..." works better. Made that change in many of the functions below and pushed to stable as:
https://hg.savannah.gnu.org/hgweb/octave/rev/0b8f3470d1fb

closing report again.

Nicholas Jankowski <nrjank>
Group Member
Wed 14 Feb 2024 10:10:36 PM UTC, comment #13: 

I'm still of the opinion that object is the right word to use. Even the Octave docs have a section about built-in data types named 'Numeric Objects', and it talks about the different built-in classes including numeric ones. But I do see where the nomenclature gets muddy, and I also like using 'array' as the generic term and only matrix where that's specifically the right one. I think maybe the following would work if this an improvement i'll push a patch later:

issquare

Return true if X is a 2-D square array.

     A square array is any 2-D object array for which 'size (X)' returns '[N, N]' where N is a non-negative integer.


isvector

    Return true if X is a vector.

     A vector is any 2-D object array where one of the dimensions is equal to 1
     (either 1xN or Nx1).  As a consequence of this definition, a 1x1
     array (a scalar) is also a vector.


isscalar

   Return true if X is a scalar.

     A scalar is any single element 2-D object for which 'size (X)'
         returns '[1, 1]'.


ismatrix

  Return true if X is a matrix.

     A matrix is an any object array where 'ndims (X) == 2' and for
     which 'size (X)' returns '[M, N]' with non-negative M and N.


isrow (and similar for iscolumn)

     Return true if X is a row vector.

     A row vector is any 2-D object array for which 'size (X)' returns '[1, N]'
     with non-negative N.


isnull

    Return true if X is a special null array, string, or single quoted
     string.
<snip>


isdiag

    Return true if A is a diagonal numeric matrix, defined as a 2-D array
where all elements above and below the main diagonal are zero.


isbanded

 Return true if A is a numeric matrix with non-zero entries confined between
 LOWER diagonals below the main diagonal and UPPER diagonals above the
     main diagonal.

     LOWER and UPPER must be non-negative integers.


issymmetric

 Return true if A is a symmetric or skew-symmetric numeric matrix within the
     tolerance specified by TOL.


istril

    Return true if A is a lower triangular numeric matrix.

     A lower triangular matrix has nonzero entries only on the main
     diagonal and below.


istriu

   Return true if A is an upper triangular numeric matrix.

     An upper triangular matrix has nonzero entries only on the main
     diagonal and above.


ishermitian

    Return true if A is a Hermitian or skew-Hermitian numeric matrix within the
     tolerance specified by TOL.
<snip>


isdefinite

    Return true if A is symmetric positive definite numeric matrix within the
     tolerance specified by TOL.
<snip>


Nicholas Jankowski <nrjank>
Group Member
Wed 14 Feb 2024 04:01:08 PM UTC, comment #12: 

looking over at how matlab documents things, they use 'array' as a general descriptor which has always been my preference as an array can be an array of anything. We also have a lot of document language referring to matrices that isn't always correct anymore because functions can extend to n-D arrays, in addition to the notion (as inspired comment #0) that a matrix is generally considered to be a 2-D numeric array, whereas a 2-D array need not be numeric.

Nicholas Jankowski <nrjank>
Group Member
Wed 14 Feb 2024 03:55:46 PM UTC, comment #11: 

ok, sometime between this report being opened and v6.4.0 a number of the functions inspiring the initial inquiry had language updated to use 'object', so my patch was just to bring the rest in line.

Yes, I can see why Object could be seen as implying something class-related, even though technically doubles, chars, etc., are built-in classes that the language still covers. 

Let me play with some language across the things in comment #7 and post back for opinions.

Nicholas Jankowski <nrjank>
Group Member
Wed 14 Feb 2024 09:02:07 AM UTC, comment #10: 

Maybe, replace "object" by "array of any kind" (e.g., "A vector is a 2-D array of any kind where one of the dimensions is equal to 1") to make clearer that the type doesn't matter.

Markus Mützel <mmuetzel>
Group administrator
Wed 14 Feb 2024 08:19:06 AM UTC, comment #9: 

I'm not sure if "object" is the correct term here. At least for me, "object" hints that this would only apply to some class or classdef values.

The previous documentation didn't specify that it only applies to double arrays or double matrices. At least for me that meant that it applied to any kind of arrays or matrices including arrays of cells/structs/uint64/...

Markus Mützel <mmuetzel>
Group administrator
Tue 13 Feb 2024 09:46:20 PM UTC, comment #8: 

rebased and pushed the docstring changes for for isrow, iscolumn, isempty, and isvector to stable:

https://hg.savannah.gnu.org/hgweb/octave/rev/f034172cb600

closing report as fixed.

Nicholas Jankowski <nrjank>
Group Member
Fri 12 Nov 2021 04:22:46 AM UTC, comment #7: 

i think the term object is generic enough to address the issue in the bug. but i notice it's not consistent across all functions mentioned.

in Octave 6.4.0:

issquare:

     Return true if X is a 2-D square array.

     A square array is a 2-D object for which 'size (X)' returns
     '[N, N]' where N is a non-negative integer.


isrow (same with iscolumn):

     Return true if X is a row vector.

     A row vector is a 2-D array for which 'size (X)' returns '[1, N]'
     with non-negative N.


isempty:

     Return true if A is an empty matrix (any one of its dimensions is
     zero).


ismatrix:

     Return true if X is a 2-D array.

     A matrix is an object with two dimensions ('ndims (X) == 2') for
     which 'size (X)' returns '[M, N]' with non-negative M and N.


isvector:

     Return true if X is a vector.

     A vector is a 2-D array where one of the dimensions is equal to 1
     (either 1xN or Nx1).  As a consequence of this definition, a 1x1
     array (a scalar) is also a vector.


isscalar:

     Return true if X is a scalar.

     A scalar is an object with two dimensions for which 'size (X)'
     returns '[1, 1]'.


isnull, isdiag, issymettric, istril, and istriu are specific to matrices, so no changes there.  I don't see any others in the is* list.

Attached is a patch that makes the docstring changes for isrow, iscolumn, isempty, and isvector to use the 'object' terminology (all in data.cc).

The revised docstrings:

isrow (and column):

     Return true if X is a row vector.

     A row vector is a 2-D object for which 'size (X)' returns '[1, N]'
     with non-negative N.


isempty:

     Return true if A is an empty object (any one of its dimensions is
     zero).


isvector:

     Return true if X is a vector.

     A vector is a 2-D object where one of the dimensions is equal to 1
     (either 1xN or Nx1).  As a consequence of this definition, a 1x1
     object (a scalar) is also a vector.


Please add a comment if there are other functions i missed.


(file #52255)

Nicholas Jankowski <nrjank>
Group Member
Mon 19 Apr 2021 03:15:06 PM UTC, comment #6: 

Yes, I think this is probably good enough and certainly better than my initial proposal

The only drawback is that we are defining here what an array is.  The manual only speaks about character arrays, cell arrays, struct arrays, Java arrays.  The notion that an "array" is a generic concept including also matrices would probably be a useful addition to the manual, especially for use in function descriptions, as this is not unique to issquare.

Francesco Potortì <pot>
Sun 07 Mar 2021 05:51:58 AM UTC, comment #5: 

For version 6.1.0


help issquare
'issquare' is a built-in function from the file libinterp/corefcn/data.cc

 -- issquare (X)
     Return true if X is a 2-D square array.

     A square array is a 2-D object for which 'size (X)' returns
     '[N, N]' where N is a non-negative integer.

     See also: isscalar, isvector, ismatrix, size.


This is better than comment #0.
Francesco, what are your thoughts?

Anonymous
Fri 24 Jun 2016 03:41:24 PM UTC, comment #4: 

Well, certainly the word "matrix" should either removed from the help or accompanied by other possible types to which issquare applies.

Ideally, I would like to find something along these lines:

return true if X is square.
X can be a matrix, cell array or any other type for which size(X) returns [r, c] with r == c.

Maybe your proposal is good as well.

Francesco Potortì <pot>
Fri 24 Jun 2016 04:43:00 AM UTC, comment #3: 

The Matlab documentation often lists the types a function can be applied to.

However, "help isrow" for example, simply gives the definition in terms of "size", without mentioning whether the argument is a matrix, a cell array or a class object.

Perhaps "issquare" could say
  Return true of X has size(X) = [r, c] with r == c.

Francesco, would that be sufficient for you?

Lachlan Andrew <lachlan>
Thu 02 Jun 2016 03:13:16 PM UTC, comment #2: 

Should be briefly mentioned in all functions. The way I use the documentation, it would be almost useless otherwise.

Francesco Potortì <pot>
Thu 02 Jun 2016 02:42:04 PM UTC, comment #1: 

This applies to all the "shape" functions, isempty, isrow, iscolumn, issquare, ismatrix, isvector, etc.

Should each function have to mention cell arrays? Or should the documentation section on cell arrays say something like "many functions that operate on matrices also apply to cell arrays")?

Mike Miller <mtmiller>
Group Member
Thu 02 Jun 2016 11:26:40 AM UTC, original submission:  


> help issquare

'issquare' is a built-in function from the file libinterp/corefcn/data.cc

 -- Function File: issquare (X)
     Return true if X is a square matrix.

     See also: isscalar, isvector, ismatrix, size.

Francesco Potortì <pot>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #52255:  issquare_on_object_docfix_bug48088.diff added by nrjank (2KiB - application/octet-stream)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mmuetzel (Posted a comment)
  • -email is unavailable- added by nrjank (Updated the item)
  • -email is unavailable- added by lachlan (Posted a comment)
  • -email is unavailable- added by siko1056 (Updated the item)
  • -email is unavailable- added by pot (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 16 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-02-16 nrjank Open/ClosedOpen Closed
    2024-02-16 nrjank StatusIn Progress Fixed
    2024-02-14 nrjank Open/ClosedClosed Open
    2024-02-14 nrjank StatusFixed In Progress
    2024-02-13 nrjank StatusPatch Submitted Fixed
        Open/ClosedOpen Closed
        Fixed ReleaseNone 9.1.0
        Planned ReleaseNone 9.1.0
    2021-11-12 nrjank Attached File- Added issquare_on_object_docfix_bug48088.diff, #52255
        StatusConfirmed Patch Submitted
    2019-03-04 mtmiller Release4.0.2 dev
    2019-03-04 mtmiller Carbon-CopyRemoved 80942 -
    2016-06-02 mtmiller SummaryDocs from issquare() should mention that it works for cell arrays too. document that issquare, iscolumn, isempty, etc operate on cell arrays
    2016-06-02 mtmiller Severity3 - Normal 2 - Minor
    2016-06-02 siko1056 Priority5 - Normal 3 - Low
        StatusNone Confirmed

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code