SB2_ControlSettings.py

# The following is a Python translation of a MATLAB file originally written principally by Mike Tipping
# as part of his SparseBayes software library. Initially published on GitHub on July 21st, 2015.

# SB2_CONTROLSETTINGS  Set parameters to control the SPARSEBAYES algorithm
#
# CONTROLS = SB2_CONTROLSETTINGS
#
# OUTPUT ARGUMENTS:
# 
#    CONTROLS    A structure whose fields control various aspects of the
#                running of the SPARSEBAYES algorithm.
# 
#    .ZeroFactor            Small number equivalent to zero for Q^2-S
#    .MinDeltaLogAlpha    Termination criterion for changes in log-alpha
#    .MinDeltaLogBeta    Termination criterion for changes in log-beta
# 
#    .PriorityAddition    Prefer "addition" operations
#    .PriorityDeletion    Prefer "deletion" operations
# 
#    .BetaUpdateStart    How many "fast start" beta updates
#    .BetaUpdateFrequency    
#                        How regularly to update beta after the above
#    .BetaMaxFactor        Minimum value control for noise estimate
# 
#    .PosteriorModeFrequency    
#                        How regularly to re-find the posterior mode
# 
#    .BasisAlignmentTest    Test for redundant basis vectors?
#    .AlignmentMax        Basis redundancy criterion
# 
# NOTES:
# 
# The various definitions in the file are effectively "fixed" and not
# modified elsewhere.
#
# The interested user may wish to experiment with the operation of the
# SPARSEBAYES algorithm by modifying the values the file directly. See the
# inline comments for hints on the various control settings.
#

#
# Copyright 2009, Vector Anomaly Ltd
#
# This file is part of the SPARSEBAYES library for Matlab (V2.0).
#
# SPARSEBAYES 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 2 of the License, or (at your option)
# any later version.
#
# SPARSEBAYES 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 along
# with SPARSEBAYES in the accompanying file "licence.txt"; if not, write to
# the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
# MA 02110-1301 USA
#
# Contact the author: m a i l [at] m i k e t i p p i n g . c o m
#

def SB2_ControlSettings():
    
    ## Define parameters which influence the underlying operation of the 
    ## SparseBayes inference algorithm
    
    CONTROLS = {}
    
    # TOLERANCES
    
    # Any Q^2-S "relevance factor" less than this is considered to be zero
    
    CONTROLS['ZeroFactor']              = 1e-12
    
    # If the change in log-alpha for the best re-estimation is less than this,
    # we consider termination
    
    CONTROLS['MinDeltaLogAlpha']        = 1e-3
    
    # In the Gaussian case, we also require a beta update to change the value
    # of log-beta (inverse noise variance) less than this to terminate
    
    CONTROLS['MinDeltaLogBeta']         = 1e-6
    
    # ADD/DELETE
     
    # - preferring addition where possible will probably make the algorithm a
    # little slower and perhaps less "greedy"
    
    # - preferring deletion may make the model a little more sparse and the
    # algorithm may run slightly quicker
    
    # Note: both these can be set to 'true' at the same time, in which case
    # both take equal priority over re-estimation.
    
    CONTROLS['PriorityAddition']        = False
    CONTROLS['PriorityDeletion']        = True
    
    # (GAUSSIAN) NOISE
    
    # When to update the noise estimate
    
    # The number of iterations from the start for which we update it every
    # iteration (to get in the right ball-park to begin with)
    
    CONTROLS['BetaUpdateStart']         = 10
    
    # After the above, we only regularly update it after 
    # a given number of iterations
    
    CONTROLS['BetaUpdateFrequency']     = 5
    
    # Prevent zero-noise estimate (perfect fit) problem
    # -    effectively says the noise variance estimate is clamped to be no
    #    lower than variance-of-targets / BetaMaxFactor.
     
    CONTROLS['BetaMaxFactor']           = 1e6

    # POSTERIORMODE

    # How many alpha updates to do in between each full posterior mode
    # computation in the non-Gaussian case
    
    # In principle, this should be set to one (to update the posterior every
    # iteration) but it may be more efficient to do several alpha updates before
    # re-finding the posterior mode.

    CONTROLS['PosteriorModeFrequency']  = 1
    
    # REDUNDANT BASIS
    
    # Check for basis vector alignment/correlation redundancy

    CONTROLS['BasisAlignmentTest']     = True
     
    ALIGNMENT_ZERO                     = 1e-3

    # If BasisAlignmentTest is true, any basis vector with inner product more
    # than MAX_ALIGNMENT with any existing model vector will not be added
    
    CONTROLS['AlignmentMax']            = 1 - ALIGNMENT_ZERO


    return CONTROLS