Better directory organization for examples

[sf-issues]

Converted from SourceForge issue 2900472, submitted by jbednar Submit Date: 2009-11-19 14:23 GMT

At present, user-written example files and models go into either examples/, if they are settled and ready for someone else to build on, or in contrib/ otherwise.

In the long run, we'll probably need more precise categorization so that the purpos and usage of these files is clear. Based on a discussion between me and Chris Ball in September 2008, below is our current plan, awaiting having some of this work published or otherwise drawn to a close so that there can be a canonical version of the models.

examples/

Simple example scripts, not replicating published work (tiny.ty, hierarchical.ty, other demos, etc.)

models/

Complete specifications of inputs and networks that, when run, generate an adult brain of some sort. Currently most of the things in examples/ are like this, but there would be an expectation that models/ are published or otherwise polished or complete. Of the current examples/, candidates for models/ include:

goodhill\_network90\.ty
lissom\_fsa\.ty
lissom\_oo\_or\.ty
lissom\_or\.ty
lissom\.ty
obermayer\_pnas90\.ty
sullivan\_neurocomputing04\.ty

experiments/

Scripts that, when run, replicate some sort of experiment that could in principle be run on an animal or human.

Experiments should whenever practical be possible to apply to an arbitrary network, without knowing much about its structure. E.g. the name of the cortical area to analyze (e.g.) should be a parameter, defaulting to "V1" usually, but overridable. Inputs should be presented to all GeneratorSheets by default, but again overridable. Scripts should return a value that would be the result of the analysis, in addition to any printing or plotting that they do, and preferably there would be sub-functions that do this (not necessarily in experiments/) so that experiments/ would be trivial lists of printing and plotting rather than actual detailed analysis.

Everything important should be in a function, so that the file can be imported, but it should have a section

          if \_\_name\_\_ == '\_\_main\_\_':
              run\(\)

where run() runs the typical experiment. That way, simply specifying the experiment on the command line:

  \./topographica \-g examples/tiny\.ty contrib/ae\.py

is enough to run it.

A .ty suffix (e.g. ae.ty) would cause problems here, though, as we can't currently import from .ty files, and thus won't be able to have any experiments that share code with other things in experiments/. But maybe that's not a big deal, as reusable chunks should probably go into topo (e.g. topo/analysis/) anyway...

For scripts that operate on adult cortex, it would be nice if they automatically generated (while printing a notice) the saved network, then used it. We're not sure exactly how to do this cleanly (given different densities, different runs, etc.), but it seems like we can figure that out.

contrib/

Code (in .py files) or models (in .ty files) in heavy development or not suitable for most users to examine.

In addition to these top-level directories, we want to somehow achieve more mixing and matching and reduce code duplication by making separate repositories for:

topo/region/

Complete models of a single brain region. Examples:

Single\-layer SOM model of V1, adding the necessary defaults to CFSheet
Single\-layer LISSOM model of V1, with scheduled actions, output\_fn, etc\.
Multi\-layer models of V1, e\.g\. LESI, simple\+complex layers, and laminar SF models,
Multi\-layer models of the LGN \(ON/OFF, plus R/G,G/R, different sizes, etc\.\)

In each case the regions would be wrapped into some interface that would allow the constituent Sheet(s) to receive projections, and would make it simple to connect them as a set to a target region, but also somehow allow combined processing of the group of sheets (e.g. for estimating the signal that would be measured by optical imaging or LFP).

topo/patternset/ (or some other name)

Generalizations of a PatternGenerator, something like a PatternPresenter, consisting of a coordinated set of inputs to a set of GeneratorSheets (e.g. Nature, Noisy Disks, etc.) This could then be combined with one or more topo.region models to build a network model.

[sf-issues]

Submitted by jbednar Date: 2012-02-13 11:43 GMT

Partial plan to be implemented in the current release:

examples/ gcal.ty hierarchical.ty perrinet_retina_pynest.py perrinet_retina.ty som_retinotopy.ty ptztracker.ty saccade_demo.ty tiny.ty lissom_audio.ty

models/ goodhill_network90.ty lissom_fsa.ty lissom_oo_or.ty lissom_or_movie.ty lissom_or.ty lissom.ty sullivan_neurocomputing04.ty lissom_whisker_barrels.ty obermayer_pnas90.ty leaky_lissom_or.ty lissom_oo_or_cr.ty

Makefile (delete) README.txt (split in two and make complete for each directory)

The other work on regions, patternsets, and experiments isn't ready for release yet.

[jlstevens]

I think this has been implemented (/models and /examples).

We no longer have contrib and I think we have new plans for the equivalents of topo/patternset, topo/region and topo/experiments (see Tobias' project). Can we close this issue?

[jbednar]

Almost! I think patternset and region will be addressed by Tobias, but experiments are still not worked out. The above discussion of experiments has some useful and non-obvious discussion, and so we should keep this open until we have implemented experiments properly (e.g. Giacomo's McCollough Effect paradigm), in a form that can be used with multiple different networks.