4. Reviewing Scores (`review` command)

The review command re-reads a comparison that is already finished. It recalculates the similarity of each pair from the function similarities a comparison stored. This avoids having to completely rerun expensive pairwise comparisons if you simply want to test a different aggregation method (e.g., swapping between hungarian and topn:N).

review was called reaggregate before v0.8.0. The old name is refused with a message naming review.

🏃 Usage

#

oinkie review [OPTIONS] <SCORE_DIRECTORY>

Arguments

#

• <SCORE_DIRECTORY>
  Path to the score directory, which holds the saved function similarities (often located inside the output folder generated by the compare command).

Options

#

• -A, --aggregator <METHOD>
  Specify the aggregator method to combine the function similarities of a pair into its single similarity. [default: hungarian]
  • hungarian: Optimal overall bipartite matching between functions.
  • topn:N: Average the \(N\) best of each function’s best matches, from each side.
  • containment: The hungarian pairing, averaged over the smaller side’s functions: how much of the smaller is found in the larger.
  • matched:T: The proportion of functions the hungarian pairing matches with a similarity of at least \(T\).
  • weighted: A one-to-one pairing in which each function counts by its number of elements. It reads the sizes from the birthmarks the comparison names, as --min-elements does, so those files must still be there and unchanged.
• -d, --dest-file <RESULT.CSV>
  The path to the destination CSV file where the recomputed similarity of each pair is saved. [default: review.csv]
• --min-elements <N|Rx>
  Drop the functions with fewer elements than this from each pair before aggregating. See Dropping short functions.
  • N: a count of elements, such as 5.
  • Rx: (R) times the mean element count, such as 0.3x. A bare 0.3 is refused.
• --threads <N>
  The number of threads to compute on, for every part of the command that runs in parallel. [default: one per core]

💡 Practical Workflow Example

#

Imagine you have run a large comparison across hundreds of files using the standard hungarian aggregator:

oinkie compare -d comparison_results -A hungarian ./birthmarks/*.json

If you later want to analyze the results using the topn:3 strategy, you do not need to compare all function sequences again. You can re-run just the aggregation stage:

oinkie review -A topn:3 -d comparison_results/review_top3.csv comparison_results

This significantly speeds up analysis workflows on large-scale datasets.

✂️ Dropping short functions

#

A function whose birthmark has only a few elements agrees with many others by chance: two one-element sets are often the same set, and two empty birthmarks are identical. Such functions raise the score of unrelated programs. --min-elements drops them after the fact, so one comparison can be re-read under several thresholds without comparing anything again:

oinkie review --min-elements 5    -d results/min5.csv   results
oinkie review --min-elements 0.3x -d results/min03x.csv results

• Dropping a function removes its row and its column from the pair’s function-to-function matrix, and the pair is aggregated from what is left. Nothing is compared again.
• For Rx, the mean is over every function of every birthmark in the directory, taken once each. The threshold is therefore the same for every pair, and two reviews at different thresholds can be compared with each other.
• A pair with no functions left on one side scores 0.0. A pair with none left on either side scores 1.0, as compare scores two empty birthmarks.
• The summary ends with a line saying which threshold produced it, as given and as resolved to a count, because scores under different thresholds are not comparable:

  min elements,0.3x,4.2

The element counts come from the birthmark files each pair’s CSV names. A directory written by compare, or by run since v0.8.0, names them; review refuses one that does not, and one whose birthmarks have changed since the comparison. A birthmark recorded with a relative path is looked up from the directory review is run in.