Previous topic

metadata module

Next topic

evaluate module

This Page

testcollection module

class bregman.testcollection.KeyMapper(adb=None, num_patterns=100)
A helper class to manage key encodings for TestCollection instances
list_key_instances()
Search adb.liszt() for instances of GROUND_TRUTH_KEY, list (KEY,POS)
map_forward(param_dict, count_key=True, key=None, suffix='')
param_dict -> key="md5 hash on sorted dict"+".instance_count"
map_inverse(key, suffix='')
key="md5 hash on sorted values" -> dict(keys, values)
class bregman.testcollection.RhythmPLCATest(path=None, num_components=3, num_channels=3, num_patterns=100, root_path='/home/mcasey/exp')
A class to create Rhythm Streams in PLCA timbre channels. Works as for RhythmStreamTest but audio synthesis
is RhythmTest (summed timbre channels) and extract_features performs timbre-channel extraction.    
extract_features(extract_only=False, wave_suffix='.wav')
Override of TestCollection.feature_extraction() method to perform PLCA and KMeans cluster extraction
Extract features from audio collection and insert into audiodb instance in the following order:
   Extract TestCollection features by feature_params[...]
   PLCA extraction and timbre-channel clustering on GT features (training)
   PLCA extraction and timbre-channel assignment on Transformation faetures (testing)
   Write new timbre-channel features (replacing old)
   insert_features_into_audioDB -> audiodb
   A TestCollection instance is a test_set instance consisting of self.num_patterns ground-truth patterns 
   audio files and self.num_patterns transformed patterns audio files.
extract_timbre_channels(key, keyrepl, train=True, wave_suffix='.wav')
For given audio files in test_collection:
  clear rTupleList (list of keys and feature/power files to insert against associated keys)
  map audio_file keys matching *key* to feature keys
  for each feature_file:
   insert timbre-channel keys, powers, features into rTupleList
   Perform PLCA using self.num_components
   Perform clustering on collection of GT W functions (classify only if train=False)
   Sum H functions into channels by per-segment cluster assignments
   Write features as c timbre-channel feature files replacing original feature file                     
   Write Z functions as '.probs'
synthesize_audio(patterns=None, syn_params=None, suffix='')
Generate audio from given rhythm patterns using self.syn_fun()
Reverts to TestCollection.synthesize_audio because we want mixed audio to test PLCA extraction.
class bregman.testcollection.RhythmStreamTest(path=None, num_channels=3, num_patterns=100, root_path='/home/mcasey/exp')

“”

A TimbreCollection class based on RhythmTest for rhythm sequences in timbre channels

Input arguments;
Stored instance:
path: directory containing an instance of a previously saved RhythmTest [None]
Data will be loaded into this instance ready for adding more test sets and evaluating
New instance:
num_channels: how many timbre channels [3] num_patterns: how many rhythm patterns to generate in this collection [100] root_path: path to root directory for holding rhythm test collections [audiocollection.DATA_ROOT=”$HOME/exp”]
Data members:

patterns - integer bit-field representation of num_patterns patterns for subdiv subdivisions transformations - random transformations of each pattern by flipping n_flip_bits in each of rand_channels seq_params - pattern generation and transformations parameters syn_params - audio synthesis from patterns parameters syn_fun - audio synthesis algorithm [testsignal.rhythm] feature_params - audio feature extraction parameters

default syn_params dict for the collection:
‘sr’ : 48000, # sample rate ‘bw’ : [80., 2500., 1000.], # band-widths ‘cf’ : [110., 5000., 16000.], # center-frequencies ‘dur’: [0.5, 0.5, 0.5] # relative duration of timbre ‘normalization’ : ‘none’ # balance timbre channels ‘none’, ‘maxabs’, ‘rms’, ‘norm’
default seq_params dict for the collection:
‘poiss_channels’ : [.25, .25, .25], # Poisson parameter per channel ‘n_flip_bits’ : 1, # number of perturbed (transformed) subdivisions ‘rand_channels’ : [0], # timbre channels on which to perform n_flip_bits ‘subdiv’ : 16, # subdivision of 4/4 measure ‘tempo’ : 120. # tempo of rhythmic sequences
evaluate(test_set_key=None, clear_lists=True)
Overridden method from RhythmTest for timbre channels
 Map distances and weights for each query in each channel
 Reduce using Bhattacharyya distance metric.

 Sets self.ranks_list, self.dists_list
 Display ranked results as in print_results()

Evaluate ranks and distances for each ground-truth pattern against a set of rhythm transformations
by retrieval of transformed patterns using original patterns as queries.

test_set_key: a test-set hash-key identifier as returned by get_test_lists()
clear_lists: set to True to make a fresh set of results lists for this evaluation
             set to False to append current evaluation to previsouly stored lists
Returns a tuple (ranks,dists)
Each element of the tuple contains len(test_set_list) lists, 
 each list contains ground-truth ranks, and whole-dataset distances, of each test-set 
 in the test_set_list
setup_evaluation(test_set_list, timbre_channel_offset)
Overridden method for timbre-channel setup evaluation.
Load a adb database as a python object
Initialize search parameters
Evaluate retrieval of each ground-truth pattern against a set of transformations
Level-1 evaluation:
   - retrieval of ground-truth patterns from a collection of transformed patterns
synthesize_audio(patterns=None, syn_params=None, suffix='')
Overridden method from RhythmTest for timbre channels
Synthesize audio into separate timbre-channel wave files

Create wavs from self.patterns n-tuples and self.syn_params
   Write audio files to self.collection_path

   Arguments:
     patterns -  music sequences to synthesize in format expected by self.syn_fun            
     suffix   -  unique identifier suffix if required [usually a parameter key]

   Special case: syn_params['num_timbre_channels'] must be same value as feature_params[...],
   required for rendering pattern audio into separate timbre channels prior to feature extraction
timbre_channel_distance(ikeys, rkeys, dists)
Reduce timbre-channel distances to ranked list by relevant-key-index 
class bregman.testcollection.RhythmTest(path=None, num_patterns=100, root_path='/home/mcasey/exp')
A TestCollection class for rhythm sequences

Input arguments;
  Stored instance:
   path: directory containing an instance of a previously saved RhythmTest [None]
         Data will be loaded into this instance ready for adding more test sets and evaluating

  New instance:
   num_patterns: how many rhythm patterns to generate in this collection [100]
   root_path: path to root directory for holding rhythm test collections [audiocollection.DATA_ROOT="$HOME/exp"]

  Data members:
    patterns  - integer bit-field representation of num_patterns patterns for subdiv subdivisions
    transformations - random transformations of each pattern by flipping n_flip_bits in each of rand_channels
    seq_params - pattern generation and transformations parameters
    syn_params  - audio synthesis from patterns parameters
    syn_fun - audio synthesis algorithm [testsignal.rhythm]
    feature_params - audio feature extraction parameters

    default syn_params dict for the collection:
        'sr' : 48000,        # sample rate
        'bw' : [80., 2500., 1000.], # band-widths
        'cf' : [110., 5000., 16000.], # center-frequencies
        'dur': [0.5, 0.5, 0.5] # relative duration of timbre
        'normalization' : 'none' # balance timbre channels 'none', 'maxabs', 'rms', 'norm'

    default seq_params dict for the collection:
        'poiss_channels' : [.25, .25, .25], # Poisson parameter per channel
        'n_flip_bits' : 1, # number of perturbed (transformed) subdivisions
        'rand_channels' : [0], # timbre channels on which to perform n_flip_bits
        'subdiv' : 16, # subdivision of 4/4 measure
        'tempo' : 120. # tempo of rhythmic sequences
run_test()
Pre-conditions:
  self.intialize() has been called
  self.syn_params is set to desired values
  self.feature_params is set to desired values

Post-conditions:
  Generated random synthetic rhythm patterns, synthesized audio, extracted features, persisted in an adb database
  Generated pattern transformations, synthesized audio, extracted features, persisted in an adb database
  Saved state and data in an audioDB instance identified by feature_params
    the corresponding adb_database name is unique to self.feature_params.
sequence_patterns()
Map: self.seq_params -> num_patterns x random sequence
Generate a set of poisson random percussive patterns from self.seq_params
Returns a list of multi-timbre patterns as (a,b,c,...) integer n-tuples
transform_patterns()
Given a set of M base patterns over T timbres perform
transformation by:
   n_flip_bits: randomly flipping n pattern bits in rand_channels
   delta_cf: add amount to cf of each channel
   delta_bw: add amount to bw of each channel
class bregman.testcollection.TestCollection(num_patterns=100, path=None, root_path='/home/mcasey/exp')
Base class for test collections, stub

TestCollection objects encapsulate audio test sets, database instances, ground truth, and evaluators

Classes derived from the TestCollection base class do the following:
 * Generate musical sequences via sequence parameters
 * Automatically generate ground truth lists
 * Generate audio test sets according to synthesis parameters
 * Analyze audio collection via feature extractor parameters
 * Manage audioDB database instances to store and search the audio features
 * Evaluate multiple test sets using automatically generated ground truth
 * Report on Evaluations in various formats: text output, file output, graphs
collection_results(plotting=False, title_param=None, evaluate=False)
Collect, print, and, optionally, reevaluate all the results in the collection.
Re-evaluation collects all the results into the current instance, which are then saved.
evaluate(test_set_key=None, clear_lists=True)
Evaluate ranks and distances for each ground-truth pattern against a set of rhythm transformations
by retrieval of transformed patterns using original patterns as queries.

test_set_key: a test-set hash-key identifier as returned by get_test_lists()
clear_lists: set to True to make a fresh set of results lists for this evaluation
             set to False to append current evaluation to previsouly stored lists
Returns a tuple (ranks,dists)
Each element of the tuple contains len(test_set_list) lists, 
 each list contains ground-truth ranks, and whole-dataset distances, of each test-set 
 in the test_set_list
evaluation_loop(sequencer_dict_list=None, synthesizer_dict_list=None, analyzer_dict_list=None)
Comprehensive evaluation: a time and space efficient workflow
Iterations over sequencing, synthesis, and analysis parameters
extract_features(extract_only=False, wave_suffix='.wav')
Extract features from audio collection and insert into audiodb instance in the following order:
   check for an audioDB instance on current feature_params, create if none
   ground truth patterns - hex32hash(0) + hex4(key_count) -> audioDB
   variation patterns    - hex32hash(seq_params + self.syn_params) + hex4(key_count) -> audioDB
   insert_features_into_audioDB -> audiodb

   an instance is a test_set instance consisting of self.num_patterns audio files.
gen_pattern_set(save_patterns=False)
Generate set patterns according to self.seq_params
Write audio, extract features
Persist in an audioDB (adb) database
gen_transformation_set(save_transformations=False)
Generate transformations of self.patterns using seq_params
Persist transformation set parameters via a pattern key
get_mean_ranks()
Display mean ranks for each test set
Requires either load_results or evaluate() to have been called
get_test_sets()
Return a list of data sets in this database instance.
Each data set is indexed by the transformation parameters using a hash code.
Mutliple instances of the same parameters are allowed and are counted.
Use print_test_sets() to get a more readable display
initialize()
Generate a new TestCollection instance and ground-truth set
Uses the current values in self.seq_params to make pattern set.
key_map_inverse(key)
Return parameter dict for give key
load(data_path=None)
Load patterns and data paths:
   self.collection_path - the location of the current data set
   self.collection_stem - the stem name of the collection
   self.patterns - integer representation of each rhythm pattern
   self.adb_path - the name of the base rhythm patterns database
   self.num_patterns - number of rhythm patterns == len(self.adb.liszt())
   self.seq_params - pattern sequencer parameters
   self.syn_params - audio synthesis parameters
   self.feature_params - audio feature extraction parameters
load_results()
Load a previously-saved evaluation result set
print_results(test_set_list=None)
Display the mean ranks of rank lists.
print_test_sets()
Print the test sets in a readable format:
save()
Save current patterns and transformations, and data paths.
   self.collection_path - the location of the current data set
   self.collection_stem - the stem name of the collection
   self.adb_path - the name of the base rhythm patterns database
   self.num_patterns - number of rhythm patterns == len(self.adb.liszt())
   self.seq_params - pattern sequencer parameters
   self.syn_params - audio synthesis parameters
   self.feature_params - audio feature extraction parameters

   self.patterns - integer representation of each rhythm pattern
   self.transformations - integer representation of each rhythm transformation for n_flip_bits and [rand_channels]
save_results()
Persist last evaluation result set to a file
sequence_patterns()
Implement this method to generate ground-truth patterns from self.seq_params
setup_evaluation(test_set_list)
Load a adb database as a python object
Initialize search parameters
Evaluate ranks and distances for each ground-truth pattern against a set of transformations
Level-1 evaluation:
   - retrieval of ground-truth patterns from a collection of transformed patterns
synthesize_audio(patterns=None, syn_params=None, suffix='')
Synthesize audio from self.patterns n-tuples and self.syn_params
Write audio files to self.collection_path

Arguments:
  patterns -  music sequences to synthesize in format expected by self.syn_fun
  suffix   -  unique identifier suffix if required [usually a parameter key]
transform_patterns()
Implement this method to transform self.patterns to self.transformations via self.seq_params