distance() documentation

Managing anatomically complex model cells with the CellBuilder. Importing morphometric data with NEURON's Import3D tool or Robert Cannon's CVAPP. Where to find detailed morphometric data.
Post Reply
Brad

distance() documentation

Post by Brad »

I find the documentation for "distance()" to be a bit confusing. (The one I am looking at is here http://www.neuron.yale.edu/neuron/stati ... l#distance.)

It appears there are two ways one could use this function, possibly a consequence of maintaining backwards compatability.


Style 1: Reference point at root of branch

Use

Code: Select all

distance()
to set the origin at the root of the currently accessed section. Then use

Code: Select all

distance(x)
to calculate the distance from the root to the current point at position x. See SECTION 1 below.



Style 2: Reference point specified by user

Use

Code: Select all

distance(0,x1)
to set the origin at position x1 of the currently accessed section and

Code: Select all

distance(1,x2)
returns the distance between position x2 of the currently accessed section and x1. See SECTION 2 below.



A little test script to demonstrate this is:

Code: Select all

create dend
dend {
	L = 100
	diam = 1
	nseg = 10	// usually, it's a good idea to use an odd value of nseg, but an even value is used here for illustrative purposes

	// SECTION 1

	distance()	// sets origin to root of currently accessed section

	for i= 0,4 {
		p = 0.25*i
		print distance(p)
	}

	print ""

	// SECTION 2

	distance(0,0.5)	// sets origin to arbitrary point of currently accessed section

	for i= 0,4 {
		p = 0.25*i
		print distance(1,p)
	}

}
It appears that one can "mix and match" the styles (i.e.use "distance()" to set origin and "distance(1,x2)" to set the 2nd point). But are these all the nuances to "distance()"?

It might be beneficial to users to have this documentation updated and clarified. Thanks.

Brad
ted
Site Admin
Posts: 6286
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

distance()

Post by ted »

I'm not sure what the source of confusion is. The Programmer's Reference entry for
distance() is

Code: Select all

SYNTAX
distance() or distance(0, x)
len = distance(x) or len = distance(1, x)

DESCRIPTION
Compute the path distance between two points on a neuron.

distance() with no arguments
    specifies the origin as location 0 of the currently accessed section. 
distance(x) (0<=x<=1)
    returns the distance (in microns) from the origin to this point on the currently 
accessed section. 

To overcome the old initialization restriction, distance(0, x) can be used to 
set the origin. Note that distance is measured from the centers of segments. 
This states clearly that distance() and distance(0,x) have different effects. No such
difference is noted between the results of distance(x) and distance(1, x), which return
identical values regardless of how the origin for distance measurements was specified.
(it's easy enough to run a simple test to verify this interpretation). I suppose it could be
clearer if there was an explicit statement that distance(x) and distance(1, x) return
identical results; is this what you mean?

--Ted
Brad

Post by Brad »

Currently, the "Syntax" section lists a total of four different statements one can make, but the "Description" section details only two and a half. For the second style, I initially found it confusing as to what the 0 and 1 were refrencing (ie not positions!). For me, it took many readings and interpretations (and the test code) to discover that there are two methods, the distance()/distance(x) pair being an older, slightly less powerful way, and the more powerful distance(0,x)/distance(1,x). I feel it should more explicitly detail the usage of the latter.

Under the assumption that my statements in the original post are correct (since you didn't mention it), I would reword it as
distance


SYNTAX
distance() or distance(0, x)
len = distance(x) or len = distance(1, x)

DESCRIPTION
Compute the path distance between two points on a neuron.


Method 1
distance() with no arguments
specifies the origin as location 0 of the currently accessed section.

distance(x) (0<=x<=1)
returns the distance (in microns) from the origin to location x on the currently accessed section.



Method 2
distance(0, x) (0<=x<=1)
specifies origin as location x of the currently accessed section.

distance(1, x) (0<=x<=1)
returns the distance (in microns) from the origin to location x on the currently accessed section.


Note that distance is measured from the centers of segments.
[The formatting of the above is messed up a bit; I guess that the html strips out the whitespace at the start of some lines.]

distance is not a function I use everyday, and everytime I revisit it, I have to relearn how to use it and I found the documentation a small hurdle. Hope this helps you see where I am coming from.
Brad

Post by Brad »

Neglected to specifically answer Ted's questions:
I suppose it could be clearer if there was an explicit statement that distance(x) and distance(1, x) return identical results; is this what you mean?

Yes. I see your way of looking at it now. So perhaps this is more appropriate
distance

SYNTAX
distance() or distance(0, x)
len = distance(x) or len = distance(1, x)

DESCRIPTION
Compute the path distance between two points on a neuron.


Setting Origin
distance() with no arguments
specifies the origin as location 0 of the currently accessed section.
distance(0, x) (0<=x<=1)
specifies the origin as location x of the currently accessed section.


Returning distance from Origin
distance(x) (0<=x<=1)
or
distance(1, x) (0<=x<=1)
returns the distance (in microns) from the origin to location x on the currently accessed section. Both return identical results, regardless of the method in which the origin was set.


Note that distance is measured from the centers of segments.
ted
Site Admin
Posts: 6286
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Post by ted »

For me, it took many readings and interpretations (and the test code) to discover that there are two methods, the distance()/distance(x) pair being an older, slightly less powerful way, and the more powerful distance(0,x)/distance(1,x)
There really aren't two methods. There is just a single distance func that takes
different actions depending on its arguments. distance() with no arguments specifies
the origin for distance measurements as the midpoint of the current section, and
distance(0, x) specifies the origin as the x location of the current section. distance(x)
and distance(1,x) both do the same thing: return the distance from the x location of the
current section to the previously specified origin for distance measurement. What's
missing from the documentation is an explicit statement that distance(1,x) is equivalent
to distance(x).

--Ted
oren
Posts: 55
Joined: Fri Mar 22, 2013 1:03 am

Re: distance() documentation

Post by oren »

I also got confused, I think the documentation should be changed to the way Brad suggested.

Thanks.
Post Reply