ajbrown/name-machine

Generate realistic random American male and female names.

Name Machine

Name machine is a Java utility for generating random names with realistic probabilities of occurrence. In other words, names that occur more often in real life will also occur more often in the random generation.

It's lightweight, and has no dependencies. It loves being used to generate sample data for tests and demos!

NameGenerator generator = new NameGenerator();

// generate 1000 female names
List<Name> names = generator.generateNames( 1000, Gender.FEMALE );


// generate 5000 male and female names.
List<Name> names = generator.generateNames( 5000 );

It can also be run on the command line to output random names:

java -jar name-machine.jar 1000 females

java -jar name-machine.jar 5000

Gender probability

When generating names for both genders, there is a slightly higher chance of generating a female name than a male name.
This is in line with the real-world male-to-female ratio in the United States. This ratio can be adjusted for your specific application using the NameGeneratorOptions:

NameGeneratorOptions options = new NameGeneratorOptions();

//Heavily prefer male names.
options.setGenderWeight( 12.23 );
NameGenerator generator = new NameGenerator( options );
generator.generateNames( 1000 );

Random seed

If for some reason, the generated names need to be identical from one execution to another, a seed can be specified using the NameGeneratorOptions:

NameGeneratorOptions options = new NameGeneratorOptions();

//Get deterministic results by setting a random seed.
options.setRandomSeed( 123L );
NameGenerator generator = new NameGenerator( options );
generator.generateNames( 1000 );

Limitations

• The maximum number of random names you can generate in one pass is bound to integer max. However, that's on order of 2 billion names on 32 bit systems. At the time of writing there were only an estimated 7 billion humans on the planet, and most of those people don't have American names. I just wasted your time describing a limitation that is actually not a limitation.
• There are only 4275 female first names and 1219 male first names represented. However, with over 150 thousand last names, there are about 645 million female and 184 million male full name combinations available.

How Does it Work?

The name files used to generate random names are provides by the 1990 U.S. Census data. The originals are available on the web. Along with the names in ranked order is the Frequency in percent, Cumulative frequency in percent, and the rank.

We randomly select a name from the list by generating a random floating point number, and picking the first name that has a higher or equal cumulative frequency than our random number.

Installing

...to build.gradle:

dependencies {
    compile 'org.ajbrown:name-machine:1.1.0'
}

...to pom.xml:

<dependencies>
 <dependency>
   <groupId>org.ajbrown</groupId>
   <artifactId>name-machine</artifactId>
   <version>1.1.0</version>
 </dependency>
</dependencies>

About the Author

I'm a product owner and technical leader that loves open source and building SaaS products at internet scale.
You can always contact me directly with your questions, suggestions, or friendly conversation.

• Email: aj AT ajbrown DOT org
• Twitter: @adrianjbrown
• Web: ajbrown.org
• LinkedIn linkedin.com/in/ajbrown/

name-machine's Issues

DepShield Deprecation Notice

Depshield will be deprecated on Monday December 12th

Please install our new product, Sonatype Lift with advanced features

Repo

It must be a nice library, but it's apparently absent in Maven Central (at least it's what my error message suggests). Do you think you can include a few notes in your readme file on how to add the project's repository in one's pom.xml file?

Use 2000 Census Data for Surnames

The 2000 Census surnames are available, but not in the same format as the 1990 data. We'll need to convert to the same probability table as the current data:

http://www.census.gov/topics/population/genealogy/data/2000_surnames.html

compile gradle

Hi,

getting this error when I sync!

dependencies {
compile 'org.ajbrown:NameMachine:0.1.1'
}

Error:Failed to resolve: org.ajbrown:NameMachine:0.1.1

Pre-format names as capitalized

Instead of capitalizing the names as they're being generated, we can save a few cycles by fixing the format in the seed files themselves.

Optimize memory usage when outputting names.

the NameGenerator builds a list of random names by the count it's provided, and then supplies that payload to NameMachine for output. That means that if I want 500k names, it has to load all 500k into memory before it can begin outputting them.

If we were to output them as they're being generated, that memory would be saved.

building fails with recent Java or gradle

Used gradle init to enable building the project with JDK 11 and gradle 7
Just did a quick hack to get the project running

See my forked branch, in case anybody wants to use this project

https://github.com/omichels/name-machine/tree/upgrade-gradle-7-java-jdk-11

Allow setting generation options on each pass

The http://namemachine.xyz API allows the specification of gender probability. Because of this, a new instance of NameGenerator has to be instantiated for each request, which means parsing the names files every since time.

This would be much more efficient if options could be specified each time. We could then keep one generator in application state.

To keep the API consistent and compatible, the current method of specifying options should set the default options that are used if options aren't specified for a particular invocation.