Review parameterization of location-dependent connection kernels

[heplesser]

This issue is inspired by #2388. The attached notebook provides a brief overview over some problems with the current implementation and documentation of location-dependent connection kernels, especially the Gaussian variants

• SpatialKernelProblems notebook as PDF
• SpatialKernelProblems as zipped notebook

Here some suggestions for a solution:

• Around the table of "distributions" in https://github.com/nest/nest-simulator/blob/master/doc/userdoc/guides/spatially_structured_networks.rst, make very explicit that these are not distributions, but functions and that their behavior depends on what they are "fed".
• Very clearly distinguish between distance (Euclidean distance of source and target neuron, non-negative scalar) and displacement, the vector pointing from source neuron to target neuron.
• Similar to nest.spatial.distance, introduce nest.spatial.displacement, which will be a 2D or 3D vector.
• Users can provide either distance or displacement as input, but they will be explicit then, and we should provide examples for behaviour in both cases.
• Where kernel functions need scalar values while the user provides vectors, we implicitly apply the Euclidean norm to the vector.
• Explicit passing of x- and y-components is reserved for very special cases.
• Rotation of the 2D gaussian is expressed using an angle as in Add rectified Gabor distribution for nest.spatial #2387. The use of $\rho$ might be kept for backward compatibility for a transition period.

[ackurth]

When deciding for a parametrization for rotation, as e.g. suggested in #2387 we need to be careful and avoid inconsistencies:

• NEST already has an rotation parameter: azimuth_angle in the elliptical mask
• there one passes the angle in degree, not in rad as for the Gabor function
• the rotations in the elliptical mask and in Add rectified Gabor distribution for nest.spatial #2387 are shifted by 90 deg: 0 deg for the mask -> parallel to horizontal axis, 0 deg for Gabor -> parallel to vertical axis

Do we want the angle in degree or rad?
Do we want 0 deg to be aligned to the vertical of horizontal axis. In view of back-portability, the latter seems more favorable.
What do you think?

[heplesser]

@ackurth Thanks for working this out! We should indeed align. In mathematics, 0 angle is usually at the horizontal and one counts counterclockwise, while on maps it is on the vertical and one goes around clockwise. What would be most intuitive to computational neuroscientists? How does the neuroscience literature describe receptive field orientation and similar? The same questions apply to degree vs radians.

[ackurth]

In the literature I only found ambiguous uses: Here (from Allen institute) the vertical axis corresponds to 0 deg. On the other hand, in this study by Hubel and Wiesel the horizontal axis seems to be 0 deg (without making it explicit, though). Here (again without being to explicit) it is again the vertical axis.
To my surprise, all these studies have in common that rotation is performed not in the mathematical positive course but clockwise.

Regarding the question of degree vs radians:
While I prefer radians, I think degree is better here: the physicists/mathematicians do usually not care too much, for a lot of other people degree might feel more natural.
Or do you have experience to the contrary?

Beyond that, my suggestion is to be aligned with the general math/physics literatue:

• 0 deg -> horizontal axis
• rotation anticlockwise

This is also aligned with the elliptical mask in NEST.

[github-actions]

Issue automatically marked stale!