Ethnicolr

https://github.com/appeler/ethnicolr
Admin
Ethnicolr is a machine learning library that predicts race and ethnicity from first and last names...
Tokens:9,592
Snippets:53
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Jupyter Quickstart

Source: https://pypi.org/project/ethnicolr

Commands to install dependencies, download census models, and launch example notebooks.

```bash
pip install ethnicolr jupyter
python -m ethnicolr.cli models download census
jupyter notebook ethnicolr/examples
```

--------------------------------

### Install ethnicolr

Source: https://pypi.org/project/ethnicolr

Standard installation command for the library.

```bash
pip install ethnicolr
```

--------------------------------

### CLI Quick Start

Source: https://pypi.org/project/ethnicolr

Basic commands to check model status, download models, and run predictions.

```bash
# Check which models are available
python -m ethnicolr.cli models status

# Download required models
python -m ethnicolr.cli models download census

# Run predictions
python -m ethnicolr.cli predict census data.csv -l surname -o results.csv
```

--------------------------------

### Ethnicolr CLI - Examples

Source: https://pypi.org/project/ethnicolr

Practical examples demonstrating how to use the ethnicolr CLI for census data lookup and race/ethnicity prediction.

```APIDOC
## Examples
To append census data from 2010 to a sample file with column header in the first row, specify the column name carrying last names using the [`-l`] option, keeping the rest the same:
```
# Download the sample file first:
curl -O https://raw.githubusercontent.com/appeler/ethnicolr/refs/heads/master/examples/input-with-header.csv

# Then run census lookup:
census_ln -y 2010 -o output-census2010.csv -l last_name input-with-header.csv

```

To predict race/ethnicity using Wikipedia full name model, specify the column name of last name and first name by using [`-l`] and [`-f`] flags respectively.
```
pred_wiki_name -o output-wiki-pred-race.csv -l last_name -f first_name input-with-header.csv

```
```

--------------------------------

### Model Management

Source: https://pypi.org/project/ethnicolr

Command to verify the installation status of available models.

```bash
# Check installation status of all models
python -m ethnicolr.cli models status
```

--------------------------------

### Download Sample Data with Curl

Source: https://pypi.org/project/ethnicolr

Download a sample CSV file using curl. This file can be used with the ethnicolr CLI or API examples.

```bash
curl -O https://raw.githubusercontent.com/appeler/ethnicolr/refs/heads/master/examples/input-with-header.csv
```

--------------------------------

### Get Information About a Specific Model

Source: https://pypi.org/project/ethnicolr

Retrieve detailed information about a particular prediction model, such as the 'census' model.

```bash
python -m ethnicolr.cli models info census
```

--------------------------------

### Predict Race and Ethnicity with Census Data

Source: https://pypi.org/project/ethnicolr

Examples of using census-based functions to infer race and ethnicity from a DataFrame column containing last names.

```python
>>> census_ln(df, 'name')
      name pctwhite pctblack pctapi pctaian pct2prace pcthispanic
0    smith    73.35    22.22   0.40    0.85      1.63        1.56
1    zhang     0.61     0.09  98.16    0.02      0.96        0.16
2  jackson    41.93    53.02   0.31    1.04      2.18        1.53

>>> census_ln(df, 'name', 2010)
      name   race pctwhite pctblack pctapi pctaian pct2prace pcthispanic
0    smith  white     70.9    23.11    0.5    0.89      2.19         2.4
1    zhang    api     0.99     0.16  98.06    0.02      0.62        0.15
2  jackson  black    39.89    53.04   0.39    1.06      3.12         2.5

>>> pred_census_ln(df, 'name')
      name   race       api     black  hispanic     white
0    smith  white  0.002019  0.247235  0.014485  0.736260
1    zhang    api  0.997807  0.000149  0.000470  0.001574
2  jackson  black  0.002797  0.528193  0.014605  0.454405
```

--------------------------------

### Legacy CLI Commands

Source: https://pypi.org/project/ethnicolr

These are legacy command-line tools available for backward compatibility. Use `--help` to see their specific options.

```bash
census_ln --help
```

```bash
pred_census_ln --help
```

```bash
pred_wiki_name --help
```

--------------------------------

### List Available Prediction Models

Source: https://pypi.org/project/ethnicolr

Use this command to see all available prediction models and their details.

```bash
python -m ethnicolr.cli models list --detailed
```

--------------------------------

### Ethnicolr CLI - Legacy Commands

Source: https://pypi.org/project/ethnicolr

Information about legacy command-line tools available for backward compatibility.

```APIDOC
### Legacy CLI
The original command-line tools are still available for backward compatibility:
```
census_ln --help
pred_census_ln --help
pred_wiki_name --help
# ... etc
```
```

--------------------------------

### Download Specific Prediction Models

Source: https://pypi.org/project/ethnicolr

Download specific prediction models for use. You can specify models like 'census' with a year or other available models.

```bash
python -m ethnicolr.cli models download census --year 2010
```

```bash
python -m ethnicolr.cli models download florida
```

--------------------------------

### Prediction Commands

Source: https://pypi.org/project/ethnicolr

Commands for running predictions using different models and configuration options.

```bash
# Census-based prediction (most common)
python -m ethnicolr.cli predict census data.csv -l surname

# With specific census year and confidence intervals
python -m ethnicolr.cli predict census data.csv -l surname -y 2010 -c 0.95 -i 200

# Florida voter registration model
python -m ethnicolr.cli predict florida data.csv -l surname

# Wikipedia model (detailed ethnic categories)
python -m ethnicolr.cli predict wiki data.csv -l surname
```

--------------------------------

### Quick Prediction with CSV Data

Source: https://pypi.org/project/ethnicolr

Perform a fast prediction using a CSV file. Specify the column containing last names and optionally first names. The system can auto-select the best model if a first name column is provided.

```bash
python -m ethnicolr.cli quick-predict data.csv -l surname --model census
```

```bash
python -m ethnicolr.cli quick-predict data.csv -l surname -f firstname
```

--------------------------------

### Ethnicolr CLI - Quick Prediction

Source: https://pypi.org/project/ethnicolr

Perform quick predictions using the command-line interface, with options for auto-selecting models or specifying them.

```APIDOC
## Quick Prediction
# Fast prediction with minimal setup
python -m ethnicolr.cli quick-predict data.csv -l surname --model census

# Auto-selects best model based on available data
python -m ethnicolr.cli quick-predict data.csv -l surname -f firstname
```

--------------------------------

### Run Census Lookup with Specific Year and Output

Source: https://pypi.org/project/ethnicolr

Append census data from a specific year (e.g., 2010) to a CSV file. Requires specifying the last name column and an output file path.

```bash
census_ln -y 2010 -o output-census2010.csv -l last_name input-with-header.csv
```

--------------------------------

### Ethnicolr CLI - Models

Source: https://pypi.org/project/ethnicolr

Commands for managing prediction models, including listing available models and downloading specific ones.

```APIDOC
## List available prediction models
python -m ethnicolr.cli models list --detailed

## Download specific models
python -m ethnicolr.cli models download census --year 2010
python -m ethnicolr.cli models download florida

## Get information about a model
python -m ethnicolr.cli models info census
```

--------------------------------

### Predict Race/Ethnicity using Wikipedia Model

Source: https://pypi.org/project/ethnicolr

Predict race/ethnicity using the Wikipedia full name model. Specify the last name and first name columns, and an output file.

```bash
pred_wiki_name -o output-wiki-pred-race.csv -l last_name -f first_name input-with-header.csv
```

--------------------------------

### Ethnicolr CLI - Common Options

Source: https://pypi.org/project/ethnicolr

Common command-line options supported by most ethnicolr prediction commands.

```APIDOC
### CLI Options
All prediction commands support these common options:
  * `-l, --last-column`: Column containing last names (required)
  * `-f, --first-column`: Column containing first names (when supported)
  * `-o, --output`: Output file path (auto-generated if not specified)
  * `-c, --confidence`: Confidence interval level (0.0-1.0)
  * `-i, --iterations`: Monte Carlo iterations for confidence intervals
  * `--overwrite`: Overwrite existing output files
  * `-v, --verbose`: Enable detailed progress information
```

--------------------------------

### Predict Race using pred_fl_reg_ln

Source: https://pypi.org/project/ethnicolr

Removes extra spaces and predicts race/ethnicity using the last name FL registration model. Requires a DataFrame or CSV file containing names and the name of the column with last names.

```python
pred_fl_reg_ln(df, lname_col, num_iter=100, conf_int=1.0)
```

--------------------------------

### Predict Race with FL Model (Full Name)

Source: https://pypi.org/project/ethnicolr

Appends race and ethnicity predictions with confidence intervals to a DataFrame using the full name model. Requires a DataFrame and column names for first and last names.

```python
>>> odf = pred_fl_reg_ln_five_cat(df,'last')
['asian', 'hispanic', 'nh_black', 'nh_white', 'other']

>>> odf
   last first true_race  asian_mean  asian_std  asian_lb  asian_ub  hispanic_mean  hispanic_std  ...  nh_white_mean  nh_white_std  nh_white_lb  nh_white_ub  other_mean  other_std  other_lb  other_ub      race
0  Sawyer  john  nh_white    0.100038   0.020539  0.073266  0.143334       0.044263      0.013077  ...       0.376639      0.048289     0.296989     0.452834    0.248466   0.021040  0.219721  0.283785  nh_white
1  Torres  raul  hispanic    0.062390   0.021863  0.033837  0.103737       0.774414      0.043238  ...       0.030393      0.009591     0.019713     0.046483    0.117761   0.019524  0.089418  0.150615  hispanic

[2 rows x 24 columns]

>>> odf.iloc[0]
last               Sawyer
first                john
true_race        nh_white
asian_mean       0.100038
asian_std        0.020539
asian_lb         0.073266
asian_ub         0.143334
hispanic_mean    0.044263
hispanic_std     0.013077
hispanic_lb       0.02476
hispanic_ub      0.067965
n h_black_mean    0.230593
n h_black_std     0.063948
n h_black_lb      0.130577
n h_black_ub      0.343513
n h_white_mean    0.376639
n h_white_std     0.048289
n h_white_lb      0.296989
n h_white_ub      0.452834
other_mean       0.248466
other_std         0.02104
other_lb         0.219721
other_ub         0.283785
race             nh_white
Name: 0, dtype: object
```

--------------------------------

### POST /pred_wiki_ln

Source: https://pypi.org/project/ethnicolr

Predicts race and ethnicity using the last name wiki model with uncertainty estimation.

```APIDOC
## POST /pred_wiki_ln

### Description
Removes extra spaces from names and uses the last name wiki model to predict the race and ethnicity of individuals.

### Method
POST

### Endpoint
/pred_wiki_ln

### Parameters
#### Request Body
- **df** (DataFrame/CSV) - Required - Pandas dataframe or CSV file containing the names to be inferred.
- **lname_col** (string) - Required - Name of the column containing the last name.
- **num_iter** (int) - Optional - Number of iterations to calculate uncertainty in the model (default=100).
- **conf_int** (float) - Optional - Confidence interval in predicted class (default=1.0).
```

--------------------------------

### Ethnicolr - Name Cleaning

Source: https://pypi.org/project/ethnicolr

Guidelines and recommendations for cleaning names before using ethnicolr prediction models to ensure optimal results.

```APIDOC
### Cleaning Names
The prediction models work best when first and last names contain only alphabetic characters. Before calling the CLI or Python APIs, strip out titles (e.g., _Dr_ , _Hon._), middle names, suffixes, punctuation and non-ASCII characters. The `pred_wiki_name` command automatically normalizes names by removing diacritics and extraneous characters. If the tool still skips entries, check that the first and last name columns are not empty after cleaning.
```

--------------------------------

### Predict Race using Wiki Last Name Model

Source: https://pypi.org/project/ethnicolr

Appends predicted race and confidence intervals to a DataFrame using the last name. Requires pandas and ethnicolr. The conf_int parameter controls the confidence interval.

```python
import pandas as pd

from ethnicolr import pred_wiki_ln

names = [
            {"last": "smith", "first": "john", "true_race": "GreaterEuropean,British"},
            {
                "last": "zhang",
                "first": "simon",
                "true_race": "Asian,GreaterEastAsian,EastAsian",
            },
        ]
df = pd.DataFrame(names)

odf = pred_wiki_ln(df,'last', conf_int=0.9)
```

```python
odf
```

```python
odf.iloc[0, :8]
```

--------------------------------

### Predict Race with NC Model (Full Name)

Source: https://pypi.org/project/ethnicolr

Appends race and ethnicity predictions with confidence intervals to a DataFrame using the NC model. Requires a DataFrame and column names for first and last names.

```python
>>> odf = pred_nc_reg_name_five_cat(df, 'last','first')
['asian', 'hispanic', 'nh_black', 'nh_white', 'other']

>>> odf
   last first true_race  asian_mean  asian_std  asian_lb  asian_ub  hispanic_mean  hispanic_std  ...  nh_white_mean  nh_white_std  nh_white_lb  nh_white_ub  other_mean  other_std  other_lb  other_ub      race
0  Sawyer  john  nh_white    0.039310   0.011657  0.025982  0.059719       0.019737      0.005813  ...       0.650306      0.059327     0.553913     0.733201    0.192242   0.021004  0.160185  0.226063  nh_white
1  Torres  raul  hispanic    0.020086   0.011765  0.008240  0.041741       0.899110      0.042237  ...       0.019073      0.009901     0.010166     0.040081    0.055774   0.017897  0.036245  0.088741  hispanic

[2 rows x 24 columns]

>>> odf.iloc[1]
last               Torres
first                raul
true_race        hispanic
asian_mean       0.020086
asian_std        0.011765
asian_lb          0.00824
asian_ub         0.041741
hispanic_mean     0.89911
hispanic_std     0.042237
hispanic_lb      0.823799
hispanic_ub      0.937612
n h_black_mean    0.005956
n h_black_std     0.006528
n h_black_lb      0.002686
n h_black_ub      0.010134
n h_white_mean    0.019073
n h_white_std     0.009901
n h_white_lb      0.010166
n h_white_ub      0.040081
other_mean       0.055774
other_std        0.017897
other_lb         0.036245
other_ub         0.088741
race             hispanic
Name: 1, dtype: object
```

--------------------------------

### Predict Race with Last Name Model

Source: https://pypi.org/project/ethnicolr

Uses the last name FL registration model to predict race and ethnicity, appending statistical columns to the input DataFrame.

```python
>>> import pandas as pd

>>> names = [
...             {"last": "sawyer", "first": "john", "true_race": "nh_white"},
...             {"last": "torres", "first": "raul", "true_race": "hispanic"},
...         ]

>>> df = pd.DataFrame(names)

>>> from ethnicolr import pred_fl_reg_ln, pred_fl_reg_name, pred_fl_reg_ln_five_cat, pred_fl_reg_name_five_cat

>>> odf = pred_fl_reg_ln(df, 'last', conf_int=0.9)
['asian', 'hispanic', 'nh_black', 'nh_white']

>>> odf
   last first true_race  asian_mean  asian_std  asian_lb  asian_ub  hispanic_mean  hispanic_std  hispanic_lb  hispanic_ub  nh_black_mean  nh_black_std  nh_black_lb  nh_black_ub  nh_white_mean  nh_white_std  nh_white_lb  nh_white_ub      race
0  Sawyer  john  nh_white    0.009859   0.006819  0.005338  0.019673       0.021488      0.004602     0.014802     0.030148       0.180929      0.052784     0.105756     0.270238       0.787724      0.051082     0.705290     0.860286  nh_white
1  Torres  raul  hispanic    0.006463   0.001985  0.003915  0.010146       0.878119      0.021998     0.839274     0.909151       0.013118      0.005002     0.007364     0.021633       0.102300      0.017828     0.075911     0.130929  hispanic

[2 rows x 20 columns]

>>> odf.iloc[0]
last               Sawyer
first                john
true_race        nh_white
asian_mean       0.009859
asian_std        0.006819
asian_lb         0.005338
asian_ub         0.019673
hispanic_mean    0.021488
hispanic_std     0.004602
hispanic_lb      0.014802
hispanic_ub      0.030148
nh_black_mean    0.180929
nh_black_std     0.052784
nh_black_lb      0.105756
nh_black_ub      0.270238
nh_white_mean    0.787724
nh_white_std     0.051082
nh_white_lb       0.70529
nh_white_ub      0.860286
race             nh_white
Name: 0, dtype: object
```

--------------------------------

### pred_wiki_ln - Predict Race/Ethnicity from Last Name

Source: https://pypi.org/project/ethnicolr

Appends predicted race and ethnicity information to a DataFrame based on the last name. It calculates confidence intervals for each predicted race.

```APIDOC
## POST /api/predict/lastname

### Description
Predicts race and ethnicity probabilities based on the last name column of a DataFrame. Appends columns for each race including mean, standard error, and confidence interval bounds (lower and upper).

### Method
POST

### Endpoint
/api/predict/lastname

### Parameters
#### Request Body
- **df** (DataFrame/CSV) - Required - Pandas DataFrame or CSV file containing the names.
- **namecol** (string) - Required - The name of the column containing the last names.
- **conf_int** (float, default=1.0) - Optional - Confidence interval level for predictions.

### Request Example
```json
{
  "df": "path/to/your/names.csv" or DataFrame object,
  "namecol": "last_name",
  "conf_int": 0.9
}
```

### Response
#### Success Response (200)
- **DataFrame** - The original DataFrame with appended columns for predicted race probabilities, means, standard errors, and confidence intervals.

#### Response Example
```json
{
  "example": "DataFrame with appended columns for race predictions and confidence intervals."
}
```
```

--------------------------------

### Predict Race with Full Name Model

Source: https://pypi.org/project/ethnicolr

Uses the full name FL registration model to predict race and ethnicity, requiring both last and first name columns.

```python
>>> odf = pred_fl_reg_name(df, 'last', 'first', conf_int=0.9)
['asian', 'hispanic', 'nh_black', 'nh_white']

>>> odf
   last first true_race  asian_mean  asian_std  asian_lb  asian_ub  hispanic_mean  hispanic_std  hispanic_lb  hispanic_ub  nh_black_mean  nh_black_std  nh_black_lb  nh_black_ub  nh_white_mean  nh_white_std  nh_white_lb  nh_white_ub      race
0  Sawyer  john  nh_white    0.001534   0.000850  0.000636  0.002691       0.006818      0.002557     0.003684     0.011660       0.028068      0.015095     0.011488     0.055149       0.963581      0.015738     0.935445     0.983224  nh_white
1  Torres  raul  hispanic    0.005791   0.002906  0.002446  0.011748       0.890561      0.029581     0.841328     0.937706       0.011397      0.004682     0.005829     0.020796       0.092251      0.026675     0.049868     0.139210  hispanic

>>> odf.iloc[1]
last               Torres
first                raul
true_race        hispanic
asian_mean       0.005791
asian_std        0.002906
asian_lb         0.002446
asian_ub         0.011748
hispanic_mean    0.890561
hispanic_std     0.029581
hispanic_lb      0.841328
hispanic_ub      0.937706
nh_black_mean    0.011397
nh_black_std     0.004682
nh_black_lb      0.005829
nh_black_ub      0.020796
nh_white_mean    0.092251
nh_white_std     0.026675
nh_white_lb      0.049868
nh_white_ub       0.13921
race             hispanic
Name: 1, dtype: object
```

--------------------------------

### Predict Race with conf_int using pred_wiki_name

Source: https://pypi.org/project/ethnicolr

Appends race prediction columns to a DataFrame. Use `conf_int` to specify the confidence interval for predictions. The output includes mean, standard error, and confidence bounds for each predicted race.

```python
>>> odf = pred_wiki_name(df,'last', 'first', conf_int=0.9)
['Asian,GreaterEastAsian,EastAsian', 'Asian,GreaterEastAsian,Japanese', 'Asian,IndianSubContinent', 'GreaterAfrican,Africans', 'GreaterAfrican,Muslim', 'GreaterEuropean,British', 'GreaterEuropean,EastEuropean', 'GreaterEuropean,Jewish', 'GreaterEuropean,WestEuropean,French', 'GreaterEuropean,WestEuropean,Germanic', 'GreaterEuropean,WestEuropean,Hispanic', 'GreaterEuropean,WestEuropean,Italian', 'GreaterEuropean,WestEuropean,Nordic']

>>> odf
   last  first                         true_race       __name  Asian,GreaterEastAsian,EastAsian_mean  ...  GreaterEuropean,WestEuropean,Nordic_mean  GreaterEuropean,WestEuropean,Nordic_std  GreaterEuropean,WestEuropean,Nordic_lb  GreaterEuropean,WestEuropean,Nordic_ub                              race
0  Smith   john           GreaterEuropean,British   Smith John                               0.004111  ...                                  0.006246                                 0.004760                                0.001048                                0.016288           GreaterEuropean,British
1  Zhang  simon  Asian,GreaterEastAsian,EastAsian  Zhang Simon                               0.944203  ...                                  0.000793                                 0.002557                                0.000019                                0.002470  Asian,GreaterEastAsian,EastAsian

[2 rows x 57 columns]

>>> odf.iloc[0,:8]
last                                                       Smith
first                                                       john
true_race                                GreaterEuropean,British
__name                                                Smith John
Asian,GreaterEastAsian,EastAsian_mean                   0.004111
Asian,GreaterEastAsian,EastAsian_std                    0.002929
Asian,GreaterEastAsian,EastAsian_lb                     0.001356
Asian,GreaterEastAsian,EastAsian_ub                     0.010571
Name: 0, dtype: object

```

--------------------------------

### pred_wiki_name - Predict Race/Ethnicity from Full Name

Source: https://pypi.org/project/ethnicolr

Uses the full name wiki model to predict race and ethnicity after removing extra spaces. It calculates uncertainty of predictions through iterations.

```APIDOC
## POST /api/predict/fullname

### Description
Predicts race and ethnicity using a model trained on full names. This function cleans up extra spaces in names before prediction and allows for iterative calculation of prediction uncertainty.

### Method
POST

### Endpoint
/api/predict/fullname

### Parameters
#### Request Body
- **df** (DataFrame/CSV) - Required - Pandas DataFrame or CSV file containing the names.
- **namecol** (string) - Required - The name of the column containing the full names.
- **num_iter** (int, default=100) - Optional - Number of iterations to calculate the uncertainty of predictions.
- **conf_int** (float, default=1.0) - Optional - Confidence interval level for predictions.

### Request Example
```json
{
  "df": "path/to/your/names.csv" or DataFrame object,
  "namecol": "full_name",
  "num_iter": 100,
  "conf_int": 0.95
}
```

### Response
#### Success Response (200)
- **DataFrame** - The original DataFrame with appended columns for predicted race and ethnicity.

#### Response Example
```json
{
  "example": "DataFrame with appended columns for race and ethnicity predictions."
}
```
```

--------------------------------

### Predict Race and Ethnicity with Confidence Intervals

Source: https://pypi.org/project/ethnicolr

Demonstrates using the pred_nc_reg_name function to append race and ethnicity predictions with confidence intervals to a pandas DataFrame.

```python
>>> import pandas as pd

>>> names = [
...             {"last": "hernandez", "first": "hector", "true_race": "HL+O"},
...             {"last": "zhang", "first": "simon", "true_race": "NL+A"},
...         ]

>>> df = pd.DataFrame(names)

>>> from ethnicolr import pred_nc_reg_name

>>> odf = pred_nc_reg_name(df, 'last','first', conf_int=0.9)
['HL+A', 'HL+B', 'HL+I', 'HL+M', 'HL+O', 'HL+W', 'NL+A', 'NL+B', 'NL+I', 'NL+M', 'NL+O', 'NL+W']

>>> odf
      last   first true_race            __name     HL+A_mean  HL+A_std       HL+A_lb       HL+A_ub     HL+B_mean  HL+B_std       HL+B_lb       HL+B_ub  HL+I_mean  ...     NL+M_mean  NL+M_std       NL+M_lb       NL+M_ub  NL+O_mean  NL+O_std   NL+O_lb   NL+O_ub  NL+W_mean  NL+W_std   NL+W_lb   NL+W_ub  race
0  hernandez  hector      HL+O  Hernandez Hector  2.727371e-13       0.0  2.727372e-13  2.727372e-13  6.542178e-04       0.0  6.542183e-04  6.542183e-04   0.000032  ...  7.863581e-06       0.0  7.863589e-06  7.863589e-06   0.184513       0.0  0.184514  0.184514   0.001256       0.0  0.001256  0.001256  HL+O
1      zhang   simon      NL+A       Zhang Simon  1.985421e-06       0.0  1.985423e-06  1.985423e-06  8.708256e-09       0.0  8.708265e-09  8.708265e-09   0.000049  ...  1.446786e-07       0.0  1.446784e-07  1.446784e-07   0.003238       0.0  0.003238  0.003238   0.000154       0.0  0.000154  0.000154  NL+A

[2 rows x 53 columns]

>>> odf.iloc[0]
last                hernandez
first                  hector
true_race                HL+O
__name       Hernandez Hector
HL+A_mean                 0.0
HL+A_std                  0.0
HL+A_lb                   0.0
HL+A_ub                   0.0
HL+B_mean            0.000654
HL+B_std                  0.0
HL+B_lb              0.000654
HL+B_ub              0.000654
HL+I_mean            0.000032
HL+I_std                  0.0
HL+I_lb              0.000032
HL+I_ub              0.000032
HL+M_mean            0.000541
HL+M_std                  0.0
HL+M_lb              0.000541
HL+M_ub              0.000541
HL+O_mean             0.58944
HL+O_std                  0.0
HL+O_lb               0.58944
HL+O_ub               0.58944
HL+W_mean            0.221309
HL+W_std                  0.0
HL+W_lb              0.221309
HL+W_ub              0.221309
NL+A_mean            0.000044
NL+A_std                  0.0
NL+A_lb              0.000044
NL+A_ub              0.000044
NL+B_mean            0.002199
NL+B_std                  0.0
NL+B_lb              0.002199
NL+B_ub              0.002199
NL+I_mean            0.000004
NL+I_std                  0.0
NL+I_lb              0.000004
NL+I_ub              0.000004
NL+M_mean            0.000008
NL+M_std                  0.0
NL+M_lb              0.000008
NL+M_ub              0.000008
NL+O_mean            0.184513
NL+O_std                  0.0
NL+O_lb              0.184514
NL+O_ub              0.184514
NL+W_mean            0.001256
NL+W_std                  0.0
NL+W_lb              0.001256
NL+W_ub              0.001256
race                     HL+O
Name: 0, dtype: object
```

--------------------------------

### pred_fl_reg_ln

Source: https://pypi.org/project/ethnicolr

Predicts race and ethnicity using the last name FL registration model.

```APIDOC
## pred_fl_reg_ln

### Description
Uses the last name FL registration model to predict the race and ethnicity of individuals in a DataFrame.

### Parameters
- **df** (DataFrame/csv) - Required - Pandas dataframe or CSV file containing the names.
- **last_name_col** (string) - Required - Name of the column containing the last name.
- **conf_int** (float) - Optional (default=1.0) - Confidence interval for the prediction.

### Response
- **Appended Columns** - Returns the original DataFrame with added columns: race, asian, hispanic, nh_black, nh_white (including mean, std, lb, ub for each).
```

--------------------------------

### pred_fl_reg_ln_five_cat

Source: https://pypi.org/project/ethnicolr

Predicts race and ethnicity using the last name FL registration model with five categories.

```APIDOC
## pred_fl_reg_ln_five_cat

### Description
Uses the last name FL registration model to predict the race and ethnicity, supporting five categories.

### Parameters
- **df** (DataFrame/csv) - Required - Pandas dataframe or CSV file containing the names.
- **lname_col** (string/list/int) - Required - Name or location of the column containing the last name.
- **num_iter** (int) - Optional (default=100) - Number of iterations to calculate uncertainty.
```

--------------------------------

### pred_fl_reg_name

Source: https://pypi.org/project/ethnicolr

Predicts race and ethnicity using the full name FL registration model.

```APIDOC
## pred_fl_reg_name

### Description
Uses the full name FL model to predict the race and ethnicity after removing extra spaces.

### Parameters
- **df** (DataFrame/csv) - Required - Pandas dataframe or CSV file containing the names.
- **lname_col** (list) - Required - Name of the column containing the last name.
- **num_iter** (int) - Optional (default=100) - Number of iterations to calculate uncertainty.
- **conf_int** (float) - Optional (default=1.0) - Confidence interval in predicted class.

### Response
- **Appended Columns** - Returns the original DataFrame with added columns: race, asian, hispanic, nh_black, nh_white (including mean, std, lb, ub for each).
```

--------------------------------

### POST /pred_fl_reg_ln

Source: https://pypi.org/project/ethnicolr

Predicts race and ethnicity based on last names provided in a DataFrame or CSV, with optional confidence interval calculation.

```APIDOC
## POST /pred_fl_reg_ln

### Description
Uses the Florida registration model to predict the race and ethnicity of individuals based on their last name. It cleans input data by removing extra spaces and supports uncertainty estimation.

### Method
POST

### Parameters
#### Request Body
- **df** (DataFrame/CSV) - Required - Pandas dataframe or CSV file containing the names to be inferred.
- **lname_col** (string) - Required - The name of the column containing the last name.
- **num_iter** (int) - Optional - Default: 100. Number of iterations to calculate the uncertainty.
- **conf_int** (float) - Optional - Default: 1.0. The confidence interval level for the prediction output.

### Response
#### Success Response (200)
- **Output** (DataFrame) - Returns the original DataFrame appended with race categories and statistical columns (mean, standard error, lower bound, upper bound) for each race category.
```

--------------------------------

### Census Lookup with Pandas DataFrame

Source: https://pypi.org/project/ethnicolr

Use the `census_ln` function to append census data to a pandas DataFrame. This function requires the DataFrame and the name of the last name column. It automatically appends probability columns for different racial/ethnic groups.

```python
import pandas as pd

from ethnicolr import census_ln, pred_census_ln

names = [{'name': 'smith'},
        {'name': 'zhang'},
        {'name': 'jackson'}]

df = pd.DataFrame(names)

df

census_ln(df, 'name')
```

--------------------------------

### Ethnicolr Function - pred_census_ln

Source: https://pypi.org/project/ethnicolr

Details on the `pred_census_ln` function for predicting race and ethnicity using census models.

```APIDOC
  * **pred_census_ln(df, lname_col, year=2000, num_iter=100, conf_int=1.0)**
    * What it does:
      * Removes extra space.
      * Uses the last name census 2000 model or last name census 2010 model to predict race and ethnicity.
* * * 
Parameters 
* * *
**df** : _{DataFrame, csv}_ Pandas dataframe of CSV file contains the names of the individual to be inferred
**namecol** : _{string}_ name of the column containing the last name
**year** : _{2000, 2010}, default=2000_ year of census to use
**num_iter** : _int, default=100_ number of iterations to calculate uncertainty in model
```

--------------------------------

### pred_nc_reg_name

Source: https://pypi.org/project/ethnicolr

Predicts race and ethnicity using the full name North Carolina model.

```APIDOC
## pred_nc_reg_name

### Description
Removes extra space and uses the full name NC model to predict the race and ethnicity of individuals.

### Parameters
- **df** (DataFrame/csv) - Required - Pandas dataframe or CSV file containing the names to be inferred.
- **namecol** (string/list) - Required - String or list of the name or location of the column containing the first name and last name.
- **num_iter** (int) - Optional - Default=100. Number of iterations to calculate uncertainty.
- **conf_int** (float) - Optional - Default=1.0. Confidence interval.
```

--------------------------------

### pred_fl_reg_name_five_cat

Source: https://pypi.org/project/ethnicolr

Predicts race and ethnicity using the full name Florida model.

```APIDOC
## pred_fl_reg_name_five_cat

### Description
Removes extra space and uses the full name FL model to predict the race and ethnicity of individuals.

### Parameters
- **df** (DataFrame/csv) - Required - Pandas dataframe or CSV file containing the names to be inferred.
- **namecol** (string/list) - Required - String or list of the name or location of the column containing the first name and last name.
- **num_iter** (int) - Optional - Default=100. Number of iterations to calculate uncertainty.
- **conf_int** (float) - Optional - Default=1.0. Confidence interval.

### Response
Appends columns: race, asian, hispanic, nh_black, nh_white, other. For each race, provides mean, standard error, lower bound, and upper bound of confidence interval.
```

--------------------------------

### Ethnicolr Function - census_ln

Source: https://pypi.org/project/ethnicolr

Details on the `census_ln` function for appending census data to a DataFrame or CSV.

```APIDOC
## Functions
We expose several functions, each of which either takes a pandas DataFrame or a CSV.
  * **census_ln(df, lname_col, year=2000)**
    * What it does: 
      * Removes extra space
      * For names in the census file, it appends relevant data of what probability the name provided is of a certain race/ethnicity

> * * *
> Parameters 
> * * *
> **df** : _{DataFrame, csv}_ Pandas dataframe of CSV file contains the names of the individual to be inferred
> **lname_col** : _{string}_ name of the column containing the last name
> ##  **Year** : _{2000, 2010}, default=2000_ year of census to use
  * Output: Appends the following columns to the pandas DataFrame or CSV: pctwhite, pctblack, pctapi, pctaian, pct2prace, pcthispanic. See here for what the column names mean.
```
>>> import pandas as pd

>>> from ethnicolr import census_ln, pred_census_ln

>>> names = [{'name': 'smith'},
...         {'name': 'zhang'},
...         {'name': 'jackson'}]

>>> df = pd.DataFrame(names)

>>> df
      name
0    smith
1    zhang
2  jackson

>>> census_ln(df, 'name')
      name pctwhite pctblack pctapi pctaian pct2prace pcthispanic
0    smith    73.35    22.22   0.40    0.85      1.63        1.56
1    zhang     0.61     0.09  98.16    0.02      0.96        0.16
2  jackson    41.93    53.02   0.31    1.04      2.18        1.53

```
```
Tokens:
Raw