signature:
def _should_use_transaction_isolation ( self , test , settings ) :
    """Determine if the given test supports transaction management for
 database rollback test isolation and also whether or not the test has
 opted out of that support .
 Transactions make database rollback much quicker when supported , with
 the caveat that any tests that are explicitly testing transactions
 won ' t work properly and any tests that depend on external access to the
 test database won ' t be able to view data created / altered during the
 test ."""

implementation:
if not getattr ( test . context , 'use_transaction_isolation' , True ) : # The test explicitly says not to use transaction isolation
    return False
if getattr ( settings , 'DISABLE_TRANSACTION_MANAGEMENT' , False ) : # Do not use transactions if user has forbidden usage .
    return False
if hasattr ( settings , 'DATABASE_SUPPORTS_TRANSACTIONS' ) :
    if not settings . DATABASE_SUPPORTS_TRANSACTIONS : # The DB doesn ' t support transactions . Don ' t try it
        return False
return True


signature:
def finalize ( self , result = None ) :
    """Clean up any created database and schema ."""

implementation:
if not self . settings_path : # short circuit if no settings file can be found
    return
from django . test . utils import teardown_test_environment
from django . db import connection
from django . conf import settings
self . call_plugins_method ( 'beforeDestroyTestDb' , settings , connection )
try :
    connection . creation . destroy_test_db ( self . old_db , verbosity = self . verbosity , )
except Exception : # If we can ' t tear down the test DB , don ' t worry about it .
    pass
self . call_plugins_method ( 'afterDestroyTestDb' , settings , connection )
self . call_plugins_method ( 'beforeTeardownTestEnv' , settings , teardown_test_environment )
teardown_test_environment ( )
self . call_plugins_method ( 'afterTeardownTestEnv' , settings )


signature:
def norm ( field , vmin = 0 , vmax = 255 ) :
    """Truncates field to 0,1 ; then normalizes to a uin8 on [ 0,255]"""

implementation:
field = 255 * np . clip ( field , 0 , 1 )
field = field . astype ( 'uint8' )
return field


signature:
def extract_field ( state , field = 'exp-particles' ) :
    """Given a state , extracts a field . Extracted value depends on the value
 of field :
 ' exp - particles ' : The inverted data in the regions of the particles ,
 zeros otherwise - - i . e . particles + noise .
 ' exp - platonic ' : Same as above , but nonzero in the region of the
 entire platonic image - - i . e . platonic + noise .
 ' sim - particles ' : Just the particles image ; no noise from the data .
 ' sim - platonic ' : Just the platonic image ; no noise from the data ."""

implementation:
es , pp = field . split ( '-' )
# exp vs sim , particles vs platonic
# 1 . The weights for the field , based off the platonic vs particles
if pp == 'particles' :
    o = state . get ( 'obj' )
    if isinstance ( o , peri . comp . comp . ComponentCollection ) :
        wts = 0 * o . get ( ) [ state . inner ]
        for c in o . comps :
            if isinstance ( c , peri . comp . objs . PlatonicSpheresCollection ) :
                wts += c . get ( ) [ state . inner ]
    else :
        wts = o . get ( ) [ state . inner ]
elif pp == 'platonic' :
    wts = state . get ( 'obj' ) . get ( ) [ state . inner ]
else :
    raise ValueError ( 'Not a proper field.' )
# 2 . Exp vs sim - like data
if es == 'exp' :
    out = ( 1 - state . data ) * ( wts > 1e-5 )
elif es == 'sim' :
    out = wts
else :
    raise ValueError ( 'Not a proper field.' )
return norm ( clip ( roll ( out ) ) )


signature:
def volume_render ( field , outfile , maxopacity = 1.0 , cmap = 'bone' , size = 600 , elevation = 45 , azimuth = 45 , bkg = ( 0.0 , 0.0 , 0.0 ) , opacitycut = 0.35 , offscreen = False , rayfunction = 'smart' ) :
    """Uses vtk to make render an image of a field , with control over the
 camera angle and colormap .
 Input Parameters
 field : np . ndarray
 3D array of the field to render .
 outfile : string
 The save name of the image .
 maxopacity : Float
 Default is 1.0
 cmap : matplotlib colormap string
 Passed to cmap2colorfunc . Default is bone .
 size : 2 - element list - like of ints or Int
 The size of the final rendered image .
 elevation : Numeric
 The elevation of the camera angle , in degrees . Default is 45
 azimuth : Numeric
 The azimuth of the camera angle , in degrees . Default is 45
 bkg : Tuple of floats
 3 - element tuple of floats on [ 0,1 ] of the background image color .
 Default is ( 0 . , 0 . , 0 . ) ."""

implementation:
sh = field . shape
dataImporter = vtk . vtkImageImport ( )
dataImporter . SetDataScalarTypeToUnsignedChar ( )
data_string = field . tostring ( )
dataImporter . SetNumberOfScalarComponents ( 1 )
dataImporter . CopyImportVoidPointer ( data_string , len ( data_string ) )
dataImporter . SetDataExtent ( 0 , sh [ 2 ] - 1 , 0 , sh [ 1 ] - 1 , 0 , sh [ 0 ] - 1 )
dataImporter . SetWholeExtent ( 0 , sh [ 2 ] - 1 , 0 , sh [ 1 ] - 1 , 0 , sh [ 0 ] - 1 )
alphaChannelFunc = vtk . vtkPiecewiseFunction ( )
alphaChannelFunc . AddPoint ( 0 , 0.0 )
alphaChannelFunc . AddPoint ( int ( 255 * opacitycut ) , maxopacity )
volumeProperty = vtk . vtkVolumeProperty ( )
colorFunc = cmap2colorfunc ( cmap )
volumeProperty . SetColor ( colorFunc )
volumeProperty . SetScalarOpacity ( alphaChannelFunc )
volumeMapper = vtk . vtkVolumeRayCastMapper ( )
if rayfunction == 'mip' :
    comp = vtk . vtkVolumeRayCastMIPFunction ( )
    comp . SetMaximizeMethodToOpacity ( )
elif rayfunction == 'avg' :
    comp = vtk . vtkVolumeRayCastCompositeFunction ( )
elif rayfunction == 'iso' :
    comp = vtk . vtkVolumeRayCastIsosurfaceFunction ( )
    comp . SetIsoValue ( maxopacity / 2 )
else :
    comp = vtk . vtkVolumeRayCastIsosurfaceFunction ( )
volumeMapper . SetSampleDistance ( 0.1 )
volumeMapper . SetVolumeRayCastFunction ( comp )
if rayfunction == 'smart' :
    volumeMapper = vtk . vtkSmartVolumeMapper ( )
volumeMapper . SetInputConnection ( dataImporter . GetOutputPort ( ) )
volume = vtk . vtkVolume ( )
volume . SetMapper ( volumeMapper )
volume . SetProperty ( volumeProperty )
light = vtk . vtkLight ( )
light . SetLightType ( vtk . VTK_LIGHT_TYPE_HEADLIGHT )
light . SetIntensity ( 5.5 )
light . SwitchOn ( )
renderer = vtk . vtkRenderer ( )
renderWin = vtk . vtkRenderWindow ( )
renderWin . AddRenderer ( renderer )
renderWin . SetOffScreenRendering ( 1 ) ;
if not hasattr ( size , '__iter__' ) :
    size = ( size , size )
renderer . AddVolume ( volume )
renderer . AddLight ( light )
renderer . SetBackground ( * bkg )
renderWin . SetSize ( * size )
if offscreen :
    renderWin . SetOffScreenRendering ( 1 )
def exitCheck ( obj , event ) :
    if obj . GetEventPending ( ) != 0 :
        obj . SetAbortRender ( 1 )
renderWin . AddObserver ( "AbortCheckEvent" , exitCheck )
renderInteractor = vtk . vtkRenderWindowInteractor ( )
renderInteractor . Initialize ( )
renderWin . Render ( )
renderInteractor . Start ( )
# writer = vtk . vtkFFMPEGWriter ( )
# writer . SetQuality ( 2)
# writer . SetRate ( 24)
# w2i = vtk . vtkWindowToImageFilter ( )
# w2i . SetInput ( renderWin )
# writer . SetInputConnection ( w2i . GetOutputPort ( ) )
# writer . SetFileName ( ' movie . avi ' )
# writer . Start ( )
# writer . End ( )
writer = vtk . vtkPNGWriter ( )
w2i = vtk . vtkWindowToImageFilter ( )
w2i . SetInput ( renderWin )
writer . SetInputConnection ( w2i . GetOutputPort ( ) )
renderWin . Render ( )
ac = renderer . GetActiveCamera ( )
ac . Elevation ( elevation )
ac . Azimuth ( azimuth )
renderer . ResetCameraClippingRange ( )
renderWin . Render ( )
w2i . Modified ( )
writer . SetFileName ( outfile )
writer . Write ( )


signature:
def make_clean_figure ( figsize , remove_tooltips = False , remove_keybindings = False ) :
    """Makes a ` matplotlib . pyplot . Figure ` without tooltips or keybindings
 Parameters
 figsize : tuple
 Figsize as passed to ` matplotlib . pyplot . figure `
 remove _ tooltips , remove _ keybindings : bool
 Set to True to remove the tooltips bar or any key bindings ,
 respectively . Default is False
 Returns
 fig : ` matplotlib . pyplot . Figure `"""

implementation:
tooltip = mpl . rcParams [ 'toolbar' ]
if remove_tooltips :
    mpl . rcParams [ 'toolbar' ] = 'None'
fig = pl . figure ( figsize = figsize )
mpl . rcParams [ 'toolbar' ] = tooltip
if remove_keybindings :
    fig . canvas . mpl_disconnect ( fig . canvas . manager . key_press_handler_id )
return fig


signature:
def _particle_func ( self , coords , pos , wid ) :
    """Draws a gaussian , range is ( 0,1 ] . Coords = [ 3 , n ]"""

implementation:
dx , dy , dz = [ c - p for c , p in zip ( coords , pos ) ]
dr2 = dx * dx + dy * dy + dz * dz
return np . exp ( - dr2 / ( 2 * wid * wid ) )


signature:
def update_field ( self , poses = None ) :
    """updates self . field"""

implementation:
m = np . clip ( self . particle_field , 0 , 1 )
part_color = np . zeros ( self . _image . shape )
for a in range ( 4 ) :
    part_color [ : , : , : , a ] = self . part_col [ a ]
self . field = np . zeros ( self . _image . shape )
for a in range ( 4 ) :
    self . field [ : , : , : , a ] = m * part_color [ : , : , : , a ] + ( 1 - m ) * self . _image [ : , : , : , a ]


signature:
def _remove_closest_particle ( self , p ) :
    """removes the closest particle in self . pos to ` ` p ` `"""

implementation:
# 1 . find closest pos :
dp = self . pos - p
dist2 = ( dp * dp ) . sum ( axis = 1 )
ind = dist2 . argmin ( )
rp = self . pos [ ind ] . copy ( )
# 2 . delete
self . pos = np . delete ( self . pos , ind , axis = 0 )
return rp


signature:
def diffusion ( diffusion_constant = 0.2 , exposure_time = 0.05 , samples = 200 ) :
    """See ` diffusion _ correlated ` for information related to units , etc"""

implementation:
radius = 5
psfsize = np . array ( [ 2.0 , 1.0 , 3.0 ] )
# create a base image of one particle
s0 = init . create_single_particle_state ( imsize = 4 * radius , radius = radius , psfargs = { 'params' : psfsize , 'error' : 1e-6 } )
# add up a bunch of trajectories
finalimage = 0 * s0 . get_model_image ( ) [ s0 . inner ]
position = 0 * s0 . obj . pos [ 0 ]
for i in xrange ( samples ) :
    offset = np . sqrt ( 6 * diffusion_constant * exposure_time ) * np . random . randn ( 3 )
    s0 . obj . pos [ 0 ] = np . array ( s0 . image . shape ) / 2 + offset
    s0 . reset ( )
    finalimage += s0 . get_model_image ( ) [ s0 . inner ]
    position += s0 . obj . pos [ 0 ]
finalimage /= float ( samples )
position /= float ( samples )
# place that into a new image at the expected parameters
s = init . create_single_particle_state ( imsize = 4 * radius , sigma = 0.05 , radius = radius , psfargs = { 'params' : psfsize , 'error' : 1e-6 } )
s . reset ( )
# measure the true inferred parameters
return s , finalimage , position


signature:
def diffusion_correlated ( diffusion_constant = 0.2 , exposure_time = 0.05 , samples = 40 , phi = 0.25 ) :
    """Calculate the ( perhaps ) correlated diffusion effect between particles
 during the exposure time of the confocal microscope . diffusion _ constant is
 in terms of seconds and pixel sizes exposure _ time is in seconds
 1 micron radius particle :
 D = kT / ( 6 a \ pi \ eta )
 for 80/20 g / w ( 60 mPas ) , 3600 nm ^ 2 / sec ~ 0.15 px ^ 2 / sec
 for 100 % w ( 0.9 mPas ) , ~ 10.1 px ^ 2 / sec
 a full 60 layer scan takes 0.1 sec , so a particle is 0.016 sec exposure"""

implementation:
radius = 5
psfsize = np . array ( [ 2.0 , 1.0 , 3.0 ] ) / 2
pos , rad , tile = nbody . initialize_particles ( N = 50 , phi = phi , polydispersity = 0.0 )
sim = nbody . BrownianHardSphereSimulation ( pos , rad , tile , D = diffusion_constant , dt = exposure_time / samples )
sim . dt = 1e-2
sim . relax ( 2000 )
sim . dt = exposure_time / samples
# move the center to index 0 for easier analysis later
c = ( ( sim . pos - sim . tile . center ( ) ) ** 2 ) . sum ( axis = - 1 ) . argmin ( )
pc = sim . pos [ c ] . copy ( )
sim . pos [ c ] = sim . pos [ 0 ]
sim . pos [ 0 ] = pc
# which particles do we want to simulate motion for ? particle
# zero and its neighbors
mask = np . zeros_like ( sim . rad ) . astype ( 'bool' )
neigh = sim . neighbors ( 3 * radius , 0 )
for i in neigh + [ 0 ] :
    mask [ i ] = True
img = np . zeros ( sim . tile . shape )
s0 = runner . create_state ( img , sim . pos , sim . rad , ignoreimage = True )
# add up a bunch of trajectories
finalimage = 0 * s0 . get_model_image ( ) [ s0 . inner ]
position = 0 * s0 . obj . pos
for i in xrange ( samples ) :
    sim . step ( 1 , mask = mask )
    s0 . obj . pos = sim . pos . copy ( ) + s0 . pad
    s0 . reset ( )
    finalimage += s0 . get_model_image ( ) [ s0 . inner ]
    position += s0 . obj . pos
finalimage /= float ( samples )
position /= float ( samples )
# place that into a new image at the expected parameters
s = runner . create_state ( img , sim . pos , sim . rad , ignoreimage = True )
s . reset ( )
# measure the true inferred parameters
return s , finalimage , position


signature:
def dorun ( SNR = 20 , ntimes = 20 , samples = 10 , noise_samples = 10 , sweeps = 20 , burn = 10 , correlated = False ) :
    """we want to display the errors introduced by pixelation so we plot :
 * CRB , sampled error vs exposure time
 a = dorun ( ntimes = 10 , samples = 5 , noise _ samples = 5 , sweeps = 20 , burn = 8)"""

implementation:
if not correlated :
    times = np . logspace ( - 3 , 0 , ntimes )
else :
    times = np . logspace ( np . log10 ( 0.05 ) , np . log10 ( 30 ) , ntimes )
crbs , vals , errs , poss = [ ] , [ ] , [ ] , [ ]
for i , t in enumerate ( times ) :
    print '###### time' , i , t
    for j in xrange ( samples ) :
        print 'image' , j , '|' ,
        if not correlated :
            s , im , pos = diffusion ( diffusion_constant = 0.2 , exposure_time = t )
        else :
            s , im , pos = diffusion_correlated ( diffusion_constant = 0.2 , exposure_time = t )
        # typical image
        common . set_image ( s , im , 1.0 / SNR )
        crbs . append ( common . crb ( s ) )
        val , err = common . sample ( s , im , 1.0 / SNR , N = noise_samples , sweeps = sweeps , burn = burn )
        poss . append ( pos )
        vals . append ( val )
        errs . append ( err )
shape0 = ( ntimes , samples , - 1 )
shape1 = ( ntimes , samples , noise_samples , - 1 )
crbs = np . array ( crbs ) . reshape ( shape0 )
vals = np . array ( vals ) . reshape ( shape1 )
errs = np . array ( errs ) . reshape ( shape1 )
poss = np . array ( poss ) . reshape ( shape0 )
return [ crbs , vals , errs , poss , times ]


signature:
def feature_guess ( st , rad , invert = 'guess' , minmass = None , use_tp = False , trim_edge = False , ** kwargs ) :
    """Makes a guess at particle positions using heuristic centroid methods .
 Parameters
 st : : class : ` peri . states . State `
 The state to check adding particles to .
 rad : Float
 The feature size for featuring .
 invert : { ' guess ' , True , False } , optional
 Whether to invert the image ; set to True for there are dark
 particles on a bright background , False for bright particles .
 The default is to guess from the state ' s current particles .
 minmass : Float or None , optional
 The minimum mass / masscut of a particle . Default is ` ` None ` ` =
 calculated internally .
 use _ tp : Bool , optional
 Whether or not to use trackpy . Default is ` ` False ` ` , since trackpy
 cuts out particles at the edge .
 trim _ edge : Bool , optional
 Whether to trim particles at the edge pixels of the image . Can be
 useful for initial featuring but is bad for adding missing particles
 as they are frequently at the edge . Default is ` ` False ` ` .
 Returns
 guess : [ N , 3 ] numpy . ndarray
 The featured positions of the particles , sorted in order of decreasing
 feature mass .
 npart : Int
 The number of added particles ."""

implementation:
# FIXME does not use the * * kwargs , but needs b / c called with wrong kwargs
if invert == 'guess' :
    invert = guess_invert ( st )
if invert :
    im = 1 - st . residuals
else :
    im = st . residuals
return _feature_guess ( im , rad , minmass = minmass , use_tp = use_tp , trim_edge = trim_edge )


signature:
def _feature_guess ( im , rad , minmass = None , use_tp = False , trim_edge = False ) :
    """Workhorse of feature _ guess"""

implementation:
if minmass is None : # we use 1 % of the feature size mass as a cutoff ;
# it ' s easier to remove than to add
    minmass = rad ** 3 * 4 / 3. * np . pi * 0.01
    # 0.03 is a magic number ; works well
if use_tp :
    diameter = np . ceil ( 2 * rad )
    diameter += 1 - ( diameter % 2 )
    df = peri . trackpy . locate ( im , int ( diameter ) , minmass = minmass )
    npart = np . array ( df [ 'mass' ] ) . size
    guess = np . zeros ( [ npart , 3 ] )
    guess [ : , 0 ] = df [ 'z' ]
    guess [ : , 1 ] = df [ 'y' ]
    guess [ : , 2 ] = df [ 'x' ]
    mass = df [ 'mass' ]
else :
    guess , mass = initializers . local_max_featuring ( im , radius = rad , minmass = minmass , trim_edge = trim_edge )
    npart = guess . shape [ 0 ]
# I want to return these sorted by mass :
inds = np . argsort ( mass ) [ : : - 1 ]
# biggest mass first
return guess [ inds ] . copy ( ) , npart


signature:
def check_add_particles ( st , guess , rad = 'calc' , do_opt = True , im_change_frac = 0.2 , min_derr = '3sig' , ** kwargs ) :
    """Checks whether to add particles at a given position by seeing if adding
 the particle improves the fit of the state .
 Parameters
 st : : class : ` peri . states . State `
 The state to check adding particles to .
 guess : [ N , 3 ] list - like
 The positions of particles to check to add .
 rad : { Float , ` ` ' calc ' ` ` } , optional .
 The radius of the newly - added particles . Default is ` ` ' calc ' ` ` ,
 which uses the states current radii ' s median .
 do _ opt : Bool , optional
 Whether to optimize the particle position before checking if it
 should be kept . Default is True ( optimizes position ) .
 im _ change _ frac : Float
 How good the change in error needs to be relative to the change in
 the difference image . Default is 0.2 ; i . e . if the error does not
 decrease by 20 % of the change in the difference image , do not add
 the particle .
 min _ derr : Float or ' 3sig '
 The minimal improvement in error to add a particle . Default
 is ` ` ' 3sig ' = 3 * st . sigma ` ` .
 Returns
 accepts : Int
 The number of added particles
 new _ poses : [ N , 3 ] list
 List of the positions of the added particles . If ` ` do _ opt = = True ` ` ,
 then these positions will differ from the input ' guess ' ."""

implementation:
# FIXME does not use the * * kwargs , but needs b / c called with wrong kwargs
if min_derr == '3sig' :
    min_derr = 3 * st . sigma
accepts = 0
new_poses = [ ]
if rad == 'calc' :
    rad = guess_add_radii ( st )
message = ( '-' * 30 + 'ADDING' + '-' * 30 + '\n  Z\t  Y\t  X\t  R\t|\t ERR0\t\t ERR1' )
with log . noformat ( ) :
    CLOG . info ( message )
for a in range ( guess . shape [ 0 ] ) :
    p0 = guess [ a ]
    absent_err = st . error
    absent_d = st . residuals . copy ( )
    ind = st . obj_add_particle ( p0 , rad )
    if do_opt : # the slowest part of this
        opt . do_levmarq_particles ( st , ind , damping = 1.0 , max_iter = 1 , run_length = 3 , eig_update = False , include_rad = False )
    present_err = st . error
    present_d = st . residuals . copy ( )
    dont_kill = should_particle_exist ( absent_err , present_err , absent_d , present_d , im_change_frac = im_change_frac , min_derr = min_derr )
    if dont_kill :
        accepts += 1
        p = tuple ( st . obj_get_positions ( ) [ ind ] . ravel ( ) )
        r = tuple ( st . obj_get_radii ( ) [ ind ] . ravel ( ) )
        new_poses . append ( p )
        part_msg = '%2.2f\t%3.2f\t%3.2f\t%3.2f\t|\t%4.3f  \t%4.3f' % ( p + r + ( absent_err , st . error ) )
        with log . noformat ( ) :
            CLOG . info ( part_msg )
    else :
        st . obj_remove_particle ( ind )
        if np . abs ( absent_err - st . error ) > 1e-4 :
            raise RuntimeError ( 'updates not exact?' )
return accepts , new_poses


signature:
def check_remove_particle ( st , ind , im_change_frac = 0.2 , min_derr = '3sig' , ** kwargs ) :
    """Checks whether to remove particle ' ind ' from state ' st ' . If removing the
 particle increases the error by less than max ( min _ derr , change in image *
 im _ change _ frac ) , then the particle is removed .
 Parameters
 st : : class : ` peri . states . State `
 The state to check adding particles to .
 ind : Int
 The index of the particle to check to remove .
 im _ change _ frac : Float
 How good the change in error needs to be relative to the change in
 the difference image . Default is 0.2 ; i . e . if the error does not
 decrease by 20 % of the change in the difference image , do not add
 the particle .
 min _ derr : Float or ' 3sig '
 The minimal improvement in error to add a particle . Default is
 ` ` ' 3sig ' = 3 * st . sigma ` ` .
 Returns
 killed : Bool
 Whether the particle was removed .
 p : Tuple
 The position of the removed particle .
 r : Tuple
 The radius of the removed particle ."""

implementation:
# FIXME does not use the * * kwargs , but needs b / c called with wrong kwargs
if min_derr == '3sig' :
    min_derr = 3 * st . sigma
present_err = st . error
present_d = st . residuals . copy ( )
p , r = st . obj_remove_particle ( ind )
p = p [ 0 ]
r = r [ 0 ]
absent_err = st . error
absent_d = st . residuals . copy ( )
if should_particle_exist ( absent_err , present_err , absent_d , present_d , im_change_frac = im_change_frac , min_derr = min_derr ) :
    st . obj_add_particle ( p , r )
    killed = False
else :
    killed = True
return killed , tuple ( p ) , ( r , )


signature:
def should_particle_exist ( absent_err , present_err , absent_d , present_d , im_change_frac = 0.2 , min_derr = 0.1 ) :
    """Checks whether or not adding a particle should be present .
 Parameters
 absent _ err : Float
 The state error without the particle .
 present _ err : Float
 The state error with the particle .
 absent _ d : numpy . ndarray
 The state residuals without the particle .
 present _ d : numpy . ndarray
 The state residuals with the particle .
 im _ change _ frac : Float , optional
 How good the change in error needs to be relative to the change in
 the residuals . Default is 0.2 ; i . e . return False if the error does
 not decrease by 0.2 x the change in the residuals .
 min _ derr : Float , optional
 The minimal improvement in error . Default is 0.1
 Returns
 Bool
 True if the errors is better with the particle present ."""

implementation:
delta_im = np . ravel ( present_d - absent_d )
im_change = np . dot ( delta_im , delta_im )
err_cutoff = max ( [ im_change_frac * im_change , min_derr ] )
return ( absent_err - present_err ) >= err_cutoff


signature:
def add_missing_particles ( st , rad = 'calc' , tries = 50 , ** kwargs ) :
    """Attempts to add missing particles to the state .
 Operates by :
 (1 ) featuring the difference image using feature _ guess ,
 (2 ) attempting to add the featured positions using check _ add _ particles .
 Parameters
 st : : class : ` peri . states . State `
 The state to check adding particles to .
 rad : Float or ' calc ' , optional
 The radius of the newly - added particles and of the feature size for
 featuring . Default is ' calc ' , which uses the median of the state ' s
 current radii .
 tries : Int , optional
 How many particles to attempt to add . Only tries to add the first
 ` ` tries ` ` particles , in order of mass . Default is 50.
 Other Parameters
 invert : Bool , optional
 Whether to invert the image . Default is ` ` True ` ` , i . e . dark particles
 minmass : Float or None , optionals
 The minimum mass / masscut of a particle . Default is ` ` None ` ` = calcualted
 by ` ` feature _ guess ` ` .
 use _ tp : Bool , optional
 Whether to use trackpy in feature _ guess . Default is False , since
 trackpy cuts out particles at the edge .
 do _ opt : Bool , optional
 Whether to optimize the particle position before checking if it
 should be kept . Default is True ( optimizes position ) .
 im _ change _ frac : Float , optional
 How good the change in error needs to be relative to the change
 in the difference image . Default is 0.2 ; i . e . if the error does
 not decrease by 20 % of the change in the difference image , do
 not add the particle .
 min _ derr : Float or ' 3sig ' , optional
 The minimal improvement in error to add a particle . Default
 is ` ` ' 3sig ' = 3 * st . sigma ` ` .
 Returns
 accepts : Int
 The number of added particles
 new _ poses : [ N , 3 ] list
 List of the positions of the added particles . If ` ` do _ opt = = True ` ` ,
 then these positions will differ from the input ' guess ' ."""

implementation:
if rad == 'calc' :
    rad = guess_add_radii ( st )
guess , npart = feature_guess ( st , rad , ** kwargs )
tries = np . min ( [ tries , npart ] )
accepts , new_poses = check_add_particles ( st , guess [ : tries ] , rad = rad , ** kwargs )
return accepts , new_poses


signature:
def remove_bad_particles ( st , min_rad = 'calc' , max_rad = 'calc' , min_edge_dist = 2.0 , check_rad_cutoff = [ 3.5 , 15 ] , check_outside_im = True , tries = 50 , im_change_frac = 0.2 , ** kwargs ) :
    """Removes improperly - featured particles from the state , based on a
 combination of particle size and the change in error on removal .
 Parameters
 st : : class : ` peri . states . State `
 The state to remove bad particles from .
 min _ rad : Float , optional
 All particles with radius below min _ rad are automatically deleted .
 Set to ' calc ' to make it the median rad - 25 * radius std .
 Default is ' calc ' .
 max _ rad : Float , optional
 All particles with radius above max _ rad are automatically deleted .
 Set to ' calc ' to make it the median rad + 15 * radius std .
 Default is ' calc ' .
 min _ edge _ dist : Float , optional
 All particles within min _ edge _ dist of the ( padded ) image
 edges are automatically deleted . Default is 2.0
 check _ rad _ cutoff : 2 - element list of floats , optional
 Particles with radii < check _ rad _ cutoff [ 0 ] or > check _ rad _ cutoff [ 1]
 are checked if they should be deleted . Set to ' calc ' to make it the
 median rad + - 3.5 * radius std . Default is [ 3.5 , 15 ] .
 check _ outside _ im : Bool , optional
 If True , checks if particles located outside the unpadded image
 should be deleted . Default is True .
 tries : Int , optional
 The maximum number of particles with radii < check _ rad _ cutoff
 to try to remove . Checks in increasing order of radius size .
 Default is 50.
 im _ change _ frac : Float , , optional
 Number between 0 and 1 . If removing a particle decreases the
 error by less than im _ change _ frac * the change in the image , then
 the particle is deleted . Default is 0.2
 Returns
 removed : Int
 The cumulative number of particles removed ."""

implementation:
is_near_im_edge = lambda pos , pad : ( ( ( pos + st . pad ) < pad ) | ( pos > np . array ( st . ishape . shape ) + st . pad - pad ) ) . any ( axis = 1 )
# returns True if the position is within ' pad ' of the _ outer _ image edge
removed = 0
attempts = 0
n_tot_part = st . obj_get_positions ( ) . shape [ 0 ]
q10 = int ( 0.1 * n_tot_part )
# 10 % quartile
r_sig = np . sort ( st . obj_get_radii ( ) ) [ q10 : - q10 ] . std ( )
r_med = np . median ( st . obj_get_radii ( ) )
if max_rad == 'calc' :
    max_rad = r_med + 15 * r_sig
if min_rad == 'calc' :
    min_rad = r_med - 25 * r_sig
if check_rad_cutoff == 'calc' :
    check_rad_cutoff = [ r_med - 7.5 * r_sig , r_med + 7.5 * r_sig ]
# 1 . Automatic deletion :
rad_wrong_size = np . nonzero ( ( st . obj_get_radii ( ) < min_rad ) | ( st . obj_get_radii ( ) > max_rad ) ) [ 0 ]
near_im_edge = np . nonzero ( is_near_im_edge ( st . obj_get_positions ( ) , min_edge_dist - st . pad ) ) [ 0 ]
delete_inds = np . unique ( np . append ( rad_wrong_size , near_im_edge ) ) . tolist ( )
delete_poses = st . obj_get_positions ( ) [ delete_inds ] . tolist ( )
message = ( '-' * 27 + 'SUBTRACTING' + '-' * 28 + '\n  Z\t  Y\t  X\t  R\t|\t ERR0\t\t ERR1' )
with log . noformat ( ) :
    CLOG . info ( message )
for pos in delete_poses :
    ind = st . obj_closest_particle ( pos )
    old_err = st . error
    p , r = st . obj_remove_particle ( ind )
    p = p [ 0 ]
    r = r [ 0 ]
    part_msg = '%2.2f\t%3.2f\t%3.2f\t%3.2f\t|\t%4.3f  \t%4.3f' % ( tuple ( p ) + ( r , ) + ( old_err , st . error ) )
    with log . noformat ( ) :
        CLOG . info ( part_msg )
    removed += 1
# 2 . Conditional deletion :
check_rad_inds = np . nonzero ( ( st . obj_get_radii ( ) < check_rad_cutoff [ 0 ] ) | ( st . obj_get_radii ( ) > check_rad_cutoff [ 1 ] ) ) [ 0 ]
if check_outside_im :
    check_edge_inds = np . nonzero ( is_near_im_edge ( st . obj_get_positions ( ) , st . pad ) ) [ 0 ]
    check_inds = np . unique ( np . append ( check_rad_inds , check_edge_inds ) )
else :
    check_inds = check_rad_inds
check_inds = check_inds [ np . argsort ( st . obj_get_radii ( ) [ check_inds ] ) ]
tries = np . min ( [ tries , check_inds . size ] )
check_poses = st . obj_get_positions ( ) [ check_inds [ : tries ] ] . copy ( )
for pos in check_poses :
    old_err = st . error
    ind = st . obj_closest_particle ( pos )
    killed , p , r = check_remove_particle ( st , ind , im_change_frac = im_change_frac )
    if killed :
        removed += 1
        check_inds [ check_inds > ind ] -= 1
        # cleaning up indices . . . .
        delete_poses . append ( pos )
        part_msg = '%2.2f\t%3.2f\t%3.2f\t%3.2f\t|\t%4.3f  \t%4.3f' % ( p + r + ( old_err , st . error ) )
        with log . noformat ( ) :
            CLOG . info ( part_msg )
return removed , delete_poses


signature:
def add_subtract ( st , max_iter = 7 , max_npart = 'calc' , max_mem = 2e8 , always_check_remove = False , ** kwargs ) :
    """Automatically adds and subtracts missing & extra particles .
 Operates by removing bad particles then adding missing particles on
 repeat , until either no particles are added / removed or after ` max _ iter `
 attempts .
 Parameters
 st : : class : ` peri . states . State `
 The state to add and subtract particles to .
 max _ iter : Int , optional
 The maximum number of add - subtract loops to use . Default is 7.
 Terminates after either max _ iter loops or when nothing has changed .
 max _ npart : Int or ' calc ' , optional
 The maximum number of particles to add before optimizing the non - psf
 globals . Default is ` ` ' calc ' ` ` , which uses 5 % of the initial number
 of particles .
 max _ mem : Int , optional
 The maximum memory to use for optimization after adding max _ npart
 particles . Default is 2e8.
 always _ check _ remove : Bool , optional
 Set to True to always check whether to remove particles . If ` ` False ` ` ,
 only checks for removal while particles were removed on the previous
 attempt . Default is False .
 Other Parameters
 invert : Bool , optional
 ` ` True ` ` if the particles are dark on a bright background , ` ` False ` `
 if they are bright on a dark background . Default is ` ` True ` ` .
 min _ rad : Float , optional
 Particles with radius below ` ` min _ rad ` ` are automatically deleted .
 Default is ` ` ' calc ' ` ` = median rad - 25 * radius std .
 max _ rad : Float , optional
 Particles with radius above ` ` max _ rad ` ` are automatically deleted .
 Default is ` ` ' calc ' ` ` = median rad + 15 * radius std , but you should
 change this for your particle sizes .
 min _ edge _ dist : Float , optional
 Particles closer to the edge of the padded image than this are
 automatically deleted . Default is 2.0.
 check _ rad _ cutoff : 2 - element float list .
 Particles with ` ` radii < check _ rad _ cutoff [ 0 ] ` ` or ` ` > check . . . [ 1 ] ` `
 are checked if they should be deleted ( not automatic ) . Default is
 ` ` [ 3.5 , 15 ] ` ` .
 check _ outside _ im : Bool , optional
 Set to True to check whether to delete particles whose positions are
 outside the un - padded image .
 rad : Float , optional
 The initial radius for added particles ; added particles radii are
 not fit until the end of ` ` add _ subtract ` ` . Default is ` ` ' calc ' ` ` ,
 which uses the median radii of active particles .
 tries : Int , optional
 The number of particles to attempt to remove or add , per iteration .
 Default is 50.
 im _ change _ frac : Float , optional
 How good the change in error needs to be relative to the change in
 the difference image . Default is 0.2 ; i . e . if the error does not
 decrease by 20 % of the change in the difference image , do not add
 the particle .
 min _ derr : Float , optional
 The minimum change in the state ' s error to keep a particle in the
 image . Default is ` ` ' 3sig ' ` ` which uses ` ` 3 * st . sigma ` ` .
 do _ opt : Bool , optional
 Set to False to avoid optimizing particle positions after adding .
 minmass : Float , optional
 The minimum mass for a particle to be identified as a feature ,
 as used by trackpy . Defaults to a decent guess .
 use _ tp : Bool , optional
 Set to True to use trackpy to find missing particles inside the
 image . Not recommended since trackpy deliberately cuts out particles
 at the edge of the image . Default is ` ` False ` ` .
 Returns
 total _ changed : Int
 The total number of adds and subtracts done on the data . Not the
 same as ` ` changed _ inds . size ` ` since the same particle or particle
 index can be added / subtracted multiple times .
 added _ positions : [ N _ added , 3 ] numpy . ndarray
 The positions of particles that have been added at any point in the
 add - subtract cycle .
 removed _ positions : [ N _ added , 3 ] numpy . ndarray
 The positions of particles that have been removed at any point in
 the add - subtract cycle .
 Notes
 Occasionally after the intial featuring a cluster of particles is
 featured as 1 big particle . To fix these mistakes , it helps to set
 max _ rad to a physical value . This removes the big particle and allows
 it to be re - featured by ( several passes of ) the adds .
 The added / removed positions returned are whether or not the position
 has been added or removed ever . It ' s possible that a position is
 added , then removed during a later iteration ."""

implementation:
if max_npart == 'calc' :
    max_npart = 0.05 * st . obj_get_positions ( ) . shape [ 0 ]
total_changed = 0
_change_since_opt = 0
removed_poses = [ ]
added_poses0 = [ ]
added_poses = [ ]
nr = 1
# Check removal on the first loop
for _ in range ( max_iter ) :
    if ( nr != 0 ) or ( always_check_remove ) :
        nr , rposes = remove_bad_particles ( st , ** kwargs )
    na , aposes = add_missing_particles ( st , ** kwargs )
    current_changed = na + nr
    removed_poses . extend ( rposes )
    added_poses0 . extend ( aposes )
    total_changed += current_changed
    _change_since_opt += current_changed
    if current_changed == 0 :
        break
    elif _change_since_opt > max_npart :
        _change_since_opt *= 0
        CLOG . info ( 'Start add_subtract optimization.' )
        opt . do_levmarq ( st , opt . name_globals ( st , remove_params = st . get ( 'psf' ) . params ) , max_iter = 1 , run_length = 4 , num_eig_dirs = 3 , max_mem = max_mem , eig_update_frequency = 2 , rz_order = 0 , use_accel = True )
        CLOG . info ( 'After optimization:\t{:.6}' . format ( st . error ) )
# Optimize the added particles ' radii :
for p in added_poses0 :
    i = st . obj_closest_particle ( p )
    opt . do_levmarq_particles ( st , np . array ( [ i ] ) , max_iter = 2 , damping = 0.3 )
    added_poses . append ( st . obj_get_positions ( ) [ i ] )
return total_changed , np . array ( removed_poses ) , np . array ( added_poses )


signature:
def identify_misfeatured_regions ( st , filter_size = 5 , sigma_cutoff = 8. ) :
    """Identifies regions of missing / misfeatured particles based on the
 residuals ' local deviation from uniform Gaussian noise .
 Parameters
 st : : class : ` peri . states . State `
 The state in which to identify mis - featured regions .
 filter _ size : Int , best if odd .
 The size of the filter for calculating the local standard deviation ;
 should approximately be the size of a poorly featured region in
 each dimension . Default is 5.
 sigma _ cutoff : Float or ` otsu ` , optional
 The max allowed deviation of the residuals from what is expected ,
 in units of the residuals ' standard deviation . Lower means more
 sensitive , higher = less sensitive . Default is 8.0 , i . e . one pixel
 out of every 7*10 ^ 11 is mis - identified randomly . In practice the
 noise is not Gaussian so there are still some regions mis - identified
 as improperly featured . Set to ` ` ` otsu ` ` ` to calculate this number
 based on an automatic Otsu threshold .
 Returns
 tiles : List of : class : ` peri . util . Tile `
 Each tile is the smallest bounding tile that contains an improperly
 featured region . The list is sorted by the tile ' s volume .
 Notes
 Algorithm is
 1 . Create a field of the local standard deviation , as measured over
 a hypercube of size filter _ size .
 2 . Find the maximum reasonable value of the field . [ The field should
 be a random variable with mean of r . std ( ) and standard deviation
 of ~ r . std ( ) / sqrt ( N ) , where r is the residuals and N is the
 number of pixels in the hypercube . ]
 3 . Label & Identify the misfeatured regions as portions where
 the local error is too large .
 4 . Parse the misfeatured regions into tiles .
 5 . Return the sorted tiles .
 The Otsu option to calculate the sigma cutoff works well for images
 that actually contain missing particles , returning a number similar
 to one calculated with a sigma cutoff . However , if the image is
 well - featured with Gaussian residuals , then the Otsu threshold
 splits the Gaussian down the middle instead of at the tails , which
 is very bad . So use with caution ."""

implementation:
# 1 . Field of local std
r = st . residuals
weights = np . ones ( [ filter_size ] * len ( r . shape ) , dtype = 'float' )
weights /= weights . sum ( )
f = np . sqrt ( nd . filters . convolve ( r * r , weights , mode = 'reflect' ) )
# 2 . Maximal reasonable value of the field .
if sigma_cutoff == 'otsu' :
    max_ok = initializers . otsu_threshold ( f )
else : # max _ ok = f . mean ( ) * ( 1 + sigma _ cutoff / np . sqrt ( weights . size ) )
    max_ok = f . mean ( ) + sigma_cutoff * f . std ( )
# 3 . Label & Identify
bad = f > max_ok
labels , n = nd . measurements . label ( bad )
inds = [ ]
for i in range ( 1 , n + 1 ) :
    inds . append ( np . nonzero ( labels == i ) )
# 4 . Parse into tiles
tiles = [ Tile ( np . min ( ind , axis = 1 ) , np . max ( ind , axis = 1 ) + 1 ) for ind in inds ]
# 5 . Sort and return
volumes = [ t . volume for t in tiles ]
return [ tiles [ i ] for i in np . argsort ( volumes ) [ : : - 1 ] ]


signature:
def add_subtract_misfeatured_tile ( st , tile , rad = 'calc' , max_iter = 3 , invert = 'guess' , max_allowed_remove = 20 , minmass = None , use_tp = False , ** kwargs ) :
    """Automatically adds and subtracts missing & extra particles in a region
 of poor fit .
 Parameters
 st : : class : ` peri . states . State `
 The state to add and subtract particles to .
 tile : : class : ` peri . util . Tile `
 The poorly - fit region to examine .
 rad : Float or ' calc ' , optional
 The initial radius for added particles ; added particles radii are
 not fit until the end of add _ subtract . Default is ` ` ' calc ' ` ` , which
 uses the median radii of active particles .
 max _ iter : Int , optional
 The maximum number of loops for attempted adds at one tile location .
 Default is 3.
 invert : { ' guess ' , True , False } , optional
 Whether to invert the image for feature _ guess - - True for dark
 particles on a bright background , False for bright particles . The
 default is to guess from the state ' s current particles .
 max _ allowed _ remove : Int , optional
 The maximum number of particles to remove . If the misfeatured tile
 contains more than this many particles , raises an error . If it
 contains more than half as many particles , logs a warning . If more
 than this many particles are added , they are optimized in blocks of
 ` ` max _ allowed _ remove ` ` . Default is 20.
 Other Parameters
 im _ change _ frac : Float on [ 0 , 1 ] , optional .
 If adding or removing a particle decreases the error less than
 ` ` im _ change _ frac ` ` * the change in the image , the particle is deleted .
 Default is 0.2.
 min _ derr : { Float , ` ` ' 3sig ' ` ` } , optional
 The minimum change in the state ' s error to keep a particle in the
 image . Default is ` ` ' 3sig ' ` ` which uses ` ` 3 * st . sigma ` ` .
 do _ opt : Bool , optional
 Set to False to avoid optimizing particle positions after adding
 them . Default is True .
 minmass : Float , optional
 The minimum mass for a particle to be identified as a feature , as
 used by trackpy . Defaults to a decent guess .
 use _ tp : Bool , optional
 Set to True to use trackpy to find missing particles inside the
 image . Not recommended since trackpy deliberately cuts out particles
 at the edge of the image . Default is False .
 Outputs
 n _ added : Int
 The change in the number of particles , i . e . ` ` n _ added - n _ subtracted ` `
 ainds : List of ints
 The indices of the added particles .
 Notes
 The added / removed positions returned are whether or not the
 position has been added or removed ever . It ' s possible / probably that
 a position is added , then removed during a later iteration .
 Algorithm is :
 1 . Remove all particles within the tile .
 2 . Feature and add particles to the tile .
 3 . Optimize the added particles positions only .
 4 . Run 2-3 until no particles have been added .
 5 . Optimize added particle radii
 Because all the particles are removed within a tile , it is important
 to set max _ allowed _ remove to a reasonable value . Otherwise , if the
 tile is the size of the image it can take a long time to remove all
 the particles and re - add them ."""

implementation:
if rad == 'calc' :
    rad = guess_add_radii ( st )
if invert == 'guess' :
    invert = guess_invert ( st )
# 1 . Remove all possibly bad particles within the tile .
initial_error = np . copy ( st . error )
rinds = np . nonzero ( tile . contains ( st . obj_get_positions ( ) ) ) [ 0 ]
if rinds . size >= max_allowed_remove :
    CLOG . fatal ( 'Misfeatured region too large!' )
    raise RuntimeError
elif rinds . size >= max_allowed_remove / 2 :
    CLOG . warn ( 'Large misfeatured regions.' )
elif rinds . size > 0 :
    rpos , rrad = st . obj_remove_particle ( rinds )
# 2-4 . Feature & add particles to the tile , optimize , run until none added
n_added = - rinds . size
added_poses = [ ]
for _ in range ( max_iter ) :
    if invert :
        im = 1 - st . residuals [ tile . slicer ]
    else :
        im = st . residuals [ tile . slicer ]
    guess , _ = _feature_guess ( im , rad , minmass = minmass , use_tp = use_tp )
    accepts , poses = check_add_particles ( st , guess + tile . l , rad = rad , do_opt = True , ** kwargs )
    added_poses . extend ( poses )
    n_added += accepts
    if accepts == 0 :
        break
else : # for - break - else
    CLOG . warn ( 'Runaway adds or insufficient max_iter' )
# 5 . Optimize added pos + rad :
ainds = [ ]
for p in added_poses :
    ainds . append ( st . obj_closest_particle ( p ) )
if len ( ainds ) > max_allowed_remove :
    for i in range ( 0 , len ( ainds ) , max_allowed_remove ) :
        opt . do_levmarq_particles ( st , np . array ( ainds [ i : i + max_allowed_remove ] ) , include_rad = True , max_iter = 3 )
elif len ( ainds ) > 0 :
    opt . do_levmarq_particles ( st , ainds , include_rad = True , max_iter = 3 )
# 6 . Ensure that current error after add - subtracting is lower than initial
did_something = ( rinds . size > 0 ) or ( len ( ainds ) > 0 )
if did_something & ( st . error > initial_error ) :
    CLOG . info ( 'Failed addsub, Tile {} -> {}' . format ( tile . l . tolist ( ) , tile . r . tolist ( ) ) )
    if len ( ainds ) > 0 :
        _ = st . obj_remove_particle ( ainds )
    if rinds . size > 0 :
        for p , r in zip ( rpos . reshape ( - 1 , 3 ) , rrad . reshape ( - 1 ) ) :
            _ = st . obj_add_particle ( p , r )
    n_added = 0
    ainds = [ ]
return n_added , ainds


signature:
def add_subtract_locally ( st , region_depth = 3 , filter_size = 5 , sigma_cutoff = 8 , ** kwargs ) :
    """Automatically adds and subtracts missing particles based on local
 regions of poor fit .
 Calls identify _ misfeatured _ regions to identify regions , then
 add _ subtract _ misfeatured _ tile on the tiles in order of size until
 region _ depth tiles have been checked without adding any particles .
 Parameters
 st : : class : ` peri . states . State `
 The state to add and subtract particles to .
 region _ depth : Int
 The minimum amount of regions to try ; the algorithm terminates if
 region _ depth regions have been tried without adding particles .
 Other Parameters
 filter _ size : Int , optional
 The size of the filter for calculating the local standard deviation ;
 should approximately be the size of a poorly featured region in each
 dimension . Best if odd . Default is 5.
 sigma _ cutoff : Float , optional
 The max allowed deviation of the residuals from what is expected ,
 in units of the residuals ' standard deviation . Lower means more
 sensitive , higher = less sensitive . Default is 8.0 , i . e . one pixel
 out of every ` ` 7*10 ^ 11 ` ` is mis - identified randomly . In practice the
 noise is not Gaussian so there are still some regions mis -
 identified as improperly featured .
 rad : Float or ' calc ' , optional
 The initial radius for added particles ; added particles radii are
 not fit until the end of add _ subtract . Default is ` ` ' calc ' ` ` , which
 uses the median radii of active particles .
 max _ iter : Int , optional
 The maximum number of loops for attempted adds at one tile location .
 Default is 3.
 invert : Bool , optional
 Whether to invert the image for feature _ guess . Default is ` ` True ` ` ,
 i . e . dark particles on bright background .
 max _ allowed _ remove : Int , optional
 The maximum number of particles to remove . If the misfeatured tile
 contains more than this many particles , raises an error . If it
 contains more than half as many particles , throws a warning . If more
 than this many particles are added , they are optimized in blocks of
 ` ` max _ allowed _ remove ` ` . Default is 20.
 im _ change _ frac : Float , between 0 and 1.
 If adding or removing a particle decreases the error less than
 ` ` im _ change _ frac * ` ` the change in the image , the particle is deleted .
 Default is 0.2.
 min _ derr : Float
 The minimum change in the state ' s error to keep a particle in the
 image . Default is ` ` ' 3sig ' ` ` which uses ` ` 3 * st . sigma ` ` .
 do _ opt : Bool , optional
 Set to False to avoid optimizing particle positions after adding
 them . Default is True
 minmass : Float , optional
 The minimum mass for a particle to be identified as a feature , as
 used by trackpy . Defaults to a decent guess .
 use _ tp : Bool , optional
 Set to True to use trackpy to find missing particles inside the
 image . Not recommended since trackpy deliberately cuts out
 particles at the edge of the image . Default is False .
 max _ allowed _ remove : Int , optional
 The maximum number of particles to remove . If the misfeatured tile
 contains more than this many particles , raises an error . If it
 contains more than half as many particles , throws a warning . If more
 than this many particles are added , they are optimized in blocks of
 ` ` max _ allowed _ remove ` ` . Default is 20.
 Returns
 n _ added : Int
 The change in the number of particles ; i . e the number added - number
 removed .
 new _ poses : List
 [ N , 3 ] element list of the added particle positions .
 Notes
 Algorithm Description
 1 . Identify mis - featured regions by how much the local residuals
 deviate from the global residuals , as measured by the standard
 deviation of both .
 2 . Loop over each of those regions , and :
 a . Remove every particle in the current region .
 b . Try to add particles in the current region until no more
 can be added while adequately decreasing the error .
 c . Terminate if at least region _ depth regions have been
 checked without successfully adding a particle .
 Because this algorithm is more judicious about chooosing regions to
 check , and more aggressive about removing particles in those regions ,
 it runs faster and does a better job than the ( global ) add _ subtract .
 However , this function usually does not work better as an initial add -
 subtract on an image , since ( 1 ) it doesn ' t check for removing small / big
 particles per se , and ( 2 ) when the poorly - featured regions of the image
 are large or when the fit is bad , it will remove essentially all of the
 particles , taking a long time . As a result , it ' s usually best to do a
 normal add _ subtract first and using this function for tough missing or
 double - featured particles ."""

implementation:
# 1 . Find regions of poor tiles :
tiles = identify_misfeatured_regions ( st , filter_size = filter_size , sigma_cutoff = sigma_cutoff )
# 2 . Add and subtract in the regions :
n_empty = 0
n_added = 0
new_poses = [ ]
for t in tiles :
    curn , curinds = add_subtract_misfeatured_tile ( st , t , ** kwargs )
    if curn == 0 :
        n_empty += 1
    else :
        n_added += curn
        new_poses . extend ( st . obj_get_positions ( ) [ curinds ] )
    if n_empty > region_depth :
        break
        # some message or something ?
else : # for - break - else
    pass
    # CLOG . info ( ' All regions contained particles . ' )
    # something else ? ? this is not quite true
return n_added , new_poses


signature:
def guess_invert ( st ) :
    """Guesses whether particles are bright on a dark bkg or vice - versa
 Works by checking whether the intensity at the particle centers is
 brighter or darker than the average intensity of the image , by
 comparing the median intensities of each .
 Parameters
 st : : class : ` peri . states . ImageState `
 Returns
 invert : bool
 Whether to invert the image for featuring ."""

implementation:
pos = st . obj_get_positions ( )
pxinds_ar = np . round ( pos ) . astype ( 'int' )
inim = st . ishape . translate ( - st . pad ) . contains ( pxinds_ar )
pxinds_tuple = tuple ( pxinds_ar [ inim ] . T )
pxvals = st . data [ pxinds_tuple ]
invert = np . median ( pxvals ) < np . median ( st . data )
# invert if dark particles
return invert


signature:
def load_wisdom ( wisdomfile ) :
    """Prime FFTW with knowledge of which FFTs are best on this machine by
 loading ' wisdom ' from the file ` ` wisdomfile ` `"""

implementation:
if wisdomfile is None :
    return
try :
    pyfftw . import_wisdom ( pickle . load ( open ( wisdomfile , 'rb' ) ) )
except ( IOError , TypeError ) as e :
    log . warn ( "No wisdom present, generating some at %r" % wisdomfile )
    save_wisdom ( wisdomfile )


signature:
def save_wisdom ( wisdomfile ) :
    """Save the acquired ' wisdom ' generated by FFTW to file so that future
 initializations of FFTW will be faster ."""

implementation:
if wisdomfile is None :
    return
if wisdomfile :
    pickle . dump ( pyfftw . export_wisdom ( ) , open ( wisdomfile , 'wb' ) , protocol = 2 )


signature:
def tile_overlap ( inner , outer , norm = False ) :
    """How much of inner is in outer by volume"""

implementation:
div = 1.0 / inner . volume if norm else 1.0
return div * ( inner . volume - util . Tile . intersection ( inner , outer ) . volume )


signature:
def closest_uniform_tile ( s , shift , size , other ) :
    """Given a tiling of space ( by state , shift , and size ) , find the closest
 tile to another external tile"""

implementation:
region = util . Tile ( size , dim = s . dim , dtype = 'float' ) . translate ( shift - s . pad )
vec = np . round ( ( other . center - region . center ) / region . shape )
return region . translate ( region . shape * vec )


signature:
def separate_particles_into_groups ( s , region_size = 40 , bounds = None ) :
    """Given a state , returns a list of groups of particles . Each group of
 particles are located near each other in the image . Every particle
 located in the desired region is contained in exactly 1 group .
 Parameters :
 s : state
 The PERI state to find particles in .
 region _ size : int or list of ints
 The size of the box . Groups particles into boxes of shape region _ size .
 If region _ size is a scalar , the box is a cube of length region _ size .
 Default is 40.
 bounds : 2 - element list - like of 3 - element lists .
 The sub - region of the image over which to look for particles .
 bounds [ 0 ] : The lower - left corner of the image region .
 bounds [ 1 ] : The upper - right corner of the image region .
 Default ( None - > ( [ 0,0,0 ] , s . oshape . shape ) ) is a box of the entire
 image size , i . e . the default places every particle in the image
 somewhere in the groups .
 Returns :
 particle _ groups : list
 Each element of particle _ groups is an int numpy . ndarray of the
 group of nearby particles . Only contains groups with a nonzero
 number of particles , so the elements don ' t necessarily correspond
 to a given image region ."""

implementation:
imtile = ( s . oshape . translate ( - s . pad ) if bounds is None else util . Tile ( bounds [ 0 ] , bounds [ 1 ] ) )
# does all particle including out of image , is that correct ?
region = util . Tile ( region_size , dim = s . dim )
trange = np . ceil ( imtile . shape . astype ( 'float' ) / region . shape )
translations = util . Tile ( trange ) . coords ( form = 'vector' )
translations = translations . reshape ( - 1 , translations . shape [ - 1 ] )
groups = [ ]
positions = s . obj_get_positions ( )
for v in translations :
    tmptile = region . copy ( ) . translate ( region . shape * v - s . pad )
    groups . append ( find_particles_in_tile ( positions , tmptile ) )
return [ g for g in groups if len ( g ) > 0 ]


signature:
def create_comparison_state ( image , position , radius = 5.0 , snr = 20 , method = 'constrained-cubic' , extrapad = 2 , zscale = 1.0 ) :
    """Take a platonic image and position and create a state which we can
 use to sample the error for peri . Also return the blurred platonic
 image so we can vary the noise on it later"""

implementation:
# first pad the image slightly since they are pretty small
image = common . pad ( image , extrapad , 0 )
# place that into a new image at the expected parameters
s = init . create_single_particle_state ( imsize = np . array ( image . shape ) , sigma = 1.0 / snr , radius = radius , psfargs = { 'params' : np . array ( [ 2.0 , 1.0 , 3.0 ] ) , 'error' : 1e-6 , 'threads' : 2 } , objargs = { 'method' : method } , stateargs = { 'sigmapad' : False , 'pad' : 4 , 'zscale' : zscale } )
s . obj . pos [ 0 ] = position + s . pad + extrapad
s . reset ( )
s . model_to_true_image ( )
timage = 1 - np . pad ( image , s . pad , mode = 'constant' , constant_values = 0 )
timage = s . psf . execute ( timage )
return s , timage [ s . inner ]


signature:
def dorun ( method , platonics = None , nsnrs = 20 , noise_samples = 30 , sweeps = 30 , burn = 15 ) :
    """platonics = create _ many _ platonics ( N = 50)
 dorun ( platonics )"""

implementation:
sigmas = np . logspace ( np . log10 ( 1.0 / 2048 ) , 0 , nsnrs )
crbs , vals , errs , poss = [ ] , [ ] , [ ] , [ ]
for sigma in sigmas :
    print "#### sigma:" , sigma
    for i , ( image , pos ) in enumerate ( platonics ) :
        print 'image' , i , '|' ,
        s , im = create_comparison_state ( image , pos , method = method )
        # typical image
        set_image ( s , im , sigma )
        crbs . append ( crb ( s ) )
        val , err = sample ( s , im , sigma , N = noise_samples , sweeps = sweeps , burn = burn )
        poss . append ( pos )
        vals . append ( val )
        errs . append ( err )
shape0 = ( nsnrs , len ( platonics ) , - 1 )
shape1 = ( nsnrs , len ( platonics ) , noise_samples , - 1 )
crbs = np . array ( crbs ) . reshape ( shape0 )
vals = np . array ( vals ) . reshape ( shape1 )
errs = np . array ( errs ) . reshape ( shape1 )
poss = np . array ( poss ) . reshape ( shape0 )
return [ crbs , vals , errs , poss , sigmas ]


signature:
def perfect_platonic_per_pixel ( N , R , scale = 11 , pos = None , zscale = 1.0 , returnpix = None ) :
    """Create a perfect platonic sphere of a given radius R by supersampling by a
 factor scale on a grid of size N . Scale must be odd .
 We are able to perfectly position these particles up to 1 / scale . Therefore ,
 let ' s only allow those types of shifts for now , but return the actual position
 used for the placement ."""

implementation:
# enforce odd scale size
if scale % 2 != 1 :
    scale += 1
if pos is None : # place the default position in the center of the grid
    pos = np . array ( [ ( N - 1 ) / 2.0 ] * 3 )
# limit positions to those that are exact on the size 1 . / scale
# positions have the form ( d = divisions ) :
# p = N + m / d
s = 1.0 / scale
f = zscale ** 2
i = pos . astype ( 'int' )
p = i + s * ( ( pos - i ) / s ) . astype ( 'int' )
pos = p + 1e-10
# unfortunately needed to break ties
# make the output arrays
image = np . zeros ( ( N , ) * 3 )
x , y , z = np . meshgrid ( * ( xrange ( N ) , ) * 3 , indexing = 'ij' )
# for each real pixel in the image , integrate a bunch of superres pixels
for x0 , y0 , z0 in zip ( x . flatten ( ) , y . flatten ( ) , z . flatten ( ) ) : # short - circuit things that are just too far away !
    ddd = np . sqrt ( f * ( x0 - pos [ 0 ] ) ** 2 + ( y0 - pos [ 1 ] ) ** 2 + ( z0 - pos [ 2 ] ) ** 2 )
    if ddd > R + 4 :
        image [ x0 , y0 , z0 ] = 0.0
        continue
    # otherwise , build the local mesh and count the volume
    xp , yp , zp = np . meshgrid ( * ( np . linspace ( i - 0.5 + s / 2 , i + 0.5 - s / 2 , scale , endpoint = True ) for i in ( x0 , y0 , z0 ) ) , indexing = 'ij' )
    ddd = np . sqrt ( f * ( xp - pos [ 0 ] ) ** 2 + ( yp - pos [ 1 ] ) ** 2 + ( zp - pos [ 2 ] ) ** 2 )
    if returnpix is not None and returnpix == [ x0 , y0 , z0 ] :
        outpix = 1.0 * ( ddd < R )
    vol = ( 1.0 * ( ddd < R ) + 0.0 * ( ddd == R ) ) . sum ( )
    image [ x0 , y0 , z0 ] = vol / float ( scale ** 3 )
# vol _ true = 4 . / 3 * np . pi * R * * 3
# vol _ real = image . sum ( )
# print vol _ true , vol _ real , ( vol _ true - vol _ real ) / vol _ true
if returnpix :
    return image , pos , outpix
return image , pos


signature:
def translate_fourier ( image , dx ) :
    """Translate an image in fourier - space with plane waves"""

implementation:
N = image . shape [ 0 ]
f = 2 * np . pi * np . fft . fftfreq ( N )
kx , ky , kz = np . meshgrid ( * ( f , ) * 3 , indexing = 'ij' )
kv = np . array ( [ kx , ky , kz ] ) . T
q = np . fft . fftn ( image ) * np . exp ( - 1.j * ( kv * dx ) . sum ( axis = - 1 ) ) . T
return np . real ( np . fft . ifftn ( q ) )


signature:
def doplot ( image0 , image1 , xs , crbs , errors , labels , diff_image_scale = 0.1 , dolabels = True , multiple_crbs = True , xlim = None , ylim = None , highlight = None , detailed_labels = False , xlabel = "" , title = "" ) :
    """Standardizing the plot format of the does _ matter section . See any of the
 accompaning files to see how to use this generalized plot .
 image0 : ground true
 image1 : difference image
 xs : list of x values for the plots
 crbs : list of lines of values of the crbs
 errors : list of lines of errors
 labels : legend labels for each curve"""

implementation:
if len ( crbs ) != len ( errors ) or len ( crbs ) != len ( labels ) :
    raise IndexError , "lengths are not consistent"
fig = pl . figure ( figsize = ( 14 , 7 ) )
ax = fig . add_axes ( [ 0.43 , 0.15 , 0.52 , 0.75 ] )
gs = ImageGrid ( fig , rect = [ 0.05 , 0.05 , 0.25 , 0.90 ] , nrows_ncols = ( 2 , 1 ) , axes_pad = 0.25 , cbar_location = 'right' , cbar_mode = 'each' , cbar_size = '10%' , cbar_pad = 0.04 )
diffm = diff_image_scale * np . ceil ( np . abs ( image1 ) . max ( ) / diff_image_scale )
im0 = gs [ 0 ] . imshow ( image0 , vmin = 0 , vmax = 1 , cmap = 'bone_r' )
im1 = gs [ 1 ] . imshow ( image1 , vmin = - diffm , vmax = diffm , cmap = 'RdBu' )
cb0 = pl . colorbar ( im0 , cax = gs [ 0 ] . cax , ticks = [ 0 , 1 ] )
cb1 = pl . colorbar ( im1 , cax = gs [ 1 ] . cax , ticks = [ - diffm , diffm ] )
cb0 . ax . set_yticklabels ( [ '0' , '1' ] )
cb1 . ax . set_yticklabels ( [ '-%0.1f' % diffm , '%0.1f' % diffm ] )
image_names = [ "Reference" , "Difference" ]
for i in xrange ( 2 ) :
    gs [ i ] . set_xticks ( [ ] )
    gs [ i ] . set_yticks ( [ ] )
    gs [ i ] . set_ylabel ( image_names [ i ] )
    if dolabels :
        lbl ( gs [ i ] , figlbl [ i ] )
symbols = [ 'o' , '^' , 'D' , '>' ]
for i in xrange ( len ( labels ) ) :
    c = COLORS [ i ]
    if multiple_crbs or i == 0 :
        if multiple_crbs :
            label = labels [ i ] if ( i != 0 and not detailed_labels ) else '%s CRB' % labels [ i ]
        else :
            label = 'CRB'
        ax . plot ( xs [ i ] , crbs [ i ] , '-' , c = c , lw = 3 , label = label )
    label = labels [ i ] if ( i != 0 and not detailed_labels ) else '%s Error' % labels [ i ]
    ax . plot ( xs [ i ] , errors [ i ] , symbols [ i ] , ls = '--' , lw = 2 , c = c , label = label , ms = 12 )
if dolabels :
    lbl ( ax , 'D' )
ax . loglog ( )
if xlim :
    ax . set_xlim ( xlim )
if ylim :
    ax . set_ylim ( ylim )
ax . legend ( loc = 'upper left' , ncol = 2 , prop = { 'size' : 18 } , numpoints = 1 )
ax . set_xlabel ( xlabel )
ax . set_ylabel ( r"Position CRB, Error" )
ax . grid ( False , which = 'both' , axis = 'both' )
ax . set_title ( title )
return gs , ax


signature:
def users ( ) :
    """Load default users and groups ."""

implementation:
from invenio_groups . models import Group , Membership , PrivacyPolicy , SubscriptionPolicy
admin = accounts . datastore . create_user ( email = 'admin@inveniosoftware.org' , password = encrypt_password ( '123456' ) , active = True , )
reader = accounts . datastore . create_user ( email = 'reader@inveniosoftware.org' , password = encrypt_password ( '123456' ) , active = True , )
admins = Group . create ( name = 'admins' , admins = [ admin ] )
for i in range ( 10 ) :
    Group . create ( name = 'group-{0}' . format ( i ) , admins = [ admin ] )
Membership . create ( admins , reader )
db . session . commit ( )


signature:
def _calculate ( self ) :
    self . logpriors = np . zeros_like ( self . rad )
    for i in range ( self . N - 1 ) :
        o = np . arange ( i + 1 , self . N )
        dist = ( ( self . zscale * ( self . pos [ i ] - self . pos [ o ] ) ) ** 2 ) . sum ( axis = - 1 )
        dist0 = ( self . rad [ i ] + self . rad [ o ] ) ** 2
        update = self . prior_func ( dist - dist0 )
        self . logpriors [ i ] += np . sum ( update )
        self . logpriors [ o ] += update
    """# This is equivalent
 for i in range ( self . N - 1 ) :
 for j in range ( i + 1 , self . N ) :
 d = ( ( self . zscale * ( self . pos [ i ] - self . pos [ j ] ) ) * * 2 ) . sum ( axis = - 1)
 r = ( self . rad [ i ] + self . rad [ j ] ) * * 2
 cost = self . prior _ func ( d - r )
 self . logpriors [ i ] + = cost
 self . logpriors [ j ] + = cost"""


signature:
def _weight ( self , rsq , sigma = None ) :
    """weighting function for Barnes"""

implementation:
sigma = sigma or self . filter_size
if not self . clip :
    o = np . exp ( - rsq / ( 2 * sigma ** 2 ) )
else :
    o = np . zeros ( rsq . shape , dtype = 'float' )
    m = ( rsq < self . clipsize ** 2 )
    o [ m ] = np . exp ( - rsq [ m ] / ( 2 * sigma ** 2 ) )
return o


signature:
def _eval_firstorder ( self , rvecs , data , sigma ) :
    """The first - order Barnes approximation"""

implementation:
if not self . blocksize :
    dist_between_points = self . _distance_matrix ( rvecs , self . x )
    gaussian_weights = self . _weight ( dist_between_points , sigma = sigma )
    return gaussian_weights . dot ( data ) / gaussian_weights . sum ( axis = 1 )
else : # Now rather than calculating the distance matrix all at once ,
# we do it in chunks over rvecs
    ans = np . zeros ( rvecs . shape [ 0 ] , dtype = 'float' )
    bs = self . blocksize
    for a in range ( 0 , rvecs . shape [ 0 ] , bs ) :
        dist = self . _distance_matrix ( rvecs [ a : a + bs ] , self . x )
        weights = self . _weight ( dist , sigma = sigma )
        ans [ a : a + bs ] += weights . dot ( data ) / weights . sum ( axis = 1 )
    return ans


signature:
def _newcall ( self , rvecs ) :
    """Correct , normalized version of Barnes"""

implementation:
# 1 . Initial guess for output :
sigma = 1 * self . filter_size
out = self . _eval_firstorder ( rvecs , self . d , sigma )
# 2 . There are differences between 0th order at the points and
# the passed data , so we iterate to remove :
ondata = self . _eval_firstorder ( self . x , self . d , sigma )
for i in range ( self . iterations ) :
    out += self . _eval_firstorder ( rvecs , self . d - ondata , sigma )
    ondata += self . _eval_firstorder ( self . x , self . d - ondata , sigma )
    sigma *= self . damp
return out


signature:
def _oldcall ( self , rvecs ) :
    """Barnes w / o normalizing the weights"""

implementation:
g = self . filter_size
dist0 = self . _distance_matrix ( self . x , self . x )
dist1 = self . _distance_matrix ( rvecs , self . x )
tmp = self . _weight ( dist0 , g ) . dot ( self . d )
out = self . _weight ( dist1 , g ) . dot ( self . d )
for i in range ( self . iterations ) :
    out = out + self . _weight ( dist1 , g ) . dot ( self . d - tmp )
    tmp = tmp + self . _weight ( dist0 , g ) . dot ( self . d - tmp )
    g *= self . damp
return out


signature:
def _distance_matrix ( self , a , b ) :
    """Pairwise distance between each point in ` a ` and each point in ` b `"""

implementation:
def sq ( x ) :
    return ( x * x )
# matrix = np . sum ( map ( lambda a , b : sq ( a [ : , None ] - b [ None , : ] ) , a . T ,
# b . T ) , axis = 0)
# A faster version than above :
matrix = sq ( a [ : , 0 ] [ : , None ] - b [ : , 0 ] [ None , : ] )
for x , y in zip ( a . T [ 1 : ] , b . T [ 1 : ] ) :
    matrix += sq ( x [ : , None ] - y [ None , : ] )
return matrix


signature:
def _x2c ( self , x ) :
    """Convert windowdow coordinates to cheb coordinates [ - 1,1]"""

implementation: return ( ( 2 * x - self . window [ 1 ] - self . window [ 0 ] ) / ( self . window [ 1 ] - self . window [ 0 ] ) )


signature:
def _c2x ( self , c ) :
    """Convert cheb coordinates to windowdow coordinates"""

implementation: return 0.5 * ( self . window [ 0 ] + self . window [ 1 ] + c * ( self . window [ 1 ] - self . window [ 0 ] ) )


signature:
def _construct_coefficients ( self ) :
    """Calculate the coefficients based on the func , degree , and
 interpolating points .
 _ coeffs is a [ order , N , M , . . . . ] array
 Notes
 Moved the - c0 to the coefficients defintion
 app - = 0.5 * self . _ coeffs [ 0 ] - - moving this to the coefficients"""

implementation:
coeffs = [ 0 ] * self . degree
N = float ( self . evalpts )
lvals = np . arange ( self . evalpts ) . astype ( 'float' )
xpts = self . _c2x ( np . cos ( np . pi * ( lvals + 0.5 ) / N ) )
fpts = np . rollaxis ( self . func ( xpts , * self . args ) , - 1 )
for a in range ( self . degree ) :
    inner = [ fpts [ b ] * np . cos ( np . pi * a * ( lvals [ b ] + 0.5 ) / N ) for b in range ( self . evalpts ) ]
    coeffs [ a ] = 2.0 / N * np . sum ( inner , axis = 0 )
coeffs [ 0 ] *= 0.5
self . _coeffs = np . array ( coeffs )


signature:
def tk ( self , k , x ) :
    """Evaluates an individual Chebyshev polynomial ` k ` in coordinate space
 with proper transformation given the window"""

implementation:
weights = np . diag ( np . ones ( k + 1 ) ) [ k ]
return np . polynomial . chebyshev . chebval ( self . _x2c ( x ) , weights )


signature:
def resolve_admin_type ( admin ) :
    """Determine admin type ."""

implementation:
if admin is current_user or isinstance ( admin , UserMixin ) :
    return 'User'
else :
    return admin . __class__ . __name__


signature:
def validate ( cls , policy ) :
    """Validate subscription policy value ."""

implementation: return policy in [ cls . OPEN , cls . APPROVAL , cls . CLOSED ]


signature:
def validate ( cls , policy ) :
    """Validate privacy policy value ."""

implementation: return policy in [ cls . PUBLIC , cls . MEMBERS , cls . ADMINS ]


signature:
def validate ( cls , state ) :
    """Validate state value ."""

implementation: return state in [ cls . ACTIVE , cls . PENDING_ADMIN , cls . PENDING_USER ]


signature:
def create ( cls , name = None , description = '' , privacy_policy = None , subscription_policy = None , is_managed = False , admins = None ) :
    """Create a new group .
 : param name : Name of group . Required and must be unique .
 : param description : Description of group . Default : ` ` ' ' ` `
 : param privacy _ policy : PrivacyPolicy
 : param subscription _ policy : SubscriptionPolicy
 : param admins : list of user and / or group objects . Default : ` ` [ ] ` `
 : returns : Newly created group
 : raises : IntegrityError : if group with given name already exists"""

implementation:
assert name
assert privacy_policy is None or PrivacyPolicy . validate ( privacy_policy )
assert subscription_policy is None or SubscriptionPolicy . validate ( subscription_policy )
assert admins is None or isinstance ( admins , list )
with db . session . begin_nested ( ) :
    obj = cls ( name = name , description = description , privacy_policy = privacy_policy , subscription_policy = subscription_policy , is_managed = is_managed , )
    db . session . add ( obj )
    for a in admins or [ ] :
        db . session . add ( GroupAdmin ( group = obj , admin_id = a . get_id ( ) , admin_type = resolve_admin_type ( a ) ) )
return obj


signature:
def delete ( self ) :
    """Delete a group and all associated memberships ."""

implementation:
with db . session . begin_nested ( ) :
    Membership . query_by_group ( self ) . delete ( )
    GroupAdmin . query_by_group ( self ) . delete ( )
    GroupAdmin . query_by_admin ( self ) . delete ( )
    db . session . delete ( self )


signature:
def update ( self , name = None , description = None , privacy_policy = None , subscription_policy = None , is_managed = None ) :
    """Update group .
 : param name : Name of group .
 : param description : Description of group .
 : param privacy _ policy : PrivacyPolicy
 : param subscription _ policy : SubscriptionPolicy
 : returns : Updated group"""

implementation:
with db . session . begin_nested ( ) :
    if name is not None :
        self . name = name
    if description is not None :
        self . description = description
    if ( privacy_policy is not None and PrivacyPolicy . validate ( privacy_policy ) ) :
        self . privacy_policy = privacy_policy
    if ( subscription_policy is not None and SubscriptionPolicy . validate ( subscription_policy ) ) :
        self . subscription_policy = subscription_policy
    if is_managed is not None :
        self . is_managed = is_managed
    db . session . merge ( self )
return self


signature:
def get_by_name ( cls , name ) :
    """Query group by a group name .
 : param name : Name of a group to search for .
 : returns : Group object or None ."""

implementation:
try :
    return cls . query . filter_by ( name = name ) . one ( )
except NoResultFound :
    return None


signature:
def query_by_names ( cls , names ) :
    """Query group by a list of group names .
 : param list names : List of the group names .
 : returns : Query object ."""

implementation:
assert isinstance ( names , list )
return cls . query . filter ( cls . name . in_ ( names ) )


signature:
def query_by_user ( cls , user , with_pending = False , eager = False ) :
    """Query group by user .
 : param user : User object .
 : param bool with _ pending : Whether to include pending users .
 : param bool eager : Eagerly fetch group members .
 : returns : Query object ."""

implementation:
q1 = Group . query . join ( Membership ) . filter_by ( user_id = user . get_id ( ) )
if not with_pending :
    q1 = q1 . filter_by ( state = MembershipState . ACTIVE )
if eager :
    q1 = q1 . options ( joinedload ( Group . members ) )
q2 = Group . query . join ( GroupAdmin ) . filter_by ( admin_id = user . get_id ( ) , admin_type = resolve_admin_type ( user ) )
if eager :
    q2 = q2 . options ( joinedload ( Group . members ) )
query = q1 . union ( q2 ) . with_entities ( Group . id )
return Group . query . filter ( Group . id . in_ ( query ) )


signature:
def search ( cls , query , q ) :
    """Modify query as so include only specific group names .
 : param query : Query object .
 : param str q : Search string .
 : returs : Query object ."""

implementation: return query . filter ( Group . name . like ( '%{0}%' . format ( q ) ) )


signature:
def add_member ( self , user , state = MembershipState . ACTIVE ) :
    """Invite a user to a group .
 : param user : User to be added as a group member .
 : param state : MembershipState . Default : MembershipState . ACTIVE .
 : returns : Membership object or None ."""

implementation: return Membership . create ( self , user , state )


signature:
def invite ( self , user , admin = None ) :
    """Invite a user to a group ( should be done by admins ) .
 Wrapper around ` ` add _ member ( ) ` ` to ensure proper membership state .
 : param user : User to invite .
 : param admin : Admin doing the action . If provided , user is only invited
 if the object is an admin for this group . Default : None .
 : returns : Newly created Membership or None ."""

implementation:
if admin is None or self . is_admin ( admin ) :
    return self . add_member ( user , state = MembershipState . PENDING_USER )
return None


signature:
def invite_by_emails ( self , emails ) :
    """Invite users to a group by emails .
 : param list emails : Emails of users that shall be invited .
 : returns list : Newly created Memberships or Nones ."""

implementation:
assert emails is None or isinstance ( emails , list )
results = [ ]
for email in emails :
    try :
        user = User . query . filter_by ( email = email ) . one ( )
        results . append ( self . invite ( user ) )
    except NoResultFound :
        results . append ( None )
return results


signature:
def subscribe ( self , user ) :
    """Subscribe a user to a group ( done by users ) .
 Wrapper around ` ` add _ member ( ) ` ` which checks subscription policy .
 : param user : User to subscribe .
 : returns : Newly created Membership or None ."""

implementation:
if self . subscription_policy == SubscriptionPolicy . OPEN :
    return self . add_member ( user )
elif self . subscription_policy == SubscriptionPolicy . APPROVAL :
    return self . add_member ( user , state = MembershipState . PENDING_ADMIN )
elif self . subscription_policy == SubscriptionPolicy . CLOSED :
    return None


signature:
def is_member ( self , user , with_pending = False ) :
    """Verify if given user is a group member .
 : param user : User to be checked .
 : param bool with _ pending : Whether to include pending users or not .
 : returns : True or False ."""

implementation:
m = Membership . get ( self , user )
if m is not None :
    if with_pending :
        return True
    elif m . state == MembershipState . ACTIVE :
        return True
return False


signature:
def can_see_members ( self , user ) :
    """Determine if given user can see other group members .
 : param user : User to be checked .
 : returns : True or False ."""

implementation:
if self . privacy_policy == PrivacyPolicy . PUBLIC :
    return True
elif self . privacy_policy == PrivacyPolicy . MEMBERS :
    return self . is_member ( user ) or self . is_admin ( user )
elif self . privacy_policy == PrivacyPolicy . ADMINS :
    return self . is_admin ( user )


signature:
def can_invite_others ( self , user ) :
    """Determine if user can invite people to a group .
 Be aware that this check is independent from the people ( users ) which
 are going to be invited . The checked user is the one who invites
 someone , NOT who is going to be invited .
 : param user : User to be checked .
 : returns : True or False ."""

implementation:
if self . is_managed :
    return False
elif self . is_admin ( user ) :
    return True
elif self . subscription_policy != SubscriptionPolicy . CLOSED :
    return True
else :
    return False


signature:
def get ( cls , group , user ) :
    """Get membership for given user and group .
 : param group : Group object .
 : param user : User object .
 : returns : Membership or None ."""

implementation:
try :
    m = cls . query . filter_by ( user_id = user . get_id ( ) , group = group ) . one ( )
    return m
except Exception :
    return None


signature:
def _filter ( cls , query , state = MembershipState . ACTIVE , eager = None ) :
    """Filter a query result ."""

implementation:
query = query . filter_by ( state = state )
eager = eager or [ ]
for field in eager :
    query = query . options ( joinedload ( field ) )
return query


signature:
def query_by_user ( cls , user , ** kwargs ) :
    """Get a user ' s memberships ."""

implementation: return cls . _filter ( cls . query . filter_by ( user_id = user . get_id ( ) ) , ** kwargs )


signature:
def query_invitations ( cls , user , eager = False ) :
    """Get all invitations for given user ."""

implementation:
if eager :
    eager = [ Membership . group ]
return cls . query_by_user ( user , state = MembershipState . PENDING_USER , eager = eager )


signature:
def query_requests ( cls , admin , eager = False ) :
    """Get all pending group requests ."""

implementation:
# Get direct pending request
if hasattr ( admin , 'is_superadmin' ) and admin . is_superadmin :
    q1 = GroupAdmin . query . with_entities ( GroupAdmin . group_id )
else :
    q1 = GroupAdmin . query_by_admin ( admin ) . with_entities ( GroupAdmin . group_id )
q2 = Membership . query . filter ( Membership . state == MembershipState . PENDING_ADMIN , Membership . id_group . in_ ( q1 ) , )
# Get request from admin groups your are member of
q3 = Membership . query_by_user ( user = admin , state = MembershipState . ACTIVE ) . with_entities ( Membership . id_group )
q4 = GroupAdmin . query . filter ( GroupAdmin . admin_type == 'Group' , GroupAdmin . admin_id . in_ ( q3 ) ) . with_entities ( GroupAdmin . group_id )
q5 = Membership . query . filter ( Membership . state == MembershipState . PENDING_ADMIN , Membership . id_group . in_ ( q4 ) )
query = q2 . union ( q5 )
return query


signature:
def query_by_group ( cls , group_or_id , with_invitations = False , ** kwargs ) :
    """Get a group ' s members ."""

implementation:
if isinstance ( group_or_id , Group ) :
    id_group = group_or_id . id
else :
    id_group = group_or_id
if not with_invitations :
    return cls . _filter ( cls . query . filter_by ( id_group = id_group ) , ** kwargs )
else :
    return cls . query . filter ( Membership . id_group == id_group , db . or_ ( Membership . state == MembershipState . PENDING_USER , Membership . state == MembershipState . ACTIVE ) )


signature:
def search ( cls , query , q ) :
    """Modify query as so include only specific members .
 : param query : Query object .
 : param str q : Search string .
 : returs : Query object ."""

implementation:
query = query . join ( User ) . filter ( User . email . like ( '%{0}%' . format ( q ) ) , )
return query


signature:
def order ( cls , query , field , s ) :
    """Modify query as so to order the results .
 : param query : Query object .
 : param str s : Orderinig : ` ` asc ` ` or ` ` desc ` ` .
 : returs : Query object ."""

implementation:
if s == 'asc' :
    query = query . order_by ( asc ( field ) )
elif s == 'desc' :
    query = query . order_by ( desc ( field ) )
return query


signature:
def create ( cls , group , user , state = MembershipState . ACTIVE ) :
    """Create a new membership ."""

implementation:
with db . session . begin_nested ( ) :
    membership = cls ( user_id = user . get_id ( ) , id_group = group . id , state = state , )
    db . session . add ( membership )
return membership


signature:
def delete ( cls , group , user ) :
    """Delete membership ."""

implementation:
with db . session . begin_nested ( ) :
    cls . query . filter_by ( group = group , user_id = user . get_id ( ) ) . delete ( )


signature:
def accept ( self ) :
    """Activate membership ."""

implementation:
with db . session . begin_nested ( ) :
    self . state = MembershipState . ACTIVE
    db . session . merge ( self )


signature:
def create ( cls , group , admin ) :
    """Create a new group admin .
 : param group : Group object .
 : param admin : Admin object .
 : returns : Newly created GroupAdmin object .
 : raises : IntegrityError"""

implementation:
with db . session . begin_nested ( ) :
    obj = cls ( group = group , admin = admin , )
    db . session . add ( obj )
return obj


signature:
def get ( cls , group , admin ) :
    """Get specific GroupAdmin object ."""

implementation:
try :
    ga = cls . query . filter_by ( group = group , admin_id = admin . get_id ( ) , admin_type = resolve_admin_type ( admin ) ) . one ( )
    return ga
except Exception :
    return None


signature:
def delete ( cls , group , admin ) :
    """Delete admin from group .
 : param group : Group object .
 : param admin : Admin object ."""

implementation:
with db . session . begin_nested ( ) :
    obj = cls . query . filter ( cls . admin == admin , cls . group == group ) . one ( )
    db . session . delete ( obj )


signature:
def query_by_admin ( cls , admin ) :
    """Get all groups for for a specific admin ."""

implementation: return cls . query . filter_by ( admin_type = resolve_admin_type ( admin ) , admin_id = admin . get_id ( ) )


signature:
def query_admins_by_group_ids ( cls , groups_ids = None ) :
    """Get count of admins per group ."""

implementation:
assert groups_ids is None or isinstance ( groups_ids , list )
query = db . session . query ( Group . id , func . count ( GroupAdmin . id ) ) . join ( GroupAdmin ) . group_by ( Group . id )
if groups_ids :
    query = query . filter ( Group . id . in_ ( groups_ids ) )
return query


signature:
def all ( self ) :
    '''Get all social newtworks profiles'''

implementation:
response = self . api . get ( url = PATHS [ 'GET_PROFILES' ] )
for raw_profile in response :
    self . append ( Profile ( self . api , raw_profile ) )
return self


signature:
def filter ( self , ** kwargs ) :
    '''Based on some criteria , filter the profiles and return a new Profiles
 Manager containing only the chosen items
 If the manager doen ' t have any items , get all the profiles from Buffer'''

implementation:
if not len ( self ) :
    self . all ( )
new_list = filter ( lambda item : [ True for arg in kwargs if item [ arg ] == kwargs [ arg ] ] != [ ] , self )
return Profiles ( self . api , new_list )


signature:
def dorun ( SNR = 20 , sweeps = 20 , burn = 8 , noise_samples = 10 ) :
    """we want to display the errors introduced by pixelation so we plot :
 * zero noise , cg image , fit
 * SNR 20 , cg image , fit
 * CRB for both
 a = dorun ( noise _ samples = 30 , sweeps = 24 , burn = 12 , SNR = 20)"""

implementation:
radii = np . linspace ( 2 , 10 , 8 , endpoint = False )
crbs , vals , errs = [ ] , [ ] , [ ]
for radius in radii :
    print 'radius' , radius
    s , im = pxint ( radius = radius , factor = 4 )
    goodstate = s . state . copy ( )
    common . set_image ( s , im , 1.0 / SNR )
    tcrb = crb ( s )
    tval , terr = sample ( s , im , 1.0 / SNR , N = noise_samples , sweeps = sweeps , burn = burn )
    crbs . append ( tcrb )
    vals . append ( tval )
    errs . append ( terr )
return np . array ( crbs ) , np . array ( vals ) , np . array ( errs ) , radii


signature:
def _skew ( self , x , z , d = 0 ) :
    """returns the kurtosis parameter for direction d , d = 0 is rho , d = 1 is z"""

implementation:
# get the top bound determined by the kurtosis
kval = ( np . tanh ( self . _poly ( z , self . _kurtosis_coeffs ( d ) ) ) + 1 ) / 12.
bdpoly = np . array ( [ - 1.142468e+04 , 3.0939485e+03 , - 2.0283568e+02 , - 2.1047846e+01 , 3.79808487e+00 , 1.19679781e-02 ] )
top = np . polyval ( bdpoly , kval )
# limit the skewval to be 0 - > top val
skew = self . _poly ( z , self . _skew_coeffs ( d ) )
skewval = top * ( np . tanh ( skew ) + 1 ) - top
return skewval * ( 3 * x - x ** 3 )


signature:
def _kurtosis ( self , x , z , d = 0 ) :
    """returns the kurtosis parameter for direction d , d = 0 is rho , d = 1 is z"""

implementation:
val = self . _poly ( z , self . _kurtosis_coeffs ( d ) )
return ( np . tanh ( val ) + 1 ) / 12. * ( 3 - 6 * x ** 2 + x ** 4 )


signature:
def fit_edge ( separation , radius = 5.0 , samples = 100 , imsize = 64 , sigma = 0.05 , axis = 'z' ) :
    """axis is ' z ' or ' xy '
 seps = np . linspace ( 0,2,20 ) ' z '
 seps = np . linspace ( - 2,2,20 ) ' xy '"""

implementation:
terrors = [ ]
berrors = [ ]
crbs = [ ]
for sep in separation :
    print '=' * 79
    print 'sep =' , sep ,
    s = init . create_two_particle_state ( imsize , radius = radius , delta = sep , sigma = 0.05 , axis = 'z' , psfargs = { 'params' : ( 2.0 , 1.0 , 4.0 ) , 'error' : 1e-8 } , stateargs = { 'sigmapad' : True , 'pad' : const . PAD } )
    # move off of a pixel edge ( cheating for trackpy )
    d = np . array ( [ 0 , 0.5 , 0.5 ] )
    s . obj . pos -= d
    s . reset ( )
    # move the particles to the edge
    bl = s . blocks_particle ( 0 )
    s . update ( bl [ 0 ] , np . array ( [ s . pad + radius ] ) )
    bl = s . blocks_particle ( 1 )
    s . update ( bl [ 0 ] , np . array ( [ s . pad - radius ] ) )
    if axis == 'z' :
        bl = s . blocks_particle ( 1 )
        s . update ( bl [ 0 ] , s . state [ bl [ 0 ] ] - sep )
        s . model_to_true_image ( )
    if axis == 'xy' :
        bl = s . blocks_particle ( 1 )
        s . update ( bl [ 2 ] , s . state [ bl [ 2 ] ] + sep )
        s . model_to_true_image ( )
    # save where the particles were originally so we can jiggle
    p = s . state [ s . b_pos ] . reshape ( - 1 , 3 ) . copy ( )
    print p [ 0 ] , p [ 1 ]
    # calculate the CRB for this configuration
    bl = s . explode ( s . b_pos )
    crbs . append ( np . sqrt ( np . diag ( np . linalg . inv ( s . fisher_information ( blocks = bl ) ) ) ) . reshape ( - 1 , 3 ) )
    # calculate the featuring errors
    tmp_tp , tmp_bf = [ ] , [ ]
    for i in xrange ( samples ) :
        print i
        bench . jiggle_particles ( s , pos = p , sig = 0.3 , mask = np . array ( [ 1 , 1 , 1 ] ) )
        t = bench . trackpy ( s )
        b = bench . bamfpy_positions ( s , sweeps = 15 )
        tmp_tp . append ( bench . error ( s , t ) )
        tmp_bf . append ( bench . error ( s , b ) )
    terrors . append ( tmp_tp )
    berrors . append ( tmp_bf )
return np . array ( crbs ) , np . array ( terrors ) , np . array ( berrors )


signature:
def zjitter ( jitter = 0.0 , radius = 5 ) :
    """scan jitter is in terms of the fractional pixel difference when
 moving the laser in the z - direction"""

implementation:
psfsize = np . array ( [ 2.0 , 1.0 , 3.0 ] )
# create a base image of one particle
s0 = init . create_single_particle_state ( imsize = 4 * radius , radius = radius , psfargs = { 'params' : psfsize , 'error' : 1e-6 } )
sl = np . s_ [ s0 . pad : - s0 . pad , s0 . pad : - s0 . pad , s0 . pad : - s0 . pad ]
# add up a bunch of trajectories
finalimage = 0 * s0 . get_model_image ( ) [ sl ]
position = 0 * s0 . obj . pos [ 0 ]
for i in xrange ( finalimage . shape [ 0 ] ) :
    offset = jitter * np . random . randn ( 3 ) * np . array ( [ 1 , 0 , 0 ] )
    s0 . obj . pos [ 0 ] = np . array ( s0 . image . shape ) / 2 + offset
    s0 . reset ( )
    finalimage [ i ] = s0 . get_model_image ( ) [ sl ] [ i ]
    position += s0 . obj . pos [ 0 ]
position /= float ( finalimage . shape [ 0 ] )
# place that into a new image at the expected parameters
s = init . create_single_particle_state ( imsize = 4 * radius , sigma = 0.05 , radius = radius , psfargs = { 'params' : psfsize , 'error' : 1e-6 } )
s . reset ( )
# measure the true inferred parameters
return s , finalimage , position


signature:
def dorun ( SNR = 20 , njitters = 20 , samples = 10 , noise_samples = 10 , sweeps = 20 , burn = 10 ) :
    """we want to display the errors introduced by pixelation so we plot :
 * CRB , sampled error vs exposure time
 a = dorun ( ntimes = 10 , samples = 5 , noise _ samples = 5 , sweeps = 20 , burn = 8)"""

implementation:
jitters = np . logspace ( - 6 , np . log10 ( 0.5 ) , njitters )
crbs , vals , errs , poss = [ ] , [ ] , [ ] , [ ]
for i , t in enumerate ( jitters ) :
    print '###### jitter' , i , t
    for j in xrange ( samples ) :
        print 'image' , j , '|' ,
        s , im , pos = zjitter ( jitter = t )
        # typical image
        common . set_image ( s , im , 1.0 / SNR )
        crbs . append ( crb ( s ) )
        val , err = sample ( s , im , 1.0 / SNR , N = noise_samples , sweeps = sweeps , burn = burn )
        poss . append ( pos )
        vals . append ( val )
        errs . append ( err )
shape0 = ( njitters , samples , - 1 )
shape1 = ( njitters , samples , noise_samples , - 1 )
crbs = np . array ( crbs ) . reshape ( shape0 )
vals = np . array ( vals ) . reshape ( shape1 )
errs = np . array ( errs ) . reshape ( shape1 )
poss = np . array ( poss ) . reshape ( shape0 )
return [ crbs , vals , errs , poss , jitters ]


signature:
def interactions ( self ) :
    '''Returns the detailed information on individual interactions with the social
 media update such as favorites , retweets and likes .'''

implementation:
interactions = [ ]
url = PATHS [ 'GET_INTERACTIONS' ] % self . id
response = self . api . get ( url = url )
for interaction in response [ 'interactions' ] :
    interactions . append ( ResponseObject ( interaction ) )
self . __interactions = interactions
return self . __interactions


signature:
def edit ( self , text , media = None , utc = None , now = None ) :
    '''Edit an existing , individual status update .'''

implementation:
url = PATHS [ 'EDIT' ] % self . id
post_data = "text=%s&" % text
if now :
    post_data += "now=%s&" % now
if utc :
    post_data += "utc=%s&" % utc
if media :
    media_format = "media[%s]=%s&"
    for media_type , media_item in media . iteritems ( ) :
        post_data += media_format % ( media_type , media_item )
response = self . api . post ( url = url , data = post_data )
return Update ( api = self . api , raw_response = response [ 'update' ] )


signature:
def publish ( self ) :
    '''Immediately shares a single pending update and recalculates times for
 updates remaining in the queue .'''

implementation:
url = PATHS [ 'PUBLISH' ] % self . id
return self . api . post ( url = url )


signature:
def delete ( self ) :
    '''Permanently delete an existing status update .'''

implementation:
url = PATHS [ 'DELETE' ] % self . id
return self . api . post ( url = url )


signature:
def move_to_top ( self ) :
    '''Move an existing status update to the top of the queue and recalculate
 times for all updates in the queue . Returns the update with its new
 posting time .'''

implementation:
url = PATHS [ 'MOVE_TO_TOP' ] % self . id
response = self . api . post ( url = url )
return Update ( api = self . api , raw_response = response )


signature:
def pole_removal ( noise , poles = None , sig = 3 ) :
    """Remove the noise poles from a 2d noise distribution to show that affects
 the real - space noise picture .
 noise - - fftshifted 2d array of q values
 poles - - N , 2 list of pole locations . the last index is in the order y , x as
 determined by mpl interactive plots
 for example : poles = np . array ( [ [ 190,277 ] , [ 227,253 ] , [ 233 , 256 ] ]"""

implementation:
center = np . array ( noise . shape ) / 2
v = np . rollaxis ( np . array ( np . meshgrid ( * ( np . arange ( s ) for s in noise . shape ) , indexing = 'ij' ) ) , 0 , 3 ) . astype ( "float" )
filter = np . zeros_like ( noise , dtype = 'float' )
for p in poles :
    for pp in [ p , center - ( p - center ) ] :
        dist = ( ( v - pp ) ** 2 ) . sum ( axis = - 1 )
        filter += np . exp ( - dist / ( 2 * sig ** 2 ) )
filter [ filter > 1 ] = 1
return noise * ( 1 - filter )


signature:
def pending ( self ) :
    '''Returns an array of updates that are currently in the buffer for an
 individual social media profile .'''

implementation:
pending_updates = [ ]
url = PATHS [ 'GET_PENDING' ] % self . profile_id
response = self . api . get ( url = url )
for update in response [ 'updates' ] :
    pending_updates . append ( Update ( api = self . api , raw_response = update ) )
self . __pending = pending_updates
return self . __pending


signature:
def sent ( self ) :
    '''Returns an array of updates that have been sent from the buffer for an
 individual social media profile .'''

implementation:
sent_updates = [ ]
url = PATHS [ 'GET_SENT' ] % self . profile_id
response = self . api . get ( url = url )
for update in response [ 'updates' ] :
    sent_updates . append ( Update ( api = self . api , raw_response = update ) )
self . __sent = sent_updates
return self . __sent


signature:
def shuffle ( self , count = None , utc = None ) :
    '''Randomize the order at which statuses for the specified social media
 profile will be sent out of the buffer .'''

implementation:
url = PATHS [ 'SHUFFLE' ] % self . profile_id
post_data = ''
if count :
    post_data += 'count=%s&' % count
if utc :
    post_data += 'utc=%s' % utc
return self . api . post ( url = url , data = post_data )


signature:
def reorder ( self , updates_ids , offset = None , utc = None ) :
    '''Edit the order at which statuses for the specified social media profile will
 be sent out of the buffer .'''

implementation:
url = PATHS [ 'REORDER' ] % self . profile_id
order_format = "order[]=%s&"
post_data = ''
if offset :
    post_data += 'offset=%s&' % offset
if utc :
    post_data += 'utc=%s&' % utc
for update in updates_ids :
    post_data += order_format % update
return self . api . post ( url = url , data = post_data )


signature:
def new ( self , text , shorten = None , now = None , top = None , media = None , when = None ) :
    '''Create one or more new status updates .'''

implementation:
url = PATHS [ 'CREATE' ]
post_data = "text=%s&" % text
post_data += "profile_ids[]=%s&" % self . profile_id
if shorten :
    post_data += "shorten=%s&" % shorten
if now :
    post_data += "now=%s&" % now
if top :
    post_data += "top=%s&" % top
if when :
    post_data += "scheduled_at=%s&" % str ( when )
if media :
    media_format = "media[%s]=%s&"
    for media_type , media_item in media . iteritems ( ) :
        post_data += media_format % ( media_type , media_item )
response = self . api . post ( url = url , data = post_data )
new_update = Update ( api = self . api , raw_response = response [ 'updates' ] [ 0 ] )
self . append ( new_update )
return new_update


signature:
def set_level ( self , level = 'info' , handlers = None ) :
    """Set the logging level ( which types of logs are actually printed / recorded )
 to one of [ ' debug ' , ' info ' , ' warn ' , ' error ' , ' fatal ' ] in that order
 of severity"""

implementation:
for h in self . get_handlers ( handlers ) :
    h . setLevel ( levels [ level ] )


signature:
def set_formatter ( self , formatter = 'standard' , handlers = None ) :
    """Set the text format of messages to one of the pre - determined forms ,
 one of [ ' quiet ' , ' minimal ' , ' standard ' , ' verbose ' ]"""

implementation:
for h in self . get_handlers ( handlers ) :
    h . setFormatter ( logging . Formatter ( formatters [ formatter ] ) )


signature:
def add_handler ( self , name = 'console-color' , level = 'info' , formatter = 'standard' , ** kwargs ) :
    """Add another handler to the logging system if not present already .
 Available handlers are currently : [ ' console - bw ' , ' console - color ' , ' rotating - log ' ]"""

implementation:
# make sure the the log file has a name
if name == 'rotating-log' and 'filename' not in kwargs :
    kwargs . update ( { 'filename' : self . logfilename } )
# make sure the the log file has a name
if name == 'stringio' and 'stringio' not in kwargs :
    kwargs . update ( { 'stringio' : StringIO . StringIO ( ) } )
handler = types [ name ] ( ** kwargs )
self . add_handler_raw ( handler , name , level = level , formatter = formatter )


signature:
def remove_handler ( self , name ) :
    """Remove handler from the logging system if present already .
 Available handlers are currently : [ ' console - bw ' , ' console - color ' , ' rotating - log ' ]"""

implementation:
if name in self . handlers :
    self . log . removeHandler ( self . handlers [ name ] )


signature:
def noformat ( self ) :
    """Temporarily do not use any formatter so that text printed is raw"""

implementation:
try :
    formats = { }
    for h in self . get_handlers ( ) :
        formats [ h ] = h . formatter
    self . set_formatter ( formatter = 'quiet' )
    yield
except Exception as e :
    raise
finally :
    for k , v in iteritems ( formats ) :
        k . formatter = v


signature:
def set_verbosity ( self , verbosity = 'vvv' , handlers = None ) :
    """Set the verbosity level of a certain log handler or of all handlers .
 Parameters
 verbosity : ' v ' to ' vvvvv '
 the level of verbosity , more v ' s is more verbose
 handlers : string , or list of strings
 handler names can be found in ` ` peri . logger . types . keys ( ) ` `
 Current set is : :
 [ ' console - bw ' , ' console - color ' , ' rotating - log ' ]"""

implementation:
self . verbosity = sanitize ( verbosity )
self . set_level ( v2l [ verbosity ] , handlers = handlers )
self . set_formatter ( v2f [ verbosity ] , handlers = handlers )


signature:
def normalize ( im , invert = False , scale = None , dtype = np . float64 ) :
    """Normalize a field to a ( min , max ) exposure range , default is ( 0 , 255 ) .
 ( min , max ) exposure values . Invert the image if requested ."""

implementation:
if dtype not in { np . float16 , np . float32 , np . float64 } :
    raise ValueError ( 'dtype must be numpy.float16, float32, or float64.' )
out = im . astype ( 'float' ) . copy ( )
scale = scale or ( 0.0 , 255.0 )
l , u = ( float ( i ) for i in scale )
out = ( out - l ) / ( u - l )
if invert :
    out = - out + ( out . max ( ) + out . min ( ) )
return out . astype ( dtype )


signature:
def generate_sphere ( radius ) :
    """Generates a centered boolean mask of a 3D sphere"""

implementation:
rint = np . ceil ( radius ) . astype ( 'int' )
t = np . arange ( - rint , rint + 1 , 1 )
x , y , z = np . meshgrid ( t , t , t , indexing = 'ij' )
r = np . sqrt ( x * x + y * y + z * z )
sphere = r < radius
return sphere