sorted = longbone_Pair (DATA, BONE) will analyze the measurements in DATA for a specific long bone specified in BONE and it will sort the skeletal elements by pair-matching bilateral elements that belong to the same individual as well as identify single elements, whose complement is missing. DATA can be an $N\times 62$ numeric matrix or an $N\times 63$ cell array, with each row corresponding to a skeletal element.

• As a numeric matrix, DATA uses the first column to identify the side of the skeletal element, where left side is specified as 1 and right side denoted by 2, whereas the remaining 61 columns contain the long bone measurements in the same order as returned in the DATA output argument of the longbone_Geometry function. The names of these measurements can be retrieved by the longbone_Measurements function.
• As a cell array, DATA uses the first column to specify the identifier of each skeletal element, the second column holds the numeric value corresponding to side, and the remaining columns hold the measurement data.

The second input argument, BONE, must be a character vector specifying the type of bone under analysis and can take one of following options:

1. 'Humerus'
2. 'Ulna'
3. 'Femur'
4. 'Tibia'

The matched skeletal elements are returned in the output table sorted, which contains three variables (columns): 'Left side', 'Right side' and 'Score'. The first two variables contain the identifiers of the skeletal elements sorted by individual per each row, and the last one holds the cummulative $z$-score value used for pair-matching (the lower the better) bilateral elements of the same individual. Single skeletal elements, which are identified by means of elimination, hence their corresponding $z$-score value is NaN, are reported first at the top rows of the sorted table. The table contains 'RowNames' using the naming convention "Individual 1", …, "Individual k" up to the total number of distinct individuals identified in the DATA. When DATA is a numeric matrix, the skeletal element identifiers are automatically assigned as "1", "2", …, "N" with each number corresponding to the row each element is stored in.

When a second output argument is requested, longbone_Pair returns an additional table, stats, with various statistics regarding the results of the pair-matching process specified in the following table variables:

1. 'Samples' : the number of processed samples, which is equivalent to the number of rows in DATA.
2. 'Sorted' : the total number of skeletal elements, which have been sorted to distinct individuals.
3. 'Paired' the number of bilateral paired elements, which have been identified.
4. 'Single' : the number of single skeletal elements, which have been identified to distinct individuals.
5. 'Individuals' : the total number of distinct individuals identified in the skeletal assemblage.
6. 'Unsorted' : the number of skeletal elements, which could not be sorted.
7. 'Plausible' : the number of plausible pair-matches among the remaining skeletal elements, which were not sorted.

A comprehensive list of the plausible pairs of unsorted elements may be returned as the third output argument, unsorted, which is also a table similar to the one returned for the sorted skeletal elements. Each plausible pair is accompanied by the respective cummulative $z$-score value, which may are may not be indicative of which plausible pair is more likely to be a true match. Keep in mind, that skeletal elements in the plausible pairs list may well be single elements without their bilateral counterpart being present in the data sample. Also note, that the algorithm utilized by the longbone_Pair function favors precision over recall and thus is optimized for maximizing the ratio of true positives over the sum of true positives and false positives. It is highly advised, to isolate the unsorted skeletal elements into a new dataset and re-apply the pair-matching analysis on this new smaller subgroup.

As an alternative functionality, longbone_Pair can work directly with 3D models. sorted = longbone_Pair (folder, BONE) will analyze all available bones models of type BONE which are present in the directory specified by folder and return the output as described above. When folder is specified, longbone_Pair utilizes the longbone_Geometry function to retrieve the DATA from the 3D models as well as identify their side. Keep in mind that in certain cases the side of ulna bones might be misidentified, thus it is good practice to check the side of each element in the returning tables. The filenames of the 3D models are used as identifiers for the skeletal elements being analyzed.

See also: longbone_Sex, longbone_Geometry, longbone_Measurements

Source Code: longbone_Pair