# Introduction to the charlatan package

#### Scott Chamberlain

#### Roel M. Hogervorst

#### 2026-01-13

`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] "Chiropodist"
    x$name()
    #> [1] "Herman Terry"
    x$job()
    #> [1] "Advertising account planner"
    x$color_name()
    #> [1] "Orchid"

## 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] "Arboriculturist"                 "Advertising copywriter"
    #> [3] "Runner, broadcasting/film/video"
    ch_job(locale = "fr_FR", n = 3)
    #> [1] "Enseignant"
    #> [2] "Technicien en engins de travaux publics"
    #> [3] "Biologiste en environnement"
    ch_job(locale = "hr_HR", n = 3)
    #> [1] "Ovlašteni ispitivač"    "Restaurator tehničar"   "Profesionalni diplomat"
    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] "Indigo"    "Violet"    "PeachPuff"
    ch_color_name(locale = "uk_UA", n = 3)
    #> [1] "Болотний"              "Алізариновий червоний" "Блідий рожево-ліловий"

## generate a dataset

    ch_generate()
    #> # A tibble: 10 × 3
    #>    name                     job                              phone_number
    #>    <chr>                    <chr>                            <chr>
    #>  1 Toy Olson                Land/geomatics surveyor          100-172-0323x9435
    #>  2 Byrd Hyatt               Chartered certified accountant   1-720-377-7607x369
    #>  3 Mr. Ansel Hoppe          Financial adviser                428.454.3111
    #>  4 Gennie Paucek            Environmental education officer  1-364-963-7415
    #>  5 Knute Larkin MD          Surveyor, building control       365-153-1512x640
    #>  6 Ms. Columbia O'Keefe PhD Psychologist, sport and exercise 1-675-608-6043
    #>  7 Hazelle Kertzmann        Radiographer, diagnostic         +43(6)5410096700
    #>  8 Mr. Landon Rempel PhD    Broadcast presenter              (407)670-1445
    #>  9 Emmett Blick-Stroman     Engineer, civil (consulting)     07211831032
    #> 10 Mrs. Enid Weimann        Tourism officer                  612.504.1906

    ch_generate("job", "phone_number", n = 30)
    #> # A tibble: 30 × 2
    #>    job                                phone_number
    #>    <chr>                              <chr>
    #>  1 Paramedic                          (117)599-7211x265
    #>  2 Geophysical data processor         1-698-432-3070
    #>  3 Lawyer                             883.498.5949x033
    #>  4 Diagnostic radiographer            (791)275-5975x879
    #>  5 Financial risk analyst             (054)799-0236
    #>  6 Broadcast presenter                395-340-7575x33687
    #>  7 Warehouse manager                  (166)502-3536
    #>  8 Government social research officer 812-310-8934x49355
    #>  9 Engineer, civil (contracting)      02670092370
    #> 10 Agricultural consultant            +01(0)2831341920
    #> # ℹ 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] "Dr. Lawrence Kunde"

    ch_name(10)
    #>  [1] "Thea McKenzie DDS"         "Pierre Brekke-Weissnat"
    #>  [3] "Gustie Gusikowski"         "Fernando Reynolds-Murray"
    #>  [5] "Margot Bartoletti"         "Campbell Rolfson"
    #>  [7] "Diana Rath MD"             "Mrs. Hassie Huel MD"
    #>  [9] "Godfrey Schuster Sr."      "Ms. Pepper Gusikowski DVM"

### phone number

    ch_phone_number()
    #> [1] "1-165-010-3537"

    ch_phone_number(10)
    #>  [1] "(635)197-0396x6413" "(082)647-9716"      "029-535-6739x35240"
    #>  [4] "(019)449-7175x357"  "202.408.9181x1298"  "(401)177-2530x2307"
    #>  [7] "1-356-342-7687"     "(725)247-8616"      "1-885-126-7772x160"
    #> [10] "590-879-7859"

### job

    ch_job()
    #> [1] "Risk analyst"

    ch_job(10)
    #>  [1] "Chemical engineer"
    #>  [2] "Administrator, sports"
    #>  [3] "Secretary, company"
    #>  [4] "Ophthalmologist"
    #>  [5] "Technical brewer"
    #>  [6] "Industrial buyer"
    #>  [7] "Editorial assistant"
    #>  [8] "Loss adjuster, chartered"
    #>  [9] "Engineer, control and instrumentation"
    #> [10] "Psychologist, sport and exercise"

## 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] "LTL" "RON" "GHS"

### credit cards

    ch_credit_card_provider()
    #> [1] "Discover"
    ch_credit_card_provider(n = 4)
    #> [1] "Diners Club / Carte Blanche" "VISA 16 digit"
    #> [3] "JCB 15 digit"                "Diners Club / Carte Blanche"

    ch_credit_card_number()
    #> [1] "4910218727801000"
    ch_credit_card_number(n = 10)
    #>  [1] "3027286704035888"    "3158731917012546371" "3112509263038535449"
    #>  [4] "3158976738315571054" "6011217371035136781" "4995484405809"
    #>  [7] "3112985431943077574" "3096622039431748876" "6011438916110691341"
    #> [10] "3028602338907012"

    ch_credit_card_security_code()
    #> [1] "540"
    ch_credit_card_security_code(10)
    #>  [1] "439" "846" "968" "224" "461" "621" "560" "189" "016" "954"

## 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] "Josephine Baumbach"     "Kaycee Mayert"          "Jonah Kihn PhD"
    #>  [4] "Michal Bashirian Jr."   "Brittany Kemmer-Renner" "Sibyl Leuschke"
    #>  [7] "Albin Koepp IV"         "Dr. Duane Oberbrunner"  NA
    #> [10] "Bess Marquardt"

### numeric data

    testVector$make_missing(x = ch_integer(10))
    #>  [1] 923  NA  NA 666 261  NA  NA 333 755 522

### 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.