Introduction to the charlatan package

charlatan makes realistic looking fake data, inspired from and borrowing some code from Python’s faker

Why would you want to make fake data that looks real? Here’s some possible use cases to give you a sense for what you can do with this package:

Students in a classroom setting learning any task that needs a dataset.
People doing simulations/modeling that need some fake data
Generate fake dataset of users for a database before actual users exist
Complete missing spots in a dataset
Generate fake data to replace sensitive real data with before public release
Create a random set of colors for visualization
Generate random coordinates for a map
Get a set of randomly generated DOIs (Digital Object Identifiers) to assign to fake scholarly artifacts
Generate fake taxonomic names for a biological dataset
Get a set of fake sequences to use to test code/software that uses sequence data

See the Creating realistic data vignette for a few realistic examples.

Contributing

See the Contributing to charlatan vignette.

Package API

Low level interfaces: All of these are R6 objects that a user can initialize and then call methods on. These contain all the logic that the below interfaces use.
High level interfaces: There are high level functions prefixed with ch_*() that wrap low level interfaces, and are meant to be easier to use and provide an easy way to make many instances of a thing.
ch_generate() - generate a data.frame with fake data, choosing which columns to include from the data types provided in charlatan
fraudster() - single interface to all fake data methods, - returns vectors/lists of data - this function wraps the ch_*() functions described above

Install

Stable version from CRAN

install.packages("charlatan")

Development version from Github

remotes::install_github("ropensci/charlatan")

library("charlatan")

high level function

… for all fake data operations

x <- fraudster()
x$job()
#> [1] "Regulatory affairs officer"
x$name()
#> [1] "Minoru Conroy"
x$job()
#> [1] "Architectural technologist"
x$color_name()
#> [1] "DarkRed"

locale support

Here we create 3 jobs, for different locales:

English USA
French, France
Croatian, Croatia
Ukrainian, Ukraine
Chinese, Taiwan

ch_job(locale = "en_US", n = 3)
#> [1] "Production assistant, radio" "Nurse, adult"               
#> [3] "Tour manager"
ch_job(locale = "fr_FR", n = 3)
#> [1] "Climatologue"                                 
#> [2] "Esthéticien"                                  
#> [3] "Ingénieur en R et D en énergies renouvelables"
ch_job(locale = "hr_HR", n = 3)
#> [1] "Medicinska sestra opće njege"        
#> [2] "Kontrolor zračnog prometa"           
#> [3] "Doktor dentalne medicine specijalist"
ch_job(locale = "uk_UA", n = 3)
#> [1] "Ботанік"              "Астроном"             "Державний службовець"
ch_job(locale = "zh_TW", n = 3)
#> [1] "救生員"             "星象占卜人員"       "媒體公關／宣傳採買"

For colors:

ch_color_name(locale = "en_US", n = 3)
#> [1] "Beige"         "SkyBlue"       "DarkGoldenRod"
ch_color_name(locale = "uk_UA", n = 3)
#> [1] "Синій (RYB)"      "Грушевий"         "Берлінська лазур"

generate a dataset

ch_generate()
#> # A tibble: 10 × 3
#>    name                job                                   phone_number       
#>    <chr>               <chr>                                 <chr>              
#>  1 Shirlie Kovacek PhD Health and safety inspector           497.184.5896       
#>  2 Dr. Albertus Johns  Structural engineer                   291-484-9180x591   
#>  3 Keila Cruickshank   Mining engineer                       434-442-2380x99923 
#>  4 Wilford Mosciski    Volunteer coordinator                 08104098275        
#>  5 Delwin Beer         Pension scheme manager                012.369.0996x3481  
#>  6 Prudence Kris       Therapist, horticultural              (773)683-4066x357  
#>  7 Keion Johnson       Printmaker                            (195)309-9459      
#>  8 Dezzie Koepp-Mertz  Engineer, control and instrumentation (374)120-9644x3262 
#>  9 Lydia Gerlach MD    Chief Operating Officer               +62(1)3393667083   
#> 10 Britni Gibson       Tourism officer                       1-802-470-0342x984…

ch_generate("job", "phone_number", n = 30)
#> # A tibble: 30 × 2
#>    job                                phone_number        
#>    <chr>                              <chr>               
#>  1 Surgeon                            (713)091-3784x415   
#>  2 Public librarian                   (223)405-0850x2366  
#>  3 Television/film/video producer     737.861.0655x72315  
#>  4 Financial trader                   1-201-587-9570x11104
#>  5 Theatre stage manager              08744431506         
#>  6 Radiographer, therapeutic          253.235.0707x2184   
#>  7 Community development worker       (356)801-8077x8740  
#>  8 Engineer, production               952.832.7175        
#>  9 Tourist information centre manager 149.709.3491x8215   
#> 10 Scientist, physiological           (017)343-6123       
#> # ℹ 20 more rows

Data types, localized

We can create locale specific versions of:

Colors
Companies
Elements (of the periodic table)
Files
Internet
Jobs
Lorem
Persons
Phone numbers
Social Security Numbers
Taxonomies
UserAgent

Examples:

person name

ch_name()
#> [1] "Mr. Daulton Klein V"

ch_name(10)
#>  [1] "Mr. Baker Dietrich III"  "Dr. Drake Block MD"     
#>  [3] "Idabelle Brown"          "Vena Shanahan MD"       
#>  [5] "Nyree Langworth"         "Zion Mraz DDS"          
#>  [7] "Solon Nicolas"           "Mathews Bergstrom"      
#>  [9] "Lilyan Corkery-Kshlerin" "Shyanne Purdy"

phone number

ch_phone_number()
#> [1] "02268241644"

ch_phone_number(10)
#>  [1] "1-723-653-1108x91177" "(012)748-9641x938"    "(709)070-3665"       
#>  [4] "537-435-5132x69252"   "(687)445-2519x506"    "1-427-157-6300"      
#>  [7] "513.720.6095x678"     "(924)306-7629x26292"  "+47(2)4602340580"    
#> [10] "1-220-200-4638"

job

ch_job()
#> [1] "Veterinary surgeon"

ch_job(10)
#>  [1] "Sales executive"              "Air cabin crew"              
#>  [3] "Music tutor"                  "Warehouse manager"           
#>  [5] "Housing manager/officer"      "Designer, industrial/product"
#>  [7] "Teacher, primary school"      "Embryologist, clinical"      
#>  [9] "Call centre manager"          "Charity fundraiser"

Data types, universal

Some data types are not localized (arguably the files and user_agents, are mostly universal too).

Currency
credit card
Sequence (DNA)
Numerics (doubles, integers, numbers from a distribution; uniform, normal, log-normal, and beta)
Miscellaneous (booleans, language codes)
DOIs (Digital Object Identifiers, used in scientific journals)
Coordinates (GPS coordinates)

currency

ch_currency(3)
#> [1] "XDR" "PHP" "SBD"

credit cards

ch_credit_card_provider()
#> [1] "Maestro"
ch_credit_card_provider(n = 4)
#> [1] "JCB 16 digit"  "Maestro"       "JCB 15 digit"  "VISA 13 digit"

ch_credit_card_number()
#> [1] "3040599706331882"
ch_credit_card_number(n = 10)
#>  [1] "3021872720837104"    "3112714928865844723" "3158728291276897978"
#>  [4] "676372938018545"     "3792406979491147"    "869970479287494927" 
#>  [7] "869971490438818988"  "3055334974586859"    "4764257932844782"   
#> [10] "6011768652337304257"

ch_credit_card_security_code()
#> [1] "000"
ch_credit_card_security_code(10)
#>  [1] "631"  "828"  "348"  "4931" "954"  "699"  "963"  "196"  "139"  "458"

Missing data

charlatan makes it very easy to generate fake data with missing entries. First, you need to run MissingDataProvider() and then make an appropriate make_missing() call specifying the data type to be generated. This method picks a random number (N) of slots in the input make_missing vector and then picks N random positions that will be replaced with NA matching the input class.

testVector <- MissingDataProvider$new()

character strings

testVector$make_missing(x = ch_generate()$name)
#>  [1] "Lissa Kessler"       "Aletha Heathcote"    "Diane Fisher"       
#>  [4] NA                    "Jasmine Wehner"      "Toriano Maggio"     
#>  [7] "Tucker Fay"          "Darwin Dare-Bartell" NA                   
#> [10] "Booker Koch IV"

numeric data

testVector$make_missing(x = ch_integer(10))
#>  [1] 268 975 660 124 649  NA 814 838 164 495

logicals

set.seed(123)
testVector$make_missing(x = sample(c(TRUE, FALSE), 10, replace = TRUE))
#>  [1]  TRUE    NA    NA FALSE  TRUE    NA FALSE FALSE    NA  TRUE

Messy data

Real data is messy, right? charlatan makes it easy to create messy data. This is still in the early stages so is not available across most data types and languages, but we’re working on it.

For example, create messy names:

ch_name(50, messy = TRUE)
#>  [1] "Destiney Dicki"            "Mrs. Freddie Pouros DDS"  
#>  [3] "Ms. Jada Lesch"            "Inga Dach"                
#>  [5] "Keyshawn Schaefer"         "Ferdinand Bergstrom"      
#>  [7] "Justen Simonis"            "Ms. Doloris Stroman DVM"  
#>  [9] "Mrs. Ermine Heidenreich"   "Marion Corwin"            
#> [11] "Jalen Grimes"              "Mr. Sullivan Hammes IV"   
#> [13] "Adrien Vandervort-Dickens" "Dr. Sharif Kunde"         
#> [15] "Marlena Reichert PhD"      "Mr. Brandan Oberbrunner"  
#> [17] "Lloyd Adams III"           "Randy Ziemann"            
#> [19] "Gina Sanford"              "Cornell Funk"             
#> [21] "Yadiel Collier"            "Kamryn Johnson"           
#> [23] "Tyesha Schmeler"           "Ernie Hegmann-Graham"     
#> [25] "Zackery Runolfsdottir"     "Cleveland Predovic"       
#> [27] "Melvyn Hickle"             "Larry Nienow IV"          
#> [29] "Vilma Rutherford"          "Wiliam Ziemann-Fadel"     
#> [31] "Mrs. Kathy Halvorson"      "Mirtie Harvey-Shanahan"   
#> [33] "Eliezer Pfeffer"           "Dr. Shep Buckridge"       
#> [35] "Kyree Kutch"               "Ms. Delpha Grant"         
#> [37] "Ms. Icie Crooks"           "Loney Jenkins-Lindgren"   
#> [39] "Shania Donnelly DVM"       "Dr. Patric Veum"          
#> [41] "Amirah Rippin DVM"         "Randle Hilpert"           
#> [43] "Soren Dare"                "Roderic Walter"           
#> [45] "Farah Daugherty MD"        "Marva Crooks"             
#> [47] "Ryland Ledner"             "Girtha Harvey DDS"        
#> [49] "Staci Spencer"             "Mr. Olan Bernhard"

Right now only suffixes and prefixes for names in en_US locale are supported. Notice above some variation in prefixes and suffixes.