CLI Reference

Installing the package puts a philanthropy executable on your PATH. See Use the CLI for worked invocations.

validate output

Alongside the threshold-0.5 precision/recall/F1, validate prints ROC-AUC, average precision, the base rate, a 10-row decile table, and a top-N hit-rate/capture line (--top-n, a count or a percentage, default 10% of rows):

precision (at threshold 0.5) 1.000
recall    (at threshold 0.5) 1.000
f1        (at threshold 0.5) 1.000
roc_auc                      1.000
average_precision            1.000
base_rate                    0.124

decile  n     positives  hit_rate  lift
     1  146   146        1.000     8.05x
     2  146   35         0.240     1.93x
     3  146   0          0.000     0.00x
     ...
    10  145   0          0.000     0.00x

top 146 of 1457: hit_rate 1.000, captures 0.807 of all positives

philanthropy.cli

A CSV-in / CSV-out command line for analysts who aren't primarily Python engineers. Five subcommands:

philanthropy features --source raisers_edge --data gifts.csv --out features.csv
philanthropy train    --data features.csv --target is_major_donor \
                      --features total_gift_amount,years_active --out model.joblib
philanthropy score    --model model.joblib --data prospects.csv --out scores.csv
philanthropy validate --model model.joblib --data holdout.csv --target is_major_donor
philanthropy check    --task lapse --source npsp --data gifts.csv

features rolls a raw CRM gift export up into the donor-level table the models consume, so the path from an export to a scored CSV needs no Python. It does not invent a label: train still needs a --target column, and constructing one from your own definition of a major donor stays your job. features also accepts repeated --activity TYPE=PATH flags to fold engagement data in alongside the gift features (see activities_to_features).

train saves a self-describing bundle (the fitted model, the feature list, and the scikit-learn / philanthropy versions used); score and validate reuse the feature list stored in that bundle unless you override it with --features. train --task leadership is a different shape entirely: it reads a raw gift export (not a pre-built features CSV) and calls philanthropy.models.score_leadership_prospects directly, which trains on history and scores today's prospects in one call, so --out there is a scored CSV, not a saved model bundle. check runs philanthropy.model_selection.compare_to_rule on a raw gift export: it tests the model against fixed simple rules on the file's own last complete fiscal year and prints the verdict and which list to use.

main(argv=None)

Execute the philanthropy command-line interface.

Parameters:

Name	Type	Description	Default
argv	list of str	Command-line arguments passed to the parser. If None, defaults to sys.argv[1:].	None

Source code in philanthropy/cli.py

def main(argv: Optional[Sequence[str]] = None) -> None:
    """Execute the philanthropy command-line interface.

    Parameters
    ----------
    argv : list of str, optional
        Command-line arguments passed to the parser. If None, defaults to sys.argv[1:].
    """
    args = _build_parser().parse_args(argv)
    args.func(args)