adult-income-classifier

Adult Income Classifier

An educational scikit-learn model that predicts whether an Adult/Census Income record is labeled >50K or <=50K per year. The repository packages the project-selected tuned AdaBoost estimator with the category mappings required to score raw Adult-style records.

Model Description

This is a binary classification project based on the UCI Adult dataset. The model uses 14 features: age, workclass, final weight (fnlwgt), education, education number, marital status, occupation, relationship, race, sex, capital gain, capital loss, hours per week, and native country.

The original notebook stripped whitespace and applied one LabelEncoder per categorical column. The resulting integer mappings are preserved in preprocessing.json, and the exact feature order is recorded in model_config.json. No raw dataset is redistributed in this repository.

Intended Use

Use this repository for learning, reproducibility checks, and demonstrations of classical supervised learning. It is not a validated assessment tool and should not be used to make employment, lending, insurance, admissions, eligibility, or other consequential decisions about people.

How to Use

Install the dependencies from requirements.txt, then run:

from inference import predict

record = {
    "age": 39,
    "workclass": "State-gov",
    "fnlwgt": 77516,
    "education": "Bachelors",
    "education-num": 13,
    "marital-status": "Never-married",
    "occupation": "Adm-clerical",
    "relationship": "Not-in-family",
    "race": "White",
    "sex": "Male",
    "capital-gain": 2174,
    "capital-loss": 0,
    "hours-per-week": 40,
    "native-country": "United-States",
}

print(predict(record))

The same helper is available from the command line with python inference.py --json '<JSON object>'.

Training

The notebook used the encoded adult.csv included in the source GitHub repository, separated income from the 14 predictors, and used train_test_split(test_size=0.30, random_state=1). The project compared decision trees, bagging, random forests, logistic regression, AdaBoost, gradient boosting, and XGBoost. Several tree, bagging, and random-forest searches optimized recall with cross-validation; the final AdaBoost settings were specified directly in the notebook.

The uploaded estimator is the notebook's project-selected tuned AdaBoost model:

AdaBoostClassifier(
    estimator=DecisionTreeClassifier(max_depth=2),
    n_estimators=100,
    learning_rate=0.8,
    algorithm="SAMME.R",
    random_state=0,
)

Evaluation

The artifact was retrained from the repository's encoded adult.csv using the same split and settings. The resulting confusion matrix exactly matches the notebook's recorded tuned AdaBoost matrix ([[7066, 484], [737, 1482]]).

The first four values are the project-reported classification metrics, reproduced on the same split. ROC-AUC and PR-AUC were computed during artifact verification from the model probabilities; they were not included in the original README table.

The README in the source project calls tuned AdaBoost the best overall model because it balances precision and recall. The notebook's expanded comparison is affected by a one-row model-name shift caused by a missing SVM object in the comparison list. After aligning estimator order, tuned AdaBoost remains a defensible project-selected model with the strongest reported overall balance, while XGBoost has a very similar profile and slightly higher recall in the expanded comparison. This card therefore does not claim that AdaBoost dominates every metric.

Limitations

The Adult dataset was extracted from 1994 U.S. Census data and may not represent current populations, labor markets, or contexts outside the source sample. It contains missing-value markers and sensitive demographic features. The experiment uses a single random holdout split, integer encodings for nominal categories, and a limited manual/model search. Performance can shift under distribution change, different preprocessing, or different decision thresholds.

Ethical Considerations

This is an educational/research artifact. The target and several inputs encode socially sensitive information, including race and sex, and the dataset reflects historical social and economic conditions. Predictions may reproduce or amplify historical inequities. Do not use this model to make or recommend consequential decisions about individuals, including employment, lending, insurance, admissions, benefits, or eligibility.

Source / Project

Source project: tanujranjith/Stanford-ML-Project on GitHub

Dataset: UCI Adult / Census Income, credited to Barry Becker and Ronny Kohavi. The UCI dataset is licensed CC BY 4.0; this repository does not redistribute the raw dataset. The GitHub source repository did not include a repository LICENSE file, so no separate model-repository license is asserted here.