Expand API to surface and neighborhood measurements

[kevinyamauchi]

This issue is to discuss expanding the measurement API to include surface measurements and neighborhood aggregation functions. Surface measurements are performed on either vertices or faces of a mesh. Neighborhood aggregation functions take any measurement table and aggregate the measurements using neighborhoods defined by an adjacency matrix (can be binary or weighted).

A few principles I would like to propose:

• The different types of measurements should be defined by their function signature.
  • label_measurements take a LabelImage + optional IntensityImage and return a LabelMeasurementTable.
  • surface_vertex_measurements take a Surface + optional IntensityImage and return a VertexMeasurementTable. Measurements are performed on the vertices of the surface mesh.
  • surface_face_measurements take a Surface + optional IntensityImage and return a FaceMeasurementTable. Measurements are performed on the
  • neighborhood_aggregation takes a LabelMeasurementTable, VertexMeasurementTable, or a FaceMeasurementTable, and an adjacency graph and returns the measurement table with the neighborhood aggregations performed (e.g.,
• we create separate registration functions, measurement functions, and registries for each type of measurements. By keeping things separate, it is always clear what one is doing and the code doesn't have to guess.

A few questions:

• Can we depend on numba? @MaksHess and I noticed pretty significant speedups when using numba for the aggregation functions (~10x). While numba can be annoying due to relatively strict numpy and python version requirements, I think it is reliable when the correct numpy pins are in place and many analysis packages are starting to use it for acceleration anyway. Since not all measurements can be jit-ed, we can make separate runners that use numba.
• Do we want to include any basic aggregation functions in morphometrics-engine (e.g., mean, standard deviation, median)?

Related issues:

• https://github.com/morphometrics/morphometrics/issues/45
• https://github.com/morphometrics/morphometrics/issues/31

Next steps:

• [ ] rename the current measurements and registries to label_measurement, etc.
• [ ] add surface measurement
• [ ] add neighborhood aggregation

[kevinyamauchi]

What do you think, @haesleinhuepf and @jo-mueller?

[haesleinhuepf]

Can we depend on numba? @MaksHess and I noticed pretty significant speedups when using numba for the aggregation functions (~10x).

Could we instead define an interface for aggregations (with and without neighbors)? I'm asking because clesperanto also offers neighborhood aggregation functionality: https://clesperanto.github.io/pyclesperanto_prototype/docs/_build/html/search.html?q=Of+neighbors+&check_keywords=yes&area=default