Processing SWC Files
====================

CAJAL supports neuronal tracing data in the SWC spec as specified here:
http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html

The sample_swc.py file contains functions to help the user sample points
from an \*.swc file.

.. autoclass:: cajal.swc.NeuronNode
.. autoclass:: cajal.swc.NeuronTree
.. class:: cajal.swc.SWCForest

	   A :class:`swc.SWCForest` is a list of
	   :class:`swc.NeuronTree`'s. It is intended to be used
	   to represent a list of all connected components from an SWC
	   file. An SWCForest represents all contents of one SWC file.

.. autofunction:: cajal.swc.read_swc

One can alternately represent an SWC file in a simple list format, rather than
using a nested class structure. The class structure may be more elegant, but we
have encountered a number of SWCs so far where the depth of the graph
associated to an SWC exceeds the default stack limit of Python, and so
recursive algorithms on graphs are prone to stack overflow errors. A list is
more amenable to iterative algorithms. In particular, if the user wants to
serialize the data of an SWC graph (for example, to pass it between two
processes or threads) they should recast it as a list so that the Python
serialization function does not cause a stack overflow.

.. autofunction:: cajal.swc.linearize
.. autofunction:: cajal.swc.forest_from_linear
.. autofunction:: cajal.swc.write_swc

If the user is batch-processing all \*.swc files in a given directory, it is appropriate to
include a filtering function so that the user does not accidentally crash the program by
trying to read a non-SWC file into memory. Such extraneous files could include backup text files
automatically generated by a text editor or by the operating system, hidden files, log files,
or lists of cell indices. Therefore the user has the option to supply a "name validation" function
which returns either True or False for each file name in the directory, only the filenames which
pass the name validation test will be sampled from. The default name validation function is this one:

.. autofunction:: cajal.swc.default_name_validate

The user should be warned that passing information between distinct Python processes
is costly, and the following function is not recommended if the user wants to employ multiprocessing,
as any child process which takes cells from this iterator as input will incur high overhead by
serializing and copying the data between processes. For multiprocessing/parallelization it is better
to give each process its own list of file names to operate on, and let them read the files
independently.

.. autofunction:: cajal.swc.cell_iterator

The following function is very useful for sampling from fragments of a neuron.
.. autofunction:: cajal.swc.filter_forest

.. autofunction:: cajal.swc.keep_only_eu
.. autofunction:: cajal.swc.preprocessor_geo
.. autofunction:: cajal.swc.preprocessor_eu		  
.. autofunction:: cajal.swc.total_length
.. autofunction:: cajal.swc.weighted_depth
.. autofunction:: cajal.swc.discrete_depth
.. autofunction:: cajal.swc.node_type_counts_tree
.. autofunction:: cajal.swc.node_type_counts_forest
.. autofunction:: cajal.swc.num_nodes
.. autofunction:: cajal.swc.read_preprocess_save
.. autofunction:: cajal.swc.get_filenames
.. autofunction:: cajal.swc.batch_filter_and_preprocess

For computing geodesic distances, it is more convenient to have a data structure
with the weights precomputed and attached to the edges, so we introduce an alternate
representation for a neuron where coordinates are forgotten and only the weighted tree
structure remains. These objects can be smaller than the original NeuronTrees.

.. autoclass:: cajal.weighted_tree.WeightedTreeRoot
.. autoclass:: cajal.weighted_tree.WeightedTreeChild

A :class:`cajal.weighted_tree.WeightedTree` is either a
:class:`cajal.weighted_tree.WeightedTreeRoot` or a
:class:`cajal.weighted_tree.WeightedTreeChild`.

.. autofunction:: cajal.weighted_tree.WeightedTree_of
