started advanced doku, added examples and todos and rought structure

Readme.md

@@ -273,6 +273,7 @@ Work mostly like analogous methods from pd.DataFrame.
 - `to_string()`
 - `apply()`
 - `astype()`
+- `isin()`
 - `isna()`
 - `notna()`
 - `dropna()`

docs/aloc_usage.md

+`aloc` usage
+=========
+
+Purpose
+- select gracefully, so rows or columns, that was given as indexer, but doesn't exist, don't raise an error
+- align series/dios-indexer 
+- setting multiple columns at once with a list-like value
+
+Example dios
+---------
+
+The dios used in the examples, unless stated otherwise:
+
+``` 
+>>> 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 | 
+```
+
+Select columns, gracefully
+---------------------------
+
+**single columns**
+
+Use `.aloc[:, key]` to select a single column gracefully. 
+The underling pandas Series is returned, if the key exist. 
+Otherwise a empty pd.Series with `dtype=object` is returned.
+
+```
+>>> d.aloc[:, 'a']
+0     0
+1     7
+2    14
+3    21
+4    28
+Name: a, dtype: int64
+
+>>> d.aloc[:, 'x']
+Series([], dtype: object)
+```
+
+
+**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 | 
+===== | ===== | 
+0   0 | 4   7 | 
+1   7 | 5  17 | 
+2  14 | 6  27 | 
+3  21 | 7  37 | 
+4  28 | 8  47 | 
+
+>>> d.aloc[:, ['x', 'y']]
+Empty DictOfSeries
+Columns: []
+
+s = pd.Series(dict(a='a', b='x', c='c', foo='d'))
+d.aloc[:, s]
+    a |     c |     d | 
+===== | ===== | ===== | 
+0   0 | 4   7 | 6   0 | 
+1   7 | 5  17 | 7   1 | 
+2  14 | 6  27 | 8   2 | 
+3  21 | 7  37 | 9   3 | 
+4  28 | 8  47 | 10  4 | 
+```
+
+Selecting Rows a smart way
+--------------------------
+
+Overview: 
+
+|                      |        |
+| ------               | ------ |
+| `.aloc[s]`           | like `.loc[s.index]` |
+| `.aloc[list]`        | handle graceful |
+| `.aloc[bool list]`   | no merci, length must match all (selected) columns |
+| `.aloc[bool series]` | align index and just take `True`'s -- [1]  |
+| `.aloc[key]`         | translate to `.loc[key:key]` |
+[1] evaluate `usebool`-keyword
+
+Note for the curios: *Because of `.aloc[key]` translates to `.loc[key:key]`, dios never return a single item, 
+nor a columns-indexed Series*.
+
+**T_O_D_O**
+
+The power of 2D-indexer
+-----------------------
+
+Overview: 
+
+|                      |        |
+| ------               | ------ |
+| `.aloc[nested lists]`      | use different indexer-types on different columns |
+| `.aloc[bool-dios]`         | 1. align columns, 2. align rows, 3. just take `True`'s  -- [1] |
+| `.aloc[dios, ...]` (use Ellipsis)        | 1. align columns, 2. align rows, (3.) ignore values  -- [1] |
+[1] evaluate `usebool`-keyword
+
+
+**T_O_D_O**
+

docs/cookbook.md

+
+Recipes
+-------
+- select common rows from all columns
+- align columns to an other column
+- align columns to a given index
+- align dios with dios
+- get/set values by condition
+- apply a value to multiple columns
+- nan-policy - mask vs. drop values, when nan's are inserted (mv to Readme ??)
+- itype - when to use, pitfalls and best-practise
+- changing the index of series' in dios (one, some, all)
+- changing the dtype of series' in dios (one, some, all)
+- changing properties of series' in dios (one, some, all)
+
+**T_O_D_O**

docs/methods_and_properties.md

+Dios Methods and Properies
+========================
+
+Methods
+--------
+
+- `copy()`
+- `copy_empty()`
+- `all()`
+- `any()`
+- `squeeze()`
+- `to_df()`
+- `to_string()`
+- `apply()`
+- `astype()`
+- `isin()`
+- `isna()`
+- `notna()`
+- `dropna()`
+- `memory_usage()`
+- `index_of()`
+- `in`
+- `is`
+- `len(Dios)`
+
+TODO: make brief description table
+
+
+Properties
+----------
+- columns
+- indexes (series of indexes of all series's)
+- lengths (series of lengths of all series's)
+- values (not fully pd-like - np.array of series's values)
+- dtypes
+- itype  (see section Itype)
+- empty 
+- size
+
+TODO: make brief description table