README.md
1# Smart Dim Model
2
3The Smart Dim Model is an experimental model used to predict whether an upcoming
4screen-dim should go ahead or be deferred. The prediction is based on whether
5the user is likely to remain inactive or reactivate following a screen-dim. If
6the user is likely to reactivate, the model would predict the dim should be
7deferred, otherwise, the model would predict the dim should go ahead.
8
9## Model prediction
10
11The input to the model is a list of features that would help predict user
12activity after the screen is dimmed. Example features are user related features
13(e.g. activity count) and environment features (e.g. time of day). The model
14takes in these features and calculates an inactivity-score: the higher the
15score, the more likely the user will remain inactive. If this inactivity-score
16is higher than or equal to a dim-threshold (set by an experiment), the model
17will predict the dim should go ahead; otherwise it will predict the dim should
18be deferred.
19
20The features used by the model are those metrics logged to UKM by
21`UserActivityUkmLoggerImpl`. These metrics and features do not contain any user
22personal data. They are aggregated when training the model.
23
24Using these metrics, we trained a
25[DNN](https://en.wikipedia.org/wiki/Deep_learning#Deep_neural_networks) model.
26The inferencing code in `tf_native_inference.cc` consists of the model weights
27generated by [TensorFlow](https://www.tensorflow.org/) and basic operations to
28execute the model over an example.
29
30## Example preprocessing
31
32The `tf_native_inference.cc` generated from a TensorFlow model expects input
33features to be represented as a vector of floats. This conversion is handled by
34AssistRanker based on the configuration
35provided in `example_preprocessor_config.pb`. The feature-to-float conversion
36depends on the type of the feature. For example, a numerical feature will be
37converted to a corresponding float (possibly normalized). Categorical features
38(e.g. enums or bucketized numerical features) will be converted via
39[One-hot encoding](https://en.wikipedia.org/wiki/One-hot). Missing features can
40also be handled, with configurations specified in the
41`example_preprocessor_config.pb`. The configuration can be examined with the
42`print_example_preprocessor_config.py` utility:
43
44```shell
45./components/assist_ranker/print_example_preprocessor_config.py \
46 out/Release \
47 chrome/browser/chromeos/power/ml/smart_dim/example_preprocessor_config.pb
48```
49
50## Smart dim model interface
51
52Example processing and inactivity-score calculation are all internal details of
53the model. The public interface of the model is `SmartDimModel::ShouldDim()`.
54`SmartDimModelImpl::ShouldDim()` provides the actual implementation. It takes
55prediction features (`UserActivityEvent::Features`) as input and returns
56`UserActivityEvent::ModelPrediction`. The returned prediction contains both
57model response (dim, no-dim or model-error) and quantized values of
58inactivity-score and dim-threshold. These two values are quantized in the
59returned result so that they can be logged when necessary.
60