Skip to content
Snippets Groups Projects
Commit 0a7041c3 authored by Bert Palm's avatar Bert Palm 🎇
Browse files

more doku

parent 71b606e8
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 86 additions and 29 deletions
docs/aloc_usage.md
+ 86
− 29
View file @ 0a7041c3
......@@ -85,31 +85,32 @@ Some indexer are linked to later sections, where a more detailed explanation and
Values that are list- or array-like, which includes pd.Series, are set on all selected columns. pd.Series align
like `s1.loc[:] = s2` do. See also the [cookbook](/docs/cookbook.md#broadcast-array-likes-to-multiple-columns).
*Indexer Table*
| example | type | on | like `.loc` | handling | conditions | link |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ |
Indexer Table
-------------
| example | type | on | like `.loc` | handling | conditions / hints | link |
| ------- | ---- | --- | ----------- | -------- | ------------------ | ---- |
|[Column indexer](#select-columns-gracefully)|
| `.aloc[any, ['a']]` | scalar | columns |no | select graceful | - | [link](#select-columns-gracefully)|
| `.aloc[any, 'b':'z']` | slice | columns |yes| slice | - | [link](#select-columns-gracefully)|
| `.aloc[any, ['a','c']]` | list-like | columns |no | filter graceful | - | [link](#select-columns-gracefully)|
| `.aloc[any [True,False]]` | bool list-like | columns |yes| take `True`'s , length must match (!) | - | [link](#select-columns-gracefully)|
| `.aloc[any, s]` | pandas.Series | columns |no | like list, only values | - | |
| `.aloc[any, bs]` | bool pandas.Series | columns |yes| like bool-list | - | |
| `.aloc[any, ['a']]` | scalar | columns |no | select graceful | - | [cols](#select-columns-gracefully)|
| `.aloc[any, 'b':'z']` | slice | columns |yes| slice | - | [cols](#select-columns-gracefully)|
| `.aloc[any, ['a','c']]` | list-like | columns |no | filter graceful | - | [cols](#select-columns-gracefully)|
| `.aloc[any [True,False]]` | bool list-like | columns |yes| take `True`'s | length must match nr of columns | [cols](#select-columns-gracefully)|
| `.aloc[any, s]` | pandas.Series | columns |no | like list, | only `s.values` are evaluated | [cols](#select-columns-gracefully)|
| `.aloc[any, bs]` | bool pandas.Series | columns |yes| like bool-list | see there | [cols](#select-columns-gracefully)|
|[Row indexer](#selecting-rows-a-smart-way)|
| `.aloc[7, any]` | scalar | rows |no | translate to `.loc[key:key]` | - | |
| `.aloc[3:42, any]` | slice | rows |yes| slice | - | |
| `.aloc[[1,2,24], any]` | list-like | rows |no | filter graceful | - | |
| `.aloc[[True,False], any]` | bool list-like | rows |yes| take `True`'s, length must match nr of (all selected) columns (!) | - | |
| `.aloc[s, any]` | pandas.Series | rows |no | like `.loc[s.index]` | - | |
| `.aloc[bs, any]` | bool pandas.Series | rows |no | align + just take `True`'s, [1] | - | |
| `.aloc[[[s],[1,2,3]], any]` | nested list-like | both | ? | one row-indexer per column, outer length must match nr of (selected) columns(!) | - | |
| `.aloc[7, any]` | scalar | rows |no | translate to `.loc[key:key]` | - | [rows](#selecting-rows-a-smart-way) |
| `.aloc[3:42, any]` | slice | rows |yes| slice | - | |
| `.aloc[[1,2,24], any]` | list-like | rows |no | filter graceful | - | [rows](#selecting-rows-a-smart-way) |
| `.aloc[[True,False], any]` | bool list-like | rows |yes| take `True`'s | length must match nr of (all selected) columns | [blist](#boolean-array-likes-as-row-indexer)|
| `.aloc[s, any]` | pandas.Series | rows |no | like `.loc[s.index]` | - | [ser](#pandasseries-and-boolean-pandasseries-as-row-indexer) |
| `.aloc[bs, any]` | bool pandas.Series | rows |no | align + just take `True`'s | evaluate `usebool`-keyword | [ser](#pandasseries-and-boolean-pandasseries-as-row-indexer)|
| `.aloc[[[s],[1,2,3]], any]` | nested list-like | both | ? | one row-indexer per column | outer length must match nr of (selected) columns | [nlist](#nested-lists-as-row-indexer) |
|[2D-indexer](#the-power-of-2d-indexer)|
| `.aloc[di]` | dios-like | both |no | full align | - | |
| `.aloc[di, ...]` | dios-like | both |no | full align, ellipsis has no effect | - | |
| `.aloc[di>5]` | bool dios-like | both |no | full align + take `True`'s [1] | - | |
| `.aloc[di>5, ...]` | (bool) dios-like | both |no | full align, disable bool evaluation | - | |
[1] evaluate `usebool`-keyword
| `.aloc[di, ...]` | dios-like | both |no | full align | ellipsis has no effect | |
| `.aloc[di>5]` | bool dios-like | both |no | full align + take `True`'s | evaluate `usebool`-keyword | |
| `.aloc[di>5, ...]` | (bool) dios-like | both |no | full align, **no** bool evaluation | - | |
Example dios
============
......@@ -130,7 +131,7 @@ The dios used in the examples, unless stated otherwise:
Select columns, gracefully
===========================
**single columns**
**Single columns**
Use `.aloc[:, key]` to select a single column gracefully.
The underling pandas Series is returned, if the key exist.
......@@ -150,16 +151,12 @@ Series([], dtype: object)
```
**multiple columns**
**Multiple columns**
Just like selecting *single columns gracefully*, but with a array-like indexer.
A dios is returned, with a subset of the existing columns.
If no key is present a empty dios is returned.
If the key is a pandas.Series, its *values* are used for indexing, especially the Series's index is ignored.
To select all columns simply use `.aloc[:,:]` or even simpler `.aloc[:]`, just like one would do with `loc` or `iloc`.
```
>>> d.aloc[:, ['c', 99, None, 'a', 'x', 'y']]
a | c |
......@@ -185,6 +182,24 @@ d.aloc[:, s]
4 28 | 8 47 | 10 4 |
```
**Boolean indexing, indexing with pd.Series and slice indexer**
**Boolean indexer**, for example `[True, 'False', 'True', 'False']`, must have the same length than the number
of columns, then only columns, where the indexer has a `True` value are selected.
If the key is a **pandas.Series**, its *values* are used for indexing, especially the Series's index is ignored. If a
series has boolean values its treated like a boolean indexer, otherwise its treated as a array-like indexer.
A easy way to select all columns, is, to use null-**slice**es, like `.aloc[:,:]` or even simpler `.aloc[:]`.
This is just like one would do, with `loc` or `iloc`. Of course slicing with boundaries also work,
eg `.loc[:, 'a':'f']`.
For more information about boolean or slice indexing see the pandas documentation
[Slicing ranges](https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#slicing-ranges)
and
[Boolean indexing](https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#boolean-indexing)
Selecting Rows a smart way
==========================
......@@ -328,9 +343,51 @@ as long as the two series objects not have the same index. But maybe one want to
[DictOfSeries.index_of()](/docs/methods_and_properties.md#diosdictofseriesindex_of).
**T_O_D_O - nested lists**
- `.aloc[nested list]` - use a own list-like row indexer on each columns
- sublists can be series, bool-series, lists or bool-lists
Nested-lists as row indexer
---------------------------
It is possible to pass different array-like indexer to different columns, by using nested lists as indexer.
The outer list's length must match the number of columns of the dios. The items of the outer list, all must be
array-like and not further nested. For example list, pandas.Series, boolean lists or pandas.Series, numpy.arrays...
Every inner list-like item is applied as row indexer to the according column.
```
>>> d
a | b | c | d |
===== | ==== | ===== | ===== |
0 0 | 2 5 | 4 7 | 6 0 |
1 7 | 3 6 | 5 17 | 7 1 |
2 14 | 4 7 | 6 27 | 8 2 |
3 21 | 5 8 | 7 37 | 9 3 |
4 28 | 6 9 | 8 47 | 10 4 |
>>> d.aloc[ [d['a'], [True,False,True,False,False], [], [7,8,10]] ]
a | b | c | d |
===== | ==== | ======= | ===== |
0 0 | 2 5 | no data | 7 1 |
1 7 | 4 7 | | 8 2 |
2 14 | | | 10 4 |
3 21 | | | |
4 28 | | | |
>>> ar = np.array([2,3])
>>> d.aloc[[ar, ar+1, ar+2, ar+3]]
a | b | c | d |
===== | ==== | ===== | ==== |
2 14 | 3 6 | 4 7 | 6 0 |
3 21 | 4 7 | 5 17 | |
```
Even this looks like a 2D-indexer, that are explained in the next section, it is not.
In contrast to the 2D-indexer, we also can provide a column key, to pre-filter the columns.
```
>>> d.aloc[[ar, ar+1, ar+3], ['a','b','d']]
a | b | d |
===== | ==== | ==== |
2 14 | 3 6 | 6 0 |
3 21 | 4 7 | |
```
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment