Neighborhood analysis

Concept

The neighborhood analysis is a tool available in Dynamo that is meant to help describe the local spatial relationships of particles, especially after STA. As such, it is implemented in Dynamo as a function that analyses particles through their alignment tables.

Aligned particles are described by their euler angles and their aligned position. If two particles are close enough to be considered neighbors, they form a pair. The computation of the relative geometries of all pairs in a table is the neighborhood analysis.

A simplified 2D example with only three particles is presented with the following figure. The left parts of the figures represent the real space in the tomogram, while the right graph present the neighborhood analysis space.

Simplified example. We have three particles i,j,k with each their aligned position and orientation. While the tomogram has a global reference system, each particle express its own implicit reference system (red lines). Particles i, j and k are close to each other and so will be taken as neighbors of each other.

Since particle defines its own reference system, that can be used to express the other particles. Here particle i "sees" its neighbors j and k. As such, the pair (i,j) and (i,k) are noted in the neighbohood analysis plot.

We can do the same with particle j. The new pairs will be (j,i) and (j,k).

And with particle k. The new pairs will be (k,i) and (k,j).

If there is a repeating geometric relationship between close particles, then this would be reflected by the presence concentrations points in the right neighborhood plot.

It is important to note that the pair (i,j) is not necessary symmetric to the pair (j,i) even through they express the same distance vector (with opposite sign) because the reference systems of i and j have independently different orientations to each other!

Function call

The most basic way to call the neighborhood analysis function is:
analysisOfmyTable = dpktbl.neighborhood.analize(myTable)

Where myTable is the table describing the set of aligned particle in the usual Dynamo format.

dpktbl.neighborhood.analize has a set of optional parameters:

1. distance: this is the maximal allowed distance between particles to still be analysed. The distance is measured in pixels between the centers of the particles after alignment. The default value is 5 pixels. This value should be kept reasonably small, so as to highlight short-range repeating spatial relationships as well as to reduce computing time.
2. modelColumn: this indicates which column of the table is used to separate the particles into groups. Particles in different groups cannot be considered as neighbors. The default column is 21 ("reg").
3. secondTable: this options changes the behaviour of the function. If this option is active, the distribution of particles defined in the second table will be analysed as seen from the particles in the original table. This option is deactivated by default.
4. indices: this options allows for the analysis of only a subset of the groups defined by modelColumn. By default all groups are analysed.

The output analysisOfmyTable is a structure. It contains three main fields: .originalTable, .coupleTable and .couples. .originalTable is merely a copy of the input table. .coupleTable is the table that records the geometric relationships between pairs of particles, in particular the distance vector is recordes in columns 24, 25 and 26 (x,y,z following the Dynamo table conventions). .couples records the indexes of the particles that make a pair in the original table. As such, .coupleTable will have the same number of rows as .couples.tbl.

Visualization

The results of a neighborhood analysis can be inspected in different ways. A practical method is to use the dtview functionality of the resulting analysisOfmyTable.coupleTable.

The dtview GUI can be used to inspect any table. When inspecting neighborhood analysis tables the fields x, y and z indicate the relative distances of all pairs.

dtview allow for the manual drawing of lassos in 2D scatterplots. This tool can be access by right-clicking the 2D scatter figure. dtview can also be used to generate 2D histogram.

The lassos can be used to extract the indices of the pair that accumulate in a certain area. This information can than me paired with the .couples information to recover the information of each particle involved from the original table.

The pairs inside the lasso can be save by righ-clicking a lasso and selecting a "Subtable with points inside of lasso ->" option. If the "memory" option is selected, a variable called mbtblSelection will be created in the MATLAB workspace.