MATCHFORGE DOCUMENTATION

CSV Evaluation

Evaluate record-matching predictions and blocking strategies directly from CSV strings. MatchForge parses both datasets, runs the selected workflow, compares its output with labelled ground truth, and returns evaluation results together with CSV headers and parsing errors.

CSV matching evaluation

Use evaluateMatchesCSV() to measure matching predictions against labelled record pairs.

CSV blocking evaluation

Use evaluateBlockingCSV() to measure candidate recall, candidate precision, and reduction ratio.

01

How it works

Both functions accept source and target CSV strings, parse them, and then invoke the corresponding core matching or blocking and evaluation functions.

01

Provide CSV strings

Pass the source and target CSV contents.

02

Configure evaluation

Supply matching or blocking options and ground truth.

03

Inspect the result

Review metrics, parsed headers, and parse errors.

The CSV functions are convenience wrappers. They reuse MatchForge's existing evaluation logic; they do not define separate evaluation metrics.

02

CSV matching evaluation

evaluateMatchesCSV() runs matchRecords() on the parsed CSV records and evaluates the resulting predictions against the supplied ground-truth pairs.

What it measures

Whether the predicted record matches agree with the labelled relationships.

Metrics returned

Precision, recall, F1-score, accuracy, and the true/false positive/negative counts.

typescript
import { evaluateMatchesCSV } from "@matchforge/core";

const sourceCSV = `name,email
Rahul Sharma,rahul@example.com
Priya Patel,priya@example.com`;

const targetCSV = `full_name,email_address
Rahul S Sharma,rahul@example.com
Priya P Patel,priya@example.com`;

const result = evaluateMatchesCSV(sourceCSV, targetCSV, {
  fields: [
    { sourceKey: "name", targetKey: "full_name", weight: 0.6 },
    { sourceKey: "email", targetKey: "email_address", weight: 0.4 },
  ],
  method: "jaro-winkler",
  threshold: 0.8,
  topK: 1,
  groundTruth: [
    { sourceIndex: 0, targetIndex: 0, isMatch: true },
    { sourceIndex: 1, targetIndex: 1, isMatch: true },
  ],
});

console.log(result.metrics);
console.log(result.confusionMatrix);
console.log(result.sourceHeaders);
console.log(result.targetHeaders);
console.log(result.parseErrors);

Options

The third argument combines MatchingOptions with groundTruth and optional sourceParseOptions and targetParseOptions. MatchingOptions accepts either fields (an array of sourceKey/targetKey mappings with optional weights) or a single sourceKey and targetKey pair. It also supports method, threshold, topK, normalization, algorithmOptions, and blocking.

03

CSV blocking evaluation

evaluateBlockingCSV() parses both datasets, generates candidate pairs using the supplied blocking rules, and evaluates those candidates against ground truth.

Candidate recall

The proportion of labelled genuine matches retained as candidates.

Candidate precision

The proportion of labelled candidate pairs that are genuine matches.

Reduction ratio

The proportion of all possible comparisons eliminated by blocking.

typescript
import { evaluateBlockingCSV } from "@matchforge/core";

const sourceCSV = `name,city
Rahul Sharma,Ahmedabad
Priya Patel,Surat`;

const targetCSV = `full_name,location
Rahul S Sharma,Ahmedabad
Priya P Patel,Surat`;

const result = evaluateBlockingCSV(sourceCSV, targetCSV, {
  rules: [
    {
      sourceKey: "city",
      targetKey: "location",
      method: "exact",
    },
    {
      sourceKey: "name",
      targetKey: "full_name",
      method: "prefix",
      length: 3,
    },
  ],
  groundTruth: [
    { sourceIndex: 0, targetIndex: 0, isMatch: true },
    { sourceIndex: 1, targetIndex: 1, isMatch: true },
    { sourceIndex: 0, targetIndex: 1, isMatch: false },
  ],
});

console.log(result.metrics);
console.log(result.totalPossiblePairs);
console.log(result.totalCandidatePairs);
console.log(result.sourceHeaders);
console.log(result.targetHeaders);
console.log(result.parseErrors);

Options

The third argument combines BlockingOptions with groundTruth and optional sourceParseOptions and targetParseOptions. BlockingOptions requires rules. Each rule defines sourceKey, targetKey, and a method of exact, prefix, or soundex; prefix rules can also specify length. Optional normalization settings are applied during candidate generation.

04

Understanding the result

Both functions return their normal evaluation result, along with parsed CSV metadata.

FieldDescription
metrics

Matching metrics or blocking metrics, depending on the function used.

sourceHeaders

Column headers parsed from the source CSV.

targetHeaders

Column headers parsed from the target CSV.

parseErrors.source

Parsing errors reported for the source CSV.

parseErrors.target

Parsing errors reported for the target CSV.

Matching result

Also includes confusionMatrix and totalEvaluatedPairs.

Blocking result

Also includes totalPossiblePairs, totalCandidatePairs, totalEvaluatedPairs, totalLabelledCandidatePairs, trueCandidatePairs, and totalTruePairs.

Inspect parseErrors before interpreting the metrics. The parser reports errors separately for the source and target CSV inputs.

05

Important considerations

Evaluation is only as reliable as the input data and ground-truth labels.

Ground-truth indexes refer to parsed record positions

sourceIndex and targetIndex identify records in the parsed source and target datasets, respectively.

Only labelled pairs are evaluated

Unlabelled pairs are not automatically treated as non-matches. Include representative positive and negative labels.

Candidate precision depends on label coverage

For blocking evaluation, candidate precision is calculated from labelled candidate pairs. Sparse labels may not represent the full candidate set.

Parsing options can be configured independently

Use sourceParseOptions and targetParseOptions when the two CSV files require different delimiters or empty-line handling.

EXPLORE THE PLAYGROUNDS

Experience MatchForge evaluation

Try the interactive evaluation workflows using sample datasets in the Matching Evaluation and Blocking Evaluation playgrounds.