Module ideal

source code

Interface to the qubidl module (in the qubfast library) for efficiently handling sequences of dwells.

An Idealization assigns each sample to one of a limited number of Classes, then condenses this sequence of sampled Classes into a sequence of Dwells: { which class; start sample index; end sample index (inclusive) } Classes are numbered contiguously starting with 0. This module keeps track of each Class's {mean amplitude; standard deviation}.

Previously, Idealizations had been stored as parallel arrays:

>>> int class[]
>>> int first[]
>>> int last[]
>>> (and/or float duration[])

There were problems with this approach:

• editing a portion could change the number of dwells, requiring shifts and/or reallocation
• to read the dwells for samples k through m, we had to search for the first dwell, since dwell index doesn't correlate with sample index

To address these, we use data structures with log(N) edits and seeks (at the core, we use the STL map), and move "chunks" of idealization between storage levels:

• in STL maps: efficient editing and seeking; biggest memory footprint
• in arrays: no editing beyond full replacement; smaller memory footprint

The idealization is divided into chunks of QUB_IDLSEG_CHUNKSIZE samples:

• for lookup: dwells for sample k are in chunk (k >> QUB_IDLSEG_CHUNKSHIFT)
• for map traversal and editing: N events take N log N time, but since there are only so many events per map, it becomes N log M, where log M has a constant upper bound
• for multiple storage levels: only the relevant chunks need to be loaded for reading, or upgraded to "map" for editing.

The chunk size has been experimentally tuned to handle fast data smoothly, but maybe wants adjustment for newer hardware?; adjust QUB_IDLSEG_CHUNKSHIFT (log2(_CHUNKSIZE)) in qubidl.cpp.

The IdlMaps object manages one or more chunks.

Every sample is said to belong to a class. Un-idealized samples belong to dwells of class -1.

.begin(), .find(), and .end() return iterator objects. They don't necessarily iterate over entire dwells; long dwells are broken at chunk boundaries, resulting in a string of dwells of the same class -- to the user they should be represented as one dwell.

Copyright 2008-2012 Research Foundation State University of New York This file is part of QUB Express.

QUB Express is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

QUB Express is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License, named LICENSE.txt, in the QUB Express program directory. If not, see <http://www.gnu.org/licenses/>.