bugGNU Octave - Bugs: bug #36236, Boolean indexing not too prominent...

 
 

bug #36236: Boolean indexing not too prominent in the docs.

Submitter:  None
Submitted:  Wed 18 Apr 2012 07:21:10 AM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  3 - Low Item Group:  Documentation
Status:  Fixed Assigned to:  jordigh
Originator Name:  Alexander Klein Originator Email:  -email is unavailable-
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 23 Feb 2024 03:58:20 PM UTC, comment #11: 

no concerns in a week. going to close this as fixed (only 12 years!). other requests can go into a new report.

Nicholas Jankowski <nrjank>
Group Member
Sat 17 Feb 2024 04:02:47 AM UTC, comment #10: 

pushed https://hg.savannah.gnu.org/hgweb/octave/rev/6d5d39d52953 to stable.

Adds subsections to the Index expressions page, one for each type of indexing.  Adds the logical index section moving most of the example from the logical values page.  Expanded examples a bit.  Also added subsections to Advanced indexing page and added a piece about chained indexing being valid in octave.

that should more than take care of this doc request. marking as ready for test in case I missed or misstated somethnig.

Nicholas Jankowski <nrjank>
Group Member
Fri 16 Feb 2024 10:18:08 PM UTC, comment #9: 

nevermind. I just checked the behavior with matlab and all of the results match.  smaller indexes map to linear order, and larger ones do the same with an error if any true positions are beyond numel(x).

e.g.,:


>> lmap = [true, true, false; true, true, true; false true true]

lmap =

  3×3 logical array

   1   1   0
   1   1   1
   0   1   1

>> a(lmap)
The logical indices contain a true value outside of the array bounds.


Nicholas Jankowski <nrjank>
Group Member
Fri 16 Feb 2024 10:12:25 PM UTC, comment #8: 

working up a doc update to the Indexing Expressions page, making explicit subsections for the 3 indexing types (one being to add logical indexing as per this report).

it was never quite answered if Octave's logical indexing behavior is intended when the size of the index doesn't match the size of the object. whether smaller or larger, it appears to force linear indexing order of elements for selection by the logical map.  if larger, any size is valid for false elements, but any true elements doing a logical index on a linear position greater than numel(x) triggers an out of bound error.  eg:



釁쿅error: 'reshap' undefined near line 1, column 5
>> a = reshape(1:8,2,4)
a =

   1   3   5   7
   2   4   6   8

>> lmap =[true, false; true, false]
lmap =

  1  0
  1  0

>> a(lmap)
ans =

   1
   2

>> lmap =[true, false true, false]
lmap =

  1  0  1  0

>> a(lmap)
ans =

   1   3

>> lmap = [true, true, true; true, true, true; true true false]
lmap =

  1  1  1
  1  1  1
  1  1  0

>> a(lmap)
ans =

   1
   2
   3
   4
   5
   6
   7
   8

੘ӿ
>> lmap = [true, true, false; true, true, true; false true false]
lmap =

  1  1  0
  1  1  1
  0  1  0

>> a(lmap)
ans =

   1
   2
   4
   5
   6
   8


Nicholas Jankowski <nrjank>
Group Member
Tue 18 Apr 2023 08:41:47 PM UTC, comment #7: 

8.2.0, no change to any mention of either boolean indexing or logical indexing in the docs in quite some time. doesn't seem any text to add has been proposed yet.

from old mailing lists, the text on (https://docs.octave.org/v8.2.0/Logical-Values.html) has been the same since <2008.  A paragraph after detailing the different uses of logical values includes "Logical values can also be used to index matrices and cell arrays..." followed by a simple example. 

The note about boolean indexing on the Basic Vectorization page (https://docs.octave.org/v8.2.0/Basic-Vectorization.html) also unchanged.

No mention of logical indexing on the pages for Index Expressions (https://docs.octave.org/v8.2.0/Index-Expressions.html) or Advanced Indexing (https://docs.octave.org/v8.2.0/Advanced-Indexing.html)

If there is still a desire to improve the docs around this, I'd suggest adding a Logical Indexing page just in front of Advanced Indexing, linked from the same place.  Not sure how many details/examples should go there beyond the simple one on the Logical Values page, apart from detailing the shape behavior discussed in comment #3.

Nicholas Jankowski <nrjank>
Group Member
Tue 18 Feb 2020 09:27:13 PM UTC, comment #6: 

as of v5.2.0 I don't believe there has been any change on this doc request.

Nicholas Jankowski <nrjank>
Group Member
Sat 19 Nov 2016 09:38:14 PM UTC, comment #5: 

This documentation wish hasn't become better in Octave 4.2.0, yet.

Hartmut <hardy>
Thu 04 Jun 2015 01:09:59 AM UTC, comment #4: 

Revisiting this old dormant bug.

Re comment #3, the main question is why does a logical index array with out-of-range true values return an error but there is no error when all out-of-range values are false:


>> a = rand (5);
>> a(false (20))
>> ans = [](0x1)


?

I don't have an answer, just asking if that is the only thing blocking a documentation patch to resolve this bug report?

Mike Miller <mtmiller>
Group Member
Mon 04 Jun 2012 06:59:20 AM UTC, comment #3: 

Hello,

I just found some time to fix the documentation concerning boolean indexing, and wondered if the following is intended behaviour:

octave:44> a=rand(5)
a =

   0.590252   0.785107   0.789109   0.973847   0.037473
   0.720128   0.552948   0.529387   0.712228   0.285633
   0.097387   0.498243   0.368774   0.341973   0.272160
   0.302804   0.645076   0.383922   0.550020   0.883258
   0.181661   0.969068   0.376169   0.458497   0.294898

octave:45> b=a(1:3,1:3)>0.5
b =

   1   1   1
   1   1   1
   0   0   0

octave:46> a(b)
ans =

   0.59025
   0.72013
   0.30280
   0.18166
   0.55295
   0.49824

octave:47> a(1:rows(b),1:columns(b))(b)
ans =

   0.59025
   0.72013
   0.78511
   0.55295
   0.78911
   0.52939

octave:48> a(rand(7)>0.5)
error: A(I): index out of bounds; value 48 out of bound 25
octave:48> a(-rand(7)>0.5)
ans = [](0x1)

So, what we get in more than one dimension is vec(<array>)(find(vec(<boolean>))), which is OK, and seems to be the only way to go for equally sized arrays and boolean indices, but we get index errors only for out of bounds true indices, and puzzling results without a warning when the indexing array is smaller than the indexed array.

Is this really what we want?

Alex

Alexander Klein <matalex>
Wed 09 May 2012 07:20:46 AM UTC, comment #2: 

Why not, but probably not until next week.

Alexander Klein <matalex>
Wed 09 May 2012 03:46:35 AM UTC, comment #1: 

Yes, I agree that logical indexing really needs to be more prominent. And with more examples.

Can you suggest how to do this? I mean, actually write the modifications to the manual? Don't worry if you can't do it in TeXinfo. I can fix that up, but if you could contribute the actual prose to write and where to insert it, that would be very useful.

Jordi Gutiérrez Hermoso <jordigh>
Group Member
Wed 18 Apr 2012 07:21:10 AM UTC, original submission:  

I was just browsing the manual, and I noticed that 'boolean indexing' seems to be mentioned exactly once, namely in the section about 'Basic vectorization'.

The section about index expressions, however, states that "Indices may be scalars, vectors, ranges, or the special operator ‘:’, which may be used to select entire rows or columns."

I think boolean indexing should be made more prominent, since although I've been using Octave for nearly a decade, boolean indexing managed to escape my notice until only a few weeks ago.

Thanks,

Alex

Anonymous

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by nrjank (Posted a comment)
  • -email is unavailable- added by hardy (Posted a comment)
  • -email is unavailable- added by matalex (Posted a comment)
  • -email is unavailable- added by jordigh (Posted a comment)
  • -email is unavailable- added by None (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 12 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-02-23 nrjank StatusReady For Test Fixed
        Open/ClosedOpen Closed
        Fixed ReleaseNone 9.1.0
    2024-02-17 nrjank StatusConfirmed Ready For Test
        Planned ReleaseNone 9.1.0
    2019-03-01 mtmiller Carbon-CopyRemoved 80942 -
    2015-06-04 mtmiller Severity3 - Normal 2 - Minor
        Priority5 - Normal 3 - Low
        Release3.6.1 dev
    2013-10-29 mtmiller CategoryNone Documentation
    2012-05-09 jordigh StatusNone Confirmed
        Assigned toNone jordigh

    Back to the top

    Powered by Savane 3.13-12ab.
    Corresponding source code