API Reference

Fit a reward estimator to the given data and then estimate the rewards for the same data, with measures to guard against overfitting the in-sample reward estimates.

The specific method depends on the type of reward estimation:

• fit_predict! for categorical treatments
• fit_predict! for numeric treatments

Learner for reward estimation with categorical treatments.

The following parameters are supported (refer to the documentation for each):

• shared Learner parameters
• CategoricalRewardEstimator parameters

fit_predict!(lnr::CategoricalRewardEstimationLearner, X::FeatureInput,
             treatments::AbstractVector, outcomes::AbstractVector;
             keyword_arguments...)

Fit lnr with a reward estimation model on features X, treatments treatments, and outcomes outcomes, and return predicted counterfactual rewards for each observation along with the scores of the internal estimators during training.

Supports the same keyword_arguments as score.

predict(lnr::SupervisedLearner, X::FeatureInput)

Return the predictions made by the trained model in lnr for each point in the data X.

predict(lnr::CategoricalRewardEstimationLearner, X::FeatureInput,
        treatments::AbstractVector, outcomes::AbstractVector)

Return counterfactual rewards estimated by lnr for each observation in the data given by X, treatments and outcomes.

predict(lnr::CategoricalRewardEstimationLearner, X::FeatureInput)

Alternate form of predict that can be used when using the direct method for reward estimation.

score(lnr::CategoricalRewardEstimationLearner, X::FeatureInput,
      treatments::AbstractVector, outcomes::AbstractVector;
      keyword_arguments...)

Calculate the scores of the internal estimators in lnr on the data given by X, treatments and outcomes.

Returns a Dict with the following entries:

• :propensity: the score for the propensity estimator
• :outcome: a Dict where the keys are the possible treatments, and the values are the scores of the outcome estimator corresponding to each treatment

A score of NaN will be returned for any internal estimator that is not present.

Keyword Arguments

• propensity_score_criterion=:default: the criterion to use for evaluating the propensity estimator
• propensity_score_kwargs::Dict: any additional keyword arguments to use when evaluating the score for the propensity estimator
• outcome_score_criterion=:default: the criterion to use for evaluating the outcome estimator
• outcome_score_kwargs::Dict: any additional keyword arguments to use when evaluating the score for the outcome estimator

Learner that estimates equal propensity for all treatments.

For use with data from randomized experiments where treatments are known to be randomly assigned.

Learner for reward estimation with numeric treatments.

The following parameters are supported (refer to the documentation for each):

• shared Learner parameters
• NumericRewardEstimator parameters

fit_predict!(lnr::NumericRewardEstimationLearner, X::FeatureInput,
             treatments::Union{FeatureInput,AbstractVector},
             outcomes::AbstractVector,
             treatment_candidates::Union{FeatureInput,AbstractVector},
             keyword_arguments...)

Fit lnr with a reward estimation model on features X, treatments treatments, and outcomes outcomes, and return predicted counterfactual rewards for each observation under each treatment option in treatment_candidates, as well as the score of the internal outcome estimator.

all_treatment_combinations can be used to construct treatment_candidates in the correct format.

Supports the same keyword_arguments as score.

predict(lnr::NumericRewardEstimationLearner, X::FeatureInput,
        treatment_candidates::Union{FeatureInput,AbstractVector})

Return counterfactual rewards estimated by lnr for each observation in the data given by X under each treatment option in treatment_candidates.

all_treatment_combinations can be used to construct treatment_candidates in the correct format.

score(lnr::NumericRewardEstimationLearner, X::FeatureInput,
      treatments::Union{FeatureInput,AbstractVector},
      outcomes::AbstractVector; keyword_arguments...)

Calculate the score of the internal outcome estimator in lnr on the data given by X, treatments and outcomes.

The score calculation can be controlled using the usual keyword arguments to score.

all_treatment_combinations(args...)
all_treatment_combinations(keyword_arguments...)

Return a DataFrame containing all treatment combinations of one or more treatment vectors, ready for use as treatment_candidates in fit_predict! or predict.

Each argument should be an AbstractVector containing the possible options for each treatment, or a keyword argument with the name of the treatment and the value as the possible options.

Examples

All combinations of two treatments ranging between 2 and 4:

IAI.all_treatment_combinations(2:4, 2:4)

9×2 DataFrame
 Row │ treatment1  treatment2
     │ Int64       Int64
─────┼────────────────────────
   1 │          2           2
   2 │          3           2
   3 │          4           2
   4 │          2           3
   5 │          3           3
   6 │          4           3
   7 │          2           4
   8 │          3           4
   9 │          4           4

All combinations of treatments A (ranging between 1 and 3) and B (with three possible values):

IAI.all_treatment_combinations(A=1:3, B=[0.5, 0.75, 1.0])

9×2 DataFrame
 Row │ A     B
     │ Real  Real
─────┼────────────
   1 │    1   0.5
   2 │    2   0.5
   3 │    3   0.5
   4 │    1  0.75
   5 │    2  0.75
   6 │    3  0.75
   7 │    1   1.0
   8 │    2   1.0
   9 │    3   1.0

convert_treatments_to_numeric(treatments::Union{Symbol,AbstractString})
convert_treatments_to_numeric(treatments::AbstractArray)

Convert treatments from symbol/string format into numeric values.

When numeric treatments are used, each column in the rewards dataframe corresponds to numeric doses of one or more numeric treatments. However, dataframe column names are saved internally as strings, meaning that some functions can only return these values as strings rather than in their original numeric form, including:

• predict for numeric-dose policy learners
• predict_treatment_rank
• get_policy_treatment_rank

This function provides a convenient method to convert these strings back into numeric doses, either as a scalar value for single treatment problems, or as a vector of doses for multiple treatment problems.

Examples

Converting treatment names back to numeric values with a single numeric treatment:

predictions = ["1", "2", "3", "4", "5", "6"]
IAI.convert_treatments_to_numeric(predictions)

6-element Array{Int64,1}:
 1
 2
 3
 4
 5
 6

Converting treatment names back to numeric values with multiple numeric treatments:

predictions = ["[1,1]", "[2,1]", "[3,1]", "[1,2]", "[2,2]", "[3,2]"]
IAI.convert_treatments_to_numeric(predictions)

6-element Array{Array{Float64,1},1}:
 [1.0, 1.0]
 [2.0, 1.0]
 [3.0, 1.0]
 [1.0, 2.0]
 [2.0, 2.0]
 [3.0, 2.0]