Skip to content

Using / reproducing DAC from the paper "Disentangled Attribution Curves for Interpreting Random Forests and Boosted Trees"

License

Notifications You must be signed in to change notification settings

csinva/disentangled-attribution-curves

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

97 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Disentangled attribution curves (DAC) 🔎

Official code for using / reproducing DAC from the paper Disentangled Attribution Curves for Interpreting Random Forests (arXiv 2018 pdf)

Note: this repo is actively maintained. For any questions please file an issue.

documentation

using DAC on new models

  • quick install: pip install git+https://github.com/csinva/disentangled-attribution-curves
  • the core of the method code lies in the dac folder and is compatible with scikit-learn
  • the examples/xor_dac.ipynb folder contains examples of how to use DAC on a new dataset with some simple datasets (e.g. XOR, etc.)
  • the basic api consists of two functions: from dac import dac, dac_plot
  • dac(forest, input_space_x, outcome_space_y, assignment, S, continuous_y=True, class_id=1)
    • inputs:

      • forest: an sklearn ensemble of decision trees
      • input_space_x: the matrix of training data (feature values), a numpy 2D array
      • outcome_space_y: the array of training data (labels/regression targets), a numpy 1D array
      • assignment: a matrix of feature values that will have their DAC importance score evaluated, a numpy 2D array
      • S: a binary indicator of whether to include each feature in the importance calculation, a numpy 1D array with values 0 and 1 only
      • continuous_y: a boolean indicator of whether the y targets are regression(true) or classification(false), defaults to true
      • class_id: if classification, the class value to return proportions for, defaults to 1
    • returns

      • dac_curve
    • for regression: a numpy array whose length corresponds to the number of samples in the assignment input. Each entry is a DAC importance score, a float between min(outcome_space_y) and max(outcome_space_y)

      • for classification: a numpy array whose length corresponds to the number of samples in the assignment input. Each entry is a DAC importance score, a float between 0 and 1
  • dac_plot(forest, input_space_x, outcome_space_y, S, interval_x, interval_y, di_x, di_y, C, continuous_y, weights
    • inputs
      • forest: an sklearn ensemble of decision trees (random forest or adaboosted forest)
      • input_space_x: the matrix of training data (feature values), a numpy 2D array
      • outcome_space_y: the array of training data (labels/regression targets), a numpy 1D array
      • S: a binary indicator of whether to include each feature in the importance calculation, a numpy 1D array with values 0 and 1 only
      • interval_x: an interval for the x axis of the plot, defaults to None. If None, a reasonable interval will be extrapolated from the range of the first feature specified in S.
      • interval_y: an interval for the y axis of the plot (only applicable to heat maps), defaults to None.
        If None, a reasonable interval will be extrapolated from the range of the second feature specified in S.
      • di_x: a step length for the x axis of the plot, defaults to None. If None, a reasonable step length will be extrapolated from the range of the first feature specified in S.
      • di_y: a step length for the y axis of the plot (only applicable to heat maps), defaults to None. If None, a reasonable step length will be extrapolated from the range of the second feature specified in S.
      • C: a hyper-parameter specifying the number of standard deviations samples can be from the mean of the leaf and be counted into the curve. Smaller values yield a more sensitive curve, larger values yield a smoother curve.
      • continuous_y: a boolean indicator of whether the y targets are regression(true) or classification(false), defaults to true
      • weights: weights for the individual estimators contributions to the curve, defaults to None. If None, weights will be extrapolated from the forest type.
    • returns
      • dac_curve a numpy array containing values for the DAC curve or heatmap describing the interaction of the variables specified in S

reproducing results from the paper

  • the examples/bike_sharing_dac.ipynb folder contains examples of how to use DAC to reproducing the qualitative curves on the bike-sharing dataset in the paper
  • the simulation script replicates the experiments with running simulations
  • the pmlb script replicates the experiments of automatic feature engineering on pmlb datasets

dac animation

a gif demonstrating calculating a DAC curve for a simple tree

related work

  • this work is part of an overarching project on interpretable machine learning, guided by the PDR framework for interpretable machine learning
  • for related work, see the github repo for disentangled hierarchical dnn interpretations (ICLR 2019)

reference

  • feel free to use/share this code openly

  • citation for this work:

    @article{devlin2019disentangled,
        title={Disentangled Attribution Curves for Interpreting Random Forests and Boosted Trees},
        author={Devlin, Summer and Singh, Chandan and Murdoch, W James and Yu, Bin},
        journal={arXiv preprint arXiv:1905.07631},
        year={2019}
    }