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:  Confirmed Assigned to:  jordigh
Originator Name:  Alexander Klein Originator Email:  -email is unavailable-
Open/Closed:  * Open Release:  * dev
Operating System:  * Any Fixed Release:  None
Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup

Jump to the original submission

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 administrator
Mon 04 Jun 2012 06:59:20 AM UTC, comment #3: 


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 =


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


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?


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 administrator
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.





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

Attach Files:

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 project members can vote.


    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    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.12