Usage Examples

Basic Distance Calculation

Using the default pre-defined map for common OCR errors:

import ocr_stringdist as osd

# Compare "OCR5" and "OCRS"
# The default ocr_distance_map gives 'S' <-> '5' a cost of 0.3
distance = osd.weighted_levenshtein_distance("OCR5", "OCRS")
print(f"Distance between 'OCR5' and 'OCRS' (default map): {distance}")
# Output: Distance between 'OCR5' and 'OCRS' (default map): 0.3

Using Custom Costs

Define your own substitution costs:

import ocr_stringdist as osd

# Define a custom cost for substituting "rn" with "m"
custom_substitutions = {("rn", "m"): 0.5}

distance = osd.weighted_levenshtein_distance(
    "Churn Bucket", "Chum Bucket", substitution_costs=custom_substitutions
)
print(f"Distance using custom map: {distance}") # 0.5

Matching OCR Output Against Candidates

This is a primary use case: finding the best match for an OCR string from a list of known possibilities.

import ocr_stringdist as osd

ocr_output = "Harnburg"  # OCR potentially misread 'm' as 'rn'
possible_cities = ["Harburg", "Hamburg", "Hannover", "Berlin"]

# Define costs relevant to the potential error
ocr_fix_costs = {("rn", "m"): 0.2}

# Method 1: Using find_best_candidate
best_match_finder, min_distance_finder = osd.find_best_candidate(
    ocr_output,
    possible_cities,
    distance_fun=lambda s1, s2: osd.weighted_levenshtein_distance(
        s1, s2, substitution_costs=ocr_fix_costs
    ),
)
print(
    f"(find_best_candidate) Best match for '{ocr_output}': '{best_match_finder}' "
    f"(Distance: {min_distance_finder:.2f})"
)
# Output: (find_best_candidate) Best match for 'Harnburg': 'Hamburg' (Distance: 0.20)


# Method 2: Using batch_weighted_levenshtein_distance
# Generally more efficient when comparing against many candidates.
distances = osd.batch_weighted_levenshtein_distance(
    ocr_output, possible_cities, substitution_costs=ocr_fix_costs
)

min_dist_batch = min(distances)
best_candidate_batch = possible_cities[distances.index(min_dist_batch)]

print(
    f"(Batch) Best match for '{ocr_output}': '{best_candidate_batch}' "
    f"(Distance: {min_dist_batch:.2f})"
)
# Output: (Batch) Best match for 'Harnburg': 'Hamburg' (Distance: 0.20)