blib/lib/Lingua/EN/MatchNames.pm

filter: Statementstmt 83.0% 88 / 106 Branchbran 58.9% 46 / 78 Conditioncond 47.6% 10 / 21 MC/DCmcdc 21.4% 3 / 14 Subroutinesub 92.3% 12 / 13 Podpod 0.0% 0 / 3 totaltotal 67.6% 159 / 235 CC 49 SCAR 36.5
CC
49
Cov
70%
fname_eq
68.2
lname_eq
24.6
_nparse
12.0
CRAP 38.4
↑ Summary
1
2 =head1 NAME
3
4 Lingua::EN::MatchNames - Smart matching for human names.
5
6 =head1 SYNOPSIS
7
8 use Lingua::EN::MatchNames;
9
10 $score= name_eq( $firstn_0, $lastn_0, $firstn_1, $lastn_1 );
11
12 =head1 DESCRIPTION
13
14 You have two databases of person records that need to be synchronized or matched up,
15 but they use different keys--maybe one uses SSN and the other uses employee id.
16 The only fields you have to match on are first and last name.
17
18 That's what this module is for.
19
20 Just feed the first and last names to the C<name_eq()> function, and it returns
21 C<undef> for no possible match, and a percentage of certainty (rank) otherwise.
22 The ranking system isn't very scientific, and gender isn't considered, though
23 it probably should be.
24
25 The C<name_eq()> function, checks for:
26
27 =over 4
28
29 =item * inconsistent case (MacHenry = Machenry = MACHENRY)
30
31 =item * inconsistent symbols (O'Brien = Obrien = O BRIEN)
32
33 =item * misspellings (Grene = Green)
34
35 =item * last name hyphenation (Smith-Curry = Curry)
36
37 =item * similar phonetics (Hanson = Hansen)
38
39 =item * nicknames (Midge = Peggy = Margaret)
40
41 =item * extraneous initials (H. Ross = Ross)
42
43 =item * extraneous suffixes (Reed, Jr. = Reed II = Reed)
44
45 =item * and more...
46
47 =back
48
49 =head2 Preliminary Tests:
50
51 Homer Simpson HOMER SIMPOSN: 77
52 Marge Simpson MIDGE SIMPSON: 81
53 Brian Lalonde BRYAN LA LONDE: 82
54 Brian Lalonde RYAN LALAND: 72
55 Peggy MacHenry Midge Machenry: 81
56 Liz Grene Elizabeth Green: 72
57 Chuck Reed, Jr. Charles Reed II: 82
58 Kathy O'Brien Catherine Obrien: 81
59 Lizzie Hanson Lisa Hanson: 91
60 H. Ross Perot Ross PEROT: 88
61 Kathy Smith-Curry KATIE CURRY: 81
62 Dina Johnson-Warner Dinah J-Warner: 80
63 Leela Miles-Conrad Leela MilesConrad: 86
64 C. Renee Smythe Cathy Smythe: 71
65 Victoria (Honey) Rider HONEY RIDER: 88
66 Bart Simpson El Barto Simpson: 80
67 Bart Simpson Lisa Simpson: (no match)
68 Arthur Dent Zaphod Beeblebrox: (no match)
69
70 =head1 WARNING
71
72 The scoring in this version is utterly arbitrary.
73 I made all of the numbers up.
74 The certainty percentages should be OK relative to each other, but
75 would be better if someone could give me some statistical data.
76
77 Be sure and B<test> this against your data first!
78 Your data may not look like my test data.
79
80 And although I hope this is useful to many, I do not provide any
81 kind of warranty (expressed or implied), and do not suggest the
82 suitability of this module to any particular purpose.
83 This module probably should not be used for life support or military
84 purposes, and it B<must> not be used for unsolicited commercial email
85 or other bulk advertising.
86
87 =head1 REPOSITORY
88
89 L<https://github.com/brianary/Lingua-EN-MatchNames>
90
91 =head1 AUTHOR
92
93 Brian Lalonde, E<lt>brian@webcoder.infoE<gt>
94
95 =head1 REQUIREMENTS
96
97 Lingua::EN::NameParse,
98 Lingua::EN::Nickname,
99 Parse::RecDescent,
100 String::Approx,
101 Text::Metaphone,
102 Text::Soundex
103
104 =head1 SEE ALSO
105
106 perl(1),
107 L<Lingua::EN::NameParse>,
108 L<Lingua::EN::Nickname>,
109 L<String::Approx>,
110 L<Text::Metaphone>,
111 L<Text::Soundex>
112
113 =cut
114
115 package Lingua::EN::MatchNames;
116 1 require Exporter;
117 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
118 1 ▶use Lingua::EN::NameParse;
Subroutine BEGIN: called CC=1 SCAR=0.0
119 1 ▶use Lingua::EN::Nickname;
Subroutine BEGIN: called CC=1 SCAR=0.0
120 1 ▶use String::Approx 'amatch';
Subroutine BEGIN: called CC=1 SCAR=0.0
121 1 ▶use Text::Metaphone;
Subroutine BEGIN: called CC=1 SCAR=0.0
122 1 ▶use Text::Soundex;
Subroutine BEGIN: called CC=1 SCAR=0.0
123 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
124 1 ▶use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
Subroutine BEGIN: called CC=1 SCAR=0.0
125 1 ▶use vars qw($debug);
Subroutine BEGIN: called CC=1 SCAR=0.0
126
127 1 $VERSION= '1.36';
128 1 @ISA= qw(Exporter);
129 1 @EXPORT= qw(name_eq);
130 1 @EXPORT_OK= qw(fname_eq lname_eq);
131 1 %EXPORT_TAGS=
132 (
133 ALL => [ @EXPORT, @EXPORT_OK ],
134 );
135
136 sub _nparse($)
137 0 ▶{
Subroutine _nparse: not called CC=3 SCAR=24.8
138 0 local $_= shift;
139 0 ▶ my $nparse= new Lingua::EN::NameParse( auto_clean => 1, force_case => 1 )
Branch: 1 branch
BranchTrueFalseTotal
my $nparse = "Lingua::EN::NameParse"->new("auto_clean", 1, "force_case", 1) or carp("Unable to set up name parser.\n$!\n") 0 0 0
140 or carp "Unable to set up name parser.\n$!\n";
141 0 $nparse->parse($_);
142 0 my %name= $nparse->components;
143 return($name{given_name_1},$name{surname_1}.
144 0 ▶ ( $name{surname_2} ? '-'.$name{surname_2} : '' ));
Branch: 1 branch
BranchTrueFalseTotal
$name{'surname_2'} ? : 0 0 0
145 }
146
147 sub fname_eq
148 20 ▶{
Subroutine fname_eq: called CC=27 SCAR=42.2
Pod undocumented
149 20 my($name0,$name1,$match)= @_;
150 20 ▶ return unless $name0 and $name1;
Branch: 1 branch
BranchTrueFalseTotal
unless $name0 and $name1 0 20 20
Condition33%1/3
$name0 and $name1
!ll&&!rl&&r
0020
MC/DC0%0/2
$name0 and $name1
$name0 $name1
Truth table33%1/3
A and B
A= $name0B= $name1
ABresult
0X0
100
111
151 20 ▶ return 100 if $name0 eq $name1;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 eq $name1 1 19 20
152 # recurse offset nicknames
153 19 ▶ if($name0=~ m/\((\w+)\)/) { return $match if $match= fname_eq($name1,$1); }
Branch: 2 branches
BranchTrueFalseTotal
if ($name0 =~ /\((\w+)\)/) 1 18 19
if $match = fname_eq($name1, $1) 1 0 1
154 0 ▶ if($name0=~ m/"(\w+)"/) { return $match if $match= fname_eq($name1,$1); }
Branch: 2 branches
BranchTrueFalseTotal
if ($name0 =~ /"(\w+)"/) 0 18 18
if $match = fname_eq($name1, $1) 0 0 0
155 0 ▶ if($name1=~ m/\((\w+)\)/) { return $match if $match= fname_eq($name0,$1); }
Branch: 2 branches
BranchTrueFalseTotal
if ($name1 =~ /\((\w+)\)/) 0 18 18
if $match = fname_eq($name0, $1) 0 0 0
156 0 ▶ if($name1=~ m/"(\w+)"/) { return $match if $match= fname_eq($name0,$1); }
Branch: 2 branches
BranchTrueFalseTotal
if ($name1 =~ /"(\w+)"/) 0 18 18
if $match = fname_eq($name0, $1) 0 0 0
157 # strip leading/trailing initial(s) (98%)
158 18 $name0=~ s/\W*\b\w\b\W*//g;
159 18 $name1=~ s/\W*\b\w\b\W*//g;
160 18 ▶ return 98 if $name0 eq $name1;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 eq $name1 1 17 18
161 # recurse separate parts
162 17 ▶ if($name0=~ /\W/)
Branch: 2 branches
BranchTrueFalseTotal
if ($name0 =~ /\W/) { } 0 17 17
elsif ($name1 =~ /\W/) { } 1 16 17
163 { # split parts, find best match
164 0 my($match)= sort { $b <=> $a } map {fname_eq($name1,$_)} split /\W+/, $name0;
165 0 ▶ return $match if $match;
Branch: 1 branch
BranchTrueFalseTotal
if $match 0 0 0
166 }
167 elsif($name1=~ /\W/)
168 { # split parts, find best match
169 0 my($match)= sort { $b <=> $a } map {fname_eq($name0,$_)} split /\W+/, $name1;
170 1 ▶ return $match if $match;
Branch: 1 branch
BranchTrueFalseTotal
if $match 1 0 1
171 }
172 # all caps, no symbols (95%)
173 16 ($name0= uc $name0)=~ y/A-Z//cd;
174 16 ($name1= uc $name1)=~ y/A-Z//cd;
175 16 ▶ return 95 if $name0 eq $name1;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 eq $name1 2 14 16
176 # nickname (80%)
177 14 ▶ return int 0.8*$match if $match= nickname_eq($name0,$name1);
Branch: 1 branch
BranchTrueFalseTotal
if $match = nickname_eq($name0, $name1) 9 5 14
178 # fuzzy approx (15%)
179 5 ▶ return 35 if amatch($name0,$name1) and amatch($name1,$name0);
Branch: 1 branch
BranchTrueFalseTotal
if amatch($name0, $name1) and amatch($name1, $name0) 2 3 5
Condition66%2/3
amatch($name0, $name1) and amatch($name1, $name0)
!ll&&!rl&&r
302
MC/DC50%1/2
amatch($name0, $name1) and amatch($name1, $name0)
amatch($name0, $name1) amatch($name1, $name0)
Truth table66%2/3
A and B
A= amatch($name0, $name1)B= amatch($name1, $name0)
ABresult
0X0
100
111
180 # simple trucation
181 3 ▶ return 10 if $name0=~ /^$name1|$name1$/ or $name1=~ /^$name0|$name0$/;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 =~ /^$name1|$name1$/ or $name1 =~ /^$name0|$name0$/ 0 3 3
Condition33%1/3
$name0 =~ /^$name1|$name1$/ or $name1 =~ /^$name0|$name0$/
l!l&&r!l&&!r
003
MC/DC0%0/2
$name0 =~ /^$name1|$name1$/ or $name1 =~ /^$name0|$name0$/
$name0 =~ /^$name1|$name1$/ $name1 =~ /^$name0|$name0$/
Truth table33%1/3
A or B
A= $name0 =~ /^$name1|$name1$/B= $name1 =~ /^$name0|$name0$/
ABresult
1X1
011
000
182 # a single initial
183 3 ($name0,$name1)= @_;
184 3 ▶ for($name0=~ m/\b(\w)\b/) { return 5 if $name1=~ /^$_/i; }
Branch: 1 branch
BranchTrueFalseTotal
if $name1 =~ /^$_/i 1 0 1
185 0 ▶ for($name1=~ m/\b(\w)\b/) { return 5 if $name0=~ /^$_/i; }
Branch: 1 branch
BranchTrueFalseTotal
if $name0 =~ /^$_/i 0 0 0
186 2 return;
187 }
188
189 sub lname_eq
190 34 ▶{
Subroutine lname_eq: called CC=18 SCAR=32.0
Pod undocumented
191 34 my($name0,$name1)= @_;
192 34 ▶ return unless $name0 and $name1;
Branch: 1 branch
BranchTrueFalseTotal
unless $name0 and $name1 0 34 34
Condition33%1/3
$name0 and $name1
!ll&&!rl&&r
0034
MC/DC0%0/2
$name0 and $name1
$name0 $name1
Truth table33%1/3
A and B
A= $name0B= $name1
ABresult
0X0
100
111
193 34 ▶ return 100 if $name0 eq $name1;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 eq $name1 3 31 34
194 # strip trailing suffixes (95%)
195 31 $name0=~ s/\s+([IVX]+|,.*|[JS]r\.?)\s*$//;
196 31 $name1=~ s/\s+([IVX]+|,.*|[JS]r\.?)\s*$//;
197 31 ▶ return 95 if $name0 eq $name1;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 eq $name1 0 31 31
198 # recurse hyphenated components
199 31 ▶ if($name0=~ /-/)
Branch: 2 branches
BranchTrueFalseTotal
if ($name0 =~ /-/) { } 7 24 31
elsif ($name1 =~ /-/) { } 0 24 24
200 { # split hyphenation on hyphen ONLY
201 7 my($match)= sort { $b <=> $a } map {lname_eq($name1,$_)} split /-/, $name0;
202 7 ▶ return $match if $match;
Branch: 1 branch
BranchTrueFalseTotal
if $match 7 0 7
203 }
204 elsif($name1=~ /-/)
205 { # split hyphenation on hyphen ONLY
206 0 my($match)= sort { $b <=> $a } map {lname_eq($name0,$_)} split /-/, $name1;
207 0 ▶ return $match if $match;
Branch: 1 branch
BranchTrueFalseTotal
if $match 0 0 0
208 }
209 # all caps, no symbols (85%)
210 24 ($name0= uc $name0)=~ y/A-Z//cd;
211 24 ($name1= uc $name1)=~ y/A-Z//cd;
212 24 ▶ return 85 if $name0 eq $name1;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 eq $name1 12 12 24
213 # metaphone (70%)
214 12 ▶ return 70 if Metaphone($name0) eq Metaphone($name1);
Branch: 1 branch
BranchTrueFalseTotal
if &Metaphone($name0) eq &Metaphone($name1) 3 9 12
215 # soundex (40%)
216 9 ▶ return 40 if soundex($name0) eq soundex($name1);
Branch: 1 branch
BranchTrueFalseTotal
if soundex($name0) eq soundex($name1) 0 9 9
217 # fuzzy approx (15%)
218 9 ▶ return 25 if amatch($name0,$name1) and amatch($name1,$name0);
Branch: 1 branch
BranchTrueFalseTotal
if amatch($name0, $name1) and amatch($name1, $name0) 0 9 9
Condition33%1/3
amatch($name0, $name1) and amatch($name1, $name0)
!ll&&!rl&&r
900
MC/DC0%0/2
amatch($name0, $name1) and amatch($name1, $name0)
amatch($name0, $name1) amatch($name1, $name0)
Truth table33%1/3
A and B
A= amatch($name0, $name1)B= amatch($name1, $name0)
ABresult
0X0
100
111
219 # nonstandard 'hyphenation'/simple truncation
220 9 ($name0,$name1)= map {(my$n=$_)=~s/\s+([IVX]+|,.*|[JS]r\.?)\s*$//;$n=~y/A-Za-z\-//cd;$n} @_;
221 9 ▶ return int 0.8*lname_eq($name0,$name1) if $name0=~ s/(\B[A-Z][a-z]+)/-$1/g
Branch: 1 branch
BranchTrueFalseTotal
if $name0 =~ s/(\B[A-Z][a-z]+)/-$1/g or $name1 =~ s/(\B[A-Z][a-z]+)/-$1/g 2 7 9
Condition66%2/3
$name0 =~ s/(\B[A-Z][a-z]+)/-$1/g or $name1 =~ s/(\B[A-Z][a-z]+)/-$1/g
l!l&&r!l&&!r
207
MC/DC50%1/2
$name0 =~ s/(\B[A-Z][a-z]+)/-$1/g or $name1 =~ s/(\B[A-Z][a-z]+)/-$1/g
$name0 =~ s/(\B[A-Z][a-z]+)/-$1/g $name1 =~ s/(\B[A-Z][a-z]+)/-$1/g
Truth table66%2/3
A or B
A= $name0 =~ s/(\B[A-Z][a-z]+)/-$1/gB= $name1 =~ s/(\B[A-Z][a-z]+)/-$1/g
ABresult
1X1
011
000
222 or $name1=~ s/(\B[A-Z][a-z]+)/-$1/g;
223 7 ▶ return 10 if $name0=~ /^$name1|$name1$/i or $name1=~ /^$name0|$name0$/i;
Branch: 1 branch
BranchTrueFalseTotal
if $name0 =~ /^$name1|$name1$/i or $name1 =~ /^$name0|$name0$/i 1 6 7
Condition66%2/3
$name0 =~ /^$name1|$name1$/i or $name1 =~ /^$name0|$name0$/i
l!l&&r!l&&!r
106
MC/DC50%1/2
$name0 =~ /^$name1|$name1$/i or $name1 =~ /^$name0|$name0$/i
$name0 =~ /^$name1|$name1$/i $name1 =~ /^$name0|$name0$/i
Truth table66%2/3
A or B
A= $name0 =~ /^$name1|$name1$/iB= $name1 =~ /^$name0|$name0$/i
ABresult
1X1
011
000
224 6 return;
225 }
226
227 sub name_eq
228 18 ▶{
Subroutine name_eq: called CC=4 SCAR=13.9
Pod undocumented
229 18 ▶ my($nomF0,$nomL0,$nomF1,$nomL1,$Frank,$Lrank)=
Branch: 1 branch
BranchTrueFalseTotal
@_ < 4 ? : 0 18 18
230 ( @_ < 4 ? (_nparse($_[0]),_nparse($_[1])) : @_ );
231 18 ▶ return unless $Lrank= lname_eq $nomL0, $nomL1;
Branch: 1 branch
BranchTrueFalseTotal
unless $Lrank = lname_eq($nomL0, $nomL1) 1 17 18
232 17 ▶ return unless $Frank= fname_eq $nomF0, $nomF1;
Branch: 1 branch
BranchTrueFalseTotal
unless $Frank = fname_eq($nomF0, $nomF1) 1 16 17
233 16 return int $Lrank*0.7 + $Frank*0.3; # another ratio I just made up
234 }
235
236 1 1
↑ Summary