Biskit :: BisList :: BisList :: Class BisList

Class BisList


An *abstract* base class that lays out the basic interface for
collections of dictionary-like objects. To the outside, it behaves
like a list, albeit one with a second dimension addressed by
'keys'. You could think of BisList as a kind of two-dimensional
array or a dictionary of lists. However, no assumptions are yet
made as to the internal data structure. BisList provides uniform
methods for sorting, filtering, extraction and combination of
sub-lists (take, compress), and plotting.

Classes derived from BisList have to override several
methods to be functional (a NotImplementedError is raised otherwise):

  * getValue, extend, append, take, keys,
  * __len__, __setitem__, __getslice__

The latter 3 are not yet defined in BisList (no
NotImplementedError) but are nevertheless required. They can also
be provided from the python built-in list type via multiple
inheritence (see L{Biskit.DictList}, for an example).

That means there are two ways of implementing BisList.
  1. via multiple inheritence from BisList (first!) and list
     -> only L{getValue}, L{extend}, L{append} and L{take} need to be
     overriden.
  2. inheritence from BisList only
     -> the __xxx__ methods have to be implemented, too.

See L{DictList} for an example of strategy 1.

Instance Methods

[hide private]

__init__(self)
Override but call.

str version(self)
Returns CVS version of this class (see also attribute initVersion)

any getValue(self, i, key, default=None)
Get the value of a dictionary entry of a list item.

any __add__(c, other)
c + other

any __iadd__(c, other)
c += other

extend(self, other)
Add all items of other to (the end of) this instance.

append(self, v)
Append a single item to the end of this list.

[ any ] keys(self)
Returns attribute keys used by the current items.

[ int ] argsort(self, sortKey, cmpfunc=cmp)
Sort by values of a certain item attribute.

instance take(self, indices, deepcopy=0)
Extract certain items in a certain order.

instance compress(self, mask, deepcopy=0)
Extract certain items.

instance sortBy(self, sortKey, cmpfunc=cmp)
Use:

list valuesOf(self, key, default=None, indices=None, unique=0)
Get all values assigned to a certain key of all or some items.

array filterRange(self, key, vLow, vHigh)
Get indices of items where vLow <= item[ key ] <= vHigh.

array filterEqual(self, key, lst)
Get indices of items for which item[ key ] in lst.

array filterFunct(self, f)
Get indices of items for which f( item ) == 1.

instance filter(self, key, cond)
Extract items matching condition.

int argmax(self, key)
Returns index of item with highest item[key] value

float max(self, key)
Returns item with highest item[key] value

int argmin(self, key)
Returns index of item with lowest item[infokey] value

float min(self, key)
Returns item with lowest item[key] value

int getIndex(self, key, value)
Returns position of item for which item[key] == value

any getItem(self, key, value)
Returns item for which item[key] == value

dict toDict(self, key)
Convert collection into dict indexed by the value of a certain item attribute.

[ item ] toList(self)
Returns simple python list of items

(l1, l2) __maskNone(self, l1, l2)
Take out positions from l1 and l2 that are None in either of them.

Biggles.FramedPlot plot(self, xkey, *ykey, **arg)
Plot pairs of item values.

Biggles.FramedArray plotArray(self, xkey, *ykey, **arg)
Plot pairs of item values.

Method Details

[hide private]

init(self)
(Constructor)

source code

Override but call.

version(self)

source code

Returns: str: CVS version of this class (see also attribute initVersion)

getValue(self, i, key, default=None)

source code

Get the value of a dictionary entry of a list item. Override!

Parameters:

i (int) - position in collection
key (any) - attribute key
default (any) - return value if key is not found [None]

Returns: any: any

add(c, other)
(Addition operator)

source code

c + other

Parameters:

other (instance) - other instance

Returns: any: new instance with one collection appended to the other

iadd(c, other)

source code

c += other

Parameters:

other (instance) - other instance

Returns: any: this instance with other appended

extend(self, other)

source code

Add all items of other to (the end of) this instance. Override!

Parameters:

other (instance) - other instance

append(self, v)

source code

Append a single item to the end of this list. Override!

Parameters:

v (any) - any (left to the implementing class)

keys(self)

source code

Returns: [ any ]: attribute keys used by the current items.

argsort(self, sortKey, cmpfunc=cmp)

source code

Sort by values of a certain item attribute.

Parameters:

sortKey (any) - attribute key
cmpfunc (function) - used for comparing values; cmpfunc(v1,v2) -> -1,0,1 [built-in cmp]

Returns: [ int ]: indices after sorting (the collection itself is not sorted)

take(self, indices, deepcopy=0)

source code

Extract certain items in a certain order. Override!

Parameters:

indices ([ int ]) - positions
deepcopy (0|1) - deepcopy items (default: 0)

Returns: instance: new instance (or sub-class) with specified items

compress(self, mask, deepcopy=0)

source code

Extract certain items.

Parameters:

mask ([ 1|0 ]) - mask of positions; len( mask ) == len( self )
deepcopy (1|0) - deepcopy items (default: 0)

Returns: instance: new instance (or sub-class) with specified items

sortBy(self, sortKey, cmpfunc=cmp)

source code

Use:

 sortBy( sortKey ) -> new instance sorted by item[ sortKey ]

Parameters:

sortKey (any) - key for item attribute
cmpfunc (function) - comparison function

Returns: instance: new instance (or sub-class) sorted by item

valuesOf(self, key, default=None, indices=None, unique=0)

source code

Get all values assigned to a certain key of all or some items. If unique==0, the result is guaranteed to have the same length as the collection (or the list of given indices). Missing values are replaced by default (None).

Parameters:

key (any) - key for item attribute
default (any) - default value if key is not found (default: None)
indices (list of int OR None) - indices defining a subset of this list (default: None)
unique (1|0) - report each value only once (set union), (default 0)

Returns: list: list of values

filterRange(self, key, vLow, vHigh)

source code

Get indices of items where vLow <= item[ key ] <= vHigh.

Parameters:

key (any) - item attribute
vLow (any) - lower bound
vHigh (any) - upper bound

Returns: array: array of int

filterEqual(self, key, lst)

source code

Get indices of items for which item[ key ] in lst.

Parameters:

key (any) - item attribute
lst (list) - [ any ], list of allowed values

Returns: array: array of int

filterFunct(self, f)

source code

Get indices of items for which f( item ) == 1.

Parameters:

f (function) - f must take a single item as argument and return 1 or 0

Returns: array: array of int

filter(self, key, cond)

source code

Extract items matching condition.

Parameters:

key (any) - item attribute (not used if cond is function )

cond (any) - conditon:

            - (vLow, vHigh) -> vLow <= item[ key ] <= vHigh
            - list          -> item[ key ] in cond
            - function      -> cond( c ) == 1

Returns: instance: new instance (or sub-class)

Raises:

ConditionError - if cond is neither list nor tuple nor function:

argmax(self, key)

source code

Parameters:

key (any) - item attribute

Returns: int: index of item with highest item[key] value

max(self, key)

source code

Parameters:

key (any) - item attribute

Returns: float: item with highest item[key] value

argmin(self, key)

source code

Parameters:

key (any) - item attribute

Returns: int: index of item with lowest item[infokey] value

min(self, key)

source code

Parameters:

key (any) - item attribute

Returns: float: item with lowest item[key] value

getIndex(self, key, value)

source code

Parameters:

key (any) - item attribute
value (any) - item value

Returns: int: position of item for which item[key] == value

Raises:

AmbiguousMatch - ItemNotFound, if there are more or less than 1 matches

getItem(self, key, value)

source code

Parameters:

key (any) - item attribute
value (any) - item value

Returns: any: item for which item[key] == value

Raises:

AmbiguousMatch - ItemNotFound, if there are more or less than 1 matches

toDict(self, key)

source code

Convert collection into dict indexed by the value of a certain item attribute. If several items have the same value, the result will have a list registered for this key.

EXAMPLE: lst.toDict('soln') {soln1:Item, soln3:Item, solnN:Item}

Parameters:

key (any) - item attribute

Returns: dict: { info1:dict, info2:dict, info3:[dict, dict].. }

toList(self)

source code

Returns: [ item ]: simple python list of items

__maskNone(self, l1, l2)

source code

Take out positions from l1 and l2 that are None in either of them.

Parameters:

l1 (list) - first list
l2 (list) - second list

Returns: (l1, l2): modified lists

plot(self, xkey, *ykey, **arg)

source code

Plot pairs of item values. The additional arg arguments are handed over to biggles.Points(). The special xkey value 'index' uses the position of each item as x-axis. If only one key is given, it is taken as ykey and the x-axis is the index of each item (xkey='index').

EXAMPLE: plot( xkey, [ykey1, ykey2..],[arg1=x, arg2=y]) -> biggles.FramedPlot

Parameters:

xkey (any) - key for x-values
ykey (any) - key for y-values
arg (any) - arguments handed over to biggles.Points()

Returns: Biggles.FramedPlot: Biggles.FramedPlot, display with show() !

plotArray(self, xkey, *ykey, **arg)

source code

Plot pairs of item values.

EXAMPLE: plot( xkey, [ykey1, ykey2..],[arg1=x, arg2=y])

         -> biggles.FramedPlot

Parameters:

xkey (any) - key for x-values
ykey (any) - key for y-values
arg (any) - arguments handed over to biggles.Points()

Returns: Biggles.FramedArray: Biggles.FramedArray, display with show()

Class BisList

__init__(self) (Constructor)

version(self)

getValue(self, i, key, default=None)

__add__(c, other) (Addition operator)

__iadd__(c, other)

extend(self, other)

append(self, v)

keys(self)

argsort(self, sortKey, cmpfunc=cmp)

take(self, indices, deepcopy=0)

compress(self, mask, deepcopy=0)

sortBy(self, sortKey, cmpfunc=cmp)

valuesOf(self, key, default=None, indices=None, unique=0)

filterRange(self, key, vLow, vHigh)

filterEqual(self, key, lst)

filterFunct(self, f)

filter(self, key, cond)

argmax(self, key)

max(self, key)

argmin(self, key)

min(self, key)

getIndex(self, key, value)

getItem(self, key, value)

toDict(self, key)

toList(self)

__maskNone(self, l1, l2)

plot(self, xkey, *ykey, **arg)

plotArray(self, xkey, *ykey, **arg)

init(self)
(Constructor)

add(c, other)
(Addition operator)

iadd(c, other)