R/morphometry.R
neuromorpho_persistence_vectors.RdFor each neuron corresponding to a given neuron name or neuron ID, return the persistence vectors stored on neuromorpho.org. See details for a brief explanation for these persistence vectors.
neuromorpho_persistence_vectors(
neuron_name = NULL,
neuron_id = NULL,
batch.size = 5,
progress = TRUE,
neuromorpho_url = "http://neuromorpho.org",
...
)a neuron name, or vector of neuron names, as recorded in the neuromorpho database. Names and neuron IDs
can be found by searching the repository, for example via neuromorpho_search
a neuron ID, or vector of neuron IDs, as recorded in the neuromorpho database. If neuron_name is given
this supersedes neuron_id, which is then treated as if its value were NULL.
the number of requests sent at once to the neuromorpho.org, using multi_run.
Requests are sent to neuromorpho.org in parallel to speed up the process of reading neurons. Batches of queries are processed serially.
Increasing the value of batch.size may reduce read time.
if TRUE or a numeric value, a progress bar is shown.
The bar progresses when each batch is completed.
If TRUE, or 100, the bar completes where all batches are done.
the base URL for querying the neuromorpho database, defaults to http://neuromorpho.org
methods passed to neuromorpho_async_req, or in some cases, neuromorphr:::neuromorpho_fetch
a list of measurements for a neuron, or a list of lists if neuron_name/neuron_id is a vector with more than one element
Text taken from neuromorpho.org's FAQs:
Persistent homology is a methodology to characterise and summarise geometric shapes, as well as to describe meaningful features across scales. In this approach, a given shape is summarised using a mathematical construct called a "filtration", which consists of a nested sequence of subsets of the original shape. One can think of a filtration as a specific way to grow and generate the shape being examined. As we "filter" through the shape using this sequence, new topological features may be created and some older ones may be destroyed. In the case of neuronal morphologies, the standard swc format represents a tree embedded in three-dimensional physical space, and the observed features could be, for instance, neurite branches. Persistent homology tracks the creation ("birth") and destruction ("death") of these topological features during the filtration process. The resulting births and deaths of features are summarised in a so-called persistence diagram: a set of 2D points whose (x, y) coordinates represent the birth and death times of the features. The life-time of a feature (death time minus birth time) is called the persistence of this feature, encoding how long this feature exists during the filtration.
In particular, for the persistence feature included here, the descriptor function is derived from a simplified representation of the neuron that only considers the roots, bifurcations, and terminations while ignoring all continuation points along the branches. In other words, we put a straight segment between any two tree nodes (with degree not equal to 2); the weight of this arc is its Euclidean length. The descriptor function is the total length of the unique path (i.e., the geodesic distance) from the tree root (as specified in the SWC file) to any point in the tree. We then filter the neuron tree by sweeping it in decreasing function values, and compute the induced persistence diagram. Intuitively, the set of points in the persistence diagram captures a nested branch decomposition of the neuron tree with respect to the chosen description.
Finally, we convert the persistence diagram summary into a 1D persistence feature vector. The first two numbers in the persistence vector file represent the range (minimum and maximum values) of the descriptor function. The remaining entries represent the function values at 100 positions sampled uniformly in this range.
The original software code to compute Persistence Vectors from SWC files is available open source at the NeuronTools repository.
Reference: Li Y, Wang D, Ascoli GA, Mitra P, Wang Y (2017) Metrics for comparing neuronal tree shapes based on persistent homology. PLoS ONE 12(8): e0182184. DOI:10.1371/journal.pone.0182184.
For each neuron, the following is returned:
neuron_id
scaling factor
distance
coefficients