topo.misc Package

---

misc Package

Miscellaneous functions used by Topographica code outside of topo.base.

Several of these files are completely self-contained, not importing anything from Topographica, and can thus be copied and used in unrelated projects.

---

asizeof Module

This module exposes 10 functions and 2 classes to obtain lengths

and sizes of Python objects (for Python 2.2 or later [1]).

The main changes in this version are new function calcsize(), use gc.get_objects() to get all objects and improvements in this documentation.

Public Functions [2]

Function asizeof calculates the combined (approximate) size in bytes of one or several Python objects.

Function asizesof returns a tuple containing the (approximate) size in bytes for each given Python object separately.

Function asized returns for each object an instance of class Asized containing all the size information of the object and a tuple with the referents.

Functions basicsize and itemsize return the basic respectively item size of the given object.

Function flatsize returns the flat size of a Python object in bytes defined as the basic size plus the item size times the length of the given object.

Function leng returns the length of an object, like standard len but extended for several types, e.g. the leng of a multi- precision int (or long) is the number of digits [3]. The length of most mutable sequence objects includes an estimate of the over-allocation and therefore, the leng value may differ from the standard len result.

Function refs returns (a generator for) the referents of the given object, i.e. the objects referenced by the given object.

Function calcsize is equivalent to standard struct.calcsize but handles format characters ‘z’ for signed C type Py_ssize_t and ‘Z’ for unsigned C type size_t.

Certain classes are known to be sub-classes of or to behave as dict objects. Function adict can be used to install other class objects to be treated like dict.

Public Classes [2]

An instance of class Asized is returned for each object sized with the asized function or method.

Class Asizer can be used to accumulate the results of several asizeof or asizesof calls. After creating an Asizer instance, use methods asizeof and asizesof to size additional objects.

Call methods exclude_refs and/or exclude_types to exclude references to or instances or types of certain objects.

Use one of the print_... methods to report the statistics.

Duplicate Objects

Any duplicate, given objects are sized only once and the size is included in the combined total only once. But functions asizesof and asized do return a size value respectively an Asized instance for each given object, the same for duplicates.

Definitions [4]

The size of an object is defined as the sum of the flat size of the object plus the sizes of any referents. Referents are visited recursively up to a given limit. However, the size of objects referenced multiple times is included only once.

The flat size of an object is defined as the basic size of the object plus the item size times the number of allocated items. The flat size does include the size for the items (references to the referents), but not the referents themselves.

The flat size returned by function flatsize equals the result of the asizeof function with options code=True, ignored=False, limit=0 and option align set to the same value.

The accurate flat size for an object is obtained from function sys.getsizeof() where available. Otherwise, the length and size of sequence objects as dicts, lists, sets, etc. is based on an estimate for the number of allocated items. As a result, the reported length and size may substantially differ from the actual length and size.

The basic and item sizes are obtained from the __basicsize__ respectively __itemsize__ attribute of the (type of the) object. Where necessary (e.g. sequence objects), a zero __itemsize__ is replaced by the size of a corresponding C type.

The basic size (of GC managed objects) objects includes the overhead for Python’s garbage collector (GC) as well as the space needed for refcounts (only in certain Python builds).

Optionally, sizes can be aligned to any power of 2 multiple.

Size of (byte)code

The (byte)code size of objects as classes, functions, methods, modules, etc. can be included by setting option code.

Iterators are handled similar to sequences: iterated object(s) are sized like referents if the recursion limit permits. Also, function gc.get_referents() must return the referent object of iterators.

Generators are sized as (byte)code only, but generated objects are never sized.

Old- and New-style Classes

All old- and new-style class, instance and type objects, are handled uniformly such that (a) instance and class objects can be distinguished and (b) instances of different old-style classes can be dealt with separately.

Class and type objects are represented as <class ....* def> respectively as <type ... def> where an ‘*’ indicates an old- style class and the def suffix marks the definition object. Instances of old-style classes are shown as new-style ones but with an ‘*’ at the end of the name, like <class module.name*>.

Ignored Objects

To avoid excessive sizes, several object types are ignored [4] by default, e.g. built-in functions, built-in types and classes [5], function globals and module referents. However, any instances thereof are sized and module objects will be sized when passed as given objects. Ignored object types are included if option ignored is set accordingly.

In addition, many __...__ attributes of callable objects are ignored, except crucial ones, e.g. class attributes __dict__, __doc__, __name__ and __slots__. For more details, see the type-specific _..._refs() and _len_...() functions below.

Option all can be used to size all Python objects and/or get the referents from gc.get_referents() and override the type- specific __..._refs() functions.

Notes

[1] Tested with Python 2.2.3, 2.3.7, 2.4.5, 2.5.1, 2.5.2, 2.6.2,

3.0.1 or 3.1a2 on CentOS 4.6, SuSE 9.3, MacOS X 10.4.11 Tiger (Intel) and 10.3.9 Panther (PPC), Solaris 10 (Opteron) and Windows XP all 32-bit Python and on RHEL 3u7 and Solaris 10 (Opteron) both 64-bit Python.

[2] The functions and classes in this module are not thread-safe.

[3] See Python source file .../Include/longinterp.h for the

C typedef of digit used in multi-precision int (or long) objects. The size of digit in bytes can be obtained in Python from the int (or long) __itemsize__ attribute. Function leng (rather _len_int) below deterimines the number of digits from the int (or long) value.

[4] These definitions and other assumptions are rather arbitrary

and may need corrections or adjustments.

[5] Types and classes are considered built-in if the module of

the type or class is listed in _builtin_modules below.

topo.misc.asizeof.adict(*classes)

Install one or more classes to be handled as dict.

topo.misc.asizeof.asized(*objs, **opts)

Return a tuple containing an Asized instance for each object passed as positional argment using the following options.

align=8 – size alignment all=False – all current GC objects and referents clip=80 – clip repr() strings code=False – incl. (byte)code size derive=False – derive from super type detail=0 – Asized refs level ignored=True – ignore certain types infer=False – try to infer types limit=100 – recursion limit stats=0.0 – print statistics and cutoff percentage

If only one object is given, the return value is the Asized instance for that object.

Set detail to the desired referents level (recursion depth).

See function asizeof for descriptions of the other options.

The length of the returned tuple matches the number of given objects, if more than one object is given.

topo.misc.asizeof.asizeof(*objs, **opts)

Return the combined size in bytes of all objects passed as positional argments.

The available options and defaults are the following.

align=8 – size alignment all=False – all current GC objects and referents clip=80 – clip repr() strings code=False – incl. (byte)code size derive=False – derive from super type ignored=True – ignore certain types infer=False – try to infer types limit=100 – recursion limit stats=0.0 – print statistics and cutoff percentage

Set align to a power of 2 to align sizes. Any value less than 2 avoids size alignment.

All current GC objects are sized if all is True and if no positional arguments are supplied. Also, if all is True the GC referents are used instead of the limited ones.

A positive clip value truncates all repr() strings to at most clip characters.

The (byte)code size of callable objects like functions, methods, classes, etc. is included only if code is True.

If derive is True, new types are handled like an existing (super) type provided there is one and only of those.

By default, certain base types like object are ignored for sizing. Set ignored to False to force all ignored types in the size of objects.

By default certain base types like object, super, etc. are ignored. Set ignored to False to include those.

If infer is True, new types are inferred from attributes (only implemented for dict types on callable attributes as get, has_key, items, keys and values).

Set limit to a positive value to accumulate the sizes of the referents of each object, recursively up to the limit. Using limit zero returns the sum of the flat [1] sizes of the given objects. High limit values may cause runtime errors and miss objects for sizing.

A positive value for stats prints up to 8 statistics, (1) a summary of the number of objects sized and seen, (2) a simple profile of the sized objects by type and (3+) up to 6 tables showing the static, dynamic, derived, ignored, inferred and dict types used, found respectively installed.

The fractional part of the stats value (x 100) is the cutoff percentage for simple profiles. Objects below the cutoff value are not reported.

[1] See the documentation of this module for the definition

of flat size.

topo.misc.asizeof.asizesof(*objs, **opts)

Return a tuple containing the size in bytes of all objects passed as positional argments using the following options.

align=8 – size alignment all=False – use GC objects and referents clip=80 – clip repr() strings code=False – incl. (byte)code size derive=False – derive from super type ignored=True – ignore certain types infer=False – try to infer types limit=100 – recursion limit stats=0.0 – print statistics and cutoff percentage

See function asizeof for a description of the options.

The length of the returned tuple equals the number of given objects.

class topo.misc.asizeof.Asized(size, flat, refs=(), name=None)

Bases: object

Store the results of an asized object in these 4 attributes:

size - total size of the object flat - flat size of the object name - name or repr of the object refs - tuple containing an instance

of Asized for each referent

format(named)

Format name from _NamedRef instance.

class topo.misc.asizeof.Asizer(**opts)

Bases: object

Sizer state and options.

asized(*objs, **opts)

Size each object and return an Asized instance with size information and referents up to the given detail level (and with modified options, see method set).

If only one object is given, the return value is the Asized instance for that object.

asizeof(*objs, **opts)

Return the combined size of the given objects (with modified options, see also method set).

asizesof(*objs, **opts)

Return the individual sizes of the given objects (with modified options, see also method set).

duplicate

Number of duplicate objects.

exclude_refs(*objs)

Exclude any references to the specified objects from sizing.

While any references to the given objects are excluded, the objects will be sized if specified as positional arguments in subsequent calls to methods asizeof and asizesof.

exclude_types(*objs)

Exclude the specified object instances and types from sizing.

All instances and types of the given objects are excluded, even objects specified as positional arguments in subsequent calls to methods asizeof and asizesof.

missed

Number of objects missed due to errors.

print_profiles(w=0, cutoff=0, **print3opts)

Print the profiles above cutoff percentage.

w=0 – indentation for each line cutoff=0 – minimum percentage printed print3options – print options, as in Python 3.0

print_stats(objs=(), opts={}, sized=(), sizes=(), stats=3.0, **print3opts)

Print the statistics.

w=0 – indentation for each line objs=() – optional, list of objects opts={} – optional, dict of options used sized=() – optional, tuple of Asized instances returned sizes=() – optional, tuple of sizes returned stats=3.0 – print statistics and cutoff percentage print3options – print options, as in Python 3.0

print_summary(w=0, objs=(), **print3opts)

Print the summary statistics.

w=0 – indentation for each line objs=() – optional, list of objects print3options – print options, as in Python 3.0

print_typedefs(w=0, **print3opts)

Print the types and dict tables.

w=0 – indentation for each line print3options – print options, as in Python 3.0

reset(align=8, all=False, clip=80, code=False, derive=False, detail=0, ignored=True, infer=False, limit=100, stats=0)

Reset options, state, etc.

The available options and default values are:

align=8 – size alignment all=False – all current GC objects and referents clip=80 – clip repr() strings code=False – incl. (byte)code size derive=False – derive from super type detail=0 – Asized refs level ignored=True – ignore certain types infer=False – try to infer types limit=100 – recursion limit stats=0.0 – print statistics and cutoff percentage

See function asizeof for a description of the options.

set(align=None, code=None, detail=None, limit=None, stats=None)

Set some options. Any options not set remain the same as the previous setting.

align=8 – size alignment code=False – incl. (byte)code size detail=0 – Asized refs level limit=100 – recursion limit stats=0.0 – print statistics and cutoff percentage

total

Total size accumulated so far.

topo.misc.asizeof.basicsize(obj, **opts)

Return the basic size of an object (in bytes).

Valid options and defaults are

derive=False – derive type from super type infer=False – try to infer types save=False – save typedef if new

topo.misc.asizeof.flatsize(obj, align=0, **opts)

Return the flat size of an object (in bytes), optionally aligned to a given power of 2.

See function basicsize for a description of the other options. See the documentation of this module for the definition of flat size.

topo.misc.asizeof.itemsize(obj, **opts)

Return the item size of an object (in bytes).

See function basicsize for a description of the options.

topo.misc.asizeof.leng(obj, **opts)

Return the length of an object (in items).

See function basicsize for a description of the options.

topo.misc.asizeof.refs(obj, all=False, **opts)

Return (a generator for) specific referents of an object.

If all is True return the GC referents.

See function basicsize for a description of the options.

topo.misc.asizeof.calcsize(fmt)

struct.calcsize() handling ‘z’ for signed Py_ssize_t and ‘Z’ for unsigned size_t.

---

attrdict Module

class topo.misc.attrdict.AttrDict(*args, **kwargs)

Bases: dict

A dictionary type object that supports attribute access (e.g. for IPython tab completion).

clear() → None. Remove all items from D.

copy() → a shallow copy of D

static fromkeys(S[, v]) → New dict with keys from S and values equal to v.

v defaults to None.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

has_key(k) → True if D has a key k, else False

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → list of D's values

viewitems() → a set-like object providing a view on D's items

viewkeys() → a set-like object providing a view on D's keys

viewvalues() → an object providing a view on D's values

---

color Module

Provides optimized color conversion utilities to speedup imagen color conversion (imagen.colorspaces.rgb_to_hsv and imagen.colorspaces.hsv_to_rgb.

---

commandline Module

Support functions for parsing command-line arguments and providing the Topographica command prompt. Typically called from the ‘./topographica’ script, but can be called directly if using Topographica files within a separate Python.

class topo.misc.commandline.CommandPrompt

Bases: topo.misc.commandline.IPCommandPromptHandler

Control over input prompt.

Several predefined formats are provided, and any of these (or any arbitrary string) can be used by calling set_format() with their values.

See the IPython manual for details: http://ipython.scipy.org/doc/manual/html/config/index.html

Examples:

# Use one of the predefined formats: CommandPrompt.set_format(CommandPrompt.basic_format) # Just print the command number: CommandPrompt.set_format(‘# ‘) # Print the command number but don’t use color: CommandPrompt.set_format(‘N ‘) # Print the value of my_var at each prompt: CommandPrompt.set_format(‘{my_var}>>> ‘)

classmethod get_format()

Return the current template.

classmethod set_format(format)

Set IPython’s prompt template to format.

class topo.misc.commandline.CommandPrompt2

Bases: topo.misc.commandline.IPCommandPromptHandler

Control over continuation prompt.

(See CommandPrompt.)

classmethod get_format()

Return the current template.

classmethod set_format(format)

Set IPython’s prompt template to format.

class topo.misc.commandline.GlobalParams(context=None, **params)

Bases: param.parameterized.Parameterized, topo.base.simulation.OptionalSingleton

A Parameterized class providing script-level parameters.

Script-level parameters can be set from the commandline by passing via -p, e.g. ./topographica -p retina_density=10

Within scripts, parameters can be declared by using the add() method.

Example usage in a script:

from topo.misc.commandline import global_params as p p.add(

retina_density=param.Number(default=24.0,bounds=(0,None), inclusive_bounds=(False,True),doc=”“” The nominal_density to use for the retina.”“”))

... topo.sim[‘Retina’]=sheet.GeneratorSheet(

nominal_density=p.retina_density)

Further information:

‘context’ is usually set to __main__.__dict__ and is used to find the value of a parameter as it is add()ed to this object (i.e. add() has access to values set via the commandline or in scripts).

Values set via set_in_context() or exec_in_context() (used by -p) are tracked: warnings are issued for overwritten values, and unused values can be warned about via check_for_unused_names().

The context is not saved in snapshots, but parameter values are saved.

add(**kw)

For each parameter_name=parameter_object specified in kw: * adds the parameter_object to this object’s class * if there is an entry in context that has the same name as the parameter,

sets the value of the parameter in this object to that value, and then removes the name from context

check_for_unused_names()

Warn about any unused names.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

exec_in_context(arg)

exec arg in self.context, tracking new names and warning of any replacements.

force_new_dynamic_value = <functools.partial object at 0x2b07ae51b4c8>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07ae51b5d0>

inspect_value = <functools.partial object at 0x2b07ae51b628>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07ae51b9f0>

set_in_context(**params)

Set in self.context all name=val pairs specified in **params, tracking new names and warning of any replacements.

set_param = <functools.partial object at 0x2b07ae51baf8>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.commandline.IPCommandPromptHandler

Bases: object

Allows control over IPython’s dynamic command prompts.

classmethod get_format()

Return the current template.

classmethod set_format(format)

Set IPython’s prompt template to format.

class topo.misc.commandline.OutputPrompt

Bases: topo.misc.commandline.IPCommandPromptHandler

Control over output prompt.

(See CommandPrompt.)

classmethod get_format()

Return the current template.

classmethod set_format(format)

Set IPython’s prompt template to format.

topo.misc.commandline.V_action(option, opt_str, value, parser)

Callback function for the -V option.

topo.misc.commandline.a_action(option, opt_str, value, parser)

Callback function for the -a option.

topo.misc.commandline.auto_import_commands()

Import the contents of all files in the topo/command/ directory.

topo.misc.commandline.boolean_option_action(option, opt_str, value, parser)

Callback function for boolean-valued options that apply to the entire run.

topo.misc.commandline.c_action(option, opt_str, value, parser)

Callback function for the -c option.

topo.misc.commandline.d_action(option, opt_str, value, parser)

Callback function for the -d option.

topo.misc.commandline.default_output_path()

Determine the appropriate default location in which to create files on this operating system.

topo.misc.commandline.exec_startup_files()

Execute startup files.

Linux/UNIX/OS X: ~/.topographicarc Windows: %USERPROFILE% opographica.ini

topo.misc.commandline.g_action(option, opt_str, value, parser)

Callback function for the -g option.

topo.misc.commandline.gui(start=True, exit_on_quit=True)

Start the GUI as if -g were supplied in the command used to launch Topographica.

topo.misc.commandline.i_action(option, opt_str, value, parser)

Callback function for the -i option.

topo.misc.commandline.l_action(option, opt_str, value, parser)

Callback function for the -l option.

topo.misc.commandline.o_action(option, opt_str, value, parser)

Callback function for the -o option.

topo.misc.commandline.p_action(option, opt_str, value, parser)

Callback function for the -p option.

topo.misc.commandline.process_argv(argv)

Process command-line arguments (minus argv[0]!), rearrange and execute.

topo.misc.commandline.set_output_path(path)

Set the default output path to the specified path, creating it if it does not exist and adding it to the input searching path (to allow just-saved files to be reloaded).

topo.misc.commandline.sim_name_from_filename(filename)

Set the simulation title from the given filename, if none has been set already.

topo.misc.commandline.t_action(option, opt_str, value, parser)

Callback function for the -t option for invoking tests.

topo.misc.commandline.v_action(option, opt_str, value, parser)

Callback function for the -v option.

---

featurecoordinators Module

Additional FeatureCoordinators specific to cortical modelling work, supplementing the general-purpose ones in imagen.patterncoordinator.

class topo.misc.featurecoordinators.DisparityCoordinator(**params)

Bases: imagen.patterncoordinator.FeatureCoordinator

Coordinates the disparity (difference of pattern locations) of two pattern generators. The pattern_label of the generators must contain ‘Left’ or ‘Right’

param Number disparity_bound (allow_None=False, bounds=None, constant=False, default=0.08333, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Maximum difference of the pattern locations between the two eyes (on the x axis).

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07ae6943c0>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07ae6944c8>

inspect_value = <functools.partial object at 0x2b07ae694520>

instance = <functools.partial object at 0x2b07ae6945d0>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix='n ', unknown_value='<?>', qualify=False, separator='')

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07ae694998>

set_param = <functools.partial object at 0x2b07ae6949f0>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.featurecoordinators.MotionCoordinator(**params)

Bases: imagen.patterncoordinator.FeatureCoordinator

Coordinates the motion of patterns.

param Number reset_period (allow_None=False, bounds=(0.0, None), constant=False, default=4, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Period between generating each new translation episode.

param Number speed (allow_None=False, bounds=(0.0, None), constant=False, default=0.0833333333333, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The speed with which the pattern should move, in sheet coordinates per time_fn unit.

param Callable time_fn (allow_None=False, constant=False, default=<Time Time00001>, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Function to generate the time used as a base for translation.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07ae694310>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07ae6943c0>

inspect_value = <functools.partial object at 0x2b07ae694470>

instance = <functools.partial object at 0x2b07ae694418>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix='n ', unknown_value='<?>', qualify=False, separator='')

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07ae6944c8>

set_param = <functools.partial object at 0x2b07ae694520>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.featurecoordinators.OcularityCoordinator(**params)

Bases: imagen.patterncoordinator.FeatureCoordinator

Coordinates the ocularity (brightness difference) of two pattern generators. The pattern_label of the generators must contain ‘Left’ or ‘Right’

param Number dim_fraction (allow_None=False, bounds=(0.0, 1.0), constant=False, default=0.7, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Fraction by which the pattern brightness varies between the two eyes.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07ae694368>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07ae694578>

inspect_value = <functools.partial object at 0x2b07ae6945d0>

instance = <functools.partial object at 0x2b07ae694680>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix='n ', unknown_value='<?>', qualify=False, separator='')

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07ae694af8>

set_param = <functools.partial object at 0x2b07ae694aa0>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.featurecoordinators.SpatialFrequencyCoordinator(**params)

Bases: imagen.patterncoordinator.FeatureCoordinator

Coordinates the size of pattern generators. This is useful when multiple spatial frequency channels are used, to cover a wide range of sizes of pattern generators.

param Integer sf_max_channel (allow_None=False, bounds=(2, None), constant=False, default=2, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Highest spatial frequency channel. Together with sf_spacing, this is used to compute the upper bound of the size of the supplied pattern generator.

param Number sf_spacing (allow_None=False, bounds=(0.0, None), constant=False, default=2.0, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Determines the factor by which successive SF channels increase in size. Together with sf_max_channel, this is used to compute the upper bound of the size of the supplied pattern generator.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07ae6942b8>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07ae694628>

inspect_value = <functools.partial object at 0x2b07ae694578>

instance = <functools.partial object at 0x2b07ae6946d8>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix='n ', unknown_value='<?>', qualify=False, separator='')

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07ae6945d0>

set_param = <functools.partial object at 0x2b07ae694680>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

---

fixedpoint Module

FixedPoint objects support decimal arithmetic with a fixed number of digits (called the object’s precision) after the decimal point. The number of digits before the decimal point is variable & unbounded.

The precision is user-settable on a per-object basis when a FixedPoint is constructed, and may vary across FixedPoint objects. The precision may also be changed after construction via FixedPoint.set_precision(p). Note that if the precision of a FixedPoint is reduced via set_precision, information may be lost to rounding.

>>> x = FixedPoint("5.55")  # precision defaults to 2
>>> print x
5.55
>>> x.set_precision(1)      # round to one fraction digit
>>> print x
5.6
>>> print FixedPoint("5.55", 1)  # same thing setting to 1 in constructor
5.6
>>> repr(x) #  returns constructor string that reproduces object exactly
"FixedPoint('5.6', 1)"
>>>

When FixedPoint objects of different precision are combined via + - * /, the result is computed to the larger of the inputs’ precisions, which also becomes the precision of the resulting FixedPoint object.

>>> print FixedPoint("3.42") + FixedPoint("100.005", 3)
103.425
>>>

When a FixedPoint is combined with other numeric types (ints, floats, strings representing a number) via + - * /, then similarly the computation is carried out using– and the result inherits –the FixedPoint’s precision.

>>> print FixedPoint(1) / 7
0.14
>>> print FixedPoint(1, 30) / 7
0.142857142857142857142857142857
>>>

The string produced by str(x) (implictly invoked by “print”) always contains at least one digit before the decimal point, followed by a decimal point, followed by exactly x.get_precision() digits. If x is negative, str(x)[0] == “-”.

The FixedPoint constructor can be passed an int, long, string, float, FixedPoint, or any object convertible to a float via float() or to a long via long(). Passing a precision is optional; if specified, the precision must be a non-negative int. There is no inherent limit on the size of the precision, but if very very large you’ll probably run out of memory.

Note that conversion of floats to FixedPoint can be surprising, and should be avoided whenever possible. Conversion from string is exact (up to final rounding to the requested precision), so is greatly preferred.

>>> print FixedPoint(1.1e30)
1099999999999999993725589651456.00
>>> print FixedPoint("1.1e30")
1100000000000000000000000000000.00
>>>

The following Python operators and functions accept FixedPoints in the expected ways:

binary + - * / % divmod

with auto-coercion of other types to FixedPoint. + - % divmod of FixedPoints are always exact. * / of FixedPoints may lose information to rounding, in

which case the result is the infinitely precise answer rounded to the result’s precision.

divmod(x, y) returns (q, r) where q is a long equal to

floor(x/y) as if x/y were computed to infinite precision, and r is a FixedPoint equal to x - q * y; no information is lost. Note that q has the sign of y, and abs(r) < abs(y).

unary - == != < > <= >= cmp min max float int long (int and long truncate) abs str repr hash use as dict keys use as boolean (e.g. “if some_FixedPoint:” – true iff not zero)

Methods unique to FixedPoints:

.copy() return new FixedPoint with same value .frac() long(x) + x.frac() == x .get_precision() return the precision(p) of this FixedPoint object .set_precision(p) set the precision of this FixedPoint object

Provided as-is; use at your own risk; no warranty; no promises; enjoy!

class topo.misc.fixedpoint.FixedPoint(value=0, precision=None)

Bases: object

Basic FixedPoint object class, The exact value is self.n / 10**self.p; self.n is a long; self.p is an int

frac()

Return fractional portion as a FixedPoint.

x.frac() + long(x) == x

get_precision()

Return the precision of this FixedPoint.

The precision is the number of decimal digits carried after the decimal point, and is an int >= 0.

precision

Return the precision of this FixedPoint.

The precision is the number of decimal digits carried after the decimal point, and is an int >= 0.

round(dividend, divisor, quotient, remainder)

rounding via nearest-even increment the quotient if

the remainder is more than half of the divisor

or the remainder is exactly half the divisor and the quotient is odd

set_precision(precision=2)

Change the precision carried by this FixedPoint to p.

precision must be an int >= 0, and defaults to DEFAULT_PRECISION.

If precision is less than this FixedPoint’s current precision, information may be lost to rounding.

topo.misc.fixedpoint.addHalfAndChop(self, dividend, divisor, quotient, remainder)

the equivalent of ‘add half and chop’ increment the quotient if

the remainder is greater than half of the divisor

or the remainder is exactly half the divisor and the quotient is >= 0

topo.misc.fixedpoint.bankersRounding(self, dividend, divisor, quotient, remainder)

rounding via nearest-even increment the quotient if

the remainder is more than half of the divisor

or the remainder is exactly half the divisor and the quotient is odd

---

gendocs Module

Topographica-specific changes to the standard pydoc command.

Moves generated pydoc HTML files to the docs directory after they are created by pydoc. Intended for use with MAKE, from within the base topographica/ directory.

The generated index.html file is for the topo/__init__.py file, which does not necessarily catalog every .py file in topo/. To see all files, select the ‘index’ link at the top of one of the html docs.

To generate documentation, enter ‘make docs’ from the base topographica/ directory, which will call this file on the Topographica sources.

From the Makefile (Tabs have been stripped):

cleandocs:
    - rm -r docs

docs: topo/*.py
    mkdir -p docs
    ./topographica topo/gendocs.py
    mv docs/topo.__init__.html docs/index.html

topo.misc.gendocs.filename_to_docname(f)

Convert a path name into the PyDoc filename it will turn into.

If the path name ends in a .py, then it is cut off. If there is no extension, the name is assumed to be a directory.

topo.misc.gendocs.filename_to_packagename(f)

Convert a path name into the Python dotted-notation package name.

If the name ends in a .py, then cut it off. If there is no extension, the name is assumed to be a directory, and nothing is done other than to replace the ‘/’ with ‘.’

topo.misc.gendocs.generate_docs()

Generate all pydoc documentation files within a docs directory under ./topographica according to the constant DOCS. After generation, there is an index.html that displays all the modules. Note that if the documentation is being changed, it may be necessary to call ‘make cleandocs’ to force a regeneration of documentation. (We don’t want to regenerate all the documentation each time a source file is changed.)

---

genexamples Module

Commands for running the examples files in various ways.

Like a Makefile: contains a list of targets (and groups of targets) that specify various commands to run.

E.g.

topographica -c ‘from topo.misc.genexamples import generate; generate(targets=[“all_quick”,”saved_examples”])’

Runs the ‘all_quick’ target if called without any arguments:

topographica -c ‘from topo.misc.genexamples import generate; generate()’

To add new single targets, add to the targets dictionary; for groups of targets, add to the group_targets dictionary.

topo.misc.genexamples.or_analysis()

Return a command for orientation analysis.

topo.misc.genexamples.retinotopy_analysis()

Return a command for retinotopy analysis.

topo.misc.genexamples.run(examples, script_name, density=None, commands=['topo.sim.run(1)'])

Return a complete command for running the given topographica example script (i.e. a script in the examples/ directory) at the given density, along with any additional commands.

topo.misc.genexamples.snapshot(filename)

Return a command for saving a snapshot named filename.

---

inlinec Module

Interface class for inline C/C++ functions. Based on the SciPy Weave package.

Weave (from SciPy) allows programmers to implement Python methods or functions using C code written as a string in the Python file. This is generally done to speed up code that would be slow if written directly in Python. Because not all users can be assumed to have a working C/C++ compiler, it is crucial for such optimizations to be optional. This file provides an interface for processing the inline C/C++ code in a way that can gracefully revert back to the unoptimized version when Weave is not available.

The fallback is implemented by making use of the way Python allows function names to be overwritten, as in these simple examples:

def x(y = 5): return y def x2(y = 6): return y*y print ‘x:’, x(), ‘x2:’, x2() # Result – x: 5 x2: 36 x = x2 print ‘x:’, x(), ‘x2:’, x2() # Result – x: 36 x2: 36

In this file, inline() is overwritten to call inline_weave() if Weave is available. If Weave is not available, inline() will raise a NotImplementedError exception. For a program to be usable without Weave, just test inlinec.optimized after defining each optimized component, replacing it with a non-optimized equivalent if inlinec.optimized is False.

For more information on weave, see: http://old.scipy.org/documentation/weave/weaveusersguide.html

Some of the C functions also support OpenMP, which allows them to use multiple threads automatically on multi-core machines to give better performance. To enable OpenMP support for those functions, set openmp=True in the main namespace before importing this file, and (optionally) set openmp_threads to the number of threads desired. If openmp_threads is not set, then a thread will be allocated for each available core by default.

Note that in order to use OpenMP, the C functions are obliged to use the thread-safe portions of the Python/Numpy C API. In general, the Python C API cannot be assumed to be thread safe. Calls to PyObject_SetAttrString are a common hazard which can often be avoided using LOOKUP_FROM_SLOT_OFFSET. This makes use of Python’s __slots__ mechanism with the added benefit of bypassing the GIL.

topo.misc.inlinec.provide_unoptimized_equivalent(optimized_name, unoptimized_name, local_dict)

If not using optimization, replace the optimized component with its unoptimized equivalent.

The objects named by optimized_name and unoptimized_name should be plug-compatible. The local_dict argument should be given the contents of locals(), so that this function can replace the optimized version with the unoptimized one in the namespace from which it has been called.

As an example, calling this function as:

provide_unoptimized_equivalent("sort_opt","sort",locals())

is equivalent to putting the following code directly into the calling location:

if not optimized:
  sort_opt = sort
  print 'module: Inline-optimized components not available; using sort instead of sort_opt.'

---

ipython Module

Topographica IPython extension for notebook support. Automatically loaded when importing the topo module but may also be explicitly loaded using:

%load_ext topo.misc.ipython

class topo.misc.ipython.ExportMagic(shell=None, **kwargs)

Bases: IPython.core.magic.Magics

Line magic that defines a cell magic to export the cell contents to a specific file. For instance, running

%define_exporter OUT ./output.txt

will define an %%OUT cell magic that writes to the file output.txt. This cell magic takes a optional arguments ‘clear’ and ‘run’. If ‘clear’ should be specified for the first cell to be exported. If ‘run’ is specified, the cell is executed in the active notebook as well as exported.

add_traits(**traits)

Dynamically add trait attributes to the HasTraits instance.

arg_err(func)

Print docstring if incorrect arguments were passed

classmethod class_config_rst_doc()

Generate rST documentation for this class’ config options.

Excludes traits defined on parent classes.

classmethod class_config_section()

Get the config class config section

classmethod class_get_help(inst=None)

Get the help string for this class in ReST format.

If inst is given, it’s current trait values will be used in place of class defaults.

classmethod class_get_trait_help(trait, inst=None)

Get the help string for a single trait.

If inst is given, it’s current trait values will be used in place of the class default.

classmethod class_own_traits(**metadata)

Get a dict of all the traitlets defined on this class, not a parent.

Works like class_traits, except for excluding traits from parents.

classmethod class_print_help(inst=None)

Get the help string for a single trait and print it.

classmethod class_trait_names(**metadata)

Get a list of all the names of this class’ traits.

This method is just like the trait_names() method, but is unbound.

classmethod class_traits(**metadata)

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

This method is just like the traits() method, but is unbound.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. This does not allow for any simple way of testing that a metadata name exists and has any value because get_metadata returns None if a metadata key doesn’t exist.

default_option(fn, optstr)

Make an entry in the options_table for fn, with value optstr

format_latex(strng)

Format a string for latex inclusion.

has_trait(name)

Returns True if the object has a trait with the specified name.

hold_trait_notifications(*args, **kwds)

Context manager for bundling trait change notifications and cross validation.

Use this when doing multiple trait assignments (init, config), to avoid race conditions in trait notifiers requesting other trait values. All trait notifications will fire after all values have been assigned.

on_trait_change(handler, name=None, remove=False)

Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Static handlers can be created by creating methods on a HasTraits subclass with the naming convention ‘_[traitname]_changed’. Thus, to create static handler for the trait ‘a’, create the method _a_changed(self, name, old, new) (fewer arguments can be used, see below).

handler : callable

A callable that is called when a trait changes. Its signature can be handler(), handler(name), handler(name, new) or handler(name, old, new).

name : list, str, None

If None, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.

remove : bool

If False (the default), then install the handler. If True then unintall it.

parse_options(arg_str, opt_str, *long_opts, **kw)

Parse options passed to an argument string.

The interface is similar to that of getopt.getopt(), but it returns a Struct with the options as keys and the stripped argument string still as a string.

arg_str is quoted as a true sys.argv vector by using shlex.split. This allows us to easily expand variables, glob files, quote arguments, etc.

arg_str : str

The arguments to parse.

opt_str : str

The options specification.

mode : str, default ‘string’

If given as ‘list’, the argument string is returned as a list (split on whitespace) instead of a string.

list_all : bool, default False

Put all option values in lists. Normally only options appearing more than once are put in a list.

posix : bool, default True

Whether to split the input line in POSIX mode or not, as per the conventions outlined in the shlex module from the standard library.

classmethod section_names()

return section names as a list

trait_metadata(traitname, key, default=None)

Get metadata values for trait by key.

trait_names(**metadata)

Get a list of all the names of this class’ traits.

traits(**metadata)

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. This does not allow for any simple way of testing that a metadata name exists and has any value because get_metadata returns None if a metadata key doesn’t exist.

update_config(config)

Fire the traits events when the config is updated.

topo.misc.ipython.export_notebook(notebook, output_path=None, ext='.ty', identifier='_export_', diff=True, invert=False, stale_time=None)

Given a v3-format .ipynb notebook file (from IPython 0.13 or later), allows the contents of labelled code cells to be exported to a plaintext file. The typical use case is for generating a runnable plain Python source file from selected cells of an IPython notebook.

Code is selected for export by placing the given identifier on the first line of the chosen code cells. By default, only the labelled cells are exported. This behavior may be inverted to exclude labelled cells by setting the invert flag.

notebook The filename of the notebook (.ipynb). output_path Optional output file path. Otherwise, uses the notebook basename. ext The file extension of the output. identifier The identifier used to label cells. diff Whether to print a diff when overwriting content. invert When set, only the non-labelled cells are exported. stale_time Number of seconds that may elapse since the last notebook

save before a staleness warning is issued. Useful when exporting from an active IPython notebook.

topo.misc.ipython.prompt(message, default, options, skip=False)

Helper function to repeatedly prompt the user with a list of options. If no input is given, the default value is returned. If wither the skip flag is True or the prompt is in a batch mode environment (e.g. for automated testing), the default value is immediately returned.

---

lancext Module

The Topographica Lancet extension allows Topographica simulations to be easily integrated into a Lancet workflow (see github.com/ioam/lancet). The TopoCommand is appropriate for simple runs using the default analysis function, whereas the RunBatchCommand allow for more sophisticated measurements and analysis to be executed during a simulation run using a holoviews Collector object.

class topo.misc.lancext.BatchCollector(collector, **params)

Bases: lancet.core.PrettyPrinted, param.parameterized.Parameterized

BatchCollector is a wrapper class used to execute a Collector in a Topographica run_batch context, saving the HoloViews to disk as *.hvz files.

param String time_dimension (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=time, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Name of the Topographica simulation time dimension.

param List metadata (allow_None=False, bounds=(0, None), constant=False, default=[‘tid’], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

Spec keys or collector paths to include as metadata in the output file along with the simulation time. Layout paths are specified by dotted paths e.g. ‘PinwheelAnalysis.V1’ would add the pinwheel analysis on V1 to the metadata.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07aa022578>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07a9fe5470>

inspect_value = <functools.partial object at 0x2b07a9fe51b0>

classmethod load(tid, specs, root_directory, batch_name, batch_tag)

Classmethod used to load the RunBatchCommand callable into a Topographica run_batch context. Loads the pickle file based on the batch_name and root directory in batch_info.

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

classmethod pickle_path(root_directory, batch_name)

Locates the pickle file based on the given launch info dictionary. Used by load as a classmethod and by save as an instance method.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

pprint_args(pos_args, keyword_args, infix_operator=None, extra_params={})

Method to define the positional arguments and keyword order for pretty printing.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07aebc2d08>

set_param = <functools.partial object at 0x2b07aebc2ba8>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

verify(specs, model_params)

Check that a times list has been supplied, call verify_times on the Collator and if model_params has been supplied, check that a valid parameter set has been used.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.lancext.RunBatchCommand(tyfile, analysis, **params)

Bases: topo.misc.lancext.TopoCommand

Runs a custom analysis function specified by a Collector using run_batch. This command is far more flexible for regular usage than TopoCommand as it allows you to build a run_batch analysis incrementally.

param String executable (allow_None=False, basestring=<type ‘basestring’>, constant=True, default=python, instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

The executable that is to be run by this Command. Unless the executable is a standard command expected on the system path, this should be an absolute path. By default this invokes python or the python environment used to invoke the Command (Topographica for instance).

param Callable param_formatter (allow_None=False, constant=False, default=param_formatter(), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Used to specify run_batch formatting.

param String analysis_fn (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=default_analysis_function, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The name of the analysis_fn to run. If modified from the default, the named callable will need to be imported into the namespace using a ‘-c’ command in topo_flag_options.

param String progress_bar (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=disabled, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Number max_name_length (allow_None=False, bounds=None, constant=False, default=200, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Matches run_batch parameter of same name.

param Boolean tag (allow_None=False, bounds=(0, 1), constant=False, default=False, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Whether to label the run_batch generated directory with the batch name and batch tag.

param Boolean do_format (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Set to True to receive input arguments as formatted strings, False for the raw unformatted objects.

param ClassSelector analysis (allow_None=True, constant=False, default=None, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

The object used to define the analysis executed in RunBatch. This object may be a Topographica Collector or a BatchCollector which is a wrapper of a Collector.

param String tyfile (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The Topographica model file to run.

param Parameter model_params (allow_None=False, constant=False, default={}, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

A list or dictionary of model parameters to be passed to the model via run_batch. This is used to validate the parameter names specified. If set to an empty container, no checking is applied (default).

param Boolean vc_info (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Boolean snapshot (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Number progress_interval (allow_None=False, bounds=None, constant=False, default=100, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Matches run_batch parameter of same name.

param Boolean save_global_params (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Dict topo_flag_options (allow_None=False, constant=False, default={}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

Specifies Topographica flags and their corresponding options as a dictionary. This parameter is suitable for setting -c and -p flags for Topographica. This parameter is important for introducing the callable named by the analysis_fn parameter into the namespace. Tuples can be used to indicate groups of options using the same flag: {‘-p’:’retina_density=5’} => -p retina_density=5 {‘-p’:(‘retina_density=5’, ‘scale=2’) => -p retina_density=5 -p scale=2 If a plain Python dictionary is used, the keys are alphanumerically sorted, otherwise the dictionary is assumed to be an OrderedDict (Python 2.7+, Python3 or param.external.OrderedDict) and the key ordering will be preserved. Note that the ‘-‘ is prefixed to the key if missing (to ensure a valid flag). This allows keywords to be specified with the dict constructor eg.. dict(key1=value1, key2=value2).

param List topo_switches (allow_None=False, bounds=(0, None), constant=False, default=[‘-a’], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

Specifies the Topographica qsub switches (flags without arguments) as a list of strings. Note the that the -a switch is always used to auto import commands.

param List metadata (allow_None=False, bounds=(0, None), constant=False, default=[], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

Keys to include as metadata in the output file along with ‘time’ (Topographica simulation time).

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

finalize(info)

Pickle the analysis before launch.

force_new_dynamic_value = <functools.partial object at 0x2b07963bb578>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07963bb158>

inspect_value = <functools.partial object at 0x2b07aebc2d08>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

pprint_args(pos_args, keyword_args, infix_operator=None, extra_params={})

Method to define the positional arguments and keyword order for pretty printing.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07aebc2c00>

set_param = <functools.partial object at 0x2b07aebc2af8>

show(args, file_handle=None, **kwargs)

Write to file_handle if supplied, othewise print output

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

verify(args)

Check that the supplied arguments make sense given the specified analysis.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.lancext.TopoCommand(tyfile, executable=None, **params)

Bases: lancet.launch.Command

TopoCommand is designed to to format Lancet Args objects into run_batch commands in a general way. Note that Topographica is always invoked with the -a flag so all of topo.command is imported.

Some of the parameters duplicate those in run_batch to ensure consistency with previous run_batch usage in Topographica. As a consequence, this class sets all the necessary options for run_batch except the ‘times’ parameter which may vary specified arbitrarily by the Lancet Args object.

param String executable (allow_None=False, basestring=<type ‘basestring’>, constant=True, default=python, instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

The executable that is to be run by this Command. Unless the executable is a standard command expected on the system path, this should be an absolute path. By default this invokes python or the python environment used to invoke the Command (Topographica for instance).

param Callable param_formatter (allow_None=False, constant=False, default=param_formatter(), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Used to specify run_batch formatting.

param String analysis_fn (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=default_analysis_function, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The name of the analysis_fn to run. If modified from the default, the named callable will need to be imported into the namespace using a ‘-c’ command in topo_flag_options.

param String progress_bar (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=disabled, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Number max_name_length (allow_None=False, bounds=None, constant=False, default=200, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Matches run_batch parameter of same name.

param Boolean tag (allow_None=False, bounds=(0, 1), constant=False, default=False, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Whether to label the run_batch generated directory with the batch name and batch tag.

param Boolean do_format (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Set to True to receive input arguments as formatted strings, False for the raw unformatted objects.

param String tyfile (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The Topographica model file to run.

param Boolean vc_info (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Boolean snapshot (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Number progress_interval (allow_None=False, bounds=None, constant=False, default=100, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Matches run_batch parameter of same name.

param Boolean save_global_params (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Matches run_batch parameter of same name.

param Dict topo_flag_options (allow_None=False, constant=False, default={}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

Specifies Topographica flags and their corresponding options as a dictionary. This parameter is suitable for setting -c and -p flags for Topographica. This parameter is important for introducing the callable named by the analysis_fn parameter into the namespace. Tuples can be used to indicate groups of options using the same flag: {‘-p’:’retina_density=5’} => -p retina_density=5 {‘-p’:(‘retina_density=5’, ‘scale=2’) => -p retina_density=5 -p scale=2 If a plain Python dictionary is used, the keys are alphanumerically sorted, otherwise the dictionary is assumed to be an OrderedDict (Python 2.7+, Python3 or param.external.OrderedDict) and the key ordering will be preserved. Note that the ‘-‘ is prefixed to the key if missing (to ensure a valid flag). This allows keywords to be specified with the dict constructor eg.. dict(key1=value1, key2=value2).

param List topo_switches (allow_None=False, bounds=(0, None), constant=False, default=[‘-a’], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

Specifies the Topographica qsub switches (flags without arguments) as a list of strings. Note the that the -a switch is always used to auto import commands.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

finalize(info)

Optional method that allows a Command to save state before launch. The info argument is supplied by the Launcher.

force_new_dynamic_value = <functools.partial object at 0x2b07aa022578>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07aa0229f0>

inspect_value = <functools.partial object at 0x2b07aebc2ba8>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

pprint_args(pos_args, keyword_args, infix_operator=None, extra_params={})

Method to define the positional arguments and keyword order for pretty printing.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07aebc2c00>

set_param = <functools.partial object at 0x2b07aebc2c58>

show(args, file_handle=None, **kwargs)

Write to file_handle if supplied, othewise print output

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

summary()

A succinct summary of the Command configuration. Unlike the repr, a summary does not have to be complete but must supply key information relevant to the user. Must begin by stating the executable.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

verify(args)

Optional, final check that ensures valid arguments have been passed before launch. Allows the constant and varying_keys to be be checked and can inspect the specs attribute if an instance of Args. If invalid, raise an Exception with the appropriate error message, otherwise return None.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.lancext.param_formatter(**params)

Bases: param.parameterized.ParameterizedFunction

This class is closely related to the param_formatter class in topo/command/__init__.py. Like that default class, it formats parameters as a string for use in a directory name. Unlike that default class, it does not use the parameters repr methods but the exact, succinct commandline representation as returned by a Lancet Args object.

This version has several advantages over the default:

• It formats values exactly as they appear in a command. For

example, a value specified as 6.00 on the commandline remains this way and is never represented to higher precision or with floating point error.

• Parameters are sorted from slowest to fastest varying or

(optionally) alphanumerically by default.

• It allows for a custom separator and an optional trunctation

length for values.

• By default, formats a string only for the parameters that are

varying (may be toggled).

param Number truncation_limit (allow_None=True, bounds=None, constant=False, default=None, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

If None, no truncation is performed, otherwise specifies the maximum length of any given specification value.

param Dict abbreviations (allow_None=False, constant=False, default={}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

A dictionary of abbreviations to use of type {<key>:<abbrev>}. If a specifier key has an entry in the dictionary, the abbreviation is used. Useful for shortening long parameter names in the directory structure.

param Boolean alphanumeric_sort (allow_None=False, bounds=(0, 1), constant=False, default=False, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Whether to sort the (potentially abbreviated) keys alphabetically or not. By default, keys are ordered from slowest varying to fastest varying using thr information provided by Lancet’s Args object.

param Boolean format_constant_keys (allow_None=False, bounds=(0, 1), constant=False, default=False, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Whether to represent parameters that are known to be constant across batches.

param String separator (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=,, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The separator to use between <key>=<value> pairs.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07aebc2c00>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07aebc2ba8>

inspect_value = <functools.partial object at 0x2b07aebc2c58>

instance = <functools.partial object at 0x2b07aebc2af8>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix='n ', unknown_value='<?>', qualify=False, separator='')

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07aebc2cb0>

set_param = <functools.partial object at 0x2b07aebc2a48>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.lancext.topo_metadata(**params)

Bases: param.parameterized.Parameterized

Topographica specific helper function that expands on Lancet’s vcs_metadata function to generate suitable metadata information for logging with Lancet. Records Topographica version control information as well as information about all relevant submodules and the current numpy version.

No arguments should be necessary when either contructing or calling this object as the default behaviour is designed to be useful. The summary method prints out the key information collected to assist with reproducibility. For instance, this may be called to print all the relevant git revisions in an IPython Notebook before launching jobs.

param List paths (allow_None=False, bounds=(0, None), constant=False, default=[], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

List of git repositories including Topographica and relevant submodules. Version control information from these repositories will be returned as a dictionary when called. The most important information is pretty printed when the summary method is called.

param Dict commands (allow_None=False, constant=False, default={‘.git’: ([‘git’, ‘rev-parse’, ‘HEAD’], [‘git’, ‘log’, ‘–oneline’, ‘-n’, ‘1’], [‘git’, ‘diff’])}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

The git commands to pass to subprocess to extract the necessary version control information. Uses the same specification format as the lancet.vsc_metdata helper function.

param Integer max_log_length (allow_None=False, bounds=None, constant=False, default=90, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Maximum number of characters that will be shown per message in the printed summary.

param List repository_names (allow_None=False, bounds=(0, None), constant=False, default=[‘Topographica’, ‘Param’, ‘Paramtk’, ‘Imagen’, ‘Lancet’], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

Names of the repositories corresponding to the supplied paths

param List summarized (allow_None=False, bounds=(0, None), constant=False, default=[‘Topographica’, ‘Param’, ‘Imagen’, ‘Lancet’], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

The repositories to summarize as a subset of the repository names.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07963bb998>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07aebc2c00>

inspect_value = <functools.partial object at 0x2b07aebc2ba8>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07aebc2cb0>

set_param = <functools.partial object at 0x2b07aebc2a48>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

summary()

Printed summary of the versioning information captured via git.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

---

legacy Module

Code used to support old snapshots (those created from 0.9.7/r11275 onwards).

topo.misc.legacy.allow_import(module, location)

Allow module to be imported from location.

topo.misc.legacy.module_redirect(name, parent, actual_module)

For use when module parent.name is now actual_module.

topo.misc.legacy.postprocess_state(class_, state_mod_fn)

Allow processing of instance and state after state has been applied.

state_mod_fn must accept two arguments: instance and state.

topo.misc.legacy.preprocess_state(class_, state_mod_fn)

Allow processing of state with state_mod_fn before class_.__setstate__(instance,state) is called.

state_mod_fn must accept two arguments: instance and state.

---

memuse Module

Functions for measuring memory usage, to allow usage to be optimized.

Examples:

bin/python -c 'execfile("topo/misc/memuse.py") ; print topsize_mb()'

./topographica -c 'from topo.misc import memuse' -c 'print memuse.topsize_mb()'

./topographica -c 'from topo.misc import memuse, asizeof' -c 'print memuse.topsize_mb()'

./topographica -a -c 'from topo.misc import memuse, asizeof' -c 'print memuse.topsize_mb()'

./topographica -a -c 'from topo.misc import memuse, asizeof' examples/tiny.ty -c 'print memuse.allsizes_mb()'

./topographica -a -c 'from topo.misc import memuse, asizeof' -c 'memuse.memuse_batch("examples/tiny.ty",cortex_density=20)'

./topographica -a -c 'from topo.misc import memuse, asizeof' -c 'memuse.memuse_batch("examples/tiny.ty",times=[0,100],analysis_fn=memuse.plotting_and_saving_analysis_fn,cortex_density=20)'

topo.misc.memuse.allsizes_mb()

Collates results from topsize, simsize, and wtsize.

Formatted to suggest that the topsize is made up of code (not currently estimated), topo.sim (apart from weights), and weights.

topo.misc.memuse.cmd_to_string(cmd)

Run a system command as in os.system(), but capture the stdout and return it as a string.

topo.misc.memuse.default_memuse_analysis_fn(prefix='')

Basic memuse function for use with memuse_batch()

topo.misc.memuse.mb(bytes)

Format the given value in bytes as a string in megabytes

topo.misc.memuse.memuse_batch(script_file, times=[0], analysis_fn=<function default_memuse_analysis_fn at 0x2b07ab378848>, **params)

Similar to run_batch, but analyzes the memory requirement of a simulation at different times.

First, the specified script file will be run using the specified parameters. Then at each of the specified times, the given analysis_fn (which calls allsizes_mb() by default) is run. The output is labeled with the script file, time, and parameters so that results from different runs can be compared.

topo.misc.memuse.plotting_and_saving_analysis_fn(prefix='')

For use with memuse_batch() to test snapshot and plotting memory usage.

topo.misc.memuse.simsize()

Return the size of topo.sim reported by asizeof.asizeof(). This estimate does not currently include any numpy arrays, and may also be missing other important items.

Python 2.6 supports getsizeof() and a __sizeof__ attribute that user code can implement, which should provide a more accurate estimate.

topo.misc.memuse.simsize_mb()

String-formatted version of the value reported by asizeof(topo.sim).

topo.misc.memuse.topsize()

Return the RES size of this process as reported by the top(1) command.

topo.misc.memuse.topsize_mb()

String-formatted version of the RES size of this process reported by top(1).

topo.misc.memuse.wtsize_mb()

String-formatted version of the memory taken by the weights, from print_sizes().

---

picklemain Module

Extensions to pickle allowing items in __main__ to be saved.

class topo.misc.picklemain.PickleMain

Bases: object

Pickle support for types and functions defined in __main__.

When pickled, saves types and functions defined in __main__ by value (i.e. as bytecode). When unpickled, loads previously saved types and functions back into __main__.

topo.misc.picklemain.save_classobj(self, obj)

Save an interactively defined classic class object by value

topo.misc.picklemain.save_code(self, obj)

Save a code object by value

topo.misc.picklemain.save_function(self, obj)

Save functions by value if they are defined interactively

topo.misc.picklemain.save_global_byname(self, obj, modname, objname)

Save obj as a global reference. Used for objects that pickle does not find correctly.

topo.misc.picklemain.save_instancemethod(self, obj)

Save an instancemethod object

topo.misc.picklemain.save_module(self, obj)

Save modules by reference, except __main__ which also gets its contents saved by value

topo.misc.picklemain.save_module_dict(self, obj, main_dict={'make_main': <function make_main at 0x2b0788825d70>, '__builtins__': <module '__builtin__' (built-in)>, '__file__': '/usr/bin/sphinx-build', '__package__': None, 'sys': <module 'sys' (built-in)>, '__name__': '__main__', 'main': <function main at 0x2b0788825e60>, '__doc__': '\n Sphinx - Python documentation toolchain\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.\n :license: BSD, see LICENSE for details.\n'})

Special-case __main__.__dict__. Useful for a function’s func_globals member.

---

pyxhandler Module

Support for optional Cython .pyx files.

topo.misc.pyxhandler.provide_unoptimized_equivalent_cy(optimized_name, unoptimized_name, local_dict)

Replace the optimized Cython component with its unoptimized equivalent if pyximport is not available.

If import_pyx is True, warns about the unavailable component.

---

snapshots Module

class topo.misc.snapshots.PicklableClassAttributes(module, exclusions=(), startup_commands=())

Bases: object

Supports pickling of Parameterized class attributes for a given module.

When requested to be pickled, stores a module’s PO classes’ attributes, and any given startup_commands. On unpickling, executes the startup commands and sets the class attributes.

get_PO_class_attributes(module, class_attributes, processed_modules, exclude=())

Recursively search module and get attributes of Parameterized classes within it.

class_attributes is a dictionary {module.path.and.Classname: state}, where state is the dictionary {attribute: value}.

Something is considered a module for our purposes if inspect says it’s a module, and it defines __all__. We only search through modules listed in __all__.

Keeps a list of processed modules to avoid looking at the same one more than once (since e.g. __main__ contains __main__ contains __main__...)

Modules can be specifically excluded if listed in exclude.

---

trace Module

Object classes for recording and plotting time-series data.

This module defines a set of DataRecorder object types for recording time-series data, a set of Trace object types for specifying ways of generating 1D-vs-time traces from recorded data, and a TraceGroup object that will plot a set of traces on stacked, aligned axes.

class topo.misc.trace.ActivityMovie(**params)

Bases: param.parameterized.Parameterized

An object encapsulating a series of movie frames displaying the value of one or more matrix-valued time-series contained in a DataRecorder object.

An ActivityMovie takes a DataRecorder object, a list of names of variables in that recorder and a sequence of timepoints at which to sample those variables. It uses that information to compose a sequence of MontageBitmap objects displaying the stored values of each variable at each timepoint. These bitmaps can then be saved to sequentially-named files that can be composited into a movie by external software.

Parameters are available to control the layout of the montage, adding timecodes to the frames, and the names of the frame files.

param String filename_time_fmt (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=%05.0f, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The format of the frame time, using Python string substitution for a floating-point number.

param Number timecode_offset (allow_None=False, bounds=None, constant=False, default=0, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

A value to be added to each timecode before formatting for display.

param List variables (allow_None=False, bounds=(0, None), constant=False, default=[], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

A list of variable names in a DataRecorder object containing matrix-valued time series data.

param List frame_times (allow_None=False, bounds=(0, None), constant=False, default=[0, 1], instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

A list of the times of the frames in the movie.

param Dict timecode_options (allow_None=False, constant=False, default={}, instantiate=False, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

A dictionary of keyword options to be passed to the PIL ImageDraw.text method when drawing the timecode on the frame. Valid options include font, an ImageFont object indicating the text font, and fill a PIL color specification indicating the text color. If unspecified, color defaults to the PIL default of black. Font defaults to topo.plotting.bitmap.TITLE_FONT.

param Boolean add_timecode (allow_None=False, bounds=(0, 1), constant=False, default=False, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Whether to add a visible timecode indicator to each frame.

param String filetype (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=tif, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The filetype to use when writing frames. Can be any filetype understood by the Python Imaging Library.

param String filename_fmt (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=%n_%t.%T, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The format for the filenames used to store the frames. The following substitutions are possible: %n: The name of this ActivityMovie object. %t: The frame time, as formatted by the filename_time_fmt parameter %T: The filetype given by the filetype parameter.

param String filename_prefix (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

A prefix to prepend to the filename of each frame when saving; can include directories. If the filename contains a path, any non-existent directories in the path will be created when the movie is saved.

param Dict montage_params (allow_None=False, constant=False, default={}, instantiate=False, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

A dictionary containing parameters to be used when instantiating the MontageBitmap objects representing each frame.

param Dict overlays (allow_None=False, constant=False, default={}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

A dictionary indicating overlays for the variable bitmaps. The for each key in the dict matching the name of a variable, there should be associated a triple of matrices to be overlayed on the red, green, and blue channels of the corresponding bitmap in each frame.

param String timecode_fmt (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=%05.0f, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The format of the timecode displayed in the movie frames, using Python string substitution for a floating-point number.

param ClassSelector recorder (allow_None=True, constant=False, default=None, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

The DataRecorder storing the timeseries.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd8100>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07abfd8418>

inspect_value = <functools.partial object at 0x2b07abfd84c8>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

save()

Save the movie frames.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd8470>

set_param = <functools.partial object at 0x2b07abfd85d0>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.trace.DataRecorder(**params)

Bases: topo.base.simulation.EventProcessor

Record time-series data from a simulation.

A DataRecorder instance stores a set of named time-series variables, consisting of a sequence of recorded data items of any type, along with the times at which they were recorded.

DataRecorder is an abstract class for which different implementations may exist for different means of storing recorded data. For example, the subclass InMemoryRecorder stores all the data in memory.

A DataRecorder instance can operate either as an event processor, or in a stand-alone mode. Both usage modes can be used on the same instance in the same simulation.

STAND-ALONE USAGE:

A DataRecorder instance is used as follows:

• Method .add_variable adds a named time series variable.
• Method .record_data records a new data item and timestamp.
• Method .get_data gets a time-delimited sequence of data from a variable

EVENTPROCESSOR USAGE:

A DataRecorder can also be connected to a simulation as an event processor, forming a kind of virtual recording equipment. An output port from any event processor in a simulation can be connected to a DataRecorder; the recorder will automaticall create a variable with the same name as the connection, and record any incoming data on that variable with the time it was received. For example:

topo.sim['Recorder'] =  InMemoryRecorder()
topo.sim.connect('V1','Recorder',name='V1 Activity')

This script snippet will create a new DataRecorder and automatically record all activity sent from the sheet ‘V1’.

add_variable(name)

Create a new time-series variable with the given name.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd8418>

get_data(varname, times=(None, None), fill_range=False)

Get the named timeseries between the given times (inclusive). If fill_range is true, the returned data will have timepoints exactly at the start and end of the given timerange. The data values at these timepoints will be those of the next-earlier datapoint in the series.

(NOTE: fill_range can fail to create a beginning timepoint if the start of the time range is earlier than the first recorded datapoint.]

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_time_indices(varname, start_time, end_time)

For the named variable, get the start and end indices suitable for slicing the data to include all times t:

start_time <= t <= end_time.

A start_ or end_time of None is interpreted to mean the earliest or latest available time, respectively.

get_times(var)

Get all the timestamps for a given variable.

get_value_generator = <functools.partial object at 0x2b07abfd8310>

inspect_value = <functools.partial object at 0x2b07abfd8368>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

process_current_time()

Called by the simulation before advancing the simulation time. Allows the event processor to do any computation that requires that all events for this time have been delivered. Computations performed in this method should not generate any events with a zero time delay, or else causality could be violated. (By default, does nothing.)

record_data(varname, time, data)

Record the given data item with the given timestamp in the named timeseries.

script_repr(imports=, []prefix=' ')

Generate a runnable command for creating this EventProcessor.

send_output(src_port=None, data=None)

Send some data out to all connections on the given src_port. The data is deepcopied before it is sent out, to ensure that future changes to the data are not reflected in events from the past.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd8578>

set_param = <functools.partial object at 0x2b07abfd8680>

start()

Called by the simulation when the EventProcessor is added to the simulation.

If an EventProcessor needs to have any code run when it is added to the simulation, the code can be put into this method in the subclass.

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.trace.IdentityTrace(**params)

Bases: topo.misc.trace.Trace

A Trace that returns the data, unmodified.

param Number ymargin (allow_None=False, bounds=None, constant=False, default=0.1, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The fraction of the difference ymax-ymin to add to the top of the plot as padding.

param Dict plotkw (allow_None=False, constant=False, default={‘linestyle’: ‘steps’}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

Contains the keyword arguments to pass to the plot command when plotting the trace.

param String data_name (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=None, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Name of the timeseries from which the trace is generated. E.g. the connection name into a DataRecorder object.

param Parameter ybounds (allow_None=False, constant=False, default=(None, None), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The (min,max) boundaries for y axis. If either is None, then the bound min or max of the data given, respectively.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd83c0>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07abfd8310>

inspect_value = <functools.partial object at 0x2b07abfd84c8>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd8100>

set_param = <functools.partial object at 0x2b07abfd86d8>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.trace.InMemoryRecorder(**params)

Bases: topo.misc.trace.DataRecorder

A data recorder that stores all recorded data in memory.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd83c0>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_time_indices(varname, start_time, end_time)

For the named variable, get the start and end indices suitable for slicing the data to include all times t:

start_time <= t <= end_time.

A start_ or end_time of None is interpreted to mean the earliest or latest available time, respectively.

get_value_generator = <functools.partial object at 0x2b07abfd8368>

inspect_value = <functools.partial object at 0x2b07abfd82b8>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

process_current_time()

Called by the simulation before advancing the simulation time. Allows the event processor to do any computation that requires that all events for this time have been delivered. Computations performed in this method should not generate any events with a zero time delay, or else causality could be violated. (By default, does nothing.)

script_repr(imports=, []prefix=' ')

Generate a runnable command for creating this EventProcessor.

send_output(src_port=None, data=None)

Send some data out to all connections on the given src_port. The data is deepcopied before it is sent out, to ensure that future changes to the data are not reflected in events from the past.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd8578>

set_param = <functools.partial object at 0x2b07abfd85d0>

start()

Called by the simulation when the EventProcessor is added to the simulation.

If an EventProcessor needs to have any code run when it is added to the simulation, the code can be put into this method in the subclass.

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.trace.IndexTrace(**params)

Bases: topo.misc.trace.Trace

A Trace that assumes that each data item is a sequence that can be indexed with a single integer, and traces the value of one indexed element.

param Integer index (allow_None=False, bounds=None, constant=False, default=0, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The index into the data to be traced.

param String data_name (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=None, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Name of the timeseries from which the trace is generated. E.g. the connection name into a DataRecorder object.

param Number ymargin (allow_None=False, bounds=None, constant=False, default=0.1, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The fraction of the difference ymax-ymin to add to the top of the plot as padding.

param Dict plotkw (allow_None=False, constant=False, default={‘linestyle’: ‘steps’}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

Contains the keyword arguments to pass to the plot command when plotting the trace.

param Parameter ybounds (allow_None=False, constant=False, default=(None, None), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The (min,max) boundaries for y axis. If either is None, then the bound min or max of the data given, respectively.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd85d0>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07abfd82b8>

inspect_value = <functools.partial object at 0x2b07abfd8310>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd8680>

set_param = <functools.partial object at 0x2b07abfd84c8>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.trace.SheetPositionTrace(**params)

Bases: topo.misc.trace.Trace

A trace that assumes that the data are sheet activity matrices, and traces the value of a given (x,y) position on the sheet.

param String data_name (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=None, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Name of the timeseries from which the trace is generated. E.g. the connection name into a DataRecorder object.

param Number y (allow_None=False, bounds=None, constant=False, default=0.0, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The y sheet-coordinate of the position to be traced.

param Composite position (allow_None=True, attribs=[‘x’, ‘y’], constant=False, default=None, instantiate=False, objtype=<class ‘topo.misc.trace.SheetPositionTrace’>, pickle_default_value=True, precedence=None, readonly=False)

The sheet coordinates of the position to be traced.

param Number ymargin (allow_None=False, bounds=None, constant=False, default=0.1, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The fraction of the difference ymax-ymin to add to the top of the plot as padding.

param Number x (allow_None=False, bounds=None, constant=False, default=0.0, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The x sheet-coordinate of the position to be traced.

param Parameter coordframe (allow_None=True, constant=False, default=None, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The SheetCoordinateSystem to use to convert the position into matrix coordinates.

param Dict plotkw (allow_None=False, constant=False, default={‘linestyle’: ‘steps’}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

Contains the keyword arguments to pass to the plot command when plotting the trace.

param Parameter ybounds (allow_None=False, constant=False, default=(None, None), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The (min,max) boundaries for y axis. If either is None, then the bound min or max of the data given, respectively.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd8368>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07abfd85d0>

inspect_value = <functools.partial object at 0x2b07abfd8578>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd81b0>

set_param = <functools.partial object at 0x2b07abfd86d8>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.trace.Trace(**params)

Bases: param.parameterized.Parameterized

A specification for generating 1D traces of data from recorded timeseries.

A Trace object is a callable object that encapsulates a method for generating a 1-dimensional trace from possibly multidimensional timeseries data, along with a specification for how to plot that data, including Y-axis boundaries and plotting arguments.

Trace is an abstract class. Subclasses implement the __call__ method to define how to extract a 1D trace from a sequence of data.

param Number ymargin (allow_None=False, bounds=None, constant=False, default=0.1, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

The fraction of the difference ymax-ymin to add to the top of the plot as padding.

param Dict plotkw (allow_None=False, constant=False, default={‘linestyle’: ‘steps’}, instantiate=True, is_instance=True, pickle_default_value=True, precedence=None, readonly=False)

Contains the keyword arguments to pass to the plot command when plotting the trace.

param String data_name (allow_None=False, basestring=<type ‘basestring’>, constant=False, default=None, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Name of the timeseries from which the trace is generated. E.g. the connection name into a DataRecorder object.

param Parameter ybounds (allow_None=False, constant=False, default=(None, None), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

The (min,max) boundaries for y axis. If either is None, then the bound min or max of the data given, respectively.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd8578>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07abfd8680>

inspect_value = <functools.partial object at 0x2b07abfd83c0>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd84c8>

set_param = <functools.partial object at 0x2b07abfd8730>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class topo.misc.trace.TraceGroup(recorder, traces=, []**params)

Bases: param.parameterized.Parameterized

A group of data traces to be plotted together.

A TraceGroup defines a set of associated data traces and allows them to be plotted on stacked, aligned axes. The constructor takes a DataRecorder object as a data source, and a list of Trace objects that indicate the traces to plot. The trace specifications are stored in the attribute self.traces, which can be modified at any time.

param Boolean time_axis_relative (allow_None=False, bounds=(0, 1), constant=False, default=False, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Whether to plot the time-axis tic values relative to the start of the plotted time range, or in absolute values.

param Number hspace (allow_None=False, bounds=None, constant=False, default=0.6, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, time_dependent=True, time_fn=<Time Time00001>)

Height spacing adjustment between plots. Larger values produce more space.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

force_new_dynamic_value = <functools.partial object at 0x2b07abfd8680>

get_param_values(onlychanged=False)

Return a list of name,value pairs for all Parameters of this object.

If onlychanged is True, will only return values that are not equal to the default value.

get_value_generator = <functools.partial object at 0x2b07abfd8418>

inspect_value = <functools.partial object at 0x2b07abfd81b0>

message(msg, *args, **kw)

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

classmethod params(parameter_name=None)

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

plot(times=(None, None))

Plot the traces.

Requires MatPlotLib (aka pylab).

Plots the traces specified in self.traces, over the timespan specified by times. times = (start_time,end_time); if either start_time or end_time is None, it is assumed to extend to the beginning or end of the timeseries, respectively.

pprint(imports=None, prefix=' ', unknown_value='<?>', qualify=False, separator='')

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults()

Print the default values of all cls’s Parameters.

print_param_values()

Print the values of all this object’s Parameters.

script_repr(imports=, []prefix=' ')

Variant of __repr__ designed for generating a runnable script.

classmethod set_default(param_name, value)

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn = <functools.partial object at 0x2b07abfd86d8>

set_param = <functools.partial object at 0x2b07abfd82b8>

state_pop()

Restore the most recently saved state.

See state_push() for more details.

state_push()

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

topo.misc.trace.get_images(name, times, recorder, overlays=(0, 0, 0))

Get a time-sequence of matrix data from a DataRecorder variable and convert it to a sequence of images stored in Bitmap objects.

Parameters: name is the name of the variable to be queried. times is a sequence of timepoints at which to query the variable. recorder is the data recorder. overlays is a tuple of matrices or scalars to be added to the red, green, and blue channels of the bitmaps respectively.

---

unitsupport Module

Unit Support: Classes and methods to allow Unum and Quantities unit packages to interact with Topographica.

class topo.misc.unitsupport.Conversions(units=None)

Bases: object

The UnumConversion class holds unit conversions and definitions, setting and resetting the unum unit table allowing sheet specific conversions to be performed.

declare_unit = <functools.partial object at 0x2b07aba65100>

get_unit = <functools.partial object at 0x2b07aba650a8>

classmethod set_package(obj, package)

Set the public methods in accordance with the selected package.

---

util Module

General utility functions and classes.

class topo.misc.util.MultiFile(*file_like_objs)

Bases: object

For all file_like_objs passed on initialization, provides a convenient way to call any of file’s methods (on all of them).

E.g. The following would cause ‘test’ to be written into two files, as well as to stdout:

import sys f1 = open(‘file1’,’w’) f2 = open(‘file2’,’w’) m = MultiFile(f1,f2,sys.stdout) m.write(‘test’)

topo.misc.util.NxN(tuple)

Converts a tuple (X1,X2,...,Xn) to a string ‘X1xX2x...xXn’

class topo.misc.util.Struct(**entries)

A simple structure class, taking keyword args and assigning them to attributes.

For instance:

>>> s = Struct(foo='a',bar=1)
>>> s.foo
'a'
>>> s.bar
1

From http://www.norvig.com/python-iaq.html

topo.misc.util.centroid(pts, weights)

Return the centroid of a weighted set of points as an array.

The pts argument should be an array of points, one per row, and weights should be a vector of weights.

topo.misc.util.flat_indices(shape)

Returns a list of the indices needed to address or loop over all the elements of a 1D or 2D matrix with the given shape. E.g.:

flat_indices((3,)) == [0,1,2]

topo.misc.util.flatten(l)

Flattens a list.

Written by Bearophile as published on the www.python.org newsgroups. Pulled into Topographica 3/5/2005.

topo.misc.util.frange(start, end=None, inc=1.0, inclusive=False)

A range function that accepts float increments.

Otherwise, works just as the inbuilt range() function. If inclusive is False, as in the default, the range is exclusive (not including the end value), as in the inbuilt range(). If inclusive is true, the range may include the end value.

‘All theoretic restrictions apply, but in practice this is more useful than in theory.’

From: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66472

topo.misc.util.idx2rowcol(idx, shape)

Given a flat matrix index and a 2D matrix shape, return the (row,col) coordinates of the index.

topo.misc.util.linearly_interpolate(table, value)

Interpolate an appropriate value from the given list of values, by number.

Assumes the table is a list of items to be returned for integer values, and interpolates between those items for non-integer values.

topo.misc.util.profile(command, n=50, sorting=('cumulative', 'time'), strip_dirs=False)

Profile the given command (supplied as a string), printing statistics about the top n functions when ordered according to sorting.

sorting defaults to ordering by cumulative time and then internal time; see http://docs.python.org/lib/profile-stats.html for other sorting options.

By default, the complete paths of files are not shown. If there are multiple files with the same name, you might wish to set strip_dirs=False to make it easier to follow the output.

Examples:

• profile loading a simulation:

profile(‘execfile(“examples/hierarchical.ty”)’)

• profile running an already loaded simulation:

profile(‘topo.sim.run(10)’)

• profile running a whole simulation:

profile(‘execfile(“examples/lissom_oo_or.ty”);topo.sim.run(20000)’)

• profile running a simulation, but from the commandline:

./topographica examples/hierarchical.ty -c “from topo.misc.util import profile; profile(‘topo.sim.run(10)’)”

topo.misc.util.rowcol2idx(r, c, shape)

Given a row, column, and matrix shape, return the corresponding index into the flattened (raveled) matrix.

topo.misc.util.shortclassname(x)

Returns the class name of x as a string with the leading package information removed.

E.g. if x is of type “<class ‘topo.base.sheet.Sheet’>”, returns “Sheet”

topo.misc.util.signabs(x)

Split x into its sign and absolute value.

Returns a tuple (sign(x),abs(x)). Note: sign(0) = 1, unlike numpy.sign.

topo.misc.util.weighted_sample(seq, weights=[])

Select randomly from the given sequence.

The weights, if given, should be a sequence the same length as seq, as would be passed to weighted_sample_idx().

topo.misc.util.weighted_sample_idx(weights)

Return an integer generated by sampling the discrete distribution represented by the sequence of weights.

The integer will be in the range [0,len(weights)). The weights need not sum to unity, but can contain any non-negative values (e.g., [1 1 1 100] is a valid set of weights).

To use weights from a 2D numpy array w, specify w.ravel() (not the w.flat iterator).

---