Text::GenderFromName - Guess the gender of an American first name.
use Text::GenderFromName; print gender("Jon"); # prints 'm' See EXAMPLES for additional uses.
This module provides gender(), which takes a name and returns one of three values: 'm' for male, 'f' for female, or undef for unknown.
gender()
Version 0.30 is a significant departure from previous versions. By default, version 0.30 uses the U.S. Social Security Administration's "Most Popular Names of the 1980's" list of 1001 male first names and 1013 female first names. See CAVEATS below for details on this list.
Version 0.30 also allows for arbitrary female and male hashed lists to be provided at run-time, and includes several built-ins to provide matches based on exclusivity, weight, metaphones, and both version 0.20 and version 0.10 regexp-style matching. The user can also specify additional match subroutines and change the match order at run-time.
The single exported function is:
Returns one of three values: 'm' for male, 'f' for female, or undef for unknown. gender() also accepts a "looseness" level: the higher the looseness value, the broader the match. See THE MATCH LIST below for details.
The non-exported matching subs are:
Returns 'm' or 'f' if and only if $name is found in only one of the two lists.
Returns 'm' or 'f' if $name is found in either list. If $name is in both lists, it returns the more heavily weighted of the two.
Uses Text::DoubleMetaphone for comparison. Returns 'm' or 'f' if and only if the metaphone for $name is found in only one of the two lists.
Note that this function builds a copy of the female/male name lists to speed up the metaphone lookup.
Uses Text::DoubleMetaphone for comparison. Returns 'm' or 'f' if $name is found in either list. If $name is in both lists, it sums the weights of all matching metaphones and returns the larger of the two.
Uses Jon Orwant's v0.20 rules for matching.
Uses Jon Orwant's adaptation of Scott Pakin's awk script from v0.10 for matching.
If you wish to use your own hash refs containing names and weights, you should explicitly import:
Initializes the male and female hashes. This package calls gender_init() internally: without arguments it uses the table provided by the U.S. Social Security Administration. Don't call this function unless you want to override the supplied lists. See THE FEMALE/MALE HASHES below for details.
gender_init()
@MATCH_LIST contains the list of subs gender will use to determine the gender of a given name.
@MATCH_LIST
gender
By default, there are 6 items in @MATCH_LIST, corresponding to the non-exported functions above. Strictly matching subs should go first, loosely matching subs should go last, as gender will iterate over the list from 0 to the specified looseness value or the number of subs in @MATCH_LIST, whichever comes first.
You may override this like so:
@Text::GenderFromName::MATCH_LIST = ('main::my_matching_routine');
By default, these hashes are built using data from the U.S. SSA. You may override them by calling gender_init() with your own female and male hash refs, like so:
use Text::GenderFromName qw( :DEFAULT &gender_init ); my %females = ('barbly' => 4.1, 'bar' => 2.3, ...); my %males = ('foobly' => 4.5, 'foo' => 1.3, ...); &gender_init(\%females, \%males);
The hash keys are lowercase names, and their values are their relative weights. This allows for names that could be male or female, but are more often one or the other.
Very strict usage:
use Text::GenderFromName; my @names = ('Josephine', 'Michael', 'Dondi', 'Jonny', 'Pascal', 'Velvet', 'Eamon', 'FLKMLKSJN'); for (@names) { # Use strict matching my $gender = &gender($_) || ''; if ($gender eq 'f') { print "$_: Female\n" } elsif ($gender eq 'm') { print "$_: Male\n" } else { print "$_: UNSURE\n" } }
returns:
Josephine: Female Michael: UNSURE Dondi: UNSURE Jonny: UNSURE Pascal: UNSURE Velvet: UNSURE Eamon: UNSURE FLKMLKSJN: UNSURE
Loose matching:
for (@names) { # Use loose matching my $gender = &gender($_, 9) || ''; ...
Josephine: Female Michael: Male Dondi: Male Jonny: Male Pascal: Male Velvet: Female Eamon: UNSURE FLKMLKSJN: UNSURE
Turn on debugging:
$Text::GenderFromName::DEBUG = 1;
Matching "josephine": one_only... ==> HIT (f) Matching "michael": one_only... either_weight... F: 0.0271266376105491, M: 3.4091409099979 ==> HIT (m) Matching "dondi": one_only... either_weight... one_only_metaphone... M: dondi => dante => TNT: 0.020568 ==> HIT (m) Matching "jonny": one_only... either_weight... one_only_metaphone... F: jonny => jenna => JN: 0.193945 M: jonny => john => JN: 1.629871 either_weight_metaphone... F: jonny => jenna => JN: 0.193945 F: jonny => joanna => JN: 0.118652 F: jonny => jenny => JN: 0.104875 ... M: jonny => john => JN: 1.629871 M: jonny => juan => JN: 0.309234 M: jonny => johnny => JN: 0.127193 ... ==> HIT (m) Matching "pascal": one_only... either_weight... one_only_metaphone... either_weight_metaphone... v2_rules... ==> HIT (m) Matching "velvet": one_only... either_weight... one_only_metaphone... either_weight_metaphone... v2_rules... v1_rules... ==> HIT (f) Matching "eamon": one_only... either_weight... one_only_metaphone... either_weight_metaphone... v2_rules... v1_rules... Matching "flkmlksjn": one_only... either_weight... one_only_metaphone... either_weight_metaphone... v2_rules... v1_rules... Josephine: Female Michael: Male Dondi: Male Jonny: Male Pascal: Male Velvet: Female Eamon: UNSURE FLKMLKSJN: UNSURE
Add your own match sub:
push @Text::GenderFromName::MATCH_LIST, 'main::eamon_hack'; sub eamon_hack { my $name = shift; return 'm' if $name =~ /^eamon/; }
... Matching "eamon": one_only... either_weight... one_only_metaphone... either_weight_metaphone... v2_rules... v1_rules... main::eamon_hack... ==> HIT (m) Eamon: Male
Don't use metaphones:
@Text::GenderFromName::MATCH_LIST = grep !/metaphone/, @Text::GenderFromName::MATCH_LIST;
Use your own female/male hash lists:
use Text::GenderFromName qw( :DEFAULT &gender_init ); my %females = ('josephine' => 2.1); my %males = ('dondi' => 4.5); &gender_init(\%females, \%males);
Use female/male hash lists from a database:
use Text::GenderFromName qw( :DEFAULT &gender_init ); use Tie::RDBM; tie my %females, 'Tie::RDBM', {db => 'mysql:common', table => 'females', key => 'name', value => 'weight'}; tie my %males, 'Tie::RDBM', {db => 'mysql:common', table => 'males', key => 'name', value => 'weight'}; &gender_init(\%females, \%males);
To run v0.30 in a (mostly) backward compatible mode, override the MATCH_LIST like so:
@Text::GenderFromName::MATCH_LIST = ('v2_rules', 'v1_rules');
and set the looseness to any value greater than 1:
&gender($_, 9);
Note that v0.30 uses significantly different lists than before. If you'd like to use the v0.20 name lists, you may download a previous version of Text::GenderFromName, cut out the hashes, and use the &gender_init() function to use those lists instead. To minimize the size of this module, they are not included in this module.
Text::GenderFromName
Rules are now case-insensitive, which is a departure from earlier versions of this module. Also, Orwant's v0.20 rules no longer fall through, though v0.10's do.
Version 0.30 was a complete overhaul by someone who's never submitted a module to CPAN before. Please consider this fact when using Text::GenderFromName module in a production environment.
Also note that the matching routines in this module are strongly biased toward American first names. None of the methods included in this module correctly identify the v0.30 author's gender (m) from his first name (Eamon).
From http://www.ssa.gov/OACT/babynames/1999/top1000of80s.html:
"The data comes from a 5% sampling of Social Security card applications with dates of birth from January 1980 through December 1989."
"All names which occurred at least five times in the sample are included in the table below. The total number of males in the sample is 977,255 and the total number of females is 936,349. Criteria to be included in the sample is simply that a Social Security card application was filed, that the year of birth was between 1980 and 1989, and that the birth was on US soil. As always each unique spelling is considered a unique name. It may be appropriate for purposes of ranking popularity of names to combine similar spellings of the same name. This kind of grouping, however, is subjective and time consuming, and is beyond the scope of this document. The 2000 edition of the World Almanac lists the top 10 names of each decade based on this data after combining different spellings of the same name."
"No effort has been made to edit the data and as a result some coding errors are obvious. For example initials like "A" are included in the lists. Another common problem, especially for the earlier decades is females coded as being male. For example Jessica is the ranked 647 among male names. Finally entries like "Unknown" and "Baby" are not removed from the lists."
m (0.111843889261247)
Did I mention this module doesn't match the v0.30 author's name?
Originally by Jon Orwant <orwant@readable.com>, v0.30 by Eamon Daly <eamon@eamondaly.com>.
This is an adaptation of an 8/91 awk script by Scott Pakin in the December 91 issue of Computer Language Monthly.
Small contributions by Andrew Langmead and John Strickler. Thanks to Bob Baldwin, Matt Bishop, Daniel Klein, and the U.S. SSA for their lists of names.
Text::DoubleMetaphone
To install Text::GenderFromName, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::GenderFromName
CPAN shell
perl -MCPAN -e shell install Text::GenderFromName
For more information on module installation, please visit the detailed CPAN module installation guide.