Active learning classifier based on entropy measures.
+The entropy sampler selects samples for labeling based on the entropy of the prediction. The higher the entropy, the more likely the sample will be selected for labeling. The entropy measure is normalized to [0, 1] and then raised to the power of the discount factor.
+classifier
+Type → base.Classifier
+The classifier to wrap.
+discount_factor
+Type → float
+Default → 3
The discount factor to apply to the entropy measure. A value of 1 won't affect the entropy. The higher the discount factor, the more the entropy will be discounted, and the less likely samples will be selected for labeling. A value of 0 will select all samples for labeling. The discount factor is thus a way to control how many samples are selected for labeling.
+seed
+Default → None
Random number generator seed for reproducibility.
+from river import active
+from river import datasets
+from river import feature_extraction
+from river import linear_model
+from river import metrics
+
+dataset = datasets.SMSSpam()
+metric = metrics.Accuracy()
+model = (
+ feature_extraction.TFIDF(on='body') |
+ linear_model.LogisticRegression()
+)
+model = active.EntropySampler(model, seed=42)
+
+n_samples_used = 0
+for x, y in dataset:
+ y_pred, ask = model.predict_one(x)
+ metric = metric.update(y, y_pred)
+ if ask:
+ n_samples_used += 1
+ model = model.learn_one(x, y)
+
+metric
+Accuracy: 86.60%
+dataset.n_samples, n_samples_used
+(5574, 1921)
+print(f"{n_samples_used / dataset.n_samples:.2%}")
+34.46%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of x and indicate whether a label is needed.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for x and indicate whether a label is needed.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Base class for active learning classifiers.
+classifier
+Type → base.Classifier
+The classifier to wrap.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of x and indicate whether a label is needed.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for x and indicate whether a label is needed.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Univariate Gaussian anomaly detector.
+This is a supervised anomaly detector. It fits a Gaussian distribution to the target values. The anomaly score is then computed as so:
+This makes it so that the anomaly score is between 0 and 1.
+window_size
+Default → None
Set this to fit the Gaussian distribution over a window of recent values.
+grace_period
+Default → 100
Number of samples before which a 0 is always returned. This is handy because the Gaussian distribution needs time to stabilize, and will likely produce overly high anomaly score for the first samples.
+import random
+from river import anomaly
+
+rng = random.Random(42)
+detector = anomaly.GaussianScorer()
+
+for y in (rng.gauss(0, 1) for _ in range(100)):
+ detector = detector.learn_one(None, y)
+
+detector.score_one(None, -3)
+0.999477...
+detector.score_one(None, 3)
+0.999153...
+detector.score_one(None, 0)
+0.052665...
+detector.score_one(None, 0.5)
+0.383717...
+Update the model.
+Parameters
+Returns
+SupervisedAnomalyDetector: self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds a normal observation.
+Parameters
+Returns
+float: An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + +
Half-Space Trees (HST).
+Half-space trees are an online variant of isolation forests. They work well when anomalies are spread out. However, they do not work well if anomalies are packed together in windows.
+By default, this implementation assumes that each feature has values that are comprised between 0 and 1. If this isn't the case, then you can manually specify the limits via the limits argument. If you do not know the limits in advance, then you can use a preprocessing.MinMaxScaler as an initial preprocessing step.
The current implementation builds the trees the first time the learn_one method is called. Therefore, the first learn_one call might be slow, whereas subsequent calls will be very fast in comparison. In general, the computation time of both learn_one and score_one scales linearly with the number of trees, and exponentially with the height of each tree.
Note that high scores indicate anomalies, whereas low scores indicate normal observations.
+n_trees
+Default → 10
Number of trees to use.
+height
+Default → 8
Height of each tree. Note that a tree of height h is made up of h + 1 levels and therefore contains 2 ** (h + 1) - 1 nodes.
window_size
+Default → 250
Number of observations to use for calculating the mass at each node in each tree.
+limits
+Type → dict[base.typing.FeatureName, tuple[float, float]] | None
+Default → None
Specifies the range of each feature. By default each feature is assumed to be in range [0, 1].
seed
+Type → int | None
+Default → None
Random number seed.
+size_limit
+This is the threshold under which the node search stops during the scoring phase. The value .1 is a magic constant indicated in the original paper.
+from river import anomaly
+
+X = [0.5, 0.45, 0.43, 0.44, 0.445, 0.45, 0.0]
+hst = anomaly.HalfSpaceTrees(
+ n_trees=5,
+ height=3,
+ window_size=3,
+ seed=42
+)
+
+for x in X[:3]:
+ hst = hst.learn_one({'x': x}) # Warming up
+
+for x in X:
+ features = {'x': x}
+ hst = hst.learn_one(features)
+ print(f'Anomaly score for x={x:.3f}: {hst.score_one(features):.3f}')
+Anomaly score for x=0.500: 0.107
+Anomaly score for x=0.450: 0.071
+Anomaly score for x=0.430: 0.107
+Anomaly score for x=0.440: 0.107
+Anomaly score for x=0.445: 0.107
+Anomaly score for x=0.450: 0.071
+Anomaly score for x=0.000: 0.853
+The feature values are all comprised between 0 and 1. This is what is assumed by the model +by default. In the following example, we construct a pipeline that scales the data online +and ensures that the values of each feature are comprised between 0 and 1.
+from river import compose
+from river import datasets
+from river import metrics
+from river import preprocessing
+
+model = compose.Pipeline(
+ preprocessing.MinMaxScaler(),
+ anomaly.HalfSpaceTrees(seed=42)
+)
+
+auc = metrics.ROCAUC()
+
+for x, y in datasets.CreditCard().take(2500):
+ score = model.score_one(x)
+ model = model.learn_one(x)
+ auc = auc.update(y, score)
+
+auc
+ROCAUC: 91.15%
+You can also use the evaluate.progressive_val_score function to evaluate the model on a
+data stream.
from river import evaluate
+
+model = model.clone()
+
+evaluate.progressive_val_score(
+ dataset=datasets.CreditCard().take(2500),
+ model=model,
+ metric=metrics.ROCAUC(),
+ print_every=1000
+)
+[1,000] ROCAUC: 88.43%
+[2,000] ROCAUC: 89.28%
+[2,500] ROCAUC: 91.15%
+ROCAUC: 91.15%
+Update the model.
+Parameters
+Returns
+AnomalyDetector: self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds to a normal observation.
+Parameters
+Returns
+float: An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + + +
One-class SVM for anomaly detection.
+This is a stochastic implementation of the one-class SVM algorithm, and will not exactly match its batch formulation.
+It is encouraged to scale the data upstream with preprocessing.StandardScaler, as well as use feature_extraction.RBFSampler to capture non-linearities.
nu
+Default → 0.1
An upper bound on the fraction of training errors and a lower bound of the fraction of support vectors. You can think of it as the expected fraction of anomalies.
+optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the weights.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. A optim.schedulers.Constant is used if a float is provided. The intercept is not updated when this is set to 0.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+initializer
+Type → optim.base.Initializer | None
+Default → None
Weights initialization scheme.
+from river import anomaly
+from river import compose
+from river import datasets
+from river import metrics
+from river import preprocessing
+
+model = anomaly.QuantileFilter(
+ anomaly.OneClassSVM(nu=0.2),
+ q=0.995
+)
+
+auc = metrics.ROCAUC()
+
+for x, y in datasets.CreditCard().take(2500):
+ score = model.score_one(x)
+ is_anomaly = model.classify(score)
+ model = model.learn_one(x)
+ auc = auc.update(y, is_anomaly)
+
+auc
+ROCAUC: 74.68%
+You can also use the evaluate.progressive_val_score function to evaluate the model on a
+data stream.
from river import evaluate
+
+model = model.clone()
+
+evaluate.progressive_val_score(
+ dataset=datasets.CreditCard().take(2500),
+ model=model,
+ metric=metrics.ROCAUC(),
+ print_every=1000
+)
+[1,000] ROCAUC: 74.40%
+[2,000] ROCAUC: 74.60%
+[2,500] ROCAUC: 74.68%
+ROCAUC: 74.68%
+Update the model.
+Parameters
+Returns
+AnomalyDetector: self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds to a normal observation.
+Parameters
+Returns
+An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + +
Threshold anomaly filter.
+anomaly_detector
+An anomaly detector.
+q
+Type → float
+The quantile level above which to classify an anomaly score as anomalous.
+protect_anomaly_detector
+Default → True
Indicates whether or not the anomaly detector should be updated when the anomaly score is anomalous. If the data contains sporadic anomalies, then the anomaly detector should likely not be updated. Indeed, if it learns the anomaly score, then it will slowly start to consider anomalous anomaly scores as normal. This might be desirable, for instance in the case of drift.
+from river import anomaly
+from river import compose
+from river import datasets
+from river import metrics
+from river import preprocessing
+
+model = compose.Pipeline(
+ preprocessing.MinMaxScaler(),
+ anomaly.QuantileFilter(
+ anomaly.HalfSpaceTrees(seed=42),
+ q=0.95
+ )
+)
+
+report = metrics.ClassificationReport()
+
+for x, y in datasets.CreditCard().take(2000):
+ score = model.score_one(x)
+ is_anomaly = model['QuantileFilter'].classify(score)
+ model = model.learn_one(x)
+ report = report.update(y, is_anomaly)
+
+report
+ Precision Recall F1 Support
+<BLANKLINE>
+ 0 99.95% 94.49% 97.14% 1998
+ 1 0.90% 50.00% 1.77% 2
+<BLANKLINE>
+ Macro 50.42% 72.25% 49.46%
+ Micro 94.45% 94.45% 94.45%
+Weighted 99.85% 94.45% 97.05%
+<BLANKLINE>
+ 94.45% accuracy
+Classify an anomaly score as anomalous or not.
+Parameters
+Returns
+bool: A boolean value indicating whether the anomaly score is anomalous or not.
++
Update the anomaly filter and the underlying anomaly detector.
+Parameters
+Returns
+self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds to a normal observation.
+Parameters
+Returns
+An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + +
Threshold anomaly filter.
+anomaly_detector
+An anomaly detector.
+threshold
+Type → float
+A threshold above which to classify an anomaly score as anomalous.
+protect_anomaly_detector
+Default → True
Indicates whether or not the anomaly detector should be updated when the anomaly score is anomalous. If the data contains sporadic anomalies, then the anomaly detector should likely not be updated. Indeed, if it learns the anomaly score, then it will slowly start to consider anomalous anomaly scores as normal. This might be desirable, for instance in the case of drift.
+Anomaly filters can be used as part of a pipeline. For instance, we might want to filter out
+anomalous observations so as not to corrupt a supervised model. As an example, let's take
+the datasets.WaterFlow dataset. Some of the samples have anomalous target variables because
+of human interventions. We don't want our model to learn these values.
from river import datasets
+from river import metrics
+from river import time_series
+
+dataset = datasets.WaterFlow()
+metric = metrics.SMAPE()
+
+period = 24 # 24 samples per day
+
+model = (
+ anomaly.ThresholdFilter(
+ anomaly.GaussianScorer(
+ window_size=period * 7, # 7 days
+ grace_period=30
+ ),
+ threshold=0.995
+ ) |
+ time_series.HoltWinters(
+ alpha=0.3,
+ beta=0.1,
+ multiplicative=False
+ )
+)
+
+time_series.evaluate(
+ dataset,
+ model,
+ metric,
+ horizon=period
+)
++1 SMAPE: 4.220171
++2 SMAPE: 4.322648
++3 SMAPE: 4.418546
++4 SMAPE: 4.504986
++5 SMAPE: 4.57924
++6 SMAPE: 4.64123
++7 SMAPE: 4.694042
++8 SMAPE: 4.740753
++9 SMAPE: 4.777291
++10 SMAPE: 4.804558
++11 SMAPE: 4.828114
++12 SMAPE: 4.849823
++13 SMAPE: 4.865871
++14 SMAPE: 4.871972
++15 SMAPE: 4.866274
++16 SMAPE: 4.842614
++17 SMAPE: 4.806214
++18 SMAPE: 4.763355
++19 SMAPE: 4.713455
++20 SMAPE: 4.672062
++21 SMAPE: 4.659102
++22 SMAPE: 4.693496
++23 SMAPE: 4.773707
++24 SMAPE: 4.880654
+Classify an anomaly score as anomalous or not.
+Parameters
+Returns
+bool: A boolean value indicating whether the anomaly score is anomalous or not.
++
Update the anomaly filter and the underlying anomaly detector.
+Parameters
+Returns
+self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds to a normal observation.
+Parameters
+Returns
+An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + +
An anomaly detector.
+Update the model.
+Parameters
+Returns
+AnomalyDetector: self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds to a normal observation.
+Parameters
+Returns
+float: An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + +
Anomaly filter base class.
+An anomaly filter has the ability to classify an anomaly score as anomalous or not. It can then be used to filter anomalies, in particular as part of a pipeline.
+anomaly_detector
+Type → AnomalyDetector
+An anomaly detector wrapped by the anomaly filter.
+protect_anomaly_detector
+Default → True
Indicates whether or not the anomaly detector should be updated when the anomaly score is anomalous. If the data contains sporadic anomalies, then the anomaly detector should likely not be updated. Indeed, if it learns the anomaly score, then it will slowly start to consider anomalous anomaly scores as normal. This might be desirable, for instance in the case of drift.
+Classify an anomaly score as anomalous or not.
+Parameters
+Returns
+bool: A boolean value indicating whether the anomaly score is anomalous or not.
++
Update the anomaly filter and the underlying anomaly detector.
+Parameters
+Returns
+self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds to a normal observation.
+Parameters
+Returns
+An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + +
A supervised anomaly detector.
+Update the model.
+Parameters
+Returns
+SupervisedAnomalyDetector: self
++
Return an outlier score.
+A high score is indicative of an anomaly. A low score corresponds a normal observation.
+Parameters
+Returns
+float: An anomaly score. A high score is indicative of an anomaly. A low score corresponds a
++ + + + + + + + +
Bayes-UCB bandit policy.
+Bayes-UCB is a Bayesian algorithm for the multi-armed bandit problem. It uses the posterior distribution of the reward of each arm to compute an upper confidence bound (UCB) on the expected reward of each arm. The arm with the highest UCB is then pulled. The posterior distribution is updated after each pull. The algorithm is described in [^1].
+reward_obj
+Default → None
The reward object that is used to update the posterior distribution.
+burn_in
+Default → 0
Number of initial observations per arm before using the posterior distribution.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+ranking
+Return the list of arms in descending order of performance.
+import gym
+from river import bandit
+from river import proba
+from river import stats
+
+env = gym.make(
+ 'river_bandits/CandyCaneContest-v0'
+)
+_ = env.reset(seed=42)
+_ = env.action_space.seed(123)
+
+policy = bandit.BayesUCB(seed=123)
+
+metric = stats.Sum()
+while True:
+ action = policy.pull(range(env.action_space.n))
+ observation, reward, terminated, truncated, info = env.step(action)
+ policy = policy.update(action, reward)
+ metric = metric.update(reward)
+ if terminated or truncated:
+ break
+
+metric
+Sum: 841.
+the p-th quantile of the beta distribution for the arm
+Parameters
++
Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+Returns
+ArmID: A single arm.
++
Rewrite update function
+Parameters
++ + + + + + + + +
\(\varepsilon\)-greedy bandit policy.
+Performs arm selection by using an \(\varepsilon\)-greedy bandit strategy. An arm is selected at each step. The best arm is selected (1 - \(\varepsilon\))% of the time.
+Selection bias is a common problem when using bandits. This bias can be mitigated by using burn-in phase. Each model is given the chance to learn during the first burn_in steps.
epsilon
+Type → float
+The probability of exploring.
+decay
+Default → 0.0
The decay rate of epsilon.
+reward_obj
+Default → None
The reward object used to measure the performance of each arm. This can be a metric, a statistic, or a distribution.
+burn_in
+Default → 0
The number of steps to use for the burn-in phase. Each arm is given the chance to be pulled during the burn-in phase. This is useful to mitigate selection bias.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+current_epsilon
+The value of epsilon after factoring in the decay rate.
+ranking
+Return the list of arms in descending order of performance.
+import gym
+from river import bandit
+from river import stats
+
+env = gym.make(
+ 'river_bandits/CandyCaneContest-v0'
+)
+_ = env.reset(seed=42)
+_ = env.action_space.seed(123)
+
+policy = bandit.EpsilonGreedy(epsilon=0.9, seed=101)
+
+metric = stats.Sum()
+while True:
+ arm = policy.pull(range(env.action_space.n))
+ observation, reward, terminated, truncated, info = env.step(arm)
+ policy = policy.update(arm, reward)
+ metric = metric.update(reward)
+ if terminated or truncated:
+ break
+
+metric
+Sum: 775.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+Returns
+ArmID: A single arm.
++
Update an arm's state.
+Parameters
++ + + + + + + + + +
Exp3 bandit policy.
+This policy works by maintaining a weight for each arm. These weights are used to randomly decide which arm to pull. The weights are increased or decreased, depending on the reward. An egalitarianism factor \(\gamma \in [0, 1]\) is included, to tune the desire to pick an arm uniformly at random. That is, if \(\gamma = 1\), the arms are picked uniformly at random.
+gamma
+Type → float
+The egalitarianism factor. Setting this to 0 leads to what is called the EXP3 policy.
+reward_obj
+Default → None
The reward object used to measure the performance of each arm. This can be a metric, a statistic, or a distribution.
+reward_scaler
+Default → None
A reward scaler used to scale the rewards before they are fed to the reward object. This can be useful to scale the rewards to a (0, 1) range for instance.
+burn_in
+Default → 0
The number of steps to use for the burn-in phase. Each arm is given the chance to be pulled during the burn-in phase. This is useful to mitigate selection bias.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+ranking
+Return the list of arms in descending order of performance.
+import gym
+from river import bandit
+from river import proba
+from river import stats
+
+env = gym.make(
+ 'river_bandits/CandyCaneContest-v0'
+)
+_ = env.reset(seed=42)
+_ = env.action_space.seed(123)
+
+policy = bandit.Exp3(gamma=0.5, seed=42)
+
+metric = stats.Sum()
+while True:
+ action = policy.pull(range(env.action_space.n))
+ observation, reward, terminated, truncated, info = env.step(action)
+ policy = policy.update(action, reward)
+ metric = metric.update(reward)
+ if terminated or truncated:
+ break
+
+metric
+Sum: 799.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+Returns
+ArmID: A single arm.
++
Update an arm's state.
+Parameters
++ + + + + + + + + +
LinUCB, disjoint variant.
+Although it works, as of yet it is too slow to realistically be used in practice.
+The way this works is that each arm is assigned a linear_model.BayesianLinearRegression instance. This instance is updated every time the arm is pulled. The context is used as features for the regression. The reward is used as the target. The posterior distribution is used to compute the upper confidence bound. The arm with the highest upper confidence bound is pulled.
alpha
+Type → float
+Default → 1.0
Parameter used in each Bayesian linear regression.
+beta
+Type → float
+Default → 1.0
Parameter used in each Bayesian linear regression.
+smoothing
+Type → float | None
+Default → None
Parameter used in each Bayesian linear regression.
+reward_obj
+Default → None
The reward object used to measure the performance of each arm.
+burn_in
+Default → 0
The number of time steps during which each arm is pulled once.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+ranking
+Return the list of arms in descending order of performance.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+None Returns
+ArmID: A single arm.
++
Rewrite update function
+Parameters
++ + + + + + + + + +
Random bandit policy.
+This policy simply pulls a random arm at each time step. It is useful as a baseline.
+reward_obj
+Default → None
The reward object that is used to update the posterior distribution.
+burn_in
+Default → 0
Number of initial observations per arm before using the posterior distribution.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+ranking
+Return the list of arms in descending order of performance.
+import gym
+from river import bandit
+from river import proba
+from river import stats
+
+env = gym.make(
+ 'river_bandits/CandyCaneContest-v0'
+)
+_ = env.reset(seed=42)
+_ = env.action_space.seed(123)
+
+policy = bandit.RandomPolicy(seed=123)
+
+metric = stats.Sum()
+while True:
+ action = policy.pull(range(env.action_space.n))
+ observation, reward, terminated, truncated, info = env.step(action)
+ policy = policy.update(action, reward)
+ metric = metric.update(reward)
+ if terminated or truncated:
+ break
+
+metric
+Sum: 755.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+Returns
+ArmID: A single arm.
++
Update an arm's state.
+Parameters
++ + + + + + + + +
Thompson sampling.
+Thompson sampling is often used with a Beta distribution. However, any probability distribution can be used, as long it makes sense with the reward shape. For instance, a Beta distribution is meant to be used with binary rewards, while a Gaussian distribution is meant to be used with continuous rewards.
+The randomness of a distribution is controlled by its seed. The seed should not set within the distribution, but should rather be defined in the policy parametrization. In other words, you should do this:
+policy = ThompsonSampling(dist=proba.Beta(1, 1), seed=42)
+and not this:
+policy = ThompsonSampling(dist=proba.Beta(1, 1, seed=42))
+reward_obj
+Type → proba.base.Distribution
+Default → None
A distribution to sample from.
+burn_in
+Default → 0
The number of steps to use for the burn-in phase. Each arm is given the chance to be pulled during the burn-in phase. This is useful to mitigate selection bias.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+ranking
+Return the list of arms in descending order of performance.
+import gym
+from river import bandit
+from river import proba
+from river import stats
+
+env = gym.make(
+ 'river_bandits/CandyCaneContest-v0'
+)
+_ = env.reset(seed=42)
+_ = env.action_space.seed(123)
+
+policy = bandit.ThompsonSampling(reward_obj=proba.Beta(), seed=101)
+
+metric = stats.Sum()
+while True:
+ arm = policy.pull(range(env.action_space.n))
+ observation, reward, terminated, truncated, info = env.step(arm)
+ policy = policy.update(arm, reward)
+ metric = metric.update(reward)
+ if terminated or truncated:
+ break
+
+metric
+Sum: 820.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+Returns
+ArmID: A single arm.
++
Update an arm's state.
+Parameters
++
Upper Confidence Bound (UCB) bandit policy.
+Due to the nature of this algorithm, it's recommended to scale the target so that it exhibits sub-gaussian properties. This can be done by passing a preprocessing.TargetStandardScaler instance to the reward_scaler argument.
delta
+Type → float
+The confidence level. Setting this to 1 leads to what is called the UCB1 policy.
+reward_obj
+Default → None
The reward object used to measure the performance of each arm. This can be a metric, a statistic, or a distribution.
+reward_scaler
+Default → None
A reward scaler used to scale the rewards before they are fed to the reward object. This can be useful to scale the rewards to a (0, 1) range for instance.
+burn_in
+Default → 0
The number of steps to use for the burn-in phase. Each arm is given the chance to be pulled during the burn-in phase. This is useful to mitigate selection bias.
+seed
+Type → int
+Default → None
Random number generator seed for reproducibility.
+ranking
+Return the list of arms in descending order of performance.
+import gym
+from river import bandit
+from river import preprocessing
+from river import stats
+
+env = gym.make(
+ 'river_bandits/CandyCaneContest-v0'
+)
+_ = env.reset(seed=42)
+_ = env.action_space.seed(123)
+
+policy = bandit.UCB(
+ delta=100,
+ reward_scaler=preprocessing.TargetStandardScaler(None),
+ seed=42
+)
+
+metric = stats.Sum()
+while True:
+ arm = policy.pull(range(env.action_space.n))
+ observation, reward, terminated, truncated, info = env.step(arm)
+ policy = policy.update(arm, reward)
+ metric = metric.update(reward)
+ if terminated or truncated:
+ break
+
+metric
+Sum: 744.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+Returns
+ArmID: A single arm.
++
Update an arm's state.
+Parameters
++
Contextual bandit policy base class.
+reward_obj
+Type → RewardObj | None
+Default → None
The reward object used to measure the performance of each arm. This can be a metric, a statistic, or a distribution.
+reward_scaler
+Type → compose.TargetTransformRegressor | None
+Default → None
A reward scaler used to scale the rewards before they are fed to the reward object. This can be useful to scale the rewards to a (0, 1) range for instance.
+burn_in
+Default → 0
The number of steps to use for the burn-in phase. Each arm is given the chance to be pulled during the burn-in phase. This is useful to mitigate selection bias.
+ranking
+Return the list of arms in descending order of performance.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+None Returns
+ArmID: A single arm.
++
Update an arm's state.
+Parameters
++ + + + + + + + +
Bandit policy base class.
+reward_obj
+Type → RewardObj | None
+Default → None
The reward object used to measure the performance of each arm. This can be a metric, a statistic, or a distribution.
+reward_scaler
+Type → compose.TargetTransformRegressor | None
+Default → None
A reward scaler used to scale the rewards before they are fed to the reward object. This can be useful to scale the rewards to a (0, 1) range for instance.
+burn_in
+Default → 0
The number of steps to use for the burn-in phase. Each arm is given the chance to be pulled during the burn-in phase. This is useful to mitigate selection bias.
+ranking
+Return the list of arms in descending order of performance.
+Pull arm(s).
+This method is a generator that yields the arm(s) that should be pulled. During the burn-in phase, all the arms that have not been pulled enough times are yielded. Once the burn-in phase is over, the policy is allowed to choose the arm(s) that should be pulled. If you only want to pull one arm at a time during the burn-in phase, simply call next(policy.pull(arms)).
Parameters
+Returns
+ArmID: A single arm.
++
Update an arm's state.
+Parameters
++ + + + + + + + +
Base class for bandit datasets.
+n_features
+Number of features in the dataset.
+n_samples
+Default → None
Number of samples in the dataset.
+n_classes
+Default → None
Number of classes in the dataset, only applies to classification datasets.
+n_outputs
+Default → None
Number of outputs the target is made of, only applies to multi-output datasets.
+sparse
+Default → False
Whether the dataset is sparse or not.
+arms
+The list of arms that can be pulled.
+desc
+Return the description from the docstring.
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
News articles bandit dataset.
+This is a personalization dataset. It contains 10000 observations. There are 10 arms, and the reward is binary. There are 100 features, which turns this into a contextual bandit problem.
+arms
+The list of arms that can be pulled.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+from river import bandit
+
+dataset = bandit.datasets.NewsArticles()
+context, arm, reward = next(iter(dataset))
+
+len(context)
+100
+arm, reward
+(2, False)
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Candy cane contest Kaggle competition.
+n_machines
+Default → 100
Number of vending machines.
+reward_decay
+Default → 0.03
The multiplicate rate at which the expected reward of each vending machine decays.
+np_random
+Returns the environment's internal :attr:_np_random that if not set will initialise with a random seed.
render_mode
+spec
+unwrapped
+Returns the base non-wrapped environment. Returns: Env: The base non-wrapped gym.Env instance
+import gym
+from river import stats
+
+env = gym.make('river_bandits/CandyCaneContest-v0')
+_ = env.reset(seed=42)
+_ = env.action_space.seed(123)
+
+metric = stats.Sum()
+while True:
+ arm = env.action_space.sample()
+ observation, reward, terminated, truncated, info = env.step(arm)
+ metric = metric.update(reward)
+ if terminated or truncated:
+ break
+
+metric
+Sum: 734.
+Override close in your subclass to perform any necessary cleanup.
+Environments will automatically :meth:close() themselves when garbage collected or when the program exits.
+
Compute the render frames as specified by render_mode attribute during initialization of the environment.
+The set of supported modes varies per environment. (And some third-party environments may not support rendering at all.) By convention, if render_mode is: - None (default): no render is computed. - human: render return None. The environment is continuously rendered in the current display or terminal. Usually for human consumption. - rgb_array: return a single frame representing the current state of the environment. A frame is a numpy.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image. - rgb_array_list: return a list of frames representing the states of the environment since the last reset. Each frame is a numpy.ndarray with shape (x, y, 3), as with rgb_array. - ansi: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors). Note: Make sure that your class's metadata 'render_modes' key includes the list of supported modes. It's recommended to call super() in implementations to use the functionality of this method.
+
Resets the environment to an initial state and returns the initial observation.
+This method can reset the environment's random number generator(s) if seed is an integer or if the environment has not yet initialized a random number generator. If the environment already has a random number generator and :meth:reset is called with seed=None, the RNG should not be reset. Moreover, :meth:reset should (in the typical use case) be called with an integer seed right after initialization and then never again. Args: seed (optional int): The seed that is used to initialize the environment's PRNG. If the environment does not already have a PRNG and seed=None (the default option) is passed, a seed will be chosen from some source of entropy (e.g. timestamp or /dev/urandom). However, if the environment already has a PRNG and seed=None is passed, the PRNG will not be reset. If you pass an integer, the PRNG will be reset even if it already exists. Usually, you want to pass an integer right after the environment has been initialized and then never again. Please refer to the minimal example above to see this paradigm in action. options (optional dict): Additional information to specify how the environment is reset (optional, depending on the specific environment) Returns: observation (object): Observation of the initial state. This will be an element of :attr:observation_space (typically a numpy array) and is analogous to the observation returned by :meth:step. info (dictionary): This dictionary contains auxiliary information complementing observation. It should be analogous to the info returned by :meth:step.
Parameters
+None None +
Run one timestep of the environment's dynamics.
+When end of episode is reached, you are responsible for calling :meth:reset to reset this environment's state. Accepts an action and returns either a tuple (observation, reward, terminated, truncated, info). Args: action (ActType): an action provided by the agent Returns: observation (object): this will be an element of the environment's :attr:observation_space. This may, for instance, be a numpy array containing the positions and velocities of certain objects. reward (float): The amount of reward returned as a result of taking the action. terminated (bool): whether a terminal state (as defined under the MDP of the task) is reached. In this case further step() calls could return undefined results. truncated (bool): whether a truncation condition outside the scope of the MDP is satisfied. Typically a timelimit, but could also be used to indicate agent physically going out of bounds. Can be used to end the episode prematurely before a terminal state is reached. info (dictionary): info contains auxiliary diagnostic information (helpful for debugging, learning, and logging). This might, for instance, contain: metrics that describe the agent's performance state, variables that are hidden from observations, or individual reward terms that are combined to produce the total reward. It also can contain information that distinguishes truncation and termination, however this is deprecated in favour of returning two booleans, and will be removed in a future version. (deprecated) done (bool): A boolean value for if the episode has ended, in which case further :meth:step calls will return undefined results. A done signal may be emitted for different reasons: Maybe the task underlying the environment was solved successfully, a certain timelimit was exceeded, or the physics simulation has entered an invalid state.
Parameters
++
k-armed testbed.
+This is a simple environment that can be used to test bandit algorithms. It is based on the 10 armed testbed described in the book "Reinforcement Learning: An Introduction" by Sutton and Barto.
+k
+Type → int
+Default → 10
Number of arms.
+np_random
+Returns the environment's internal :attr:_np_random that if not set will initialise with a random seed.
render_mode
+spec
+unwrapped
+Returns the base non-wrapped environment. Returns: Env: The base non-wrapped gym.Env instance
+Override close in your subclass to perform any necessary cleanup.
+Environments will automatically :meth:close() themselves when garbage collected or when the program exits.
+
Compute the render frames as specified by render_mode attribute during initialization of the environment.
+The set of supported modes varies per environment. (And some third-party environments may not support rendering at all.) By convention, if render_mode is: - None (default): no render is computed. - human: render return None. The environment is continuously rendered in the current display or terminal. Usually for human consumption. - rgb_array: return a single frame representing the current state of the environment. A frame is a numpy.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image. - rgb_array_list: return a list of frames representing the states of the environment since the last reset. Each frame is a numpy.ndarray with shape (x, y, 3), as with rgb_array. - ansi: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors). Note: Make sure that your class's metadata 'render_modes' key includes the list of supported modes. It's recommended to call super() in implementations to use the functionality of this method.
+
Resets the environment to an initial state and returns the initial observation.
+This method can reset the environment's random number generator(s) if seed is an integer or if the environment has not yet initialized a random number generator. If the environment already has a random number generator and :meth:reset is called with seed=None, the RNG should not be reset. Moreover, :meth:reset should (in the typical use case) be called with an integer seed right after initialization and then never again. Args: seed (optional int): The seed that is used to initialize the environment's PRNG. If the environment does not already have a PRNG and seed=None (the default option) is passed, a seed will be chosen from some source of entropy (e.g. timestamp or /dev/urandom). However, if the environment already has a PRNG and seed=None is passed, the PRNG will not be reset. If you pass an integer, the PRNG will be reset even if it already exists. Usually, you want to pass an integer right after the environment has been initialized and then never again. Please refer to the minimal example above to see this paradigm in action. options (optional dict): Additional information to specify how the environment is reset (optional, depending on the specific environment) Returns: observation (object): Observation of the initial state. This will be an element of :attr:observation_space (typically a numpy array) and is analogous to the observation returned by :meth:step. info (dictionary): This dictionary contains auxiliary information complementing observation. It should be analogous to the info returned by :meth:step.
Parameters
+None None +
Run one timestep of the environment's dynamics.
+When end of episode is reached, you are responsible for calling :meth:reset to reset this environment's state. Accepts an action and returns either a tuple (observation, reward, terminated, truncated, info). Args: action (ActType): an action provided by the agent Returns: observation (object): this will be an element of the environment's :attr:observation_space. This may, for instance, be a numpy array containing the positions and velocities of certain objects. reward (float): The amount of reward returned as a result of taking the action. terminated (bool): whether a terminal state (as defined under the MDP of the task) is reached. In this case further step() calls could return undefined results. truncated (bool): whether a truncation condition outside the scope of the MDP is satisfied. Typically a timelimit, but could also be used to indicate agent physically going out of bounds. Can be used to end the episode prematurely before a terminal state is reached. info (dictionary): info contains auxiliary diagnostic information (helpful for debugging, learning, and logging). This might, for instance, contain: metrics that describe the agent's performance state, variables that are hidden from observations, or individual reward terms that are combined to produce the total reward. It also can contain information that distinguishes truncation and termination, however this is deprecated in favour of returning two booleans, and will be removed in a future version. (deprecated) done (bool): A boolean value for if the episode has ended, in which case further :meth:step calls will return undefined results. A done signal may be emitted for different reasons: Maybe the task underlying the environment was solved successfully, a certain timelimit was exceeded, or the physics simulation has entered an invalid state.
Parameters
++ + + + + + + + +
Evaluate a policy on historical logs using replay.
+This is a high-level utility function for evaluating a policy using the replay methodology. This methodology is an off-policy evaluation method. It does not require an environment, and is instead data-driven.
+At each step, an arm is pulled from the provided policy. If the arm is the same as the arm that was pulled in the historical data, the reward is used to update the policy. If the arm is different, the reward is ignored. This is the off-policy aspect of the evaluation.
+policy
+Type → bandit.base.Policy
+The policy to evaluate.
+history
+Type → History | bandit.datasets.BanditDataset
+The history of the bandit problem. This is a generator that yields tuples of the form (arms, context, arm, reward).
reward_stat
+Type → stats.base.Univariate
+Default → None
The reward statistic to use. Defaults to stats.Sum.
import random
+from river import bandit
+
+rng = random.Random(42)
+arms = ['A', 'B', 'C']
+clicks = [
+ (
+ arms,
+ # no context
+ None,
+ # random arm
+ rng.choice(arms),
+ # reward
+ rng.random() > 0.5
+ )
+ for _ in range(1000)
+]
+
+total_reward, n_samples_used = bandit.evaluate_offline(
+ policy=bandit.EpsilonGreedy(0.1, seed=42),
+ history=clicks,
+)
+
+total_reward
+Sum: 172.
+n_samples_used
+321
+This also works out of the box with datasets that inherit from river.bandit.BanditDataset.
news = bandit.datasets.NewsArticles()
+total_reward, n_samples_used = bandit.evaluate_offline(
+ policy=bandit.RandomPolicy(seed=42),
+ history=news,
+)
+
+total_reward, n_samples_used
+(Sum: 105., 1027)
+As expected, the policy succeeds in roughly 10% of cases. Indeed, there are 10 arms and 10000 +samples, so the expected number of successes is 1000.
+ + + + + + + + + +Benchmark a list of policies on a given Gym environment.
+This is a high-level utility function for benchmarking a list of policies on a given Gym environment. For example, it can be used to populate a pandas.DataFrame with the contents of each step of each episode.
policies
+Type → list[bandit.base.Policy]
+A list of policies to evaluate. The policy will be reset before each episode.
+env
+Type → gym.Env
+The Gym environment to use. One copy will be made for each policy at the beginning of each episode.
+reward_stat
+Type → stats.base.Univariate | None
+Default → None
A univariate statistic to keep track of the rewards. This statistic will be reset before each episode. Note that this is not the same as the reward object used by the policies. It's just a statistic to keep track of each policy's performance. If None, stats.Sum is used.
n_episodes
+Type → int
+Default → 20
The number of episodes to run.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility. A random number generator will be used to seed differently the environment before each episode.
+import gym
+from river import bandit
+
+trace = bandit.evaluate(
+ policies=[
+ bandit.UCB(delta=1, seed=42),
+ bandit.EpsilonGreedy(epsilon=0.1, seed=42),
+ ],
+ env=gym.make(
+ 'river_bandits/CandyCaneContest-v0',
+ max_episode_steps=100
+ ),
+ n_episodes=5,
+ seed=42
+)
+
+for step in trace:
+ print(step)
+ break
+{'episode': 0, 'step': 0, 'policy_idx': 0, 'arm': 81, 'reward': 0.0, 'reward_stat': 0.0}
+The return type of this function is a generator. Each step of the generator is a dictionary.
+You can pass the generator to a pandas.DataFrame to get a nice representation of the results.
import pandas as pd
+
+trace = bandit.evaluate(
+ policies=[
+ bandit.UCB(delta=1, seed=42),
+ bandit.EpsilonGreedy(epsilon=0.1, seed=42),
+ ],
+ env=gym.make(
+ 'river_bandits/CandyCaneContest-v0',
+ max_episode_steps=100
+ ),
+ n_episodes=5,
+ seed=42
+)
+
+trace_df = pd.DataFrame(trace)
+trace_df.sample(5, random_state=42)
+ episode step policy_idx arm reward reward_stat
+521 2 60 1 25 0.0 36.0
+737 3 68 1 40 1.0 20.0
+740 3 70 0 58 0.0 36.0
+660 3 30 0 31 1.0 16.0
+411 2 5 1 35 1.0 5.0
+The length of the dataframe is the number of policies times the number of episodes times the +maximum number of steps per episode.
+len(trace_df)
+1000
+(
+ trace_df.policy_idx.nunique() *
+ trace_df.episode.nunique() *
+ trace_df.step.nunique()
+)
+1000
+Base class that is inherited by the majority of classes in River.
+This base class allows us to handle the following tasks in a uniform manner:
+Getting and setting parameters
+Displaying information
+Mutating/cloning
+Return a fresh estimator with the same parameters.
+The clone has the same parameters but has not been updated with any data. This works by looking at the parameters from the class signature. Each parameter is either - recursively cloned if its a class. - deep-copied via copy.deepcopy if not. If the calling object is stochastic (i.e. it accepts a seed parameter) and has not been seeded, then the clone will not be idempotent. Indeed, this method's purpose if simply to return a new instance with the same input parameters.
Parameters
+None False +
Modify attributes.
+This changes parameters inplace. Although you can change attributes yourself, this is the recommended way to proceed. By default, all attributes are immutable, meaning they shouldn't be mutated. Calling mutate on an immutable attribute raises a ValueError. Mutable attributes are specified via the _mutable_attributes property, and are thus specified on a per-estimator basis.
Parameters
++ + + + + + + + +
A binary drift detector that is also capable of issuing warnings.
+drift_detected
+Whether or not a drift is detected following the last update.
+warning_detected
+Whether or not a drift is detected following the last update.
+Update the detector with a single boolean input.
+Parameters
+Returns
+BinaryDriftDetector: self
++ + + + + + + + +
A drift detector for binary data.
+drift_detected
+Whether or not a drift is detected following the last update.
+Update the detector with a single boolean input.
+Parameters
+Returns
+BinaryDriftDetector: self
++ + + + + + + + +
A classifier.
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++ + + + + + + + +
A clustering model.
+Update the model with a set of features x.
Parameters
+Returns
+Clusterer: self
++
Predicts the cluster number for a set of features x.
Parameters
+Returns
+int: A cluster number.
++ + + + + + + + +
A drift detector that is also capable of issuing warnings.
+drift_detected
+Whether or not a drift is detected following the last update.
+warning_detected
+Whether or not a drift is detected following the last update.
+Update the detector with a single data point.
+Parameters
+Returns
+DriftDetector: self
++ + + + + + + + +
A drift detector.
+drift_detected
+Whether or not a drift is detected following the last update.
+Update the detector with a single data point.
+Parameters
+Returns
+DriftDetector: self
++ + + + + + + + +
An ensemble is a model which is composed of a list of models.
+models
+Type → Iterator[Estimator]
+S.append(value) -- append value to the end of the sequence
+Parameters
++
S.clear() -> None -- remove all items from S
++
S.count(value) -> integer -- return number of occurrences of value
+Parameters
++
S.extend(iterable) -- extend sequence by appending elements from the iterable
+Parameters
++
S.index(value, [start, [stop]]) -> integer -- return first index of value. Raises ValueError if the value is not present.
+Supporting start and stop arguments is optional, but recommended.
+Parameters
++
S.insert(index, value) -- insert value before index
+Parameters
++
S.pop([index]) -> item -- remove and return item at index (default last). Raise IndexError if list is empty or index is out of range.
+Parameters
+-1 +
S.remove(value) -- remove first occurrence of value. Raise ValueError if the value is not present.
+Parameters
++
S.reverse() -- reverse IN PLACE
++
A classifier that can operate on mini-batches.
+Update the model with a mini-batch of features X and boolean targets y.
Parameters
+Returns
+MiniBatchClassifier: self
++
Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+pd.Series: The predicted labels.
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the outcome probabilities for each given sample.
+Parameters
+Returns
+pd.DataFrame: A dataframe with probabilities of True and False for each sample.
+
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++ + + + + + + + +
A regressor that can operate on mini-batches.
+Update the model with a mini-batch of features X and real-valued targets y.
Parameters
+Returns
+MiniBatchRegressor: self
++
Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+pd.Series: The predicted outcomes.
++
Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++ + + + + + + + +
A supervised transformer that can operate on mini-batches.
+Update the model with a mini-batch of features X and targets y.
Parameters
+Returns
+MiniBatchSupervisedTransformer: self
++
Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a mini-batch of features.
+Parameters
+Returns
+pd.DataFrame: A new DataFrame.
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
A transform that can operate on mini-batches.
+Update with a mini-batch of features.
+A lot of transformers don't actually have to do anything during the learn_many step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_many can override this method.
Parameters
+Returns
+Transformer: self
++
Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a mini-batch of features.
+Parameters
+Returns
+pd.DataFrame: A new DataFrame.
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Multi-label classifier.
+Update the model with a set of features x and the labels y.
Parameters
+Returns
+MultiLabelClassifier: self
++
Predict the labels of a set of features x.
Parameters
+Returns
+dict[FeatureName, bool]: The predicted labels.
++
Predict the probability of each label appearing given dictionary of features x.
Parameters
+Returns
+dict[FeatureName, dict[bool, float]]: A dictionary that associates a probability which each label.
++ + + + + + + + +
Multi-target regressor.
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+MultiTargetRegressor: self
++
Predict the outputs of features x.
Parameters
+Returns
+dict[FeatureName, RegTarget]: The predictions.
++ + + + + + + + +
A regressor.
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++ + + + + + + + +
A supervised transformer.
+Update with a set of features x and a target y.
Parameters
+Returns
+SupervisedTransformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
A transformer.
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
A wrapper model.
+ + + + + + + + +A wrapper ensemble is an ensemble composed of multiple copies of the same model.
+model
+The model to copy.
+n_models
+The number of copies to make.
+seed
+Random number generator seed for reproducibility.
+CluStream
+The CluStream algorithm 1 maintains statistical information about the data using micro-clusters. These micro-clusters are temporal extensions of cluster feature vectors. The micro-clusters are stored at snapshots in time following a pyramidal pattern. This pattern allows to recall summary statistics from different time horizons.
+Training with a new point p is performed in two main tasks:
Determinate the closest micro-cluster to p.
Check whether p fits (memory) into the closest micro-cluster:
if p fits, put into micro-cluster
if p does not fit, free some space to insert a new micro-cluster.
This is done in two ways, delete an old micro-cluster or merge the two micro-clusters closest to each other.
+This implementation is an improved version from the original algorithm. Instead of calculating the traditional cluster feature vector of the number of observations, linear sum and sum of squares of data points and time stamps, this implementation adopts the use of Welford's algorithm 2 to calculate the incremental variance, facilitated through stats.Var available within River.
Since River does not support an actual "off-line" phase of the clustering algorithm (as data points are assumed to arrive continuously, one at a time), a time_gap parameter is introduced. After each time_gap, an incremental K-Means clustering algorithm will be initialized and applied on currently available micro-clusters to form the final solution, i.e. macro-clusters.
n_macro_clusters
+Type → int
+Default → 5
The number of clusters (k) for the k-means algorithm.
+max_micro_clusters
+Type → int
+Default → 100
The maximum number of micro-clusters to use.
+micro_cluster_r_factor
+Type → int
+Default → 2
Multiplier for the micro-cluster radius. When deciding to add a new data point to a micro-cluster, the maximum boundary is defined as a factor of the micro_cluster_r_factor of the RMS deviation of the data points in the micro-cluster from the centroid.
time_window
+Type → int
+Default → 1000
If the current time is T and the time window is h, we only consider the data that arrived within the period (T-h,T).
time_gap
+Type → int
+Default → 100
An incremental k-means is applied on the current set of micro-clusters after each time_gap to form the final macro-cluster solution.
seed
+Type → int | None
+Default → None
Random seed used for generating initial centroid positions.
+kwargs
+Other parameters passed to the incremental kmeans at cluster.KMeans.
centers (dict)
+Central positions of each cluster.
+In the following example, max_micro_clusters is set relatively low due to the
+limited number of training points. Moreover, all points are learnt before any predictions are made.
+The halflife is set at 0.4, to show that you can pass cluster.KMeans parameters via keyword arguments.
from river import cluster
+from river import stream
+
+X = [
+ [1, 2],
+ [1, 4],
+ [1, 0],
+ [-4, 2],
+ [-4, 4],
+ [-4, 0],
+ [5, 0],
+ [5, 2],
+ [5, 4]
+]
+
+clustream = cluster.CluStream(
+ n_macro_clusters=3,
+ max_micro_clusters=5,
+ time_gap=3,
+ seed=0,
+ halflife=0.4
+)
+
+for x, _ in stream.iter_array(X):
+ clustream = clustream.learn_one(x)
+
+clustream.predict_one({0: 1, 1: 1})
+1
+clustream.predict_one({0: -4, 1: 3})
+2
+clustream.predict_one({0: 4, 1: 3.5})
+0
+Update the model with a set of features x.
Parameters
+1.0 Returns
+Clusterer: self
++
Predicts the cluster number for a set of features x.
Parameters
+Returns
+int: A cluster number.
++
Aggarwal, C.C., Philip, S.Y., Han, J. and Wang, J., 2003, A framework for clustering evolving data +streams. In Proceedings 2003 VLDB conference (pp. 81-92). Morgan Kaufmann. ↩
+Chan, T.F., Golub, G.H. and LeVeque, R.J., 1982. Updating formulae and a pairwise algorithm for +computing sample variances. In COMPSTAT 1982 5th Symposium held at Toulouse 1982 (pp. 30-41). +Physica, Heidelberg. https://doi.org/10.1007/978-3-642-51461-6_3. ↩
+DBSTREAM
+DBSTREAM 1 is a clustering algorithm for evolving data streams. It is the first micro-cluster-based online clustering component that explicitely captures the density between micro-clusters via a shared density graph. The density information in the graph is then exploited for reclustering based on actual density between adjacent micro clusters.
+The algorithm is divided into two parts:
+Online micro-cluster maintenance (learning)
+For a new point p:
Find all micro clusters for which p falls within the fixed radius (clustering threshold). If no neighbor is found, a new micro cluster with a weight of 1 is created for p.
If no neighbor is found, a new micro cluster with a weight of 1 is created for p. If one or more neighbors of p are found, we update the micro clusters by applying the appropriate fading, increasing their weight and then we try to move them closer to p using the Gaussian neighborhood function.
Next, the shared density graph is updated. To prevent collapsing micro clusters, we will restrict the movement for micro clusters in case they come closer than \(r\) (clustering threshold) to each other. Finishing this process, the time stamp is also increased by 1.
+Finally, the cleanup will be processed. It is executed every t_gap time steps, removing weak micro clusters and weak entries in the shared density graph to recover memory and improve the clustering algorithm's processing speed.
Offline generation of macro clusters (clustering)
+The offline generation of macro clusters is generated through the two following steps:
+The connectivity graph C is constructed using shared density entries between strong micro clusters. The edges in this connectivity graph with a connectivity value greater than the intersection threshold (\(\alpha\)) are used to find connected components representing the final cluster.
After the connectivity graph is generated, a variant of the DBSCAN algorithm proposed by Ester et al. is applied to form all macro clusters from \(\alpha\)-connected micro clusters.
+clustering_threshold
+Type → float
+Default → 1.0
DBStream represents each micro cluster by a leader (a data point defining the micro cluster's center) and the density in an area of a user-specified radius \(r\) (clustering_threshold) around the center.
fading_factor
+Type → float
+Default → 0.01
Parameter that controls the importance of historical data to current cluster. Note that fading_factor has to be different from 0.
cleanup_interval
+Type → float
+Default → 2
The time interval between two consecutive time points when the cleanup process is conducted.
+intersection_factor
+Type → float
+Default → 0.3
The intersection factor related to the area of the overlap of the micro clusters relative to the area cover by micro clusters. This parameter is used to determine whether a micro cluster or a shared density is weak.
+minimum_weight
+Type → float
+Default → 1.0
The minimum weight for a cluster to be not "noisy".
+n_clusters
+Number of clusters generated by the algorithm.
+clusters
+A set of final clusters of type DBStreamMicroCluster. However, these are either micro clusters, or macro clusters that are generated by merging all \(\alpha\)-connected micro clusters. This set is generated through the offline phase of the algorithm.
centers
+Final clusters' centers.
+micro_clusters
+Micro clusters generated by the algorithm. Instead of updating directly the new instance points into a nearest micro cluster, through each iteration, the weight and center will be modified so that the clusters are closer to the new points, using the Gaussian neighborhood function.
+from river import cluster
+from river import stream
+
+X = [
+ [1, 0.5], [1, 0.625], [1, 0.75], [1, 1.125], [1, 1.5], [1, 1.75],
+ [4, 1.5], [4, 2.25], [4, 2.5], [4, 3], [4, 3.25], [4, 3.5]
+]
+
+dbstream = cluster.DBSTREAM(
+ clustering_threshold=1.5,
+ fading_factor=0.05,
+ cleanup_interval=4,
+ intersection_factor=0.5,
+ minimum_weight=1
+)
+
+for x, _ in stream.iter_array(X):
+ dbstream = dbstream.learn_one(x)
+
+dbstream.predict_one({0: 1, 1: 2})
+0
+dbstream.predict_one({0: 5, 1: 2})
+1
+dbstream._n_clusters
+2
+Update the model with a set of features x.
Parameters
+None Returns
+Clusterer: self
++
Predicts the cluster number for a set of features x.
Parameters
+None Returns
+int: A cluster number.
++
Michael Hahsler and Matthew Bolanos (2016, pp 1449-1461). Clustering Data Streams Based on + Shared Density between Micro-Clusters, IEEE Transactions on Knowledge and Data Engineering 28(6) . + In Proceedings of the Sixth SIAM International Conference on Data Mining, + April 20–22, 2006, Bethesda, MD, USA. ↩
+Ester et al (1996). A Density-Based Algorithm for Discovering Clusters in Large Spatial Databases + with Noise. In KDD-96 Proceedings, AAAI. ↩
+DenStream
+DenStream 1 is a clustering algorithm for evolving data streams. DenStream can discover clusters with arbitrary shape and is robust against noise (outliers).
+"Dense" micro-clusters (named core-micro-clusters) summarise the clusters of arbitrary shape. A pruning strategy based on the concepts of potential and outlier micro-clusters guarantees the precision of the weights of the micro-clusters with limited memory.
+The algorithm is divided into two parts:
+Online micro-cluster maintenance (learning)
+For a new point p:
Try to merge p into either the nearest p-micro-cluster (potential), o-micro-cluster (outlier), or create a new o-micro-cluster and insert it into the outlier buffer.
For each T_p iterations, consider the weights of all potential and outlier micro-clusters. If their weights are smaller than a certain threshold (different for each type of micro-clusters), the micro-cluster is deleted.
Offline generation of clusters on-demand (clustering)
+A variant of the DBSCAN algorithm 2 is used, such that all density-connected p-micro-clusters determine the final clusters. Moreover, in order for the algorithm to always be able to generate clusters, a certain number of points must be passed through the algorithm with a suitable streaming speed (number of points passed through within a unit time), indicated by n_samples_init and stream_speed.
decaying_factor
+Type → float
+Default → 0.25
Parameter that controls the importance of historical data to current cluster. Note that decaying_factor has to be different from 0.
beta
+Type → float
+Default → 0.75
Parameter to determine the threshold of outlier relative to core micro-clusters. The value of beta must be within the range (0,1].
mu
+Type → float
+Default → 2
Parameter to determine the threshold of outliers relative to core micro-cluster. As beta * mu must be greater than 1, mu must be within the range (1/beta, inf).
epsilon
+Type → float
+Default → 0.02
Defines the epsilon neighborhood
+n_samples_init
+Type → int
+Default → 1000
Number of points to to initiqalize the online process
+stream_speed
+Type → int
+Default → 100
Number of points arrived in unit time
+n_clusters
+Number of clusters generated by the algorithm.
+clusters
+A set of final clusters of type MicroCluster, which means that these cluster include all the required information, including number of points, creation time, weight, (weighted) linear sum, (weighted) square sum, center and radius.
p_micro_clusters
+The potential core-icro-clusters that are generated by the algorithm. When a generate cluster request arrives, these p-micro-clusters will go through a variant of the DBSCAN algorithm to determine the final clusters.
+o_micro_clusters
+The outlier micro-clusters.
+The following example uses the default parameters of the algorithm to test its functionality.
+The set of evolving points X are designed so that clusters are easily identifiable.
from river import cluster
+from river import stream
+
+X = [
+ [-1, -0.5], [-1, -0.625], [-1, -0.75], [-1, -1], [-1, -1.125],
+ [-1, -1.25], [-1.5, -0.5], [-1.5, -0.625], [-1.5, -0.75], [-1.5, -1],
+ [-1.5, -1.125], [-1.5, -1.25], [1, 1.5], [1, 1.75], [1, 2],
+ [4, 1.25], [4, 1.5], [4, 2.25], [4, 2.5], [4, 3],
+ [4, 3.25], [4, 3.5], [4, 3.75], [4, 4],
+]
+
+denstream = cluster.DenStream(decaying_factor=0.01,
+ beta=0.5,
+ mu=2.5,
+ epsilon=0.5,
+ n_samples_init=10)
+
+for x, _ in stream.iter_array(X):
+ denstream = denstream.learn_one(x)
+
+denstream.predict_one({0: -1, 1: -2})
+0
+denstream.predict_one({0: 5, 1: 4})
+1
+denstream.predict_one({0: 1, 1: 1})
+0
+denstream.n_clusters
+2
+Update the model with a set of features x.
Parameters
+None Returns
+Clusterer: self
++
Predicts the cluster number for a set of features x.
Parameters
+None Returns
+int: A cluster number.
++
Feng et al (2006, pp 328-339). Density-Based Clustering over an Evolving Data Stream with + Noise. In Proceedings of the Sixth SIAM International Conference on Data Mining, + April 20–22, 2006, Bethesda, MD, USA. ↩
+Ester et al (1996). A Density-Based Algorithm for Discovering Clusters in Large Spatial + Databases with Noise. In KDD-96 Proceedings, AAAI. ↩
+Incremental k-means.
+The most common way to implement batch k-means is to use Lloyd's algorithm, which consists in assigning all the data points to a set of cluster centers and then moving the centers accordingly. This requires multiple passes over the data and thus isn't applicable in a streaming setting.
+In this implementation we start by finding the cluster that is closest to the current observation. We then move the cluster's central position towards the new observation. The halflife parameter determines by how much to move the cluster toward the new observation. You will get better results if you scale your data appropriately.
n_clusters
+Default → 5
Maximum number of clusters to assign.
+halflife
+Default → 0.5
Amount by which to move the cluster centers, a reasonable value if between 0 and 1.
+mu
+Default → 0
Mean of the normal distribution used to instantiate cluster positions.
+sigma
+Default → 1
Standard deviation of the normal distribution used to instantiate cluster positions.
+p
+Default → 2
Power parameter for the Minkowski metric. When p=1, this corresponds to the Manhattan distance, while p=2 corresponds to the Euclidean distance.
seed
+Type → int | None
+Default → None
Random seed used for generating initial centroid positions.
+centers (dict)
+Central positions of each cluster.
+In the following example the cluster assignments are exactly the same as when using
+sklearn's batch implementation. However changing the halflife parameter will
+produce different outputs.
from river import cluster
+from river import stream
+
+X = [
+ [1, 2],
+ [1, 4],
+ [1, 0],
+ [-4, 2],
+ [-4, 4],
+ [-4, 0]
+]
+
+k_means = cluster.KMeans(n_clusters=2, halflife=0.1, sigma=3, seed=42)
+
+for i, (x, _) in enumerate(stream.iter_array(X)):
+ k_means = k_means.learn_one(x)
+ print(f'{X[i]} is assigned to cluster {k_means.predict_one(x)}')
+[1, 2] is assigned to cluster 1
+[1, 4] is assigned to cluster 1
+[1, 0] is assigned to cluster 0
+[-4, 2] is assigned to cluster 1
+[-4, 4] is assigned to cluster 1
+[-4, 0] is assigned to cluster 0
+k_means.predict_one({0: 0, 1: 0})
+0
+k_means.predict_one({0: 4, 1: 4})
+1
+Update the model with a set of features x.
Parameters
+Returns
+Clusterer: self
++
Equivalent to k_means.learn_one(x).predict_one(x), but faster.
Parameters
++
Predicts the cluster number for a set of features x.
Parameters
+Returns
+int: A cluster number.
++ + + + + + + + + +
STREAMKMeans
+STREAMKMeans is an alternative version of the original algorithm STREAMLSEARCH proposed by O'Callaghan et al. 1, by replacing the k-medians using LSEARCH by the k-means algorithm.
However, instead of using the traditional k-means, which requires a total reclustering each time the temporary chunk of data points is full, the implementation of this algorithm uses an increamental k-means.
+At first, the cluster centers are initialized with a KMeans instance. For a new point p:
If the size of chunk is less than the maximum size allowed, add the new point to the temporary chunk.
+When the size of chunk reaches the maximum value size allowed
+KMeans instance is created. The latter will process all points in thetemporary chunk. The centers of this new instance then become the new centers.
+When a prediction request arrives, the centers of the algorithm will be exactly the same as the centers of the original KMeans at the time of retrieval.
chunk_size
+Default → 10
Maximum size allowed for the temporary data chunk.
+n_clusters
+Default → 2
Number of clusters generated by the algorithm.
+kwargs
+Other parameters passed to the incremental kmeans at cluster.KMeans.
centers
+Cluster centers generated from running the incremental KMeans algorithm through centers of each chunk.
from river import cluster
+from river import stream
+
+X = [
+ [1, 0.5], [1, 0.625], [1, 0.75], [1, 1.125], [1, 1.5], [1, 1.75],
+ [4, 1.5], [4, 2.25], [4, 2.5], [4, 3], [4, 3.25], [4, 3.5]
+]
+
+streamkmeans = cluster.STREAMKMeans(chunk_size=3, n_clusters=2, halflife=0.5, sigma=1.5, seed=0)
+
+for x, _ in stream.iter_array(X):
+ streamkmeans = streamkmeans.learn_one(x)
+
+streamkmeans.predict_one({0: 1, 1: 0})
+0
+streamkmeans.predict_one({0: 5, 1: 2})
+1
+Update the model with a set of features x.
Parameters
+None Returns
+Clusterer: self
++
Predicts the cluster number for a set of features x.
Parameters
+None Returns
+int: A cluster number.
++
O'Callaghan et al. (2002). Streaming-data algorithms for high-quality clustering. + In Proceedings 18th International Conference on Data Engineering, Feb 26 - March 1, + San Jose, CA, USA. DOI: 10.1109/ICDE.2002.994785. ↩
+textClust, a clustering algorithm for text data.
+textClust 12 is a stream clustering algorithm for textual data that can identify and track topics over time in a stream of texts. The algorithm uses a widely popular two-phase clustering approach where the stream is first summarised in real-time.
+The result is many small preliminary clusters in the stream called micro-clusters. Micro-clusters maintain enough information to update and efficiently calculate the cosine similarity between them over time, based on the TF-IDF vector of their texts. Upon request, the miro-clusters can be reclustered to generate the final result using any distance-based clustering algorithm, such as hierarchical clustering. To keep the micro-clusters up-to-date, our algorithm applies a fading strategy where micro-clusters that are not updated regularly lose relevance and are eventually removed.
radius
+Default → 0.3
Distance threshold to merge two micro-clusters. Must be within the range (0, 1]
fading_factor
+Default → 0.0005
Fading factor of micro-clusters
+tgap
+Default → 100
Time between outlier removal
+term_fading
+Default → True
Determines whether individual terms should also be faded
+real_time_fading
+Default → True
Parameter that specifies whether natural time or the number of observations should be used for fading
+micro_distance
+Default → tfidf_cosine_distance
Distance metric used for clustering macro-clusters
+macro_distance
+Default → tfidf_cosine_distance
Distance metric used for clustering macro-clusters
+num_macro
+Default → 3
Number of macro clusters that should be identified during the reclustering phase
+min_weight
+Default → 0
Minimum weight of micro clusters to be used for reclustering
+auto_r
+Default → False
Parameter that specifies if radius should be automatically updated
auto_merge
+Default → True
Determines, if close observations shall be merged together
+sigma
+Default → 1
Parameter that influences the automated trheshold adaption technique
+micro_clusters
+Micro-clusters generated by the algorithm. Micro-clusters are of type textclust.microcluster
from river import compose
+from river import feature_extraction
+from river import metrics
+from river import cluster
+
+corpus = [
+ {"text":'This is the first document.',"idd":1, "cluster": 1, "cluster":1},
+ {"text":'This document is the second document.',"idd":2,"cluster": 1},
+ {"text":'And this is super unrelated.',"idd":3,"cluster": 2},
+ {"text":'Is this the first document?',"idd":4,"cluster": 1},
+ {"text":'This is super unrelated as well',"idd":5,"cluster": 2},
+ {"text":'Test text',"idd":6,"cluster": 5}
+]
+
+stopwords = [ 'stop', 'the', 'to', 'and', 'a', 'in', 'it', 'is', 'I']
+
+metric = metrics.AdjustedRand()
+
+model = compose.Pipeline(
+ feature_extraction.BagOfWords(lowercase=True, ngram_range=(1, 2), stop_words=stopwords),
+ cluster.TextClust(real_time_fading=False, fading_factor=0.001, tgap=100, auto_r=True,
+ radius=0.9)
+)
+
+for x in corpus:
+ y_pred = model.predict_one(x["text"])
+ y = x["cluster"]
+ metric = metric.update(y,y_pred)
+ model = model.learn_one(x["text"])
+
+print(metric)
+AdjustedRand: -0.17647058823529413
+Update the model with a set of features x.
Parameters
+None None Returns
+Clusterer: self
++
Predicts the cluster number for a set of features x.
Parameters
+None micro Returns
+int: A cluster number.
++
Assenmacher, D. und Trautmann, H. (2022). Textual One-Pass Stream Clustering with +Automated Distance Threshold Adaption. In: Asian Conference on Intelligent Information and +Database Systems (Accepted) ↩
+Carnein, M., Assenmacher, D., Trautmann, H. (2017). Stream Clustering of Chat Messages with +Applications to Twitch Streams. In: Advances in Conceptual Modeling. ER 2017. ↩
+Compatibility layer from River to scikit-learn for classification.
+river_estimator
+Type → base.Classifier
+Fits to an entire dataset contained in memory.
+Parameters
+Returns
+self
++
Get metadata routing of this object.
+Please check :ref:User Guide <metadata_routing> on how the routing mechanism works.
Returns
+MetadataRequest
++
Get parameters for this estimator.
+Parameters
+True Returns
+dict
++
Fits incrementally on a portion of a dataset.
+Parameters
+None Returns
+self
++
Predicts the target of an entire dataset contained in memory.
+Parameters
+Returns
+Predicted target values for each row of X.
+
Predicts the target probability of an entire dataset contained in memory.
+Parameters
+Returns
+Predicted target values for each row of X.
+
Return the mean accuracy on the given test data and labels.
+In multi-label classification, this is the subset accuracy which is a harsh metric since you require for each sample that each label set be correctly predicted.
+Parameters
+None Returns
+float
++
Set the parameters of this estimator.
+The method works on simple estimators as well as on nested objects (such as :class:~sklearn.pipeline.Pipeline). The latter have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.
Parameters
+Returns
+estimator instance
++
Request metadata passed to the partial_fit method.
Note that this method is only relevant if enable_metadata_routing=True (see :func:sklearn.set_config). Please see :ref:User Guide <metadata_routing> on how the routing mechanism works. The options for each parameter are: - True: metadata is requested, and passed to partial_fit if provided. The request is ignored if metadata is not provided. - False: metadata is not requested and the meta-estimator will not pass it to partial_fit. - None: metadata is not requested, and the meta-estimator will raise an error if the user provides it. - str: metadata should be passed to the meta-estimator with this given alias instead of the original name. The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others. .. versionadded:: 1.3 .. note:: This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a :class:pipeline.Pipeline. Otherwise it has no effect.
Parameters
+$UNCHANGED$ Returns
+River2SKLClassifier: object
++
Request metadata passed to the score method.
Note that this method is only relevant if enable_metadata_routing=True (see :func:sklearn.set_config). Please see :ref:User Guide <metadata_routing> on how the routing mechanism works. The options for each parameter are: - True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided. - False: metadata is not requested and the meta-estimator will not pass it to score. - None: metadata is not requested, and the meta-estimator will raise an error if the user provides it. - str: metadata should be passed to the meta-estimator with this given alias instead of the original name. The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others. .. versionadded:: 1.3 .. note:: This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a :class:pipeline.Pipeline. Otherwise it has no effect.
Parameters
+$UNCHANGED$ Returns
+River2SKLClassifier: object
++ + + + + + + + +
Compatibility layer from River to scikit-learn for clustering.
+river_estimator
+Type → base.Clusterer
+Fits to an entire dataset contained in memory.
+Parameters
+None Returns
+self
++
Perform clustering on X and returns cluster labels.
Parameters
+None Returns
+ndarray of shape (n_samples,), dtype=np.int64
++
Get metadata routing of this object.
+Please check :ref:User Guide <metadata_routing> on how the routing mechanism works.
Returns
+MetadataRequest
++
Get parameters for this estimator.
+Parameters
+True Returns
+dict
++
Fits incrementally on a portion of a dataset.
+Parameters
+Returns
+self
++
Predicts the target of an entire dataset contained in memory.
+Parameters
+Returns
+Transformed output.
++
Set the parameters of this estimator.
+The method works on simple estimators as well as on nested objects (such as :class:~sklearn.pipeline.Pipeline). The latter have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.
Parameters
+Returns
+estimator instance
++ + + + + + + + +
Compatibility layer from River to scikit-learn for regression.
+river_estimator
+Type → base.Regressor
+Fits to an entire dataset contained in memory.
+Parameters
+Returns
+self
++
Get metadata routing of this object.
+Please check :ref:User Guide <metadata_routing> on how the routing mechanism works.
Returns
+MetadataRequest
++
Get parameters for this estimator.
+Parameters
+True Returns
+dict
++
Fits incrementally on a portion of a dataset.
+Parameters
+Returns
+self
++
Predicts the target of an entire dataset contained in memory.
+Parameters
+Returns
+np.ndarray: Predicted target values for each row of X.
+
Return the coefficient of determination of the prediction.
+The coefficient of determination :math:R^2 is defined as :math:(1 - \frac{u}{v}), where :math:u is the residual sum of squares ((y_true - y_pred)** 2).sum() and :math:v is the total sum of squares ((y_true - y_true.mean()) ** 2).sum(). The best possible score is 1.0 and it can be negative (because the model can be arbitrarily worse). A constant model that always predicts the expected value of y, disregarding the input features, would get a :math:R^2 score of 0.0.
Parameters
+None Returns
+float
++
Set the parameters of this estimator.
+The method works on simple estimators as well as on nested objects (such as :class:~sklearn.pipeline.Pipeline). The latter have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.
Parameters
+Returns
+estimator instance
++
Request metadata passed to the score method.
Note that this method is only relevant if enable_metadata_routing=True (see :func:sklearn.set_config). Please see :ref:User Guide <metadata_routing> on how the routing mechanism works. The options for each parameter are: - True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided. - False: metadata is not requested and the meta-estimator will not pass it to score. - None: metadata is not requested, and the meta-estimator will raise an error if the user provides it. - str: metadata should be passed to the meta-estimator with this given alias instead of the original name. The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others. .. versionadded:: 1.3 .. note:: This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a :class:pipeline.Pipeline. Otherwise it has no effect.
Parameters
+$UNCHANGED$ Returns
+River2SKLRegressor: object
++ + + + + + + + +
Compatibility layer from River to scikit-learn for transformation.
+river_estimator
+Type → base.Transformer
+Fits to an entire dataset contained in memory.
+Parameters
+None Returns
+self
++
Fit to data, then transform it.
+Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
Parameters
+None Returns
+ndarray array of shape (n_samples, n_features_new)
++
Get metadata routing of this object.
+Please check :ref:User Guide <metadata_routing> on how the routing mechanism works.
Returns
+MetadataRequest
++
Get parameters for this estimator.
+Parameters
+True Returns
+dict
++
Fits incrementally on a portion of a dataset.
+Parameters
+None Returns
+self
++
Set output container.
+See :ref:sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an example on how to use the API.
Parameters
+None Returns
+estimator instance
++
Set the parameters of this estimator.
+The method works on simple estimators as well as on nested objects (such as :class:~sklearn.pipeline.Pipeline). The latter have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.
Parameters
+Returns
+estimator instance
++
Predicts the target of an entire dataset contained in memory.
+Parameters
+Returns
+Transformed output.
++ + + + + + + + +
Compatibility layer from scikit-learn to River for classification.
+estimator
+Type → sklearn_base.ClassifierMixin
+A scikit-learn regressor which has a partial_fit method.
classes
+Type → list
+from river import compat
+from river import evaluate
+from river import metrics
+from river import preprocessing
+from river import stream
+from sklearn import linear_model
+from sklearn import datasets
+
+dataset = stream.iter_sklearn_dataset(
+ dataset=datasets.load_breast_cancer(),
+ shuffle=True,
+ seed=42
+)
+
+model = preprocessing.StandardScaler()
+model |= compat.convert_sklearn_to_river(
+ estimator=linear_model.SGDClassifier(
+ loss='log_loss',
+ eta0=0.01,
+ learning_rate='constant'
+ ),
+ classes=[False, True]
+)
+
+metric = metrics.LogLoss()
+
+evaluate.progressive_val_score(dataset, model, metric)
+LogLoss: 0.198029
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Compatibility layer from scikit-learn to River for regression.
+estimator
+Type → sklearn_base.BaseEstimator
+A scikit-learn transformer which has a partial_fit method.
from river import compat
+from river import evaluate
+from river import metrics
+from river import preprocessing
+from river import stream
+from sklearn import linear_model
+from sklearn import datasets
+
+dataset = stream.iter_sklearn_dataset(
+ dataset=datasets.load_diabetes(),
+ shuffle=True,
+ seed=42
+)
+
+scaler = preprocessing.StandardScaler()
+sgd_reg = compat.convert_sklearn_to_river(linear_model.SGDRegressor())
+model = scaler | sgd_reg
+
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 84.501421
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Wraps a river estimator to make it compatible with scikit-learn.
+estimator
+Type → base.Estimator
+Removes features.
+This can be used in a pipeline when you want to remove certain features. The transform_one method is pure, and therefore returns a fresh new dictionary instead of removing the specified keys from the input.
keys
+Type → tuple[base.typing.FeatureName]
+Key(s) to discard.
+from river import compose
+
+x = {'a': 42, 'b': 12, 'c': 13}
+compose.Discard('a', 'b').transform_one(x)
+{'c': 13}
+You can chain a discarder with any estimator in order to apply said estimator to the +desired features.
+from river import feature_extraction as fx
+
+x = {'sales': 10, 'shop': 'Ikea', 'country': 'Sweden'}
+
+pipeline = (
+ compose.Discard('shop', 'country') |
+ fx.PolynomialExtender()
+)
+pipeline.transform_one(x)
+{'sales': 10, 'sales*sales': 100}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Wraps a function to make it usable in a pipeline.
+There is often a need to apply an arbitrary transformation to a set of features. For instance, this could involve parsing a date and then extracting the hour from said date. If you're processing a stream of data, then you can do this yourself by calling the necessary code at your leisure. On the other hand, if you want to do this as part of a pipeline, then you need to follow a simple convention.
+To use a function as part of a pipeline, take as input a dict of features and output a dict. Once you have initialized this class with your function, then you can use it like you would use any other (unsupervised) transformer.
It is up to you if you want your function to be pure or not. By pure we refer to a function that doesn't modify its input. However, we recommend writing pure functions because this reduces the chances of inserting bugs into your pipeline.
+func
+Type → typing.Callable[[dict], dict]
+A function that takes as input a dict and outputs a dict.
from pprint import pprint
+import datetime as dt
+from river import compose
+
+x = {'date': '2019-02-14'}
+
+def parse_date(x):
+ date = dt.datetime.strptime(x['date'], '%Y-%m-%d')
+ x['is_weekend'] = date.day in (5, 6)
+ x['hour'] = date.hour
+ return x
+
+t = compose.FuncTransformer(parse_date)
+pprint(t.transform_one(x))
+{'date': '2019-02-14', 'hour': 0, 'is_weekend': False}
+The above example is not pure because it modifies the input. The following example is pure +and produces the same output:
+def parse_date(x):
+ date = dt.datetime.strptime(x['date'], '%Y-%m-%d')
+ return {'is_weekend': date.day in (5, 6), 'hour': date.hour}
+
+t = compose.FuncTransformer(parse_date)
+pprint(t.transform_one(x))
+{'hour': 0, 'is_weekend': False}
+The previous example doesn't include the date feature because it returns a new dict.
+However, a common usecase is to add a feature to an existing set of features. You can do
+this in a pure way by unpacking the input dict into the output dict:
def parse_date(x):
+ date = dt.datetime.strptime(x['date'], '%Y-%m-%d')
+ return {'is_weekend': date.day in (5, 6), 'hour': date.hour, **x}
+
+t = compose.FuncTransformer(parse_date)
+pprint(t.transform_one(x))
+{'date': '2019-02-14', 'hour': 0, 'is_weekend': False}
+You can add FuncTransformer to a pipeline just like you would with any other transformer.
from river import naive_bayes
+
+pipeline = compose.FuncTransformer(parse_date) | naive_bayes.MultinomialNB()
+pipeline
+Pipeline (
+ FuncTransformer (
+ func="parse_date"
+ ),
+ MultinomialNB (
+ alpha=1.
+ )
+)
+If you provide a function without wrapping it, then the pipeline will do it for you:
+pipeline = parse_date | naive_bayes.MultinomialNB()
+Update with a mini-batch of features.
+A lot of transformers don't actually have to do anything during the learn_many step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_many can override this method.
Parameters
+Returns
+Transformer: self
++
Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a mini-batch of features.
+Parameters
+Returns
+pd.DataFrame: A new DataFrame.
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Applies a transformer within different groups.
+This transformer allows you to split your data into groups and apply a transformer within each group. This happens in a streaming manner, which means that the groups are discovered online. A separate copy of the provided transformer is made whenever a new group appears. The groups are defined according to one or more keys.
+transformer
+Type → base.Transformer
+by
+Type → base.typing.FeatureName | list[base.typing.FeatureName]
+The field on which to group the data. This can either by a single value, or a list of values.
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
A pipeline of estimators.
+Pipelines allow you to chain different steps into a sequence. Typically, when doing supervised learning, a pipeline contains one ore more transformation steps, whilst it's is a regressor or a classifier. It is highly recommended to use pipelines with River. Indeed, in an online learning setting, it is very practical to have a model defined as a single object. Take a look at the user guide for further information and practical examples.
+One special thing to take notice to is the way transformers are handled. It is usual to predict something for a sample and wait for the ground truth to arrive. In such a scenario, the features are seen before the ground truth arrives. Therefore, the unsupervised parts of the pipeline are updated when predict_one and predict_proba_one are called. Usually the unsupervised parts of the pipeline are all the steps that precede the final step, which is a supervised model. However, some transformers are supervised and are therefore also updated during calls to learn_one.
steps
+Ideally, a list of (name, estimator) tuples. A name is automatically inferred if none is provided.
+The recommended way to declare a pipeline is to use the | operator. The latter allows you
+to chain estimators in a very terse manner:
from river import linear_model
+from river import preprocessing
+
+scaler = preprocessing.StandardScaler()
+log_reg = linear_model.LinearRegression()
+model = scaler | log_reg
+This results in a pipeline that stores each step inside a dictionary.
+model
+Pipeline (
+ StandardScaler (
+ with_std=True
+ ),
+ LinearRegression (
+ optimizer=SGD (
+ lr=Constant (
+ learning_rate=0.01
+ )
+ )
+ loss=Squared ()
+ l2=0.
+ l1=0.
+ intercept_init=0.
+ intercept_lr=Constant (
+ learning_rate=0.01
+ )
+ clip_gradient=1e+12
+ initializer=Zeros ()
+ )
+)
+You can access parts of a pipeline in the same manner as a dictionary:
+model['LinearRegression']
+LinearRegression (
+ optimizer=SGD (
+ lr=Constant (
+ learning_rate=0.01
+ )
+ )
+ loss=Squared ()
+ l2=0.
+ l1=0.
+ intercept_init=0.
+ intercept_lr=Constant (
+ learning_rate=0.01
+ )
+ clip_gradient=1e+12
+ initializer=Zeros ()
+)
+Note that you can also declare a pipeline by using the compose.Pipeline constructor
+method, which is slightly more verbose:
from river import compose
+
+model = compose.Pipeline(scaler, log_reg)
+By using a compose.TransformerUnion, you can define complex pipelines that apply
+different steps to different parts of the data. For instance, we can extract word counts
+from text data, and extract polynomial features from numeric data.
from river import feature_extraction as fx
+
+tfidf = fx.TFIDF('text')
+counts = fx.BagOfWords('text')
+text_part = compose.Select('text') | (tfidf + counts)
+
+num_part = compose.Select('a', 'b') | fx.PolynomialExtender()
+
+model = text_part + num_part
+model |= preprocessing.StandardScaler()
+model |= linear_model.LinearRegression()
+The following shows an example of using debug_one to visualize how the information
+flows and changes throughout the pipeline.
from river import compose
+from river import naive_bayes
+
+dataset = [
+ ('A positive comment', True),
+ ('A negative comment', False),
+ ('A happy comment', True),
+ ('A lovely comment', True),
+ ('A harsh comment', False)
+]
+
+tfidf = fx.TFIDF() | compose.Prefixer('tfidf_')
+counts = fx.BagOfWords() | compose.Prefixer('count_')
+mnb = naive_bayes.MultinomialNB()
+model = (tfidf + counts) | mnb
+
+for x, y in dataset:
+ model = model.learn_one(x, y)
+
+x = dataset[0][0]
+report = model.debug_one(dataset[0][0])
+print(report)
+0. Input
+--------
+A positive comment
+1. Transformer union
+--------------------
+ 1.0 TFIDF | Prefixer
+ --------------------
+ tfidf_comment: 0.43017 (float)
+ tfidf_positive: 0.90275 (float)
+ 1.1 BagOfWords | Prefixer
+ -------------------------
+ count_comment: 1 (int)
+ count_positive: 1 (int)
+count_comment: 1 (int)
+count_positive: 1 (int)
+tfidf_comment: 0.43017 (float)
+tfidf_positive: 0.90275 (float)
+2. MultinomialNB
+----------------
+False: 0.19221
+True: 0.80779
+Displays the state of a set of features as it goes through the pipeline.
+Parameters
+True 5 +
Return a forecast.
+Only works if each estimator has a transform_one method and the final estimator has a forecast method. This is the case of time series models from the time_series module.
Parameters
+None +
Fit to a mini-batch.
+Parameters
+None +
Fit to a single instance.
+Parameters
+None +
Call transform_many, and then predict_many on the final step.
+Parameters
++
Call transform_one on the first steps and predict_one on the last step.
Parameters
++
Call transform_many, and then predict_proba_many on the final step.
+Parameters
++
Call transform_one on the first steps and predict_proba_one on the last step.
Parameters
++
Call transform_one on the first steps and score_one on the last step.
Parameters
++
Apply each transformer in the pipeline to some features.
+The final step in the pipeline will be applied if it is a transformer. If not, then it will be ignored and the output from the penultimate step will be returned. Note that the steps that precede the final step are assumed to all be transformers.
+Parameters
++
Apply each transformer in the pipeline to some features.
+The final step in the pipeline will be applied if it is a transformer. If not, then it will be ignored and the output from the penultimate step will be returned. Note that the steps that precede the final step are assumed to all be transformers.
+Parameters
++ + + + + + + + +
Prepends a prefix on features names.
+prefix
+Type → str
+from river import compose
+
+x = {'a': 42, 'b': 12}
+compose.Prefixer('prefix_').transform_one(x)
+{'prefix_a': 42, 'prefix_b': 12}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Renames features following substitution rules.
+mapping
+Type → dict[str, str]
+Dictionnary describing substitution rules. Keys in mapping that are not a feature's name are silently ignored.
from river import compose
+
+mapping = {'a': 'v', 'c': 'o'}
+x = {'a': 42, 'b': 12}
+compose.Renamer(mapping).transform_one(x)
+{'b': 12, 'v': 42}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Selects features.
+This can be used in a pipeline when you want to select certain features. The transform_one method is pure, and therefore returns a fresh new dictionary instead of filtering the specified keys from the input.
keys
+Type → tuple[base.typing.FeatureName]
+Key(s) to keep.
+from river import compose
+
+x = {'a': 42, 'b': 12, 'c': 13}
+compose.Select('c').transform_one(x)
+{'c': 13}
+You can chain a selector with any estimator in order to apply said estimator to the +desired features.
+from river import feature_extraction as fx
+
+x = {'sales': 10, 'shop': 'Ikea', 'country': 'Sweden'}
+
+pipeline = (
+ compose.Select('sales') |
+ fx.PolynomialExtender()
+)
+pipeline.transform_one(x)
+{'sales': 10, 'sales*sales': 100}
+This transformer also supports mini-batch processing:
+import random
+from river import compose
+
+random.seed(42)
+X = [{"x_1": random.uniform(8, 12), "x_2": random.uniform(8, 12)} for _ in range(6)]
+for x in X:
+ print(x)
+{'x_1': 10.557707193831535, 'x_2': 8.100043020890668}
+{'x_1': 9.100117273476478, 'x_2': 8.892842952595291}
+{'x_1': 10.94588485665605, 'x_2': 10.706797949691644}
+{'x_1': 11.568718270819382, 'x_2': 8.347755330517664}
+{'x_1': 9.687687278741082, 'x_2': 8.119188877752281}
+{'x_1': 8.874551899214413, 'x_2': 10.021421152413449}
+import pandas as pd
+X = pd.DataFrame.from_dict(X)
+You can then call transform_many to transform a mini-batch of features:
compose.Select('x_2').transform_many(X)
+ x_2
+0 8.100043
+1 8.892843
+2 10.706798
+3 8.347755
+4 8.119189
+5 10.021421
+Update with a mini-batch of features.
+A lot of transformers don't actually have to do anything during the learn_many step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_many can override this method.
Parameters
+Returns
+Transformer: self
++
Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a mini-batch of features.
+Parameters
+Returns
+pd.DataFrame: A new DataFrame.
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Selects features based on their type.
+This is practical when you want to apply different preprocessing steps to different kinds of features. For instance, a common usecase is to apply a preprocessing.StandardScaler to numeric features and a preprocessing.OneHotEncoder to categorical features.
types
+Type → tuple[type]
+Python types which you want to select. Under the hood, the isinstance method will be used to check if a value is of a given type.
import numbers
+from river import compose
+from river import linear_model
+from river import preprocessing
+
+num = compose.SelectType(numbers.Number) | preprocessing.StandardScaler()
+cat = compose.SelectType(str) | preprocessing.OneHotEncoder()
+model = (num + cat) | linear_model.LogisticRegression()
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Appends a suffix on features names.
+suffix
+Type → str
+from river import compose
+
+x = {'a': 42, 'b': 12}
+compose.Suffixer('_suffix').transform_one(x)
+{'a_suffix': 42, 'b_suffix': 12}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Modifies the target before training.
+The user is expected to check that func and inverse_func are coherent with each other.
regressor
+Type → base.Regressor
+Regression model to wrap.
+func
+Type → typing.Callable
+A function modifying the target before training.
+inverse_func
+Type → typing.Callable
+A function to return to the target's original space.
+import math
+from river import compose
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+model = (
+ preprocessing.StandardScaler() |
+ compose.TargetTransformRegressor(
+ regressor=linear_model.LinearRegression(intercept_lr=0.15),
+ func=math.log,
+ inverse_func=math.exp
+ )
+)
+metric = metrics.MSE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MSE: 10.999752
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Computes interactions between the outputs of a set transformers.
+This is for when you want to add interaction terms between groups of features. It may also be used an alternative to feature_extraction.PolynomialExtender when the latter is overkill.
transformers
+Ideally, a list of (name, estimator) tuples. A name is automatically inferred if none is provided.
+Let's say we have a certain set of features with two groups. In practice these may be different +namespaces, such one for items and the other for users.
+x = dict(
+ a=0, b=1, # group 1
+ x=2, y=3 # group 2
+)
+We might want to add interaction terms between groups ('a', 'b') and ('x', 'y'), as so:
from pprint import pprint
+from river.compose import Select, TransformerProduct
+
+product = TransformerProduct(
+ Select('a', 'b'),
+ Select('x', 'y')
+)
+pprint(product.transform_one(x))
+{'a*x': 0, 'a*y': 0, 'b*x': 2, 'b*y': 3}
+This can also be done with the following shorthand:
+product = Select('a', 'b') * Select('x', 'y')
+pprint(product.transform_one(x))
+{'a*x': 0, 'a*y': 0, 'b*x': 2, 'b*y': 3}
+If you want to include the original terms, you can do something like this:
+group_1 = Select('a', 'b')
+group_2 = Select('x', 'y')
+product = group_1 + group_2 + group_1 * group_2
+pprint(product.transform_one(x))
+{'a': 0, 'a*x': 0, 'a*y': 0, 'b': 1, 'b*x': 2, 'b*y': 3, 'x': 2, 'y': 3}
+Update each transformer.
+Parameters
+None +
Update each transformer.
+Parameters
+None +
Passes the data through each transformer and packs the results together.
+Parameters
++
Passes the data through each transformer and packs the results together.
+Parameters
++ + + + + + + + +
Packs multiple transformers into a single one.
+Pipelines allow you to apply steps sequentially. Therefore, the output of a step becomes the input of the next one. In many cases, you may want to pass the output of a step to multiple steps. This simple transformer allows you to do so. In other words, it enables you to apply particular steps to different parts of an input. A typical example is when you want to scale numeric features and one-hot encode categorical features.
+This transformer is essentially a list of transformers. Whenever it is updated, it loops through each transformer and updates them. Meanwhile, calling transform_one collects the output of each transformer and merges them into a single dictionary.
transformers
+Ideally, a list of (name, estimator) tuples. A name is automatically inferred if none is provided.
+Take the following dataset:
+X = [
+ {'place': 'Taco Bell', 'revenue': 42},
+ {'place': 'Burger King', 'revenue': 16},
+ {'place': 'Burger King', 'revenue': 24},
+ {'place': 'Taco Bell', 'revenue': 58},
+ {'place': 'Burger King', 'revenue': 20},
+ {'place': 'Taco Bell', 'revenue': 50}
+]
+As an example, let's assume we want to compute two aggregates of a dataset. We therefore
+define two feature_extraction.Aggs and initialize a TransformerUnion with them:
from river import compose
+from river import feature_extraction
+from river import stats
+
+mean = feature_extraction.Agg(
+ on='revenue', by='place',
+ how=stats.Mean()
+)
+count = feature_extraction.Agg(
+ on='revenue', by='place',
+ how=stats.Count()
+)
+agg = compose.TransformerUnion(mean, count)
+We can now update each transformer and obtain their output with a single function call:
+from pprint import pprint
+for x in X:
+ agg = agg.learn_one(x)
+ pprint(agg.transform_one(x))
+{'revenue_count_by_place': 1, 'revenue_mean_by_place': 42.0}
+{'revenue_count_by_place': 1, 'revenue_mean_by_place': 16.0}
+{'revenue_count_by_place': 2, 'revenue_mean_by_place': 20.0}
+{'revenue_count_by_place': 2, 'revenue_mean_by_place': 50.0}
+{'revenue_count_by_place': 3, 'revenue_mean_by_place': 20.0}
+{'revenue_count_by_place': 3, 'revenue_mean_by_place': 50.0}
+Note that you can use the + operator as a shorthand notation:
agg = mean + count
+This allows you to build complex pipelines in a very terse manner. For instance, we can +create a pipeline that scales each feature and fits a logistic regression as so:
+from river import linear_model as lm
+from river import preprocessing as pp
+
+model = (
+ (mean + count) |
+ pp.StandardScaler() |
+ lm.LogisticRegression()
+)
+Whice is equivalent to the following code:
+model = compose.Pipeline(
+ compose.TransformerUnion(mean, count),
+ pp.StandardScaler(),
+ lm.LogisticRegression()
+)
+Note that you access any part of a TransformerUnion by name:
model['TransformerUnion']['Agg']
+Agg (
+ on="revenue"
+ by=['place']
+ how=Mean ()
+)
+model['TransformerUnion']['Agg1']
+Agg (
+ on="revenue"
+ by=['place']
+ how=Count ()
+)
+You can also manually provide a name for each step:
+agg = compose.TransformerUnion(
+ ('Mean revenue by place', mean),
+ ('# by place', count)
+)
+Mini-batch example:
+X = pd.DataFrame([
+ {"place": 2, "revenue": 42},
+ {"place": 3, "revenue": 16},
+ {"place": 3, "revenue": 24},
+ {"place": 2, "revenue": 58},
+ {"place": 3, "revenue": 20},
+ {"place": 2, "revenue": 50},
+])
+Since we need a transformer with mini-batch support to demonstrate, we shall use
+a StandardScaler.
from river import compose
+from river import preprocessing
+
+agg = (
+ compose.Select("place") +
+ (compose.Select("revenue") | preprocessing.StandardScaler())
+)
+
+_ = agg.learn_many(X)
+agg.transform_many(X)
+ place revenue
+0 2 0.441250
+1 3 -1.197680
+2 3 -0.693394
+3 2 1.449823
+4 3 -0.945537
+5 2 0.945537
+Update each transformer.
+Parameters
+None +
Update each transformer.
+Parameters
+None +
Passes the data through each transformer and packs the results together.
+Parameters
++
Passes the data through each transformer and packs the results together.
+Parameters
++ + + + + + + + +
A context manager for fitting unsupervised steps during prediction.
+Usually, unsupervised parts of a pipeline are updated during learn_one. However, in the case of online learning, it is possible to update them before, during the prediction step. This context manager allows you to do so.
This usually brings a slight performance improvement. But it is not done by default because it is not intuitive and is more difficult to test. It also means that you have to call predict_one before learn_one in order for the whole pipeline to be updated.
Let's first see what methods are called if we just call predict_one.
import io
+import logging
+from river import compose
+from river import datasets
+from river import linear_model
+from river import preprocessing
+from river import utils
+
+model = compose.Pipeline(
+ preprocessing.StandardScaler(),
+ linear_model.LinearRegression()
+)
+
+class_condition = lambda x: x.__class__.__name__ in ('StandardScaler', 'LinearRegression')
+
+logger = logging.getLogger()
+logger.setLevel(logging.DEBUG)
+
+logs = io.StringIO()
+sh = logging.StreamHandler(logs)
+sh.setLevel(logging.DEBUG)
+logger.addHandler(sh)
+
+with utils.log_method_calls(class_condition):
+ for x, y in datasets.TrumpApproval().take(1):
+ _ = model.predict_one(x)
+
+print(logs.getvalue())
+StandardScaler.transform_one
+LinearRegression.predict_one
+Now let's use the context manager and see what methods get called.
+logs = io.StringIO()
+sh = logging.StreamHandler(logs)
+sh.setLevel(logging.DEBUG)
+logger.addHandler(sh)
+
+with utils.log_method_calls(class_condition), compose.learn_during_predict():
+ for x, y in datasets.TrumpApproval().take(1):
+ _ = model.predict_one(x)
+
+print(logs.getvalue())
+StandardScaler.learn_one
+StandardScaler.transform_one
+LinearRegression.predict_one
+We can see that the scaler did not get updated before transforming the data.
+This also works when working with mini-batches.
+logs = io.StringIO()
+sh = logging.StreamHandler(logs)
+sh.setLevel(logging.DEBUG)
+logger.addHandler(sh)
+
+with utils.log_method_calls(class_condition):
+ for x, y in datasets.TrumpApproval().take(1):
+ _ = model.predict_many(pd.DataFrame([x]))
+print(logs.getvalue())
+StandardScaler.transform_many
+LinearRegression.predict_many
+logs = io.StringIO()
+sh = logging.StreamHandler(logs)
+sh.setLevel(logging.DEBUG)
+logger.addHandler(sh)
+
+with utils.log_method_calls(class_condition), compose.learn_during_predict():
+ for x, y in datasets.TrumpApproval().take(1):
+ _ = model.predict_many(pd.DataFrame([x]))
+print(logs.getvalue())
+StandardScaler.learn_many
+StandardScaler.transform_many
+LinearRegression.predict_many
+An object to represent a (prediction) interval.
+Users are not expected to use this class as-is. Instead, they should use the with_interval parameter of the predict_one method of any regressor or classifier wrapped with a conformal prediction method.
lower
+Type → float
+The lower bound of the interval.
+upper
+Type → float
+The upper bound of the interval.
+center
+The center of the interval.
+width
+The width of the interval.
+Jackknife method for regression.
+This is a conformal prediction method for regression. It is based on the jackknife method. The idea is to compute the quantiles of the residuals of the regressor. The prediction interval is then computed as the prediction of the regressor plus the quantiles of the residuals.
+This works naturally online, as the quantiles of the residuals are updated at each iteration. Each residual is produced before the regressor is updated, which ensures the predicted intervals are not optimistic.
+Note that the produced intervals are marginal and not conditional. This means that the intervals are not adjusted for the features x. This is a limitation of the jackknife method. However, the jackknife method is very simple and efficient. It is also very robust to outliers.
regressor
+Type → base.Regressor
+The regressor to be wrapped.
+confidence_level
+Type → float
+Default → 0.95
The confidence level of the prediction intervals.
+window_size
+Type → int | None
+Default → None
The size of the window used to compute the quantiles of the residuals. If None, the quantiles are computed over the whole history. It is advised to set this if you expect the model's performance to change over time.
from river import conf
+from river import datasets
+from river import linear_model
+from river import metrics
+from river import preprocessing
+from river import stats
+
+dataset = datasets.TrumpApproval()
+
+model = conf.RegressionJackknife(
+ (
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression(intercept_lr=.1)
+ ),
+ confidence_level=0.9
+)
+
+validity = stats.Mean()
+efficiency = stats.Mean()
+
+for x, y in dataset:
+ interval = model.predict_one(x, with_interval=True)
+ validity = validity.update(y in interval)
+ efficiency = efficiency.update(interval.width)
+ model = model.learn_one(x, y)
+The interval's validity is the proportion of times the true value is within the interval. We +specified a confidence level of 90%, so we expect the validity to be around 90%.
+validity
+Mean: 0.939061
+The interval's efficiency is the average width of the intervals.
+efficiency
+Mean: 4.078361
+Lowering the confidence lowering will mechanically improve the efficiency.
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+False Returns
+The prediction.
++ + + + + + + + + +
Empirical covariance matrix.
+ddof
+Default → 1
Delta Degrees of Freedom.
+import numpy as np
+import pandas as pd
+from river import covariance
+
+np.random.seed(42)
+X = pd.DataFrame(np.random.random((8, 3)), columns=["red", "green", "blue"])
+X
+ red green blue
+0 0.374540 0.950714 0.731994
+1 0.598658 0.156019 0.155995
+2 0.058084 0.866176 0.601115
+3 0.708073 0.020584 0.969910
+4 0.832443 0.212339 0.181825
+5 0.183405 0.304242 0.524756
+6 0.431945 0.291229 0.611853
+7 0.139494 0.292145 0.366362
+cov = covariance.EmpiricalCovariance()
+for x in X.to_dict(orient="records"):
+ cov = cov.update(x)
+cov
+ blue green red
+ blue 0.076 0.020 -0.010
+green 0.020 0.113 -0.053
+ red -0.010 -0.053 0.079
+There is also an update_many method to process mini-batches. The results are identical.
cov = covariance.EmpiricalCovariance()
+cov = cov.update_many(X)
+cov
+ blue green red
+ blue 0.076 0.020 -0.010
+green 0.020 0.113 -0.053
+ red -0.010 -0.053 0.079
+The covariances are stored in a dictionary, meaning any one of them can be accessed as such:
+cov["blue", "green"]
+Cov: 0.020292
+Diagonal entries are variances:
+cov["blue", "blue"]
+Var: 0.076119
+Downdate with a single sample.
+Parameters
++
Update with a single sample.
+Parameters
++
Update with a dataframe of samples.
+Parameters
++ + + + + + + + +
Empirical precision matrix.
+The precision matrix is the inverse of the covariance matrix.
+This implementation leverages the Sherman-Morrison formula. The resulting inverse covariance matrix is not guaranteed to be identical to a batch computation. However, the difference shrinks with the number of observations.
+import numpy as np
+import pandas as pd
+from river import covariance
+
+np.random.seed(42)
+X = pd.DataFrame(np.random.random((1000, 3)))
+X.head()
+ 0 1 2
+0 0.374540 0.950714 0.731994
+1 0.598658 0.156019 0.155995
+2 0.058084 0.866176 0.601115
+3 0.708073 0.020584 0.969910
+4 0.832443 0.212339 0.181825
+prec = covariance.EmpiricalPrecision()
+for x in X.to_dict(orient="records"):
+ prec = prec.update(x)
+
+prec
+ 0 1 2
+0 12.026 -0.122 -0.214
+1 -0.122 11.276 -0.026
+2 -0.214 -0.026 11.632
+pd.DataFrame(np.linalg.inv(np.cov(X.T, ddof=1)))
+ 0 1 2
+0 12.159791 -0.124966 -0.218671
+1 -0.124966 11.393394 -0.026662
+2 -0.218671 -0.026662 11.756907
+Update with a single sample.
+Parameters
++
Update with a dataframe of samples.
+Parameters
++ + + + + + + + + +
Monthly number of international airline passengers.
+The stream contains 144 items and only one single feature, which is the month. The goal is to predict the number of passengers each month by capturing the trend and the seasonality of the data.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Bananas dataset.
+An artificial dataset where instances belongs to several clusters with a banana shape. There are two attributes that correspond to the x and y axis, respectively.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++
Bike sharing station information from the city of Toulouse.
+The goal is to predict the number of bikes in 5 different bike stations from the city of Toulouse.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Chick weights along time.
+The stream contains 578 items and 3 features. The goal is to predict the weight of each chick along time, according to the diet the chick is on. The data is ordered by time and then by chick.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++
Credit card frauds.
+The datasets contains transactions made by credit cards in September 2013 by european cardholders. This dataset presents transactions that occurred in two days, where we have 492 frauds out of 284,807 transactions. The dataset is highly unbalanced, the positive class (frauds) account for 0.172% of all transactions.
+It contains only numerical input variables which are the result of a PCA transformation. Unfortunately, due to confidentiality issues, we cannot provide the original features and more background information about the data. Features V1, V2, ... V28 are the principal components obtained with PCA, the only features which have not been transformed with PCA are 'Time' and 'Amount'. Feature 'Time' contains the seconds elapsed between each transaction and the first transaction in the dataset. The feature 'Amount' is the transaction Amount, this feature can be used for example-dependant cost-senstive learning. Feature 'Class' is the response variable and it takes value 1 in case of fraud and 0 otherwise.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
Andrea Dal Pozzolo, Olivier Caelen, Reid A. Johnson and Gianluca Bontempi. Calibrating Probability with Undersampling for Unbalanced Classification. In Symposium on Computational Intelligence and Data Mining (CIDM), IEEE, 2015 ↩
+Dal Pozzolo, Andrea; Caelen, Olivier; Le Borgne, Yann-Ael; Waterschoot, Serge; Bontempi, Gianluca. Learned lessons in credit card fraud detection from a practitioner perspective, Expert systems with applications,41,10,4915-4928,2014, Pergamon ↩
+Dal Pozzolo, Andrea; Boracchi, Giacomo; Caelen, Olivier; Alippi, Cesare; Bontempi, Gianluca. Credit card fraud detection: a realistic modeling and a novel learning strategy, IEEE transactions on neural networks and learning systems,29,8,3784-3797,2018,IEEE ↩
+Dal Pozzolo, Andrea Adaptive Machine learning for credit card fraud detection ULB MLG PhD thesis (supervised by G. Bontempi) ↩
+Carcillo, Fabrizio; Dal Pozzolo, Andrea; Le Borgne, Yann-Ael; Caelen, Olivier; Mazzer, Yannis; Bontempi, Gianluca. Scarff: a scalable framework for streaming credit card fraud detection with Spark, Information fusion,41, 182-194,2018,Elsevier ↩
+Carcillo, Fabrizio; Le Borgne, Yann-Ael; Caelen, Olivier; Bontempi, Gianluca. Streaming active learning strategies for real-life credit card fraud detection: assessment and visualization, International Journal of Data Science and Analytics, 5,4,285-300,2018,Springer International Publishing ↩
+Bertrand Lebichot, Yann-Ael Le Borgne, Liyun He, Frederic Oble, Gianluca Bontempi Deep-Learning Domain Adaptation Techniques for Credit Cards Fraud Detection, INNSBDDL 2019: Recent Advances in Big Data and Deep Learning, pp 78-88, 2019 ↩
+Fabrizio Carcillo, Yann-Ael Le Borgne, Olivier Caelen, Frederic Oble, Gianluca Bontempi Combining Unsupervised and Supervised Learning in Credit Card Fraud Detection Information Sciences, 2019 ↩
+Electricity prices in New South Wales.
+This is a binary classification task, where the goal is to predict if the price of electricity will go up or down.
+This data was collected from the Australian New South Wales Electricity Market. In this market, prices are not fixed and are affected by demand and supply of the market. They are set every five minutes. Electricity transfers to/from the neighboring state of Victoria were done to alleviate fluctuations.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
HTTP dataset of the KDD 1999 cup.
+The goal is to predict whether or not an HTTP connection is anomalous or not. The dataset only contains 2,211 (0.4%) positive labels.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
Higgs dataset.
+The data has been produced using Monte Carlo simulations. The first 21 features (columns 2-22) are kinematic properties measured by the particle detectors in the accelerator. The last seven features are functions of the first 21 features; these are high-level features derived by physicists to help discriminate between the two classes.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Image segments classification.
+This dataset contains features that describe image segments into 7 classes: brickface, sky, foliage, cement, window, path, and grass.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Insects dataset.
+This dataset has different variants, which are:
+abrupt_balanced
+abrupt_imbalanced
+gradual_balanced
+gradual_imbalanced
+incremental-abrupt_balanced
+incremental-abrupt_imbalanced
+incremental-reoccurring_balanced
+incremental-reoccurring_imbalanced
+incremental_balanced
+incremental_imbalanced
+out-of-control
+The number of samples and the difficulty change from one variant to another. The number of classes is always the same (6), except for the last variant (24).
+variant
+Default → abrupt_balanced
Indicates which variant of the dataset to load.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
CMU keystroke dataset.
+Users are tasked to type in a password. The task is to determine which user is typing in the password.
+The only difference with the original dataset is that the "sessionIndex" and "rep" attributes have been dropped.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
Malicious URLs dataset.
+This dataset contains features about URLs that are classified as malicious or not.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
MovieLens 100K dataset.
+MovieLens datasets were collected by the GroupLens Research Project at the University of Minnesota. This dataset consists of 100,000 ratings (1-5) from 943 users on 1682 movies. Each user has rated at least 20 movies. User and movie information are provided. The data was collected through the MovieLens web site (movielens.umn.edu) during the seven-month period from September 19th, 1997 through April 22nd, 1998.
+unpack_user_and_item
+Default → False
Whether or not the user and item should be extracted from the context and included as extra keyword arguments.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
Multi-label music mood prediction.
+The goal is to predict to which kinds of moods a song pertains to.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Phishing websites.
+This dataset contains features from web pages that are classified as phishing or not.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Data from the Kaggle Recruit Restaurants challenge.
+The goal is to predict the number of visitors in each of 829 Japanese restaurants over a priod of roughly 16 weeks. The data is ordered by date and then by restaurant ID.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
SMS Spam Collection dataset.
+The data contains 5,574 items and 1 feature (i.e. SMS body). Spam messages represent 13.4% of the dataset. The goal is to predict whether an SMS is a spam or not.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
SMTP dataset from the KDD 1999 cup.
+The goal is to predict whether or not an SMTP connection is anomalous or not. The dataset only contains 2,211 (0.4%) positive labels.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
TREC's 2007 Spam Track dataset.
+The data contains 75,419 chronologically ordered items, i.e. 3 months of emails delivered to a particular server in 2007. Spam messages represent 66.6% of the dataset. The goal is to predict whether an email is a spam or not.
+The available raw features are: sender, recipients, date, subject, body.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
Taxi ride durations in New York City.
+The goal is to predict the duration of taxi rides in New York City.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++
Donald Trump approval ratings.
+This dataset was obtained by reshaping the data used by FiveThirtyEight for analyzing Donald Trump's approval ratings. It contains 5 features, which are approval ratings collected by 5 polling agencies. The target is the approval rating from FiveThirtyEight's model. The goal of this task is to see if we can reproduce FiveThirtyEight's model.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++
Water flow through a pipeline branch.
+The series includes hourly values for about 2 months, March 2022 to May 2022. The values are expressed in liters per second. There are four anomalous segments in the series:
+This dataset is well suited for time series forecasting models, as well as anomaly detection methods. Ideally, the goal is to build a time series forecasting model that is robust to the anomalous segments.
+This data has been kindly donated by the Tecnojest s.r.l. company (www.invidea.it) from Italy.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Base class for all datasets.
+All datasets inherit from this class, be they stored in a file or generated on the fly.
+task
+Type of task the dataset is meant for. Should be one of the following: - "Regression" - "Binary classification" - "Multi-class classification" - "Multi-output binary classification" - "Multi-output regression"
+n_features
+Number of features in the dataset.
+n_samples
+Default → None
Number of samples in the dataset.
+n_classes
+Default → None
Number of classes in the dataset, only applies to classification datasets.
+n_outputs
+Default → None
Number of outputs the target is made of, only applies to multi-output datasets.
+sparse
+Default → False
Whether the dataset is sparse or not.
+desc
+Return the description from the docstring.
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Base class for datasets that are stored in a local file.
+Small datasets that are part of the river package inherit from this class.
+filename
+The file's name.
+directory
+Default → None
The directory where the file is contained. Defaults to the location of the datasets module.
desc
+Extra dataset parameters to pass as keyword arguments.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Base class for datasets that are stored in a remote file.
+Medium and large datasets that are not part of the river package inherit from this class.
+The filename doesn't have to be provided if unpack is False. Indeed in the latter case the filename will be inferred from the URL.
+url
+The URL the dataset is located at.
+size
+The expected download size.
+unpack
+Default → True
Whether to unpack the download or not.
+filename
+Default → None
An optional name to given to the file if the file is unpacked.
+desc
+Extra dataset parameters to pass as keyword arguments.
+desc
+Return the description from the docstring.
+is_downloaded
+Indicate whether or the data has been correctly downloaded.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
A synthetic dataset.
+task
+Type of task the dataset is meant for. Should be one of: - "Regression" - "Binary classification" - "Multi-class classification" - "Multi-output binary classification" - "Multi-output regression"
+n_features
+Number of features in the dataset.
+n_samples
+Default → None
Number of samples in the dataset.
+n_classes
+Default → None
Number of classes in the dataset, only applies to classification datasets.
+n_outputs
+Default → None
Number of outputs the target is made of, only applies to multi-output datasets.
+sparse
+Default → False
Whether the dataset is sparse or not.
+desc
+Return the description from the docstring.
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Agrawal stream generator.
+The generator was introduced by Agrawal et al. 1, and was a common source of data for early work on scaling up decision tree learners. The generator produces a stream containing nine features, six numeric and three categorical. There are 10 functions defined for generating binary class labels from the features. Presumably these determine whether the loan should be approved. Classification functions are listed in the original paper 1.
+Feature | Description | Values
+salary | salary | uniformly distributed from 20k to 150k
commission | commission | 0 if salary < 75k else uniformly distributed from 10k to 75k
age | age | uniformly distributed from 20 to 80
elevel | education level | uniformly chosen from 0 to 4
car | car maker | uniformly chosen from 1 to 20
zipcode | zip code of the town | uniformly chosen from 0 to 8
hvalue | house value | uniformly distributed from 50k x zipcode to 100k x zipcode
hyears | years house owned | uniformly distributed from 1 to 30
loan | total loan amount | uniformly distributed from 0 to 500k
classification_function
+Type → int
+Default → 0
The classification function to use for the generation. Valid values are from 0 to 9.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+balance_classes
+Type → bool
+Default → False
If True, the class distribution will converge to a uniform distribution.
+perturbation
+Type → float
+Default → 0.0
The probability that noise will happen in the generation. Each new sample will be perturbed by the magnitude of perturbation. Valid values are in the range [0.0 to 1.0].
desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Agrawal(
+ classification_function=0,
+ seed=42
+)
+
+dataset
+Synthetic data generator
+<BLANKLINE>
+ Name Agrawal
+ Task Binary classification
+ Samples ∞
+Features 9
+ Outputs 1
+ Classes 2
+ Sparse False
+<BLANKLINE>
+Configuration
+-------------
+classification_function 0
+ seed 42
+ balance_classes False
+ perturbation 0.0
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[103125.4837, 0, 21, 2, 8, 3, 319768.9642, 4, 338349.7437] 1
+[135983.3438, 0, 25, 4, 14, 0, 423837.7755, 7, 116330.4466] 1
+[98262.4347, 0, 55, 1, 18, 6, 144088.1244, 19, 139095.3541] 0
+[133009.0417, 0, 68, 1, 14, 5, 233361.4025, 7, 478606.5361] 1
+[63757.2908, 16955.9382, 26, 2, 12, 4, 522851.3093, 24, 229712.4398] 1
+Generate drift by switching the classification function randomly.
++
Iterate over the k samples.
+Parameters
++
The sample generation works as follows: The 9 features are generated
+with the random generator, initialized with the seed passed by the
+user. Then, the classification function decides, as a function of all
+the attributes, whether to classify the instance as class 0 or class
+1. The next step is to verify if the classes should be balanced, and
+if so, balance the classes. Finally, add noise if perturbation > 0.0.
Simulate a stream with anomalies in sine waves.
+The amount of data generated by this generator is finite.
+The data generated corresponds to sine and cosine functions. Anomalies are induced by replacing the cosine values with values from a different a sine function. The contextual flag can be used to introduce contextual anomalies which are values in the normal global range, but abnormal compared to the seasonal pattern. Contextual attributes are introduced by replacing cosine entries with sine values.
The target indicates whether or not the instances are anomalous.
+n_samples
+Type → int
+Default → 10000
The number of samples to generate. This generator creates a batch of data affected by contextual anomalies and noise.
+n_anomalies
+Type → int
+Default → 2500
Number of anomalies. Can't be larger than n_samples.
contextual
+Type → bool
+Default → False
If True, will add contextual anomalies.
+n_contextual
+Type → int
+Default → 2500
Number of contextual anomalies. Can't be larger than n_samples.
shift
+Type → int
+Default → 4
Shift in number of samples applied when retrieving contextual anomalies.
+noise
+Type → float
+Default → 0.5
Amount of noise.
+replace
+Type → bool
+Default → True
If True, anomalies are randomly sampled with replacement.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.AnomalySine(
+ seed=12345,
+ n_samples=100,
+ n_anomalies=25,
+ contextual=True,
+ n_contextual=10
+)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{'sine': -0.7119, 'cosine': 0.8777} False
+{'sine': 0.8792, 'cosine': -0.0290} False
+{'sine': 0.0440, 'cosine': 3.0852} True
+{'sine': 0.5520, 'cosine': 3.4515} True
+{'sine': 0.8037, 'cosine': 0.4027} False
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Generates a stream with concept drift.
+A stream generator that adds concept drift or change by joining two streams. This is done by building a weighted combination of two pure distributions that characterizes the target concepts before and after the change.
+The sigmoid function is an elegant and practical solution to define the probability that each new instance of the stream belongs to the new concept after the drift. The sigmoid function introduces a gradual, smooth transition whose duration is controlled with two parameters:
+\(p\), the position of the change.
+\(w\), the width of the transition.
+The sigmoid function at sample \(t\) is
+stream
+Type → datasets.base.SyntheticDataset | None
+Default → None
Original stream
+drift_stream
+Type → datasets.base.SyntheticDataset | None
+Default → None
Drift stream
+position
+Type → int
+Default → 5000
Central position of the concept drift change.
+width
+Type → int
+Default → 1000
Width of concept drift change.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+alpha
+Type → float | None
+Default → None
Angle of change used to estimate the width of concept drift change. If set, it will override the width parameter. Valid values are in the range (0.0, 90.0].
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.ConceptDriftStream(
+ stream=synth.SEA(seed=42, variant=0),
+ drift_stream=synth.SEA(seed=42, variant=1),
+ seed=1, position=5, width=2
+)
+
+for x, y in dataset.take(10):
+ print(x, y)
+{0: 6.3942, 1: 0.2501, 2: 2.7502} False
+{0: 2.2321, 1: 7.3647, 2: 6.7669} True
+{0: 8.9217, 1: 0.8693, 2: 4.2192} True
+{0: 0.2979, 1: 2.1863, 2: 5.0535} False
+{0: 6.3942, 1: 0.2501, 2: 2.7502} False
+{0: 2.2321, 1: 7.3647, 2: 6.7669} True
+{0: 8.9217, 1: 0.8693, 2: 4.2192} True
+{0: 0.2979, 1: 2.1863, 2: 5.0535} False
+{0: 0.2653, 1: 1.9883, 2: 6.4988} False
+{0: 5.4494, 1: 2.2044, 2: 5.8926} False
+Iterate over the k samples.
+Parameters
++
An optional way to estimate the width of the transition \(w\) is based on +the angle \(\alpha\), \(w = 1/ tan(\alpha)\). Since width corresponds to +the number of samples for the transition, the width is rounded to the +nearest smaller integer. Notice that larger values of \(\alpha\) result in +smaller widths. For \(\alpha > 45.0\), the width is smaller than 1 so values +are rounded to 1 to avoid division by zero errors.
+ + + + + + + + +Friedman synthetic dataset.
+Each observation is composed of 10 features. Each feature value is sampled uniformly in [0, 1]. The target is defined by the following function:
+In the last expression, \(\epsilon \sim \mathcal{N}(0, 1)\), is the noise. Therefore, only the first 5 features are relevant.
+seed
+Type → int | None
+Default → None
Random seed number used for reproducibility.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Friedman(seed=42)
+
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[0.63, 0.02, 0.27, 0.22, 0.73, 0.67, 0.89, 0.08, 0.42, 0.02] 7.66
+[0.02, 0.19, 0.64, 0.54, 0.22, 0.58, 0.80, 0.00, 0.80, 0.69] 8.33
+[0.34, 0.15, 0.95, 0.33, 0.09, 0.09, 0.84, 0.60, 0.80, 0.72] 7.04
+[0.37, 0.55, 0.82, 0.61, 0.86, 0.57, 0.70, 0.04, 0.22, 0.28] 18.16
+[0.07, 0.23, 0.10, 0.27, 0.63, 0.36, 0.37, 0.20, 0.26, 0.93] 8.90
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Friedman synthetic dataset with concept drifts.
+Each observation is composed of 10 features. Each feature value is sampled uniformly in [0, 1]. Only the first 5 features are relevant. The target is defined by different functions depending on the type of the drift.
+The three available modes of operation of the data generator are described in 1.
+drift_type
+Type → str
+Default → lea
The variant of concept drift. - 'lea': Local Expanding Abrupt drift. The concept drift appears in two distinct regions of the instance space, while the remaining regions are left unaltered. There are three points of abrupt change in the training dataset. At every consecutive change the regions of drift are expanded. - 'gra': Global Recurring Abrupt drift. The concept drift appears over the whole instance space. There are two points of concept drift. At the second point of drift the old concept reoccurs. - 'gsg': Global and Slow Gradual drift. The concept drift affects all the instance space. However, the change is gradual and not abrupt. After each one of the two change points covered by this variant, and during a window of length transition_window, examples from both old and the new concepts are generated with equal probability. After the transition period, only the examples from the new concept are generated.
position
+Type → tuple[int, ...]
+Default → (50000, 100000, 150000)
The amount of monitored instances after which each concept drift occurs. A tuple with at least two element must be passed, where each number is greater than the preceding one. If drift_type='lea', then the tuple must have three elements.
transition_window
+Type → int
+Default → 10000
The length of the transition window between two concepts. Only applicable when drift_type='gsg'. If set to zero, the drifts will be abrupt. Anytime transition_window > 0, it defines a window in which instances of the new concept are gradually introduced among the examples from the old concept. During this transition phase, both old and new concepts appear with equal probability.
seed
+Type → int | None
+Default → None
Random seed number used for reproducibility.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.FriedmanDrift(
+ drift_type='lea',
+ position=(1, 2, 3),
+ seed=42
+)
+
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[0.63, 0.02, 0.27, 0.22, 0.73, 0.67, 0.89, 0.08, 0.42, 0.02] 7.66
+[0.02, 0.19, 0.64, 0.54, 0.22, 0.58, 0.80, 0.00, 0.80, 0.69] 8.33
+[0.34, 0.15, 0.95, 0.33, 0.09, 0.09, 0.84, 0.60, 0.80, 0.72] 7.04
+[0.37, 0.55, 0.82, 0.61, 0.86, 0.57, 0.70, 0.04, 0.22, 0.28] 18.16
+[0.07, 0.23, 0.10, 0.27, 0.63, 0.36, 0.37, 0.20, 0.26, 0.93] -2.65
+dataset = synth.FriedmanDrift(
+ drift_type='gra',
+ position=(2, 3),
+ seed=42
+)
+
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[0.63, 0.02, 0.27, 0.22, 0.73, 0.67, 0.89, 0.08, 0.42, 0.02] 7.66
+[0.02, 0.19, 0.64, 0.54, 0.22, 0.58, 0.80, 0.00, 0.80, 0.69] 8.33
+[0.34, 0.15, 0.95, 0.33, 0.09, 0.09, 0.84, 0.60, 0.80, 0.72] 8.96
+[0.37, 0.55, 0.82, 0.61, 0.86, 0.57, 0.70, 0.04, 0.22, 0.28] 18.16
+[0.07, 0.23, 0.10, 0.27, 0.63, 0.36, 0.37, 0.20, 0.26, 0.93] 8.90
+dataset = synth.FriedmanDrift(
+ drift_type='gsg',
+ position=(1, 4),
+ transition_window=2,
+ seed=42
+)
+
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[0.63, 0.02, 0.27, 0.22, 0.73, 0.67, 0.89, 0.08, 0.42, 0.02] 7.66
+[0.02, 0.19, 0.64, 0.54, 0.22, 0.58, 0.80, 0.00, 0.80, 0.69] 8.33
+[0.34, 0.15, 0.95, 0.33, 0.09, 0.09, 0.84, 0.60, 0.80, 0.72] 8.92
+[0.37, 0.55, 0.82, 0.61, 0.86, 0.57, 0.70, 0.04, 0.22, 0.28] 17.32
+[0.07, 0.23, 0.10, 0.27, 0.63, 0.36, 0.37, 0.20, 0.26, 0.93] 6.05
+Iterate over the k samples.
+Parameters
++
Ikonomovska, E., Gama, J. and Džeroski, S., 2011. Learning model trees from evolving +data streams. Data mining and knowledge discovery, 23(1), pp.128-168. ↩
+Hyperplane stream generator.
+Generates a problem of prediction class of a rotation hyperplane. It was used as testbed for CVFDT and VFDT in 1.
+A hyperplane in d-dimensional space is the set of points \(x\) that satisfy
+where \(x_i\) is the i-th coordinate of \(x\).
+Examples for which \(\sum^{d}_{i=1} w_i x_i > w_0\), are labeled positive.
+Examples for which \(\sum^{d}_{i=1} w_i x_i \leq w_0\), are labeled negative.
+Hyperplanes are useful for simulating time-changing concepts because we can change the orientation and position of the hyperplane in a smooth manner by changing the relative size of the weights. We introduce change to this dataset by adding drift to each weighted feature \(w_i = w_i + d \sigma\), where \(\sigma\) is the probability that the direction of change is reversed and \(d\) is the change applied to each example.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+n_features
+Type → int
+Default → 10
The number of attributes to generate. Higher than 2.
+n_drift_features
+Type → int
+Default → 2
The number of attributes with drift. Higher than 2.
+mag_change
+Type → float
+Default → 0.0
Magnitude of the change for every example. From 0.0 to 1.0.
+noise_percentage
+Type → float
+Default → 0.05
Percentage of noise to add to the data. From 0.0 to 1.0.
+sigma
+Type → float
+Default → 0.1
Probability that the direction of change is reversed. From 0.0 to 1.0.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Hyperplane(seed=42, n_features=2)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{0: 0.2750, 1: 0.2232} 0
+{0: 0.0869, 1: 0.4219} 1
+{0: 0.0265, 1: 0.1988} 0
+{0: 0.5892, 1: 0.8094} 0
+{0: 0.3402, 1: 0.1554} 0
+Iterate over the k samples.
+Parameters
++
The sample generation works as follows: The features are generated +with the random number generator, initialized with the seed passed by +the user. Then the classification function decides, as a function of +the sum of the weighted features and the sum of the weights, whether +the instance belongs to class 0 or class 1. The last step is to add +noise and generate drift.
+G. Hulten, L. Spencer, and P. Domingos. Mining time-changing data streams. + In KDD'01, pages 97-106, San Francisco, CA, 2001. ACM Press. ↩
+LED stream generator.
+This data source originates from the CART book 1. An implementation in C was donated to the UCI 2 machine learning repository by David Aha. The goal is to predict the digit displayed on a seven-segment LED display, where each attribute has a 10% chance of being inverted. It has an optimal Bayes classification rate of 74%. The particular configuration of the generator used for experiments (LED) produces 24 binary attributes, 17 of which are irrelevant.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+noise_percentage
+Type → float
+Default → 0.0
The probability that noise will happen in the generation. At each new sample generated, a random number is generated, and if it is equal or less than the noise_percentage, the led value will be switched
+irrelevant_features
+Type → bool
+Default → False
Adds 17 non-relevant attributes to the stream.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.LED(seed = 112, noise_percentage = 0.28, irrelevant_features= False)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{0: 1, 1: 0, 2: 1, 3: 0, 4: 0, 5: 1, 6: 0} 7
+{0: 1, 1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 0} 8
+{0: 1, 1: 1, 2: 1, 3: 1, 4: 0, 5: 1, 6: 0} 9
+{0: 0, 1: 0, 2: 1, 3: 0, 4: 0, 5: 1, 6: 0} 1
+{0: 0, 1: 1, 2: 1, 3: 0, 4: 0, 5: 0, 6: 0} 1
+Iterate over the k samples.
+Parameters
++
An instance is generated based on the parameters passed. If has_noise
+is set then the total number of attributes will be 24, otherwise there will
+be 7 attributes.
Leo Breiman, Jerome Friedman, R. Olshen, and Charles J. Stone. + Classification and Regression Trees. Wadsworth and Brooks, + Monterey, CA,1984. ↩
+A. Asuncion and D. J. Newman. UCI Machine Learning Repository + [http://www.ics.uci.edu/~mlearn/mlrepository.html]. + University of California, Irvine, School of Information and + Computer Sciences,2007. ↩
+LED stream generator with concept drift.
+This class is an extension of the LED generator whose purpose is to add concept drift to the stream.
seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+noise_percentage
+Type → float
+Default → 0.0
The probability that noise will happen in the generation. At each new sample generated, a random number is generated, and if it is equal or less than the noise_percentage, the led value will be switched
+irrelevant_features
+Type → bool
+Default → False
Adds 17 non-relevant attributes to the stream.
+n_drift_features
+Type → int
+Default → 0
The number of attributes that have drift.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.LEDDrift(seed = 112, noise_percentage = 0.28,
+ irrelevant_features= True, n_drift_features=4)
+
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[1, 0, 0, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0, 1] 7
+[1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 1, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0] 6
+[0, 0, 0, 1, 1, 0, 1, 0, 1, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 1, 0, 0, 0, 1] 1
+[1, 0, 0, 1, 1, 1, 1, 0, 0, 1, 1, 1, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1, 0, 1] 6
+[1, 0, 1, 1, 1, 0, 1, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 0] 7
+Iterate over the k samples.
+Parameters
++
An instance is generated based on the parameters passed. If has_noise
+is set then the total number of attributes will be 24, otherwise there will
+be 7 attributes.
Logical functions stream generator.
+Make a toy dataset with three labels that represent the logical functions: OR, XOR, AND (functions of the 2D input).
Data is generated in 'tiles' which contain the complete set of logical operations results. The tiles are repeated n_tiles times. Optionally, the generated data can be shuffled.
n_tiles
+Type → int
+Default → 1
Number of tiles to generate.
+shuffle
+Type → bool
+Default → True
If set, generated data will be shuffled.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Logical(n_tiles=2, shuffle=True, seed=42)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{'A': 1, 'B': 1} {'OR': 1, 'XOR': 0, 'AND': 1}
+{'A': 0, 'B': 0} {'OR': 0, 'XOR': 0, 'AND': 0}
+{'A': 1, 'B': 0} {'OR': 1, 'XOR': 1, 'AND': 0}
+{'A': 1, 'B': 1} {'OR': 1, 'XOR': 0, 'AND': 1}
+{'A': 1, 'B': 0} {'OR': 1, 'XOR': 1, 'AND': 0}
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Mixed data stream generator.
+This generator is an implementation of a data stream with abrupt concept drift and boolean noise-free examples as described in 1.
+It has four relevant attributes, two boolean attributes \(v, w\) and two numeric attributes \(x, y\) uniformly distributed from 0 to 1. The examples are labeled depending on the classification function chosen from below.
+function 0: if \(v\) and \(w\) are true or \(v\) and \(z\) are true or \(w\) and \(z\) are true then 0 else 1, where \(z\) is \(y < 0.5 + 0.3 sin(3 \pi x)\)
function 1: The opposite of function 0.
Concept drift can be introduced by changing the classification function. This can be done manually or using ConceptDriftStream.
classification_function
+Type → int
+Default → 0
Which of the two classification functions to use for the generation. Valid options are 0 or 1.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+balance_classes
+Type → bool
+Default → False
Whether to balance classes or not. If balanced, the class distribution will converge to a uniform distribution.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+dataset = synth.Mixed(seed = 42, classification_function=1, balance_classes = True)
+for x, y in dataset.take(5):
+ print(x, y)
+{0: True, 1: False, 2: 0.2750, 3: 0.2232} 1
+{0: False, 1: False, 2: 0.2186, 3: 0.5053} 0
+{0: False, 1: True, 2: 0.8094, 3: 0.0064} 1
+{0: False, 1: False, 2: 0.1010, 3: 0.2779} 0
+{0: True, 1: False, 2: 0.37018, 3: 0.2095} 1
+Generate drift by switching the classification function.
++
Iterate over the k samples.
+Parameters
++
The sample generation works as follows: The two numeric attributes are +generated with the random generator initialized with the seed passed by +the user (optional). The boolean attributes are either 0 or 1 +based on the comparison of the random number generator and 0.5, +the classification function decides whether to classify the instance +as class 0 or class 1. The next step is to verify if the classes should +be balanced, and if so, balance the classes.
+The generated sample will have 4 relevant features and 1 label (it is a +binary-classification task).
+Gama, Joao, et al. "Learning with drift detection." Advances in + artificial intelligence-SBIA 2004. Springer Berlin Heidelberg, + 2004. 286-295" ↩
+Mv artificial dataset.
+Artificial dataset composed of both nominal and numeric features, whose features present co-dependencies. Originally described in 1.
+The features are generated using the following expressions:
+\(x_1\): uniformly distributed over [-5, 5].
\(x_2\): uniformly distributed over [-15, -10].
\(x_3\):
+if \(x_1 > 0\), \(x_3 \leftarrow\) 'green'
else \(x_3 \leftarrow\) 'red' with probability \(0.4\) and \(x_3 \leftarrow\) 'brown' with probability \(0.6\).
\(x_4\):
+if \(x_3 =\) 'green', \(x_4 \leftarrow x_1 + 2 x_2\)
else \(x_4 = \frac{x_1}{2}\) with probability \(0.3\) and \(x_4 = \frac{x_2}{2}\) with probability \(0.7\).
+\(x_5\): uniformly distributed over [-1, 1].
\(x_6 \leftarrow x_4 \times \epsilon\), where \(\epsilon\) is uniformly distributed
+over [0, 5].
\(x_7\): 'yes' with probability \(0.3\), and 'no' with probability \(0.7\).
\(x_8\): 'normal' if \(x_5 < 0.5\) else 'large'.
\(x_9\): uniformly distributed over [100, 500].
\(x_{10}\): uniformly distributed integer over the interval [1000, 1200].
The target value is generated using the following rules:
+if \(x_2 > 2\), \(y \leftarrow 35 - 0.5 x_4\)
+else if \(-2 \le x_4 \le 2\), \(y \leftarrow 10 - 2 x_1\)
+else if \(x_7 =\) 'yes', \(y \leftarrow 3 - \frac{x_1}{x_4}\)
else if \(x_8 =\) 'normal', \(y \leftarrow x_6 + x_1\)
else \(y \leftarrow \frac{x_1}{2}\).
+seed
+Type → int | None
+Default → None
Random seed number used for reproducibility.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Mv(seed=42)
+
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[1.39, -14.87, 'green', -28.35, -0.44, -31.64, 'no', 'normal', 370.67, 1178.43] -30.25
+[-4.13, -12.89, 'red', -2.06, 0.01, -0.27, 'yes', 'normal', 359.95, 1108.98] 1.00
+[-2.79, -12.05, 'brown', -1.39, 0.61, -4.87, 'no', 'large', 162.19, 1191.44] 15.59
+[-1.63, -14.53, 'red', -7.26, 0.20, -29.33, 'no', 'normal', 314.49, 1194.62] -30.96
+[-1.21, -12.23, 'brown', -6.11, 0.72, -17.66, 'no', 'large', 118.32, 1045.57] -0.60
+Iterate over the k samples.
+Parameters
++
2D Planes synthetic dataset.
+This dataset is described in 1 and was adapted from 2. The features are generated using the following probabilities:
+The target value is defined by the following rule:
+In the expressions, \(\epsilon \sim \mathcal{N}(0, 1)\), is the noise.
+seed
+Type → int | None
+Default → None
Random seed number used for reproducibility.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Planes2D(seed=42)
+
+for x, y in dataset.take(5):
+ print(list(x.values()), y)
+[-1, -1, 1, 0, -1, -1, -1, 1, -1, 1] -9.07
+[1, -1, -1, -1, -1, -1, 1, 1, -1, 1] -4.25
+[-1, 1, 1, 1, 1, 0, -1, 0, 1, 0] -0.95
+[-1, 1, 0, 0, 0, -1, -1, 0, -1, -1] -6.10
+[1, -1, 0, 0, 1, 0, -1, 1, 0, 1] 1.60
+Iterate over the k samples.
+Parameters
++
Breiman, L., Friedman, J., Stone, C.J. and Olshen, R.A., 1984. Classification and +regression trees. CRC press. ↩
+Random Radial Basis Function generator.
+Produces a radial basis function stream. A number of centroids, having a random central position, a standard deviation, a class label and weight are generated. A new sample is created by choosing one of the centroids at random, taking into account their weights, and offsetting the attributes in a random direction from the centroid's center. The offset length is drawn from a Gaussian distribution.
+This process will create a normally distributed hypersphere of samples on the surrounds of each centroid.
+seed_model
+Type → int | None
+Default → None
Model's random seed to generate centroids.
+seed_sample
+Type → int | None
+Default → None
Sample's random seed.
+n_classes
+Type → int
+Default → 2
The number of class labels to generate.
+n_features
+Type → int
+Default → 10
The number of numerical features to generate.
+n_centroids
+Type → int
+Default → 50
The number of centroids to generate.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+dataset = synth.RandomRBF(seed_model=42, seed_sample=42,
+ n_classes=4, n_features=4, n_centroids=20)
+for x, y in dataset.take(5):
+ print(x, y)
+{0: 1.0989, 1: 0.3840, 2: 0.7759, 3: 0.6592} 2
+{0: 0.2366, 1: 1.3233, 2: 0.5691, 3: 0.2083} 0
+{0: 1.3540, 1: -0.3306, 2: 0.1683, 3: 0.8865} 0
+{0: 0.2585, 1: -0.2217, 2: 0.4739, 3: 0.6522} 0
+{0: 0.1295, 1: 0.5953, 2: 0.1774, 3: 0.6673} 1
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Random Radial Basis Function generator with concept drift.
+This class is an extension from the RandomRBF generator. Concept drift can be introduced in instances of this class.
The drift is created by adding a "speed" to certain centroids. As the samples are generated each of the moving centroids' centers is changed by an amount determined by its speed.
+seed_model
+Type → int | None
+Default → None
Model's random seed to generate centroids.
+seed_sample
+Type → int | None
+Default → None
Sample's random seed.
+n_classes
+Type → int
+Default → 2
The number of class labels to generate.
+n_features
+Type → int
+Default → 10
The number of numerical features to generate.
+n_centroids
+Type → int
+Default → 50
The number of centroids to generate.
+change_speed
+Type → float
+Default → 0.0
The concept drift speed.
+n_drift_centroids
+Type → int
+Default → 50
The number of centroids that will drift.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+dataset = synth.RandomRBFDrift(seed_model=42, seed_sample=42,
+ n_classes=4, n_features=4, n_centroids=20,
+ change_speed=0.87, n_drift_centroids=10)
+for x, y in dataset.take(5):
+ print(x, y)
+{0: 1.0989, 1: 0.3840, 2: 0.7759, 3: 0.6592} 2
+{0: 1.1496, 1: 1.9014, 2: 1.5393, 3: 0.3210} 0
+{0: 0.7146, 1: -0.2414, 2: 0.8933, 3: 1.6633} 0
+{0: 0.3797, 1: -0.1027, 2: 0.8717, 3: 1.1635} 0
+{0: 0.1295, 1: 0.5953, 2: 0.1774, 3: 0.6673} 1
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Random Tree generator.
+This generator is based on 1. The generator creates a random tree by splitting features at random and setting labels at its leaves.
+The tree structure is composed of node objects, which can be either inner nodes or leaf nodes. The choice comes as a function of the parameters passed to its initializer.
+Since the concepts are generated and classified according to a tree structure, in theory, it should favor decision tree learners.
+seed_tree
+Type → int | None
+Default → None
Seed for random generation of tree.
+seed_sample
+Type → int | None
+Default → None
Seed for random generation of instances.
+n_classes
+Type → int
+Default → 2
The number of classes to generate.
+n_num_features
+Type → int
+Default → 5
The number of numerical features to generate.
+n_cat_features
+Type → int
+Default → 5
The number of categorical features to generate.
+n_categories_per_feature
+Type → int
+Default → 5
The number of values to generate per categorical feature.
+max_tree_depth
+Type → int
+Default → 5
The maximum depth of the tree concept.
+first_leaf_level
+Type → int
+Default → 3
The first level of the tree above max_tree_depth that can have leaves.
fraction_leaves_per_level
+Type → float
+Default → 0.15
The fraction of leaves per level from first_leaf_level onwards.
desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.RandomTree(seed_tree=42, seed_sample=42, n_classes=2,
+ n_num_features=2, n_cat_features=2,
+ n_categories_per_feature=2, max_tree_depth=6,
+ first_leaf_level=3, fraction_leaves_per_level=0.15)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{'x_num_0': 0.6394, 'x_num_1': 0.0250, 'x_cat_0': 1, 'x_cat_1': 0} 0
+{'x_num_0': 0.2232, 'x_num_1': 0.7364, 'x_cat_0': 0, 'x_cat_1': 1} 1
+{'x_num_0': 0.0317, 'x_num_1': 0.0936, 'x_cat_0': 0, 'x_cat_1': 0} 0
+{'x_num_0': 0.5612, 'x_num_1': 0.7160, 'x_cat_0': 1, 'x_cat_1': 0} 0
+{'x_num_0': 0.4492, 'x_num_1': 0.2781, 'x_cat_0': 0, 'x_cat_1': 0} 0
+Iterate over the k samples.
+Parameters
++
Domingos, Pedro, and Geoff Hulten. "Mining high-speed data streams." + In Proceedings of the sixth ACM SIGKDD international conference on + Knowledge discovery and data mining, pp. 71-80. 2000. ↩
+SEA synthetic dataset.
+Implementation of the data stream with abrupt drift described in 1. Each observation is composed of 3 features. Only the first two features are relevant. The target is binary, and is positive if the sum of the features exceeds a certain threshold. There are 4 thresholds to choose from. Concept drift can be introduced by switching the threshold anytime during the stream.
+Variant 0: True if \(att1 + att2 > 8\)
Variant 1: True if \(att1 + att2 > 9\)
Variant 2: True if \(att1 + att2 > 7\)
Variant 3: True if \(att1 + att2 > 9.5\)
variant
+Default → 0
Determines the classification function to use. Possible choices are 0, 1, 2, 3.
+noise
+Default → 0.0
Determines the amount of observations for which the target sign will be flipped.
+seed
+Type → int | None
+Default → None
Random seed number used for reproducibility.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.SEA(variant=0, seed=42)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{0: 6.39426, 1: 0.25010, 2: 2.75029} False
+{0: 2.23210, 1: 7.36471, 2: 6.76699} True
+{0: 8.92179, 1: 0.86938, 2: 4.21921} True
+{0: 0.29797, 1: 2.18637, 2: 5.05355} False
+{0: 0.26535, 1: 1.98837, 2: 6.49884} False
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
STAGGER concepts stream generator.
+This generator is an implementation of the dara stream with abrupt concept drift, as described in 1.
+The STAGGER concepts are boolean functions f with three features describing objects: size (small, medium and large), shape (circle, square and triangle) and colour (red, blue and green).
f options:
True if the size is small and the color is red.
True if the color is green or the shape is a circle.
True if the size is medium or large
Concept drift can be introduced by changing the classification function. This can be done manually or using datasets.synth.ConceptDriftStream.
One important feature is the possibility to balance classes, which means the class distribution will tend to a uniform one.
+classification_function
+Type → int
+Default → 0
Classification functions to use. From 0 to 2.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+balance_classes
+Type → bool
+Default → False
Whether to balance classes or not. If balanced, the class distribution will converge to an uniform distribution.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.STAGGER(classification_function = 2, seed = 112,
+ balance_classes = False)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{'size': 1, 'color': 2, 'shape': 2} 1
+{'size': 2, 'color': 1, 'shape': 2} 1
+{'size': 1, 'color': 1, 'shape': 2} 1
+{'size': 0, 'color': 1, 'shape': 0} 0
+{'size': 2, 'color': 1, 'shape': 0} 1
+Generate drift by switching the classification function at random.
++
Iterate over the k samples.
+Parameters
++
The sample generation works as follows: The 3 attributes are +generated with the random number generator. The classification function +defines whether to classify the instance as class 0 or class 1. Finally, +data is balanced, if this option is set by the user.
+Schlimmer, J. C., & Granger, R. H. (1986). Incremental learning + from noisy data. Machine learning, 1(3), 317-354. ↩
+Sine generator.
+This generator is an implementation of the dara stream with abrupt concept drift, as described in Gama, Joao, et al. 1.
+It generates up to 4 relevant numerical features, that vary from 0 to 1, where only 2 of them are relevant to the classification task and the other 2 are optionally added by as noise. A classification function is chosen among four options:
+SINE1. Abrupt concept drift, noise-free examples. It has two relevant attributes. Each attributes has values uniformly distributed in [0, 1]. In the first context all points below the curve \(y = sin(x)\) are classified as positive.
Reversed SINE1. The reversed classification of SINE1.
SINE2. The same two relevant attributes. The classification function is \(y < 0.5 + 0.3 sin(3 \pi x)\).
Reversed SINE2. The reversed classification of SINE2.
Concept drift can be introduced by changing the classification function. This can be done manually or using ConceptDriftStream.
Two important features are the possibility to balance classes, which means the class distribution will tend to a uniform one, and the possibility to add noise, which will, add two non relevant attributes.
+classification_function
+Type → int
+Default → 0
Classification functions to use. From 0 to 3.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+balance_classes
+Type → bool
+Default → False
Whether to balance classes or not. If balanced, the class distribution will converge to an uniform distribution.
+has_noise
+Type → bool
+Default → False
Adds 2 non relevant features to the stream.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Sine(classification_function = 2, seed = 112,
+ balance_classes = False, has_noise = True)
+
+for x, y in dataset.take(5):
+ print(x, y)
+{0: 0.4812, 1: 0.6660, 2: 0.6198, 3: 0.6994} 1
+{0: 0.9022, 1: 0.7518, 2: 0.1625, 3: 0.2209} 0
+{0: 0.4547, 1: 0.3901, 2: 0.9629, 3: 0.7287} 0
+{0: 0.4683, 1: 0.3515, 2: 0.2273, 3: 0.6027} 0
+{0: 0.9238, 1: 0.1673, 2: 0.4522, 3: 0.3447} 0
+Generate drift by switching the classification function at random.
++
Iterate over the k samples.
+Parameters
++
The sample generation works as follows: The two attributes are +generated with the random number generator. The classification function +defines whether to classify the instance as class 0 or class 1. Finally, +data is balanced and noise is added, if these options are set by the user.
+The generated sample will have 2 relevant features, and an additional
+two noise features if has_noise is set.
Gama, Joao, et al.'s 'Learning with drift detection.' + Advances in artificial intelligence-SBIA 2004. + Springer Berlin Heidelberg, 2004. 286-295." ↩
+Waveform stream generator.
+Generates samples with 21 numeric features and 3 classes, based on a random differentiation of some base waveforms. Supports noise addition, in this case the samples will have 40 features.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+has_noise
+Type → bool
+Default → False
Adds 19 unrelated features to the stream.
+desc
+Return the description from the docstring.
+from river.datasets import synth
+
+dataset = synth.Waveform(seed=42, has_noise=True)
+
+for x, y in dataset:
+ break
+
+x
+{0: -0.0397, 1: -0.7484, 2: 0.2974, 3: 0.3574, 4: -0.0735, 5: -0.3647, 6: 1.5631, 7: 2.5291, 8: 4.1599, 9: 4.9587, 10: 4.52587, 11: 4.0097, 12: 3.6705, 13: 1.7033, 14: 1.4898, 15: 1.9743, 16: 0.0898, 17: 2.319, 18: 0.2552, 19: -0.4775, 20: -0.71339, 21: 0.3770, 22: 0.3671, 23: 1.6579, 24: 0.7828, 25: 0.5855, 26: -0.5807, 27: 0.7112, 28: -0.0271, 29: 0.2968, 30: -0.4997, 31: 0.1302, 32: 0.3578, 33: -0.1900, 34: -0.3771, 35: 1.3560, 36: 0.7124, 37: -0.6245, 38: 0.1346, 39: 0.3550}
+y
+2
+Iterate over the k samples.
+Parameters
++
An instance is generated based on the parameters passed. +The generator will randomly choose one of the hard coded waveforms, as +well as random multipliers. For each feature, the actual value generated +will be a a combination of the hard coded functions, with the multipliers +and a random value.
+If noise is added then the features 21 to 40 will be replaced with a +random normal value.
+ + + + + + + + +Adaptive Windowing method for concept drift detection.
+ADWIN (ADaptive WINdowing) is a popular drift detection method with mathematical guarantees. ADWIN efficiently keeps a variable-length window of recent items; such that it holds that there has no been change in the data distribution. This window is further divided into two sub-windows \((W_0, W_1)\) used to determine if a change has happened. ADWIN compares the average of \(W_0\) and \(W_1\) to confirm that they correspond to the same distribution. Concept drift is detected if the distribution equality no longer holds. Upon detecting a drift, \(W_0\) is replaced by \(W_1\) and a new \(W_1\) is initialized. ADWIN uses a significance value \(\delta=\in(0,1)\) to determine if the two sub-windows correspond to the same distribution.
+delta
+Default → 0.002
Significance value.
+clock
+Default → 32
How often ADWIN should check for change. 1 means every new data point, default is 32. Higher values speed up processing, but may also lead to increased delay in change detection.
+max_buckets
+Default → 5
The maximum number of buckets of each size that ADWIN should keep before merging buckets (default is 5).
+min_window_length
+Default → 5
The minimum length of each subwindow (default is 5). Lower values may decrease delay in change detection but may also lead to more false positives.
+grace_period
+Default → 10
ADWIN does not perform any change detection until at least this many data points have arrived (default is 10).
+drift_detected
+Whether or not a drift is detected following the last update.
+estimation
+Estimate of mean value in the window.
+n_detections
+total
+variance
+width
+Window size
+import random
+from river import drift
+
+rng = random.Random(12345)
+adwin = drift.ADWIN()
+
+data_stream = rng.choices([0, 1], k=1000) + rng.choices(range(4, 8), k=1000)
+
+for i, val in enumerate(data_stream):
+ _ = adwin.update(val)
+ if adwin.drift_detected:
+ print(f"Change detected at index {i}, input value: {val}")
+Change detected at index 1023, input value: 4
+Update the change detector with a single data point.
+Apart from adding the element value to the window, by inserting it in the correct bucket, it will also update the relevant statistics, in this case the total sum of all values, the window width and the total variance.
+Parameters
+Returns
+DriftDetector: self
++
Albert Bifet and Ricard Gavalda. +"Learning from time-changing data with adaptive windowing." +In Proceedings of the 2007 SIAM international conference on data mining, +pp. 443-448. Society for Industrial and Applied Mathematics, 2007. ↩
+Drift retraining classifier.
+This classifier is a wrapper for any classifier. It monitors the incoming data for concept drifts and warnings in the model's accurary. In case a warning is detected, a background model starts to train. If a drift is detected, the model will be replaced by the background model, and the background model will be reset.
+model
+Type → base.Classifier
+The classifier and background classifier class.
+drift_detector
+Type → base.DriftAndWarningDetector | base.BinaryDriftAndWarningDetector | None
+Default → None
Algorithm to track warnings and concept drifts. Attention! If the parameter train_in_background is True, the drift_detector must have a warning tracker.
+train_in_background
+Type → bool
+Default → True
Parameter to determine if a background model will be used.
+from river import datasets
+from river import evaluate
+from river import drift
+from river import metrics
+from river import tree
+
+dataset = datasets.Elec2().take(3000)
+
+model = drift.DriftRetrainingClassifier(
+ model=tree.HoeffdingTreeClassifier(),
+ drift_detector=drift.binary.DDM()
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 86.46%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Baseline drift detector that generates pseudo drift detection signals.
+There are two approaches1:
+fixed where the drift signal is generated every t_0 samples.
random corresponds to a pseudo-random drift detection strategy.
trigger_method
+Type → str
+Default → fixed
The trigger method to use.
* fixed
* random
t_0
+Type → int
+Default → 300
Reference point to define triggers.
+w
+Type → int
+Default → 0
Auxiliary parameter whose purpose is twofold: - if trigger_method="fixed", the periodic drift signals will only start after an initial warm-up period randomly defined between [0, w]. Useful to avoid that all ensemble members are reset at the same time when periodic triggers are used as the adaptation strategy. - if trigger_method="random", w defines the probability bounds of triggering a drift. The chance of triggering a drift is \(0.5\) after observing t_0 instances and becomes \(1\) after monitoring t_0 + w / 2 instances. A sigmoid function is used to produce values between [0, 1] that are used as the reset probabilities.
dynamic_cloning
+Type → bool
+Default → False
Whether to change the seed and w values each time clone() is called.
seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+drift_detected
+Whether or not a drift is detected following the last update.
+import random
+from river import drift
+
+rng = random.Random(42)
+The observed values will not affect the periodic triggers.
+data = [rng.gauss(0, 1) for _ in range(1000)]
+Let's start with the fixed drift signals:
+ptrigger = DummyDriftDetector(t_0=500, seed=42)
+for i, v in enumerate(data):
+ _ = ptrigger.update(v)
+ if ptrigger.drift_detected:
+ print(f"Drift detected at instance {i}.")
+Drift detected at instance 499.
+Drift detected at instance 999.
+Now, the random drift signals:
+rtrigger = DummyDriftDetector(
+ trigger_method="random",
+ t_0=500,
+ w=100,
+ dynamic_cloning=True,
+ seed=42
+)
+for i, v in enumerate(data):
+ _ = rtrigger.update(v)
+ if rtrigger.drift_detected:
+ print(f"Drift detected at instance {i}.")
+Drift detected at instance 368.
+Drift detected at instance 817.
+Remember to set a w > 0 value if random triggers are used:
+try:
+ DummyDriftDetector(trigger_method="random")
+except ValueError as ve:
+ print(ve)
+The 'w' value must be greater than zero when 'trigger_method' is 'random'.
+Since we set dynamic_cloning to True, a clone of the periodic trigger will
+have its internal paramenters changed:
rtrigger = rtrigger.clone()
+for i, v in enumerate(data):
+ _ = rtrigger.update(v)
+ if rtrigger.drift_detected:
+ print(f"Drift detected at instance {i}.")
+Drift detected at instance 429.
+Drift detected at instance 728.
+Update the detector with a single data point.
+Parameters
+Returns
+DriftDetector: self
++
When used in ensembles, a naive implementation of periodic drift signals would make all ensemble members
+reset at the same time. To avoid that, the dynamic_cloning parameter can be set to True. In this case,
+every time the clone method of this detector is called in an ensemble a new seed is defined. If
+dynamic_cloning=True and trigger_method="fixed", a new w between [0, t_0] will also be created
+for the new cloned instance.
Heitor Gomes, Jacob Montiel, Saulo Martiello Mastelini, Bernhard Pfahringer, and Albert Bifet. +On Ensemble Techniques for Data Stream Regression. IJCNN'20. International Joint Conference on +Neural Networks. 2020. ↩
+Kolmogorov-Smirnov Windowing method for concept drift detection.
+alpha
+Type → float
+Default → 0.005
Probability for the test statistic of the Kolmogorov-Smirnov-Test. The alpha parameter is very sensitive, therefore should be set below 0.01.
+window_size
+Type → int
+Default → 100
Size of the sliding window.
+stat_size
+Type → int
+Default → 30
Size of the statistic window.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+window
+Type → typing.Iterable | None
+Default → None
Already collected data to avoid cold start.
+drift_detected
+Whether or not a drift is detected following the last update.
+import random
+from river import drift
+
+rng = random.Random(12345)
+kswin = drift.KSWIN(alpha=0.0001, seed=42)
+
+data_stream = rng.choices([0, 1], k=1000) + rng.choices(range(4, 8), k=1000)
+
+for i, val in enumerate(data_stream):
+ _ = kswin.update(val)
+ if kswin.drift_detected:
+ print(f"Change detected at index {i}, input value: {val}")
+Change detected at index 1016, input value: 6
+Update the change detector with a single data point.
+Adds an element on top of the sliding window and removes the oldest one from the window. Afterwards, the KS-test is performed.
+Parameters
+Returns
+DriftDetector: self
++
KSWIN (Kolmogorov-Smirnov Windowing) is a concept change detection method based +on the Kolmogorov-Smirnov (KS) statistical test. KS-test is a statistical test with +no assumption of underlying data distribution. KSWIN can monitor data or performance +distributions. Note that the detector accepts one dimensional input as array.
+KSWIN maintains a sliding window \(\Psi\) of fixed size \(n\) (window_size). The +last \(r\) (stat_size) samples of \(\Psi\) are assumed to represent the last +concept considered as \(R\). From the first \(n-r\) samples of \(\Psi\), +\(r\) samples are uniformly drawn, representing an approximated last concept \(W\).
+The KS-test is performed on the windows \(R\) and \(W\) of the same size. KS +-test compares the distance of the empirical cumulative data distribution \(dist(R,W)\).
+A concept drift is detected by KSWIN if:
+The difference in empirical data distributions between the windows \(R\) and \(W\) is too large +since \(R\) and \(W\) come from the same distribution.
+Christoph Raab, Moritz Heusinger, Frank-Michael Schleif, Reactive Soft Prototype Computing for +Concept Drift Streams, Neurocomputing, 2020, ↩
+Page-Hinkley method for concept drift detection.
+This change detection method works by computing the observed values and their mean up to the current moment. Page-Hinkley does not signal warning zones, only change detections.
+This detector implements the CUSUM control chart for detecting changes. This implementation also supports the two-sided Page-Hinkley test to detect increasing and decreasing changes in the mean of the input values.
+min_instances
+Type → int
+Default → 30
The minimum number of instances before detecting change.
+delta
+Type → float
+Default → 0.005
The delta factor for the Page-Hinkley test.
+threshold
+Type → float
+Default → 50.0
The change detection threshold (lambda).
+alpha
+Type → float
+Default → 0.9999
The forgetting factor, used to weight the observed value and the mean.
+mode
+Type → str
+Default → both
Whether to consider increases ("up"), decreases ("down") or both ("both") when monitoring the fading mean.
+drift_detected
+Whether or not a drift is detected following the last update.
+import random
+from river import drift
+
+rng = random.Random(12345)
+ph = drift.PageHinkley()
+
+data_stream = rng.choices([0, 1], k=1000) + rng.choices(range(4, 8), k=1000)
+
+for i, val in enumerate(data_stream):
+ _ = ph.update(val)
+ if ph.drift_detected:
+ print(f"Change detected at index {i}, input value: {val}")
+Change detected at index 1006, input value: 5
+Update the detector with a single data point.
+Parameters
+Returns
+DriftDetector: self
++
E. S. Page. 1954. Continuous Inspection Schemes. Biometrika 41, 1/2 (1954), 100-115. ↩
+Sebastião, R., & Fernandes, J. M. (2017, June). Supporting the Page-Hinkley test with +empirical mode decomposition for change detection. In International Symposium on Methodologies +for Intelligent Systems (pp. 492-498). Springer, Cham. ↩
+Drift Detection Method.
+DDM (Drift Detection Method) is a concept change detection method based on the PAC learning model premise, that the learner's error rate will decrease as the number of analysed samples increase, as long as the data distribution is stationary.
+If the algorithm detects an increase in the error rate, that surpasses a calculated threshold, either change is detected or the algorithm will warn the user that change may occur in the near future, which is called the warning zone.
+The detection threshold is calculated in function of two statistics, obtained when \((p_i + s_i)\) is minimum:
+\(p_{min}\): The minimum recorded error rate.
+\(s_{min}\): The minimum recorded standard deviation.
+At instant \(i\), the detection algorithm uses:
+\(p_i\): The error rate at instant \(i\).
+\(s_i\): The standard deviation at instant \(i\).
+The conditions for entering the warning zone and detecting change are as follows [see implementation note below]:
+if \(p_i + s_i \geq p_{min} + w_l * s_{min}\) -> Warning zone
+if \(p_i + s_i \geq p_{min} + d_l * s_{min}\) -> Change detected
+In the above expressions, \(w_l\) and \(d_l\) represent, respectively, the warning and drift thresholds.
+Input: x is an entry in a stream of bits, where 1 indicates error/failure and 0 represents correct/normal values.
For example, if a classifier's prediction \(y'\) is right or wrong w.r.t. the true target label \(y\):
+0: Correct, \(y=y'\)
+1: Error, \(y \neq y'\)
+warm_start
+Type → int
+Default → 30
The minimum required number of analyzed samples so change can be detected. Warm start parameter for the drift detector.
+warning_threshold
+Type → float
+Default → 2.0
Threshold to decide if the detector is in a warning zone. The default value gives 95\% of confidence level to the warning assessment.
+drift_threshold
+Type → float
+Default → 3.0
Threshold to decide if a drift was detected. The default value gives a 99\% of confidence level to the drift assessment.
+drift_detected
+Whether or not a drift is detected following the last update.
+warning_detected
+Whether or not a drift is detected following the last update.
+import random
+from river import drift
+
+rng = random.Random(42)
+ddm = drift.binary.DDM()
+
+data_stream = rng.choices([0, 1], k=1000)
+data_stream = data_stream + rng.choices([0, 1], k=1000, weights=[0.3, 0.7])
+
+print_warning = True
+for i, x in enumerate(data_stream):
+ _ = ddm.update(x)
+ if ddm.warning_detected and print_warning:
+ print(f"Warning detected at index {i}")
+ print_warning = False
+ if ddm.drift_detected:
+ print(f"Change detected at index {i}")
+ print_warning = True
+Warning detected at index 1084
+Change detected at index 1334
+Warning detected at index 1492
+Update the detector with a single boolean input.
+Parameters
+Returns
+BinaryDriftDetector: self
++
João Gama, Pedro Medas, Gladys Castillo, Pedro Pereira Rodrigues: Learning with Drift Detection. SBIA 2004: 286-295 ↩
+Early Drift Detection Method.
+EDDM (Early Drift Detection Method) aims to improve the detection rate of gradual concept drift in DDM, while keeping a good performance against abrupt concept drift.
+This method works by keeping track of the average distance between two errors instead of only the error rate. For this, it is necessary to keep track of the running average distance and the running standard deviation, as well as the maximum distance and the maximum standard deviation.
+The algorithm works similarly to the DDM algorithm, by keeping track of statistics only. It works with the running average distance (\(p_i'\)) and the running standard deviation (\(s_i'\)), as well as \(p'_{max}\) and \(s'_{max}\), which are the values of \(p_i'\) and \(s_i'\) when \((p_i' + 2 * s_i')\) reaches its maximum.
+Like DDM, there are two threshold values that define the borderline between no change, warning zone, and drift detected. These are as follows:
+if \((p_i' + 2 * s_i') / (p'_{max} + 2 * s'_{max}) < \alpha\) -> Warning zone
+if \((p_i' + 2 * s_i') / (p'_{max} + 2 * s'_{max}) < \beta\) -> Change detected
+\(\alpha\) and \(\beta\) are set to 0.95 and 0.9, respectively.
+Input: x is an entry in a stream of bits, where 1 indicates error/failure and 0 represents correct/normal values.
For example, if a classifier's prediction \(y'\) is right or wrong w.r.t. the true target label \(y\):
+0: Correct, \(y=y'\)
+1: Error, \(y \\neq y'\)
+warm_start
+Type → int
+Default → 30
The minimum required number of monitored errors/failures so change can be detected. Warm start parameter for the drift detector.
+alpha
+Type → float
+Default → 0.95
Threshold for triggering a warning. Must be between 0 and 1. The smaller the value, the more conservative the detector becomes.
+beta
+Type → float
+Default → 0.9
Threshold for triggering a drift. Must be between 0 and 1. The smaller the value, the more conservative the detector becomes.
+drift_detected
+Whether or not a drift is detected following the last update.
+warning_detected
+Whether or not a drift is detected following the last update.
+import random
+from river import drift
+
+rng = random.Random(42)
+eddm = drift.binary.EDDM(alpha=0.8, beta=0.75)
+
+data_stream = rng.choices([0, 1], k=1000)
+data_stream = data_stream + rng.choices([0, 1], k=1000, weights=[0.3, 0.7])
+
+print_warning = True
+for i, x in enumerate(data_stream):
+ _ = eddm.update(x)
+ if eddm.warning_detected and print_warning:
+ print(f"Warning detected at index {i}")
+ print_warning = False
+ if eddm.drift_detected:
+ print(f"Change detected at index {i}")
+ print_warning = True
+Warning detected at index 1059
+Change detected at index 1278
+Update the change detector with a single data point.
+Parameters
+Returns
+BinaryDriftDetector: self
++
Early Drift Detection Method. Manuel Baena-Garcia, Jose Del Campo-Avila, Raúl Fidalgo, Albert Bifet, Ricard Gavalda, Rafael Morales-Bueno. In Fourth International Workshop on Knowledge Discovery from Data Streams, 2006. ↩
+Drift Detection Method based on Hoeffding's bounds with moving average-test.
+HDDM_A is a drift detection method based on the Hoeffding's inequality which uses the input average as estimator.
+Input: x is an entry in a stream of bits, where 1 indicates error/failure and 0 represents correct/normal values.
For example, if a classifier's prediction \(y'\) is right or wrong w.r.t. the true target label \(y\):
+0: Correct, \(y=y'\)
+1: Error, \(y \neq y'\)
+Implementation based on MOA.
+drift_confidence
+Default → 0.001
Confidence to the drift
+warning_confidence
+Default → 0.005
Confidence to the warning
+two_sided_test
+Default → False
If True, will monitor error increments and decrements (two-sided). By default will only monitor increments (one-sided).
drift_detected
+Whether or not a drift is detected following the last update.
+warning_detected
+Whether or not a drift is detected following the last update.
+import random
+from river import drift
+
+rng = random.Random(42)
+hddm_a = drift.binary.HDDM_A()
+
+data_stream = rng.choices([0, 1], k=1000)
+data_stream = data_stream + rng.choices([0, 1], k=1000, weights=[0.3, 0.7])
+
+print_warning = True
+for i, x in enumerate(data_stream):
+ _ = hddm_a.update(x)
+ if hddm_a.warning_detected and print_warning:
+ print(f"Warning detected at index {i}")
+ print_warning = False
+ if hddm_a.drift_detected:
+ print(f"Change detected at index {i}")
+ print_warning = True
+Warning detected at index 451
+Change detected at index 1206
+Update the change detector with a single data point.
+Parameters
+Returns
+BinaryDriftDetector: self
++
Frías-Blanco I, del Campo-Ávila J, Ramos-Jimenez G, et al. Online and non-parametric drift detection +methods based on Hoeffding's bounds. IEEE Transactions on Knowledge and Data Engineering, 2014, 27(3): 810-823. ↩
+Albert Bifet, Geoff Holmes, Richard Kirkby, Bernhard Pfahringer. MOA: Massive Online Analysis; Journal +of Machine Learning Research 11: 1601-1604, 2010. ↩
+Drift Detection Method based on Hoeffding's bounds with moving weighted average-test.
+HDDM_W is an online drift detection method based on McDiarmid's bounds. HDDM_W uses the Exponentially Weighted Moving Average (EWMA) statistic as estimator.
+Input: x is an entry in a stream of bits, where 1 indicates error/failure and 0 represents correct/normal values.
For example, if a classifier's prediction \(y'\) is right or wrong w.r.t. the true target label \(y\):
+0: Correct, \(y=y'\)
+1: Error, \(y \neq y'\)
+Implementation based on MOA.
+drift_confidence
+Default → 0.001
Confidence to the drift
+warning_confidence
+Default → 0.005
Confidence to the warning
+lambda_val
+Default → 0.05
The weight given to recent data. Smaller values mean less weight given to recent data.
+two_sided_test
+Default → False
If True, will monitor error increments and decrements (two-sided). By default will only monitor increments (one-sided).
+drift_detected
+Whether or not a drift is detected following the last update.
+warning_detected
+Whether or not a drift is detected following the last update.
+import random
+from river import drift
+
+rng = random.Random(42)
+hddm_w = drift.binary.HDDM_W()
+
+data_stream = rng.choices([0, 1], k=1000)
+data_stream = data_stream + rng.choices([0, 1], k=1000, weights=[0.3, 0.7])
+
+print_warning = True
+for i, x in enumerate(data_stream):
+ _ = hddm_w.update(x)
+ if hddm_w.warning_detected and print_warning:
+ print(f"Warning detected at index {i}")
+ print_warning = False
+ if hddm_w.drift_detected:
+ print(f"Change detected at index {i}")
+ print_warning = True
+Warning detected at index 451
+Change detected at index 1077
+Update the change detector with a single data point.
+Parameters
+Returns
+BinaryDriftDetector: self
++
Frías-Blanco I, del Campo-Ávila J, Ramos-Jimenez G, et al. Online and non-parametric drift + detection methods based on Hoeffding’s bounds. IEEE Transactions on Knowledge and Data + Engineering, 2014, 27(3): 810-823. ↩
+Albert Bifet, Geoff Holmes, Richard Kirkby, Bernhard Pfahringer. MOA: Massive Online Analysis; + Journal of Machine Learning Research 11: 1601-1604, 2010. ↩
+JFK Airline Passengers
+This dataset gives the number of passengers arriving and departing at JFK. The data is obtained from New York State's official Kaggle page for this dataset.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++
https://www.kaggle.com/new-york-state/nys-air-passenger-traffic,-port-authority-of-ny-nj#air-passenger-traffic-per-month-port-authority-of-ny-nj-beginning-1977.csv ↩
+Apple Stock
+This dataset concerns the daily close price and volume of Apple stock around the year 2000. The dataset is sampled every 3 observations to reduce the length of the time series. This dataset is retrieved from Yahoo Finance.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++
https://finance.yahoo.com/quote/AAPL/history?period1=850348800&period2=1084579200&interval=1d&filter=history&frequency=1d ↩
+Bitcoin Market Price
+This is a regression task, where the goal is to predict the average USD market price across major bitcoin exchanges. This data was collected from the official Blockchain website. There is only one feature given, the day of exchange, which is in increments of three. The first 500 lines have been removed because they are not interesting.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++
https://www.blockchain.com/fr/explorer/charts/market-price?timespan=all ↩
+Brent Spot Price
+This is the USD price for Brent Crude oil, measured daily. We include the time series from 2000 onwards. The data is sampled at every 10 original observations to reduce the length of the series.
+The data is obtained from the U.S. Energy Information Administration. Since the data is in the public domain, we distribute it as part of this repository.
+Since the original data has observations only on trading days, there are arguably gaps in this time series (on non-trading days). However we consider these to be consecutive, and thus also consider the sampled time series to have consecutive observations.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + + +
Room occupancy data.
+Dataset on detecting room occupancy based on several variables. The dataset contains temperature, humidity, light, and CO2 variables.
+The data is sampled at every 16 observations to reduce the length of the series.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++Candanedo, Luis M., and Véronique Feldheim. "Accurate occupancy detection of an office room from light, temperature, humidity and CO2 measurements using statistical learning models." Energy and Buildings 112 (2016): 28-39.
+ + + + + + + + +Interval Training Running Pace.
+This dataset shows the pace of a runner during an interval training session, where a mobile application provides instructions on when to run and when to walk.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++ + + + + + + + +
Historic Employment in UK Coal Mines
+This is historic data obtained from the UK government. We use the employment column for the number of workers employed in the British coal mines Missing values in the data are replaced with the value of the preceding year.
+desc
+Return the description from the docstring.
+path
+Iterate over the k samples.
+Parameters
++
https://www.gov.uk/government/statistical-data-sets/historical-coal-data-coal-production-availability-and-consumption ↩
+Dummy classifier which returns the last class seen.
+The predict_one method will output the last class seen whilst predict_proba_one will return 1 for the last class seen and 0 for the others.
+last_class
+The last class seen.
+classes
+The set of classes seen.
+Taken from example 2.1 from +this page.
+import pprint
+from river import dummy
+
+sentences = [
+ ('glad happy glad', '+'),
+ ('glad glad joyful', '+'),
+ ('glad pleasant', '+'),
+ ('miserable sad glad', '−')
+]
+
+model = dummy.NoChangeClassifier()
+
+for sentence, label in sentences:
+ model = model.learn_one(sentence, label)
+
+new_sentence = 'glad sad miserable pleasant glad'
+model.predict_one(new_sentence)
+'−'
+pprint.pprint(model.predict_proba_one(new_sentence))
+{'+': 0, '−': 1}
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++ + + + + + + + +
Dummy classifier which uses the prior distribution.
+The predict_one method will output the most common class whilst predict_proba_one will return the normalized class counts.
counts (collections.Counter)
+Class counts.
+n (int)
+Total number of seen instances.
+Taken from example 2.1 from +this page
+from river import dummy
+
+sentences = [
+ ('glad happy glad', '+'),
+ ('glad glad joyful', '+'),
+ ('glad pleasant', '+'),
+ ('miserable sad glad', '−')
+]
+
+model = dummy.PriorClassifier()
+
+for sentence, label in sentences:
+ model = model.learn_one(sentence, label)
+
+new_sentence = 'glad sad miserable pleasant glad'
+model.predict_one(new_sentence)
+'+'
+model.predict_proba_one(new_sentence)
+{'+': 0.75, '−': 0.25}
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++
Dummy regressor that uses a univariate statistic to make predictions.
+statistic
+Type → stats.base.Univariate
+from pprint import pprint
+from river import dummy
+from river import stats
+
+sentences = [
+ ('glad happy glad', 3),
+ ('glad glad joyful', 3),
+ ('glad pleasant', 2),
+ ('miserable sad glad', -3)
+]
+
+model = dummy.StatisticRegressor(stats.Mean())
+
+for sentence, score in sentences:
+ model = model.learn_one(sentence, score)
+
+new_sentence = 'glad sad miserable pleasant glad'
+model.predict_one(new_sentence)
+1.25
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++ + + + + + + + +
ADWIN Bagging classifier.
+ADWIN Bagging 1 is the online bagging method of Oza and Russell 2 with the addition of the ADWIN algorithm as a change detector. If concept drift is detected, the worst member of the ensemble (based on the error estimation by ADWIN) is replaced by a new (empty) classifier.
model
+Type → base.Classifier
+The classifier to bag.
+n_models
+Default → 10
The number of models in the ensemble.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+
+model = ensemble.ADWINBaggingClassifier(
+ model=(
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+ ),
+ n_models=3,
+ seed=42
+)
+
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.65%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Averages the predictions of each classifier.
+Parameters
++
Albert Bifet, Geoff Holmes, Bernhard Pfahringer, Richard Kirkby, +and Ricard Gavaldà. "New ensemble methods for evolving data streams." +In 15th ACM SIGKDD International Conference on Knowledge Discovery and +Data Mining, 2009. ↩
+Oza, N., Russell, S. "Online bagging and boosting." +In: Artificial Intelligence and Statistics 2001, pp. 105–112. +Morgan Kaufmann, 2001. ↩
+ADWIN Boosting classifier.
+ADWIN Boosting 1 is the online boosting method of Oza and Russell 2 with the addition of the ADWIN algorithm as a change detector. If concept drift is detected, the worst member of the ensemble (based on the error estimation by ADWIN) is replaced by a new (empty) classifier.
model
+Type → base.Classifier
+The classifier to boost.
+n_models
+Default → 10
The number of models in the ensemble.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.Phishing()
+model = ensemble.ADWINBoostingClassifier(
+ model=(
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+ ),
+ n_models=3,
+ seed=42
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.61%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Albert Bifet, Geoff Holmes, Bernhard Pfahringer, Richard Kirkby, +and Ricard Gavaldà. "New ensemble methods for evolving data streams." +In 15th ACM SIGKDD International Conference on Knowledge Discovery and +Data Mining, 2009. ↩
+Oza, N., Russell, S. "Online bagging and boosting." +In: Artificial Intelligence and Statistics 2001, pp. 105–112. +Morgan Kaufmann, 2001. ↩
+Boosting for classification.
+For each incoming observation, each model's learn_one method is called k times where k is sampled from a Poisson distribution of parameter lambda. The lambda parameter is updated when the weaks learners fit successively the same observation.
model
+Type → base.Classifier
+The classifier to boost.
+n_models
+Default → 10
The number of models in the ensemble.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+In the following example three tree classifiers are boosted together. The performance is +slightly better than when using a single tree.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import metrics
+from river import tree
+
+dataset = datasets.Phishing()
+
+metric = metrics.LogLoss()
+
+model = ensemble.AdaBoostClassifier(
+ model=(
+ tree.HoeffdingTreeClassifier(
+ split_criterion='gini',
+ delta=1e-5,
+ grace_period=2000
+ )
+ ),
+ n_models=5,
+ seed=42
+)
+
+evaluate.progressive_val_score(dataset, model, metric)
+LogLoss: 0.370805
+print(model)
+AdaBoostClassifier(HoeffdingTreeClassifier)
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + + +
Boosting Online Learning Ensemble (BOLE).
+A modified version of Oza Online Boosting Algorithm 1. For each incoming observation, each model's learn_one method is called k times where k is sampled from a Poisson distribution of parameter lambda. The first model to be trained will be the one with worst correct_weight / (correct_weight + wrong_weight). The worst model not yet trained will receive lambda values for training from the models that incorrectly classified an instance, and the best model's not yet trained will receive lambda values for training from the models that correctly classified an instance. For more details, see 2.
model
+Type → base.Classifier
+The classifier to boost.
+n_models
+Default → 10
The number of models in the ensemble.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+error_bound
+Default → 0.5
Error bound percentage for allowing models to vote.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import drift
+from river import metrics
+from river import tree
+
+dataset = datasets.Elec2().take(3000)
+
+model = ensemble.BOLEClassifier(
+ model=drift.DriftRetrainingClassifier(
+ model=tree.HoeffdingTreeClassifier(),
+ drift_detector=drift.binary.DDM()
+ ),
+ n_models=10,
+ seed=42
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 93.63%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Oza, N.C., 2005, October. Online bagging and boosting. In 2005 IEEE international conference on systems, man and cybernetics (Vol. 3, pp. 2340-2345). Ieee. ↩
+R. S. M. d. Barros, S. Garrido T. de Carvalho Santos and P. M. Gonçalves Júnior, "A Boosting-like Online Learning Ensemble," 2016 International Joint Conference on Neural Networks (IJCNN), 2016, pp. 1871-1878, doi: 10.1109/IJCNN.2016.7727427. ↩
+Online bootstrap aggregation for classification.
+For each incoming observation, each model's learn_one method is called k times where k is sampled from a Poisson distribution of parameter 1. k thus has a 36% chance of being equal to 0, a 36% chance of being equal to 1, an 18% chance of being equal to 2, a 6% chance of being equal to 3, a 1% chance of being equal to 4, etc. You can do scipy.stats.utils.random.poisson(1).pmf(k) to obtain more detailed values.
model
+Type → base.Classifier
+The classifier to bag.
+n_models
+Default → 10
The number of models in the ensemble.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+In the following example three logistic regressions are bagged together. The performance is +slightly better than when using a single logistic regression.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+
+model = ensemble.BaggingClassifier(
+ model=(
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+ ),
+ n_models=3,
+ seed=42
+)
+
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.65%
+print(model)
+BaggingClassifier(StandardScaler | LogisticRegression)
+Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Averages the predictions of each classifier.
+Parameters
++ + + + + + + + + +
Online bootstrap aggregation for regression.
+For each incoming observation, each model's learn_one method is called k times where k is sampled from a Poisson distribution of parameter 1. k thus has a 36% chance of being equal to 0, a 36% chance of being equal to 1, an 18% chance of being equal to 2, a 6% chance of being equal to 3, a 1% chance of being equal to 4, etc. You can do scipy.stats.utils.random.poisson(1).pmf(k) for more detailed values.
model
+Type → base.Regressor
+The regressor to bag.
+n_models
+Default → 10
The number of models in the ensemble.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+In the following example three logistic regressions are bagged together. The performance is +slightly better than when using a single logistic regression.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+
+model = preprocessing.StandardScaler()
+model |= ensemble.BaggingRegressor(
+ model=linear_model.LinearRegression(intercept_lr=0.1),
+ n_models=3,
+ seed=42
+)
+
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.677586
+Averages the predictions of each regressor.
+Parameters
++ + + + + + + + + +
Exponentially Weighted Average regressor.
+models
+Type → list[base.Regressor]
+The regressors to hedge.
+loss
+Type → optim.losses.RegressionLoss | None
+Default → None
The loss function that has to be minimized. Defaults to optim.losses.Squared.
learning_rate
+Default → 0.5
The learning rate by which the model weights are multiplied at each iteration.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+from river import stream
+
+optimizers = [
+ optim.SGD(0.01),
+ optim.RMSProp(),
+ optim.AdaGrad()
+]
+
+for optimizer in optimizers:
+
+ dataset = datasets.TrumpApproval()
+ metric = metrics.MAE()
+ model = (
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression(
+ optimizer=optimizer,
+ intercept_lr=.1
+ )
+ )
+
+ print(optimizer, evaluate.progressive_val_score(dataset, model, metric))
+SGD MAE: 0.558735
+RMSProp MAE: 0.522449
+AdaGrad MAE: 0.477289
+dataset = datasets.TrumpApproval()
+metric = metrics.MAE()
+hedge = (
+ preprocessing.StandardScaler() |
+ ensemble.EWARegressor(
+ [
+ linear_model.LinearRegression(optimizer=o, intercept_lr=.1)
+ for o in optimizers
+ ],
+ learning_rate=0.005
+ )
+)
+
+evaluate.progressive_val_score(dataset, hedge, metric)
+MAE: 0.496298
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + + +
Leveraging Bagging ensemble classifier.
+Leveraging Bagging [^1] is an improvement over the Oza Bagging algorithm. The bagging performance is leveraged by increasing the re-sampling. It uses a poisson distribution to simulate the re-sampling process. To increase re-sampling it uses a higher w value of the Poisson distribution (agerage number of events), 6 by default, increasing the input space diversity, by attributing a different range of weights to the data samples.
To deal with concept drift, Leveraging Bagging uses the ADWIN algorithm to monitor the performance of each member of the enemble If concept drift is detected, the worst member of the ensemble (based on the error estimation by ADWIN) is replaced by a new (empty) classifier.
+model
+Type → base.Classifier
+The classifier to bag.
+n_models
+Type → int
+Default → 10
The number of models in the ensemble.
+w
+Type → float
+Default → 6
Indicates the average number of events. This is the lambda parameter of the Poisson distribution used to compute the re-sampling weight.
+adwin_delta
+Type → float
+Default → 0.002
The delta parameter for the ADWIN change detector.
+bagging_method
+Type → str
+Default → bag
The bagging method to use. Can be one of the following:
* 'bag' - Leveraging Bagging using ADWIN.
* 'me' - Assigns \(weight=1\) if sample is misclassified, otherwise \(weight=error/(1-error)\).
* 'half' - Use resampling without replacement for half of the instances.
* 'wt' - Resample without taking out all instances.
* 'subag' - Resampling without replacement.
seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+bagging_methods
+Valid bagging_method options.
+models
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+
+model = ensemble.LeveragingBaggingClassifier(
+ model=(
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+ ),
+ n_models=3,
+ seed=42
+)
+
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 88.55%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Averages the predictions of each classifier.
+Parameters
++ + + + + + + + +
Streaming Random Patches ensemble classifier.
+The Streaming Random Patches (SRP) 1 is an ensemble method that simulates bagging or random subspaces. The default algorithm uses both bagging and random subspaces, namely Random Patches. The default base estimator is a Hoeffding Tree, but other base estimators can be used (differently from random forest variations).
+model
+Type → base.Estimator | None
+Default → None
The base estimator.
+n_models
+Type → int
+Default → 10
Number of members in the ensemble.
+subspace_size
+Type → int | float | str
+Default → 0.6
Number of features per subset for each classifier where M is the total number of features.
A negative value means M - subspace_size.
Only applies when using random subspaces or random patches.
* If int indicates the number of features to use. Valid range [2, M].
* If float indicates the percentage of features to use, Valid range (0., 1.].
* 'sqrt' - sqrt(M)+1
* 'rmsqrt' - Residual from M-(sqrt(M)+1)
training_method
+Type → str
+Default → patches
The training method to use.
* 'subspaces' - Random subspaces.
* 'resampling' - Resampling.
* 'patches' - Random patches.
lam
+Type → int
+Default → 6
Lambda value for resampling.
+drift_detector
+Type → base.DriftDetector | None
+Default → None
Drift detector.
+warning_detector
+Type → base.DriftDetector | None
+Default → None
Warning detector.
+disable_detector
+Type → str
+Default → off
Option to disable drift detectors:
* If 'off', detectors are enabled.
* If 'drift', disables concept drift detection and the background learner.
* If 'warning', disables the background learner and ensemble members are reset if drift is detected.
disable_weighted_vote
+Type → bool
+Default → False
If True, disables weighted voting.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+metric
+Type → ClassificationMetric | None
+Default → None
The metric to track members performance within the ensemble. This implementation assumes that larger values are better when using weighted votes.
+from river import ensemble
+from river import evaluate
+from river import metrics
+from river.datasets import synth
+from river import tree
+
+dataset = synth.ConceptDriftStream(
+ seed=42,
+ position=500,
+ width=50
+).take(1000)
+
+base_model = tree.HoeffdingTreeClassifier(
+ grace_period=50, delta=0.01,
+ nominal_attributes=['age', 'car', 'zipcode']
+)
+model = ensemble.SRPClassifier(
+ model=base_model, n_models=3, seed=42,
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 72.77%
+Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
This implementation uses n_models=10 as default given the impact on
+processing time. The optimal number of models depends on the data and
+resources available.
Heitor Murilo Gomes, Jesse Read, Albert Bifet. + Streaming Random Patches for Evolving Data Stream Classification. + IEEE International Conference on Data Mining (ICDM), 2019. ↩
+Streaming Random Patches ensemble regressor.
+The Streaming Random Patches 1 ensemble method for regression trains each base learner on a subset of features and instances from the original data, namely a random patch. This strategy to enforce diverse base models is similar to the one in the random forest, yet it is not restricted to using decision trees as base learner.
+This method is an adaptation of 2 for regression.
+model
+Type → base.Regressor | None
+Default → None
The base estimator.
+n_models
+Type → int
+Default → 10
Number of members in the ensemble.
+subspace_size
+Type → int | float | str
+Default → 0.6
Number of features per subset for each classifier where M is the total number of features.
A negative value means M - subspace_size.
Only applies when using random subspaces or random patches.
* If int indicates the number of features to use. Valid range [2, M].
* If float indicates the percentage of features to use, Valid range (0., 1.].
* 'sqrt' - sqrt(M)+1
* 'rmsqrt' - Residual from M-(sqrt(M)+1)
training_method
+Type → str
+Default → patches
The training method to use.
* 'subspaces' - Random subspaces.
* 'resampling' - Resampling.
* 'patches' - Random patches.
lam
+Type → int
+Default → 6
Lambda value for bagging.
+drift_detector
+Type → base.DriftDetector | None
+Default → None
Drift detector.
+warning_detector
+Type → base.DriftDetector | None
+Default → None
Warning detector.
+disable_detector
+Type → str
+Default → off
Option to disable drift detectors:
* If 'off', detectors are enabled.
* If 'drift', disables concept drift detection and the background learner.
* If 'warning', disables the background learner and ensemble members are reset if drift is detected.
disable_weighted_vote
+Type → bool
+Default → True
If True, disables weighted voting.
+drift_detection_criteria
+Type → str
+Default → error
The criteria used to track drifts.
* 'error' - absolute error.
* 'prediction' - predicted target values.
aggregation_method
+Type → str
+Default → mean
The method to use to aggregate predictions in the ensemble.
* 'mean'
* 'median'
seed
+Default → None
Random number generator seed for reproducibility.
+metric
+Type → RegressionMetric | None
+Default → None
The metric to track members performance within the ensemble.
+from river import ensemble
+from river import evaluate
+from river import metrics
+from river.datasets import synth
+from river import tree
+
+dataset = synth.FriedmanDrift(
+ drift_type='gsg',
+ position=(350, 750),
+ transition_window=200,
+ seed=42
+).take(1000)
+
+base_model = tree.HoeffdingTreeRegressor(grace_period=50)
+model = ensemble.SRPRegressor(
+ model=base_model,
+ training_method="patches",
+ n_models=3,
+ seed=42
+)
+
+metric = metrics.R2()
+
+evaluate.progressive_val_score(dataset, model, metric)
+R2: 0.571117
+Predict the output of features x.
Parameters
+Returns
+The prediction.
++
This implementation uses n_models=10 as default given the impact on
+processing time. The optimal number of models depends on the data and
+resources available.
Heitor Gomes, Jacob Montiel, Saulo Martiello Mastelini, + Bernhard Pfahringer, and Albert Bifet. + On Ensemble Techniques for Data Stream Regression. + IJCNN'20. International Joint Conference on Neural Networks. 2020. ↩
+Heitor Murilo Gomes, Jesse Read, Albert Bifet. + Streaming Random Patches for Evolving Data Stream Classification. + IEEE International Conference on Data Mining (ICDM), 2019. ↩
+Stacking for binary classification.
+models
+Type → list[base.Classifier]
+meta_classifier
+Type → base.Classifier
+include_features
+Default → True
Indicates whether or not the original features should be provided to the meta-model along with the predictions from each model.
+from river import compose
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model as lm
+from river import metrics
+from river import preprocessing as pp
+
+dataset = datasets.Phishing()
+
+model = compose.Pipeline(
+ ('scale', pp.StandardScaler()),
+ ('stack', ensemble.StackingClassifier(
+ [
+ lm.LogisticRegression(),
+ lm.PAClassifier(mode=1, C=0.01),
+ lm.PAClassifier(mode=2, C=0.01),
+ ],
+ meta_classifier=lm.LogisticRegression()
+ ))
+)
+
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 88.14%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Voting classifier.
+A classification is made by aggregating the predictions of each model in the ensemble. The probabilities for each class are summed up if use_probabilities is set to True. If not, the probabilities are ignored and each prediction is weighted the same. In this case, it's important that you use an odd number of classifiers. A random class will be picked if the number of classifiers is even.
models
+Type → list[base.Classifier]
+The classifiers.
+use_probabilities
+Default → True
Whether or to weight each prediction with its associated probability.
+from river import datasets
+from river import ensemble
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import naive_bayes
+from river import preprocessing
+from river import tree
+
+dataset = datasets.Phishing()
+
+model = (
+ preprocessing.StandardScaler() |
+ ensemble.VotingClassifier([
+ linear_model.LogisticRegression(),
+ tree.HoeffdingTreeClassifier(),
+ naive_bayes.GaussianNB()
+ ])
+)
+
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 86.94%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++ + + + + + + + +
A track evaluate a model's performance.
+The following metrics are recorded:
+Time, which should be interpreted with wisdom. Indeed time can depend on the architecture
+and local resource situations. Comparison via FLOPS should be preferred. - The model's memory footprint.
+The model's predictive performance on the track's dataset.
+name
+Type → str
+The name of the track.
+datasets
+The datasets that compose the track.
+metric
+The metric(s) used to track performance.
+Evaluates the performance of a model on a streaming dataset and yields results.
+This does exactly the same as evaluate.progressive_val_score. The only difference is that this function returns an iterator, yielding results at every step. This can be useful if you want to have control over what you do with the results. For instance, you might want to plot the results.
dataset
+Type → base.typing.Dataset
+The stream of observations against which the model will be evaluated.
+model
+The model to evaluate.
+metric
+Type → metrics.base.Metric
+The metric used to evaluate the model's predictions.
+moment
+Type → str | typing.Callable | None
+Default → None
The attribute used for measuring time. If a callable is passed, then it is expected to take as input a dict of features. If None, then the observations are implicitly timestamped in the order in which they arrive.
delay
+Type → str | int | dt.timedelta | typing.Callable | None
+Default → None
The amount to wait before revealing the target associated with each observation to the model. This value is expected to be able to sum with the moment value. For instance, if moment is a datetime.date, then delay is expected to be a datetime.timedelta. If a callable is passed, then it is expected to take as input a dict of features and the target. If a str is passed, then it will be used to access the relevant field from the features. If None is passed, then no delay will be used, which leads to doing standard online validation.
step
+Default → 1
Iteration number at which to yield results. This only takes into account the predictions, and not the training steps.
+measure_time
+Default → False
Whether or not to measure the elapsed time.
+measure_memory
+Default → False
Whether or not to measure the memory usage of the model.
+Take the following model:
+from river import linear_model
+from river import preprocessing
+
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+)
+We can evaluate it on the Phishing dataset as so:
from river import datasets
+from river import evaluate
+from river import metrics
+
+steps = evaluate.iter_progressive_val_score(
+ model=model,
+ dataset=datasets.Phishing(),
+ metric=metrics.ROCAUC(),
+ step=200
+)
+
+for step in steps:
+ print(step)
+{'ROCAUC': ROCAUC: 90.20%, 'Step': 200}
+{'ROCAUC': ROCAUC: 92.25%, 'Step': 400}
+{'ROCAUC': ROCAUC: 93.23%, 'Step': 600}
+{'ROCAUC': ROCAUC: 94.05%, 'Step': 800}
+{'ROCAUC': ROCAUC: 94.79%, 'Step': 1000}
+{'ROCAUC': ROCAUC: 95.07%, 'Step': 1200}
+{'ROCAUC': ROCAUC: 95.07%, 'Step': 1250}
+Evaluates the performance of a model on a streaming dataset.
+This method is the canonical way to evaluate a model's performance. When used correctly, it allows you to exactly assess how a model would have performed in a production scenario.
+dataset is converted into a stream of questions and answers. At each step the model is either asked to predict an observation, or is either updated. The target is only revealed to the model after a certain amount of time, which is determined by the delay parameter. Note that under the hood this uses the stream.simulate_qa function to go through the data in arrival order.
By default, there is no delay, which means that the samples are processed one after the other. When there is no delay, this function essentially performs progressive validation. When there is a delay, then we refer to it as delayed progressive validation.
+It is recommended to use this method when you want to determine a model's performance on a dataset. In particular, it is advised to use the delay parameter in order to get a reliable assessment. Indeed, in a production scenario, it is often the case that ground truths are made available after a certain amount of time. By using this method, you can reproduce this scenario and therefore truthfully assess what would have been the performance of a model on a given dataset.
dataset
+Type → base.typing.Dataset
+The stream of observations against which the model will be evaluated.
+model
+The model to evaluate.
+metric
+Type → metrics.base.Metric
+The metric used to evaluate the model's predictions.
+moment
+Type → str | typing.Callable | None
+Default → None
The attribute used for measuring time. If a callable is passed, then it is expected to take as input a dict of features. If None, then the observations are implicitly timestamped in the order in which they arrive.
delay
+Type → str | int | dt.timedelta | typing.Callable | None
+Default → None
The amount to wait before revealing the target associated with each observation to the model. This value is expected to be able to sum with the moment value. For instance, if moment is a datetime.date, then delay is expected to be a datetime.timedelta. If a callable is passed, then it is expected to take as input a dict of features and the target. If a str is passed, then it will be used to access the relevant field from the features. If None is passed, then no delay will be used, which leads to doing standard online validation.
print_every
+Default → 0
Iteration number at which to print the current metric. This only takes into account the predictions, and not the training steps.
+show_time
+Default → False
Whether or not to display the elapsed time.
+show_memory
+Default → False
Whether or not to display the memory usage of the model.
+print_kwargs
+Extra keyword arguments are passed to the print function. For instance, this allows providing a file argument, which indicates where to output progress.
Take the following model:
+from river import linear_model
+from river import preprocessing
+
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+)
+We can evaluate it on the Phishing dataset as so:
from river import datasets
+from river import evaluate
+from river import metrics
+
+evaluate.progressive_val_score(
+ model=model,
+ dataset=datasets.Phishing(),
+ metric=metrics.ROCAUC(),
+ print_every=200
+)
+[200] ROCAUC: 90.20%
+[400] ROCAUC: 92.25%
+[600] ROCAUC: 93.23%
+[800] ROCAUC: 94.05%
+[1,000] ROCAUC: 94.79%
+[1,200] ROCAUC: 95.07%
+[1,250] ROCAUC: 95.07%
+ROCAUC: 95.07%
+We haven't specified a delay, therefore this is strictly equivalent to the following piece +of code:
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+)
+
+metric = metrics.ROCAUC()
+
+for x, y in datasets.Phishing():
+ y_pred = model.predict_proba_one(x)
+ metric = metric.update(y, y_pred)
+ model = model.learn_one(x, y)
+
+metric
+ROCAUC: 95.07%
+When print_every is specified, the current state is printed at regular intervals. Under
+the hood, Python's print method is being used. You can pass extra keyword arguments to
+modify its behavior. For instance, you may use the file argument if you want to log the
+progress to a file of your choice.
with open('progress.log', 'w') as f:
+ metric = evaluate.progressive_val_score(
+ model=model,
+ dataset=datasets.Phishing(),
+ metric=metrics.ROCAUC(),
+ print_every=200,
+ file=f
+ )
+
+with open('progress.log') as f:
+ for line in f.read().splitlines():
+ print(line)
+[200] ROCAUC: 94.00%
+[400] ROCAUC: 94.70%
+[600] ROCAUC: 95.17%
+[800] ROCAUC: 95.42%
+[1,000] ROCAUC: 95.82%
+[1,200] ROCAUC: 96.00%
+[1,250] ROCAUC: 96.04%
+Note that the performance is slightly better than above because we haven't used a fresh +copy of the model. Instead, we've reused the existing model which has already done a full +pass on the data.
+import os; os.remove('progress.log')
+Field-aware Factorization Machine for binary classification.
+The model equation is defined by:
+Where \(\mathbf{v}_{j, f_{j'}}\) is the latent vector corresponding to \(j\) feature for \(f_{j'}\) field, and \(\mathbf{v}_{j', f_j}\) is the latent vector corresponding to \(j'\) feature for \(f_j\) field.
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables. Field names are inferred from feature names by taking everything before the first underscore: feature_name.split('_')[0].
n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note that the intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+loss
+Type → optim.losses.BinaryLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman', 'time': .12}, True),
+ ({'user': 'Alice', 'item': 'Terminator', 'time': .13}, True),
+ ({'user': 'Alice', 'item': 'Star Wars', 'time': .14}, True),
+ ({'user': 'Alice', 'item': 'Notting Hill', 'time': .15}, False),
+ ({'user': 'Alice', 'item': 'Harry Potter ', 'time': .16}, True),
+ ({'user': 'Bob', 'item': 'Superman', 'time': .13}, True),
+ ({'user': 'Bob', 'item': 'Terminator', 'time': .12}, True),
+ ({'user': 'Bob', 'item': 'Star Wars', 'time': .16}, True),
+ ({'user': 'Bob', 'item': 'Notting Hill', 'time': .10}, False)
+)
+
+model = facto.FFMClassifier(
+ n_factors=10,
+ intercept=.5,
+ seed=42,
+)
+
+for x, y in dataset:
+ model = model.learn_one(x, y)
+
+model.predict_one({'user': 'Bob', 'item': 'Harry Potter', 'time': .14})
+True
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Update the model with a set of features x and a label y.
Parameters
+1.0 Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + + +
Field-aware Factorization Machine for regression.
+The model equation is defined by:
+Where \(\mathbf{v}_{j, f_{j'}}\) is the latent vector corresponding to \(j\) feature for \(f_{j'}\) field, and \(\mathbf{v}_{j', f_j}\) is the latent vector corresponding to \(j'\) feature for \(f_j\) field.
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables. Field names are inferred from feature names by taking everything before the first underscore: feature_name.split('_')[0].
n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note that the intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+loss
+Type → optim.losses.RegressionLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman', 'time': .12}, 8),
+ ({'user': 'Alice', 'item': 'Terminator', 'time': .13}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars', 'time': .14}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill', 'time': .15}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter ', 'time': .16}, 5),
+ ({'user': 'Bob', 'item': 'Superman', 'time': .13}, 8),
+ ({'user': 'Bob', 'item': 'Terminator', 'time': .12}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars', 'time': .16}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill', 'time': .10}, 2)
+)
+
+model = facto.FFMRegressor(
+ n_factors=10,
+ intercept=5,
+ seed=42,
+)
+
+for x, y in dataset:
+ model = model.learn_one(x, y)
+
+model.predict_one({'user': 'Bob', 'item': 'Harry Potter', 'time': .14})
+5.319945
+report = model.debug_one({'user': 'Bob', 'item': 'Harry Potter', 'time': .14})
+
+print(report)
+Name Value Weight Contribution
+ Intercept 1.00000 5.23501 5.23501
+ user_Bob 1.00000 0.11438 0.11438
+ time 0.14000 0.03186 0.00446
+ item_Harry Potter(time) - time(item) 0.14000 0.03153 0.00441
+ user_Bob(time) - time(user) 0.14000 0.02864 0.00401
+ item_Harry Potter 1.00000 0.00000 0.00000
+user_Bob(item) - item_Harry Potter(user) 1.00000 -0.04232 -0.04232
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Fits to a set of features x and a real-valued target y.
Parameters
+1.0 Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + + +
Factorization Machine for binary classification.
+The model equation is defined as:
+Where \(\mathbf{v}_j\) and \(\mathbf{v}_{j'}\) are \(j\) and \(j'\) latent vectors, respectively.
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables.
+n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note that the intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+loss
+Type → optim.losses.BinaryLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, True),
+ ({'user': 'Alice', 'item': 'Terminator'}, True),
+ ({'user': 'Alice', 'item': 'Star Wars'}, True),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, False),
+ ({'user': 'Alice', 'item': 'Harry Potter '}, True),
+ ({'user': 'Bob', 'item': 'Superman'}, True),
+ ({'user': 'Bob', 'item': 'Terminator'}, True),
+ ({'user': 'Bob', 'item': 'Star Wars'}, True),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, False)
+)
+
+model = facto.FMClassifier(
+ n_factors=10,
+ seed=42,
+)
+
+for x, y in dataset:
+ _ = model.learn_one(x, y)
+
+model.predict_one({'Bob': 1, 'Harry Potter': 1})
+True
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Update the model with a set of features x and a label y.
Parameters
+1.0 Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + + +
Factorization Machine for regression.
+The model equation is defined as:
+Where \(\mathbf{v}_j\) and \(\mathbf{v}_{j'}\) are \(j\) and \(j'\) latent vectors, respectively.
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables.
+n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note that the intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+loss
+Type → optim.losses.RegressionLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, 8),
+ ({'user': 'Alice', 'item': 'Terminator'}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars'}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter '}, 5),
+ ({'user': 'Bob', 'item': 'Superman'}, 8),
+ ({'user': 'Bob', 'item': 'Terminator'}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars'}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, 2)
+)
+
+model = facto.FMRegressor(
+ n_factors=10,
+ intercept=5,
+ seed=42,
+)
+
+for x, y in dataset:
+ _ = model.learn_one(x, y)
+
+model.predict_one({'Bob': 1, 'Harry Potter': 1})
+5.236504
+report = model.debug_one({'Bob': 1, 'Harry Potter': 1})
+
+print(report)
+Name Value Weight Contribution
+ Intercept 1.00000 5.23426 5.23426
+Bob - Harry Potter 1.00000 0.00224 0.00224
+ Harry Potter 1.00000 0.00000 0.00000
+ Bob 1.00000 0.00000 0.00000
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Fits to a set of features x and a real-valued target y.
Parameters
+1.0 Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + + +
Field-weighted Factorization Machine for binary classification.
+The model equation is defined as:
+Where \(f_j\) and \(f_{j'}\) are \(j\) and \(j'\) fields, respectively, and \(\mathbf{v}_j\) and \(\mathbf{v}_{j'}\) are \(j\) and \(j'\) latent vectors, respectively.
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables. Field names are inferred from feature names by taking everything before the first underscore: feature_name.split('_')[0].
n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note that the intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+int_weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the field pairs interaction weights.
+loss
+Type → optim.losses.BinaryLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+interaction_weights
+The current interaction strengths of field pairs.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, True),
+ ({'user': 'Alice', 'item': 'Terminator'}, True),
+ ({'user': 'Alice', 'item': 'Star Wars'}, True),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, False),
+ ({'user': 'Alice', 'item': 'Harry Potter '}, True),
+ ({'user': 'Bob', 'item': 'Superman'}, True),
+ ({'user': 'Bob', 'item': 'Terminator'}, True),
+ ({'user': 'Bob', 'item': 'Star Wars'}, True),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, False)
+)
+
+model = facto.FwFMClassifier(
+ n_factors=10,
+ seed=42,
+)
+
+for x, y in dataset:
+ model = model.learn_one(x, y)
+
+model.predict_one({'Bob': 1, 'Harry Potter': 1})
+True
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Update the model with a set of features x and a label y.
Parameters
+1.0 Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Junwei Pan, Jian Xu, Alfonso Lobos Ruiz, Wenliang Zhao, Shengjun Pan, Yu Sun, and Quan Lu, 2018, April. Field-weighted Factorization Machines for Click-Through Rate Prediction in Display Advertising. In Proceedings of the 2018 World Wide Web Conference on World Wide Web. International World Wide Web Conferences Steering Committee, (pp. 1349–1357). ↩
+Field-weighted Factorization Machine for regression.
+The model equation is defined as:
+Where \(f_j\) and \(f_{j'}\) are \(j\) and \(j'\) fields, respectively, and \(\mathbf{v}_j\) and \(\mathbf{v}_{j'}\) are \(j\) and \(j'\) latent vectors, respectively.
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables. Field names are inferred from feature names by taking everything before the first underscore: feature_name.split('_')[0].
n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note that the intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+int_weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the field pairs interaction weights.
+loss
+Type → optim.losses.RegressionLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+interaction_weights
+The current interaction strengths of field pairs.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, 8),
+ ({'user': 'Alice', 'item': 'Terminator'}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars'}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter '}, 5),
+ ({'user': 'Bob', 'item': 'Superman'}, 8),
+ ({'user': 'Bob', 'item': 'Terminator'}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars'}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, 2)
+)
+
+model = facto.FwFMRegressor(
+ n_factors=10,
+ intercept=5,
+ seed=42,
+)
+
+for x, y in dataset:
+ model = model.learn_one(x, y)
+
+model.predict_one({'Bob': 1, 'Harry Potter': 1})
+5.236501
+report = model.debug_one({'Bob': 1, 'Harry Potter': 1})
+
+print(report)
+Name Value Weight Contribution
+ Intercept 1.00000 5.23426 5.23426
+Bob(Harry Potter) - Harry Potter(Bob) 1.00000 0.00224 0.00224
+ Harry Potter 1.00000 0.00000 0.00000
+ Bob 1.00000 0.00000 0.00000
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Fits to a set of features x and a real-valued target y.
Parameters
+1.0 Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++
Junwei Pan, Jian Xu, Alfonso Lobos Ruiz, Wenliang Zhao, Shengjun Pan, Yu Sun, and Quan Lu, 2018, April. Field-weighted Factorization Machines for Click-Through Rate Prediction in Display Advertising. In Proceedings of the 2018 World Wide Web Conference on World Wide Web. International World Wide Web Conferences Steering Committee, (pp. 1349–1357). ↩
+Higher-Order Factorization Machine for binary classification.
+The model equation is defined as:
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables.
+degree
+Default → 3
Polynomial degree or model order.
+n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note that the intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+loss
+Type → optim.losses.BinaryLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman', 'time': .12}, True),
+ ({'user': 'Alice', 'item': 'Terminator', 'time': .13}, True),
+ ({'user': 'Alice', 'item': 'Star Wars', 'time': .14}, True),
+ ({'user': 'Alice', 'item': 'Notting Hill', 'time': .15}, False),
+ ({'user': 'Alice', 'item': 'Harry Potter ', 'time': .16}, True),
+ ({'user': 'Bob', 'item': 'Superman', 'time': .13}, True),
+ ({'user': 'Bob', 'item': 'Terminator', 'time': .12}, True),
+ ({'user': 'Bob', 'item': 'Star Wars', 'time': .16}, True),
+ ({'user': 'Bob', 'item': 'Notting Hill', 'time': .10}, False)
+)
+
+model = facto.HOFMClassifier(
+ degree=3,
+ n_factors=10,
+ intercept=.5,
+ seed=42,
+)
+
+for x, y in dataset:
+ _ = model.learn_one(x, y)
+
+model.predict_one({'user': 'Bob', 'item': 'Harry Potter', 'time': .14})
+True
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Update the model with a set of features x and a label y.
Parameters
+1.0 Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + + +
Higher-Order Factorization Machine for regression.
+The model equation is defined as:
+For more efficiency, this model automatically one-hot encodes strings features considering them as categorical variables.
+degree
+Default → 3
Polynomial degree or model order.
+n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+weight_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the feature weights. Note thatthe intercept is handled separately.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+loss
+Type → optim.losses.RegressionLoss | None
+Default → None
The loss function to optimize for.
+sample_normalization
+Default → False
Whether to divide each element of x by x's L2-norm.
l1_weight
+Default → 0.0
Amount of L1 regularization used to push weights towards 0.
+l2_weight
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+l1_latent
+Default → 0.0
Amount of L1 regularization used to push latent weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+intercept
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. An instance of optim.schedulers.Constant is used if a float is passed. No intercept will be used if this is set to 0.
weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme. Defaults to optim.initializers.Zeros()`.
latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme. Defaults to optim.initializers.Normal(mu=.0, sigma=.1, random_state=self.random_state)`.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Type → int | None
+Default → None
Randomization seed used for reproducibility.
+weights
+The current weights assigned to the features.
+latents
+The current latent weights assigned to the features.
+from river import facto
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman', 'time': .12}, 8),
+ ({'user': 'Alice', 'item': 'Terminator', 'time': .13}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars', 'time': .14}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill', 'time': .15}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter ', 'time': .16}, 5),
+ ({'user': 'Bob', 'item': 'Superman', 'time': .13}, 8),
+ ({'user': 'Bob', 'item': 'Terminator', 'time': .12}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars', 'time': .16}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill', 'time': .10}, 2)
+)
+
+model = facto.HOFMRegressor(
+ degree=3,
+ n_factors=10,
+ intercept=5,
+ seed=42,
+)
+
+for x, y in dataset:
+ _ = model.learn_one(x, y)
+
+model.predict_one({'user': 'Bob', 'item': 'Harry Potter', 'time': .14})
+5.311745
+report = model.debug_one({'user': 'Bob', 'item': 'Harry Potter', 'time': .14})
+
+print(report)
+Name Value Weight Contribution
+ Intercept 1.00000 5.23495 5.23495
+ user_Bob 1.00000 0.11436 0.11436
+ time 0.14000 0.03185 0.00446
+ user_Bob - time 0.14000 0.00884 0.00124
+user_Bob - item_Harry Potter - time 0.14000 0.00117 0.00016
+ item_Harry Potter 1.00000 0.00000 0.00000
+ item_Harry Potter - time 0.14000 -0.00695 -0.00097
+ user_Bob - item_Harry Potter 1.00000 -0.04246 -0.04246
+Debugs the output of the FM regressor.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Fits to a set of features x and a real-valued target y.
Parameters
+1.0 Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + + +
Computes a streaming aggregate.
+This transformer allows to compute an aggregate statistic, very much like the groupby method from pandas, but on a streaming dataset. This makes use of the streaming statistics from the stats module.
When learn_one is called, the running statistic how of group by is updated with the value of on. Meanwhile, the output of transform_one is a single-element dictionary, where the key is the name of the aggregate and the value is the current value of the statistic for the relevant group. The key is automatically inferred from the parameters.
Note that you can use a compose.TransformerUnion to extract many aggregate statistics in a concise manner.
on
+Type → str
+The feature on which to compute the aggregate statistic.
+by
+Type → str | list[str] | None
+The feature by which to group the data. All the data is included in the aggregate if this is None.
how
+Type → stats.base.Univariate | utils.Rolling | utils.TimeRolling
+The statistic to compute.
+state
+Return the current values for each group as a series.
+Consider the following dataset:
+X = [
+ {'country': 'France', 'place': 'Taco Bell', 'revenue': 42},
+ {'country': 'Sweden', 'place': 'Burger King', 'revenue': 16},
+ {'country': 'France', 'place': 'Burger King', 'revenue': 24},
+ {'country': 'Sweden', 'place': 'Taco Bell', 'revenue': 58},
+ {'country': 'Sweden', 'place': 'Burger King', 'revenue': 20},
+ {'country': 'France', 'place': 'Taco Bell', 'revenue': 50},
+ {'country': 'France', 'place': 'Burger King', 'revenue': 10},
+ {'country': 'Sweden', 'place': 'Taco Bell', 'revenue': 80}
+]
+As an example, we can calculate the average (how) revenue (on) for each place (by):
+from river import feature_extraction as fx
+from river import stats
+
+agg = fx.Agg(
+ on='revenue',
+ by='place',
+ how=stats.Mean()
+)
+
+for x in X:
+ agg = agg.learn_one(x)
+ print(agg.transform_one(x))
+{'revenue_mean_by_place': 42.0}
+{'revenue_mean_by_place': 16.0}
+{'revenue_mean_by_place': 20.0}
+{'revenue_mean_by_place': 50.0}
+{'revenue_mean_by_place': 20.0}
+{'revenue_mean_by_place': 50.0}
+{'revenue_mean_by_place': 17.5}
+{'revenue_mean_by_place': 57.5}
+You can compute an aggregate over multiple keys by passing a tuple to the by argument.
+For instance, we can compute the maximum (how) revenue (on) per place as well as per
+day (by):
agg = fx.Agg(
+ on='revenue',
+ by=['place', 'country'],
+ how=stats.Max()
+)
+
+for x in X:
+ agg = agg.learn_one(x)
+ print(agg.transform_one(x))
+{'revenue_max_by_place_and_country': 42}
+{'revenue_max_by_place_and_country': 16}
+{'revenue_max_by_place_and_country': 24}
+{'revenue_max_by_place_and_country': 58}
+{'revenue_max_by_place_and_country': 20}
+{'revenue_max_by_place_and_country': 50}
+{'revenue_max_by_place_and_country': 24}
+{'revenue_max_by_place_and_country': 80}
+You can use a compose.TransformerUnion in order to calculate multiple aggregates in one
+go. The latter can be constructed by using the + operator:
agg = (
+ fx.Agg(on='revenue', by='place', how=stats.Mean()) +
+ fx.Agg(on='revenue', by=['place', 'country'], how=stats.Max())
+)
+
+import pprint
+for x in X:
+ agg = agg.learn_one(x)
+ pprint.pprint(agg.transform_one(x))
+{'revenue_max_by_place_and_country': 42, 'revenue_mean_by_place': 42.0}
+{'revenue_max_by_place_and_country': 16, 'revenue_mean_by_place': 16.0}
+{'revenue_max_by_place_and_country': 24, 'revenue_mean_by_place': 20.0}
+{'revenue_max_by_place_and_country': 58, 'revenue_mean_by_place': 50.0}
+{'revenue_max_by_place_and_country': 20, 'revenue_mean_by_place': 20.0}
+{'revenue_max_by_place_and_country': 50, 'revenue_mean_by_place': 50.0}
+{'revenue_max_by_place_and_country': 24, 'revenue_mean_by_place': 17.5}
+{'revenue_max_by_place_and_country': 80, 'revenue_mean_by_place': 57.5}
+The state property returns a pandas.Series, which can be useful for visualizing the
+current state.
agg[0].state
+Taco Bell 57.5
+Burger King 17.5
+Name: revenue_mean_by_place, dtype: float64
+agg[1].state
+place country
+Taco Bell France 50
+Burger King Sweden 20
+ France 24
+Taco Bell Sweden 80
+Name: revenue_max_by_place_and_country, dtype: int64
+This transformer can also be used in conjunction with utils.TimeRolling. The latter requires
+a t argument, which is a timestamp that indicates when the current row was observed. For
+instance, we can calculate the average (how) revenue (on) for each place (by) over the last
+7 days (t):
import datetime as dt
+import random
+import string
+from river import utils
+
+agg = fx.Agg(
+ on="value",
+ by="group",
+ how=utils.TimeRolling(stats.Mean(), dt.timedelta(days=7))
+)
+
+for day in range(366):
+ g = random.choice(string.ascii_lowercase)
+ x = {
+ "group": g,
+ "value": string.ascii_lowercase.index(g) + random.random(),
+ }
+ t = dt.datetime(2023, 1, 1) + dt.timedelta(days=day)
+ agg = agg.learn_one(x, t=t)
+
+len(agg.state)
+26
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+None Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++
Counts tokens in sentences.
+This transformer can be used to counts tokens in a given piece of text. It takes care of normalizing the text before tokenizing it. In mini-batch settings, this transformers allows to convert a series of pandas of text into sparse dataframe.
+Note that the parameters are identical to those of feature_extraction.TFIDF.
on
+Type → str | None
+Default → None
The name of the feature that contains the text to vectorize. If None, then each learn_one and transform_one will assume that each x that is provided is a str, andnot a dict.
strip_accents
+Default → True
Whether or not to strip accent characters.
+lowercase
+Default → True
Whether or not to convert all characters to lowercase.
+preprocessor
+Type → typing.Callable | None
+Default → None
An optional preprocessing function which overrides the strip_accents and lowercase steps, while preserving the tokenizing and n-grams generation steps.
stop_words
+Type → set[str] | None
+Default → None
An optional set of tokens to remove.
+tokenizer_pattern
+Default → (?u)\b\w[\w\-]+\b
The tokenization pattern which is used when no tokenizer function is passed. A single capture group may optionally be specified.
tokenizer
+Type → typing.Callable | None
+Default → None
A function used to convert preprocessed text into a dict of tokens. By default, a regex formula that works well in most cases is used.
ngram_range
+Default → (1, 1)
The lower and upper boundary of the range n-grams to be extracted. All values of n such that min_n <= n <= max_n will be used. For example an ngram_range of (1, 1) means only unigrams, (1, 2) means unigrams and bigrams, and (2, 2) means only bigrams.
By default, BagOfWords will take as input a sentence, preprocess it, tokenize the
+preprocessed text, and then return a collections.Counter containing the number of
+occurrences of each token.
from river import feature_extraction as fx
+
+corpus = [
+ 'This is the first document.',
+ 'This document is the second document.',
+ 'And this is the third one.',
+ 'Is this the first document?',
+]
+
+bow = fx.BagOfWords()
+
+for sentence in corpus:
+ print(bow.transform_one(sentence))
+{'this': 1, 'is': 1, 'the': 1, 'first': 1, 'document': 1}
+{'this': 1, 'document': 2, 'is': 1, 'the': 1, 'second': 1}
+{'and': 1, 'this': 1, 'is': 1, 'the': 1, 'third': 1, 'one': 1}
+{'is': 1, 'this': 1, 'the': 1, 'first': 1, 'document': 1}
+Note that learn_one does not have to be called because BagOfWords is stateless. You can
+call it but it won't do anything.
In the above example, a string is passed to transform_one. You can also indicate which
+field to access if the string is stored in a dictionary:
bow = fx.BagOfWords(on='sentence')
+
+for sentence in corpus:
+ x = {'sentence': sentence}
+ print(bow.transform_one(x))
+{'this': 1, 'is': 1, 'the': 1, 'first': 1, 'document': 1}
+{'this': 1, 'document': 2, 'is': 1, 'the': 1, 'second': 1}
+{'and': 1, 'this': 1, 'is': 1, 'the': 1, 'third': 1, 'one': 1}
+{'is': 1, 'this': 1, 'the': 1, 'first': 1, 'document': 1}
+The ngram_range parameter can be used to extract n-grams (including unigrams):
ngrammer = fx.BagOfWords(ngram_range=(1, 2))
+
+ngrams = ngrammer.transform_one('I love the smell of napalm in the morning')
+for ngram, count in ngrams.items():
+ print(ngram, count)
+love 1
+the 2
+smell 1
+of 1
+napalm 1
+in 1
+morning 1
+('love', 'the') 1
+('the', 'smell') 1
+('smell', 'of') 1
+('of', 'napalm') 1
+('napalm', 'in') 1
+('in', 'the') 1
+('the', 'morning') 1
+BagOfWord allows to build a term-frequency pandas sparse dataframe with the transform_many method.
import pandas as pd
+X = pd.Series(['Hello world', 'Hello River'], index = ['river', 'rocks'])
+bow = fx.BagOfWords()
+bow.transform_many(X=X)
+ hello world river
+river 1 1 0
+rocks 1 0 1
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform pandas series of string into term-frequency pandas sparse dataframe.
+Parameters
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Polynomial feature extender.
+Generate features consisting of all polynomial combinations of the features with degree less than or equal to the specified degree.
+Be aware that the number of outputted features scales polynomially in the number of input features and exponentially in the degree. High degrees can cause overfitting.
+degree
+Default → 2
The maximum degree of the polynomial features.
+interaction_only
+Default → False
If True then only combinations that include an element at most once will be computed.
include_bias
+Default → False
Whether or not to include a dummy feature which is always equal to 1.
+bias_name
+Default → bias
Name to give to the bias feature.
+from river import feature_extraction as fx
+
+X = [
+ {'x': 0, 'y': 1},
+ {'x': 2, 'y': 3},
+ {'x': 4, 'y': 5}
+]
+
+poly = fx.PolynomialExtender(degree=2, include_bias=True)
+for x in X:
+ print(poly.transform_one(x))
+{'x': 0, 'y': 1, 'x*x': 0, 'x*y': 0, 'y*y': 1, 'bias': 1}
+{'x': 2, 'y': 3, 'x*x': 4, 'x*y': 6, 'y*y': 9, 'bias': 1}
+{'x': 4, 'y': 5, 'x*x': 16, 'x*y': 20, 'y*y': 25, 'bias': 1}
+X = [
+ {'x': 0, 'y': 1, 'z': 2},
+ {'x': 2, 'y': 3, 'z': 2},
+ {'x': 4, 'y': 5, 'z': 2}
+]
+
+poly = fx.PolynomialExtender(degree=3, interaction_only=True)
+for x in X:
+ print(poly.transform_one(x))
+{'x': 0, 'y': 1, 'z': 2, 'x*y': 0, 'x*z': 0, 'y*z': 2, 'x*y*z': 0}
+{'x': 2, 'y': 3, 'z': 2, 'x*y': 6, 'x*z': 4, 'y*z': 6, 'x*y*z': 12}
+{'x': 4, 'y': 5, 'z': 2, 'x*y': 20, 'x*z': 8, 'y*z': 10, 'x*y*z': 40}
+Polynomial features are typically used for a linear model to capture interactions between +features. This may done by setting up a pipeline, as so:
+from river import datasets
+from river import evaluate
+from river import linear_model as lm
+from river import metrics
+from river import preprocessing as pp
+
+dataset = datasets.Phishing()
+
+model = (
+ fx.PolynomialExtender() |
+ pp.StandardScaler() |
+ lm.LogisticRegression()
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 88.88%
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Extracts random features which approximate an RBF kernel.
+This is a powerful way to give non-linear capacity to linear classifiers. This method is also called "random Fourier features" in the literature.
+gamma
+Default → 1.0
RBF kernel parameter in (-gamma * x^2).
n_components
+Default → 100
Number of samples per original feature. Equals the dimensionality of the computed feature space.
+seed
+Type → int | None
+Default → None
Random number seed.
+from river import feature_extraction as fx
+from river import linear_model as lm
+from river import optim
+from river import stream
+
+X = [[0, 0], [1, 1], [1, 0], [0, 1]]
+Y = [0, 0, 1, 1]
+
+model = lm.LogisticRegression(optimizer=optim.SGD(.1))
+
+for x, y in stream.iter_array(X, Y):
+ model = model.learn_one(x, y)
+ y_pred = model.predict_one(x)
+ print(y, int(y_pred))
+0 0
+0 0
+1 0
+1 1
+model = (
+ fx.RBFSampler(seed=3) |
+ lm.LogisticRegression(optimizer=optim.SGD(.1))
+)
+
+for x, y in stream.iter_array(X, Y):
+ model = model.learn_one(x, y)
+ y_pred = model.predict_one(x)
+ print(y, int(y_pred))
+0 0
+0 0
+1 1
+1 1
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+None Returns
+dict: The transformed values.
++ + + + + + + + + +
Computes TF-IDF values from sentences.
+The TF-IDF formula is the same one as scikit-learn. The only difference is the fact that the document frequencies are determined online, whereas in a batch setting they can be determined by performing an initial pass through the data.
+Note that the parameters are identical to those of feature_extraction.BagOfWords.
normalize
+Default → True
Whether or not the TF-IDF values by their L2 norm.
+on
+Type → str | None
+Default → None
The name of the feature that contains the text to vectorize. If None, then the input is treated as a document instead of a set of features.
strip_accents
+Default → True
Whether or not to strip accent characters.
+lowercase
+Default → True
Whether or not to convert all characters to lowercase.
+preprocessor
+Type → typing.Callable | None
+Default → None
An optional preprocessing function which overrides the strip_accents and lowercase steps, while preserving the tokenizing and n-grams generation steps.
tokenizer
+Type → typing.Callable | None
+Default → None
A function used to convert preprocessed text into a dict of tokens. By default, a regex formula that works well in most cases is used.
ngram_range
+Default → (1, 1)
The lower and upper boundary of the range n-grams to be extracted. All values of n such that min_n <= n <= max_n will be used. For example an ngram_range of (1, 1) means only unigrams, (1, 2) means unigrams and bigrams, and (2, 2) means only bigrams. Only works if tokenizer is not set to False.
dfs (collections.defaultdict))
+Document counts.
+n (int)
+Number of scanned documents.
+from river import feature_extraction
+
+tfidf = feature_extraction.TFIDF()
+
+corpus = [
+ 'This is the first document.',
+ 'This document is the second document.',
+ 'And this is the third one.',
+ 'Is this the first document?',
+]
+
+for sentence in corpus:
+ tfidf = tfidf.learn_one(sentence)
+ print(tfidf.transform_one(sentence))
+{'this': 0.447, 'is': 0.447, 'the': 0.447, 'first': 0.447, 'document': 0.447}
+{'this': 0.333, 'document': 0.667, 'is': 0.333, 'the': 0.333, 'second': 0.469}
+{'and': 0.497, 'this': 0.293, 'is': 0.293, 'the': 0.293, 'third': 0.497, 'one': 0.497}
+{'is': 0.384, 'this': 0.384, 'the': 0.384, 'first': 0.580, 'document': 0.469}
+In the above example, a string is passed to transform_one. You can also indicate which
+field to access if the string is stored in a dictionary:
tfidf = feature_extraction.TFIDF(on='sentence')
+
+for sentence in corpus:
+ x = {'sentence': sentence}
+ tfidf = tfidf.learn_one(x)
+ print(tfidf.transform_one(x))
+{'this': 0.447, 'is': 0.447, 'the': 0.447, 'first': 0.447, 'document': 0.447}
+{'this': 0.333, 'document': 0.667, 'is': 0.333, 'the': 0.333, 'second': 0.469}
+{'and': 0.497, 'this': 0.293, 'is': 0.293, 'the': 0.293, 'third': 0.497, 'one': 0.497}
+{'is': 0.384, 'this': 0.384, 'the': 0.384, 'first': 0.580, 'document': 0.469}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform pandas series of string into term-frequency pandas sparse dataframe.
+Parameters
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Computes a streaming aggregate of the target values.
+This transformer is identical to feature_extraction.Agg, the only difference is that it operates on the target rather than on a feature. At each step, the running statistic how of target values in group by is updated with the target. It is therefore a supervised transformer.
by
+Type → str | list[str] | None
+The feature by which to group the target values. All the data is included in the aggregate if this is None.
how
+Type → stats.base.Univariate | utils.Rolling | utils.TimeRolling
+The statistic to compute.
+target_name
+Default → y
The target name which is used in the result.
+state
+Return the current values for each group as a series.
+target_name
+Consider the following dataset, where the second value of each value is the target:
+dataset = [
+ ({'country': 'France', 'place': 'Taco Bell'}, 42),
+ ({'country': 'Sweden', 'place': 'Burger King'}, 16),
+ ({'country': 'France', 'place': 'Burger King'}, 24),
+ ({'country': 'Sweden', 'place': 'Taco Bell'}, 58),
+ ({'country': 'Sweden', 'place': 'Burger King'}, 20),
+ ({'country': 'France', 'place': 'Taco Bell'}, 50),
+ ({'country': 'France', 'place': 'Burger King'}, 10),
+ ({'country': 'Sweden', 'place': 'Taco Bell'}, 80)
+]
+As an example, let's perform a target encoding of the place feature. Instead of simply
+updating a running average, we use a stats.BayesianMean which allows us to incorporate
+some prior knowledge. This makes subsequent models less prone to overfitting. Indeed, it
+dampens the fact that too few samples might have been seen within a group.
from river import feature_extraction
+from river import stats
+
+agg = feature_extraction.TargetAgg(
+ by='place',
+ how=stats.BayesianMean(
+ prior=3,
+ prior_weight=1
+ )
+)
+
+for x, y in dataset:
+ print(agg.transform_one(x))
+ agg = agg.learn_one(x, y)
+{'y_bayes_mean_by_place': 3.0}
+{'y_bayes_mean_by_place': 3.0}
+{'y_bayes_mean_by_place': 9.5}
+{'y_bayes_mean_by_place': 22.5}
+{'y_bayes_mean_by_place': 14.333}
+{'y_bayes_mean_by_place': 34.333}
+{'y_bayes_mean_by_place': 15.75}
+{'y_bayes_mean_by_place': 38.25}
+Just like with feature_extraction.Agg, we can specify multiple features on which to
+group the data:
agg = feature_extraction.TargetAgg(
+ by=['place', 'country'],
+ how=stats.BayesianMean(
+ prior=3,
+ prior_weight=1
+ )
+)
+
+for x, y in dataset:
+ print(agg.transform_one(x))
+ agg = agg.learn_one(x, y)
+{'y_bayes_mean_by_place_and_country': 3.0}
+{'y_bayes_mean_by_place_and_country': 3.0}
+{'y_bayes_mean_by_place_and_country': 3.0}
+{'y_bayes_mean_by_place_and_country': 3.0}
+{'y_bayes_mean_by_place_and_country': 9.5}
+{'y_bayes_mean_by_place_and_country': 22.5}
+{'y_bayes_mean_by_place_and_country': 13.5}
+{'y_bayes_mean_by_place_and_country': 30.5}
+agg.state
+place country
+Taco Bell France 31.666667
+Burger King Sweden 13.000000
+ France 12.333333
+Taco Bell Sweden 47.000000
+Name: y_bayes_mean_by_place_and_country, dtype: float64
+This transformer can also be used in conjunction with utils.TimeRolling. The latter requires
+a t argument, which is a timestamp that indicates when the current row was observed. For
+instance, we can calculate the average (how) revenue (on) for each place (by) over the last
+7 days (t):
import datetime as dt
+import random
+import string
+from river import utils
+
+agg = feature_extraction.TargetAgg(
+ by="group",
+ how=utils.TimeRolling(stats.Mean(), dt.timedelta(days=7))
+)
+
+for day in range(366):
+ g = random.choice(string.ascii_lowercase)
+ x = {"group": g}
+ y = string.ascii_lowercase.index(g) + random.random()
+ t = dt.datetime(2023, 1, 1) + dt.timedelta(days=day)
+ agg = agg.learn_one(x, y, t=t)
+Update with a set of features x and a target y.
Parameters
+None Returns
+SupervisedTransformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
+Randomly selects features with an inclusion trial.
+When a new feature is encountered, it is selected with probability p. The number of times a feature needs to beseen before it is added to the model follows a geometric distribution with expected value 1 / p. This feature selection method is meant to be used when you have a very large amount of sparse features.
p
+Type → float
+Probability of including a feature the first time it is encountered.
+seed
+Type → int | None
+Default → None
Random seed value used for reproducibility.
+from river import datasets
+from river import feature_selection
+from river import stream
+
+selector = feature_selection.PoissonInclusion(p=0.1, seed=42)
+
+dataset = iter(datasets.TrumpApproval())
+
+feature_names = next(dataset)[0].keys()
+n = 0
+
+while True:
+ x, y = next(dataset)
+ xt = selector.transform_one(x)
+ if xt.keys() == feature_names:
+ break
+ n += 1
+
+n
+12
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++
McMahan, H.B., Holt, G., Sculley, D., Young, M., Ebner, D., Grady, J., Nie, L., Phillips, T., Davydov, E., Golovin, D. and Chikkerur, S., 2013, August. Ad click prediction: a view from the trenches. In Proceedings of the 19th ACM SIGKDD international conference on Knowledge discovery and data mining (pp. 1222-1230) ↩
+Removes all but the \(k\) highest scoring features.
+similarity
+Type → stats.base.Bivariate
+k
+Default → 10
The number of features to keep.
+similarities (dict)
+The similarity instances used for each feature.
+leaderboard (dict)
+The actual similarity measures.
+from pprint import pprint
+from river import feature_selection
+from river import stats
+from river import stream
+from sklearn import datasets
+
+X, y = datasets.make_regression(
+ n_samples=100,
+ n_features=10,
+ n_informative=2,
+ random_state=42
+)
+
+selector = feature_selection.SelectKBest(
+ similarity=stats.PearsonCorr(),
+ k=2
+)
+
+for xi, yi, in stream.iter_array(X, y):
+ selector = selector.learn_one(xi, yi)
+
+pprint(selector.leaderboard)
+Counter({9: 0.7898,
+ 7: 0.5444,
+ 8: 0.1062,
+ 2: 0.0638,
+ 4: 0.0538,
+ 5: 0.0271,
+ 1: -0.0312,
+ 6: -0.0657,
+ 3: -0.1501,
+ 0: -0.1895})
+selector.transform_one(xi)
+{7: -1.2795, 9: -1.8408}
+Update with a set of features x and a target y.
Parameters
+Returns
+SupervisedTransformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Removes low-variance features.
+threshold
+Default → 0
Only features with a variance above the threshold will be kept.
+min_samples
+Default → 2
The minimum number of samples required to perform selection.
+variances (dict)
+The variance of each feature.
+from river import feature_selection
+from river import stream
+
+X = [
+ [0, 2, 0, 3],
+ [0, 1, 4, 3],
+ [0, 1, 1, 3]
+]
+
+selector = feature_selection.VarianceThreshold()
+
+for x, _ in stream.iter_array(X):
+ print(selector.learn_one(x).transform_one(x))
+{0: 0, 1: 2, 2: 0, 3: 3}
+{1: 1, 2: 4}
+{1: 1, 2: 1}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Aggregated Mondrian Forest classifier for online learning.
+This implementation is truly online1, in the sense that a single pass is performed, and that predictions can be produced anytime.
+Each node in a tree predicts according to the distribution of the labels it contains. This distribution is regularized using a "Jeffreys" prior with parameter dirichlet. For each class with count labels in the node and n_samples samples in it, the prediction of a node is given by
\(\frac{count + dirichlet}{n_{samples} + dirichlet \times n_{classes}}\).
+The prediction for a sample is computed as the aggregated predictions of all the subtrees along the path leading to the leaf node containing the sample. The aggregation weights are exponential weights with learning rate step and log-loss when use_aggregation is True.
This computation is performed exactly thanks to a context tree weighting algorithm. More details can be found in the paper cited in the references below.
+The final predictions are the average class probabilities predicted by each of the n_estimators trees in the forest.
n_estimators
+Type → int
+Default → 10
The number of trees in the forest.
+step
+Type → float
+Default → 1.0
Step-size for the aggregation weights. Default is 1 for classification with the log-loss, which is usually the best choice.
+use_aggregation
+Type → bool
+Default → True
Controls if aggregation is used in the trees. It is highly recommended to leave it as True.
dirichlet
+Type → float
+Default → 0.5
Regularization level of the class frequencies used for predictions in each node. A rule of thumb is to set this to 1 / n_classes, where n_classes is the expected number of classes which might appear. Default is dirichlet = 0.5, which works well for binary classification problems.
split_pure
+Type → bool
+Default → False
Controls if nodes that contains only sample of the same class should be split ("pure" nodes). Default is False, namely pure nodes are not split, but True can be sometimes better.
seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+from river import datasets
+from river import evaluate
+from river import forest
+from river import metrics
+
+dataset = datasets.Bananas().take(500)
+
+model = forest.AMFClassifier(
+ n_estimators=10,
+ use_aggregation=True,
+ dirichlet=0.5,
+ seed=1
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 85.37%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Only log_loss used for the computation of the aggregation weights is supported for now, namely +the log-loss for multi-class classification.
+Mourtada, J., Gaïffas, S., & Scornet, E. (2021). AMF: Aggregated Mondrian forests for online +learning. Journal of the Royal Statistical Society Series B: Statistical Methodology, 83(3), 505-533. ↩
+Aggregated Mondrian Forest regressor for online learning.
+This algorithm is truly online, in the sense that a single pass is performed, and that predictions can be produced anytime.
+Each node in a tree predicts according to the average of the labels it contains. The prediction for a sample is computed as the aggregated predictions of all the subtrees along the path leading to the leaf node containing the sample. The aggregation weights are exponential weights with learning rate step using a squared loss when use_aggregation is True.
This computation is performed exactly thanks to a context tree weighting algorithm. More details can be found in the original paper1.
+The final predictions are the average of the predictions of each of the n_estimators trees in the forest.
n_estimators
+Type → int
+Default → 10
The number of trees in the forest.
+step
+Type → float
+Default → 1.0
Step-size for the aggregation weights.
+use_aggregation
+Type → bool
+Default → True
Controls if aggregation is used in the trees. It is highly recommended to leave it as True.
seed
+Type → int
+Default → None
Random seed for reproducibility.
+from river import datasets
+from river import evaluate
+from river import forest
+from river import metrics
+
+dataset = datasets.TrumpApproval()
+model = forest.AMFRegressor(seed=42)
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.268533
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++
Mourtada, J., Gaïffas, S., & Scornet, E. (2021). AMF: Aggregated Mondrian forests for online +learning. Journal of the Royal Statistical Society Series B: Statistical Methodology, 83(3), 505-533. ↩
+Adaptive Random Forest classifier.
+The 3 most important aspects of Adaptive Random Forest 1 are:
+inducing diversity through re-sampling
+inducing diversity through randomly selecting subsets of features for node splits
+drift detectors per base tree, which cause selective resets in response to drifts
+It also allows training background trees, which start training if a warning is detected and replace the active tree if the warning escalates to a drift.
+n_models
+Type → int
+Default → 10
Number of trees in the ensemble.
+max_features
+Type → bool | str | int
+Default → sqrt
Max number of attributes for each node split.
- If int, then consider max_features at each split.
- If float, then max_features is a percentage and int(max_features * n_features) features are considered per split.
- If "sqrt", then max_features=sqrt(n_features).
- If "log2", then max_features=log2(n_features).
- If None, then max_features=n_features.
lambda_value
+Type → int
+Default → 6
The lambda value for bagging (lambda=6 corresponds to Leveraging Bagging).
+metric
+Type → metrics.base.MultiClassMetric | None
+Default → None
Metric used to track trees performance within the ensemble. Defaults to metrics.Accuracy()`.
disable_weighted_vote
+Default → False
If True, disables the weighted vote prediction.
drift_detector
+Type → base.DriftDetector | None
+Default → None
Drift Detection method. Set to None to disable Drift detection. Defaults to drift.ADWIN(delta=0.001)`.
warning_detector
+Type → base.DriftDetector | None
+Default → None
Warning Detection method. Set to None to disable warning detection. Defaults to drift.ADWIN(delta=0.01)`.
grace_period
+Type → int
+Default → 50
[Tree parameter] Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
[Tree parameter] The maximum depth a tree can reach. If None, the tree will grow indefinitely.
split_criterion
+Type → str
+Default → info_gain
[Tree parameter] Split criterion to use.
- 'gini' - Gini
- 'info_gain' - Information Gain
- 'hellinger' - Hellinger Distance
delta
+Type → float
+Default → 0.01
[Tree parameter] Allowed error in split decision, a value closer to 0 takes longer to decide.
+tau
+Type → float
+Default → 0.05
[Tree parameter] Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → nba
[Tree parameter] Prediction mechanism used at leafs.
- 'mc' - Majority Class
- 'nb' - Naive Bayes
- 'nba' - Naive Bayes Adaptive
nb_threshold
+Type → int
+Default → 0
[Tree parameter] Number of instances a leaf should observe before allowing Naive Bayes.
+nominal_attributes
+Type → list | None
+Default → None
[Tree parameter] List of Nominal attributes. If empty, then assume that all attributes are numerical.
+splitter
+Type → Splitter | None
+Default → None
[Tree parameter] The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.GaussianSplitter is used if splitter is None.
binary_split
+Type → bool
+Default → False
[Tree parameter] If True, only allow binary splits.
+min_branch_fraction
+Type → float
+Default → 0.01
[Tree parameter] The minimum percentage of observed data required for branches resulting from split candidates. To validate a split candidate, at least two resulting branches must have a percentage of samples greater than min_branch_fraction. This criterion prevents unnecessary splits when the majority of instances are concentrated in a single branch.
max_share_to_split
+Type → float
+Default → 0.99
[Tree parameter] Only perform a split in a leaf if the proportion of elements in the majority class is smaller than this parameter value. This parameter avoids performing splits when most of the data belongs to a single class.
+max_size
+Type → float
+Default → 100.0
[Tree parameter] Maximum memory (MB) consumed by the tree.
+memory_estimate_period
+Type → int
+Default → 2000000
[Tree parameter] Number of instances between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
[Tree parameter] If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
[Tree parameter] If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
[Tree parameter] If True, enable merit-based tree pre-pruning.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+from river import evaluate
+from river import forest
+from river import metrics
+from river.datasets import synth
+
+dataset = synth.ConceptDriftStream(
+ seed=42,
+ position=500,
+ width=40
+).take(1000)
+
+model = forest.ARFClassifier(seed=8, leaf_prediction="mc")
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 71.07%
+Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++
Heitor Murilo Gomes, Albert Bifet, Jesse Read, Jean Paul Barddal, + Fabricio Enembreck, Bernhard Pfharinger, Geoff Holmes, Talel Abdessalem. + Adaptive random forests for evolving data stream classification. + In Machine Learning, DOI: 10.1007/s10994-017-5642-8, Springer, 2017. ↩
+Adaptive Random Forest regressor.
+The 3 most important aspects of Adaptive Random Forest 1 are:
+inducing diversity through re-sampling
+inducing diversity through randomly selecting subsets of features for node splits
+drift detectors per base tree, which cause selective resets in response to drifts
+Notice that this implementation is slightly different from the original algorithm proposed in 2. The HoeffdingTreeRegressor is used as base learner, instead of FIMT-DD. It also adds a new strategy to monitor the predictions and check for concept drifts. The deviations of the predictions to the target are monitored and normalized in the [0, 1] range to fulfill ADWIN's requirements. We assume that the data subjected to the normalization follows a normal distribution, and thus, lies within the interval of the mean \(\pm3\sigma\).
n_models
+Type → int
+Default → 10
Number of trees in the ensemble.
+max_features
+Default → sqrt
Max number of attributes for each node split.
- If int, then consider max_features at each split.
- If float, then max_features is a percentage and int(max_features * n_features) features are considered per split.
- If "sqrt", then max_features=sqrt(n_features).
- If "log2", then max_features=log2(n_features).
- If None, then max_features=n_features.
aggregation_method
+Type → str
+Default → median
The method to use to aggregate predictions in the ensemble.
- 'mean'
- 'median' - If selected will disable the weighted vote.
lambda_value
+Type → int
+Default → 6
The lambda value for bagging (lambda=6 corresponds to Leveraging Bagging).
+metric
+Type → metrics.base.RegressionMetric | None
+Default → None
Metric used to track trees performance within the ensemble. Depending, on the configuration, this metric is also used to weight predictions from the members of the ensemble. Defaults to metrics.MSE()`.
disable_weighted_vote
+Default → True
If True, disables the weighted vote prediction, i.e. does not assign weights to individual tree's predictions and uses the arithmetic mean instead. Otherwise will use the metric value to weight predictions.
drift_detector
+Type → base.DriftDetector | None
+Default → None
Drift Detection method. Set to None to disable Drift detection. Defaults to drift.ADWIN(0.001)`.
warning_detector
+Type → base.DriftDetector | None
+Default → None
Warning Detection method. Set to None to disable warning detection. Defaults to drift.ADWIN(0.01)`.
grace_period
+Type → int
+Default → 50
[Tree parameter] Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
[Tree parameter] The maximum depth a tree can reach. If None, the tree will grow indefinitely.
delta
+Type → float
+Default → 0.01
[Tree parameter] Allowed error in split decision, a value closer to 0 takes longer to decide.
+tau
+Type → float
+Default → 0.05
[Tree parameter] Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → adaptive
[Tree parameter] Prediction mechanism used at leaves. - 'mean' - Target mean - 'model' - Uses the model defined in leaf_model - 'adaptive' - Chooses between 'mean' and 'model' dynamically
leaf_model
+Type → base.Regressor | None
+Default → None
[Tree parameter] The regression model used to provide responses if leaf_prediction='model'. If not provided, an instance of linear_model.LinearRegression with the default hyperparameters is used.
model_selector_decay
+Type → float
+Default → 0.95
[Tree parameter] The exponential decaying factor applied to the learning models' squared errors, that are monitored if leaf_prediction='adaptive'. Must be between 0 and 1. The closer to 1, the more importance is going to be given to past observations. On the other hand, if its value approaches 0, the recent observed errors are going to have more influence on the final decision.
nominal_attributes
+Type → list | None
+Default → None
[Tree parameter] List of Nominal attributes. If empty, then assume that all attributes are numerical.
+splitter
+Type → Splitter | None
+Default → None
[Tree parameter] The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters.By default, tree.splitter.EBSTSplitter is used if splitter is None.
min_samples_split
+Type → int
+Default → 5
[Tree parameter] The minimum number of samples every branch resulting from a split candidate must have to be considered valid.
+binary_split
+Type → bool
+Default → False
[Tree parameter] If True, only allow binary splits.
+max_size
+Type → float
+Default → 500.0
[Tree parameter] Maximum memory (MB) consumed by the tree.
+memory_estimate_period
+Type → int
+Default → 2000000
[Tree parameter] Number of instances between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
[Tree parameter] If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
[Tree parameter] If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
[Tree parameter] If True, enable merit-based tree pre-pruning.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+models
+valid_aggregation_method
+Valid aggregation_method values.
+from river import datasets
+from river import evaluate
+from river import forest
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+
+model = (
+ preprocessing.StandardScaler() |
+ forest.ARFRegressor(seed=42)
+)
+
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.800378
+Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++
Gomes, H.M., Bifet, A., Read, J., Barddal, J.P., Enembreck, F., + Pfharinger, B., Holmes, G. and Abdessalem, T., 2017. Adaptive random + forests for evolving data stream classification. Machine Learning, + 106(9-10), pp.1469-1495. ↩
+Gomes, H.M., Barddal, J.P., Boiko, L.E., Bifet, A., 2018. + Adaptive random forests for data stream regression. ESANN 2018. ↩
+Online Extra Trees regressor.
+The online Extra Trees1 ensemble takes some steps further into randomization when compared to Adaptive Random Forests (ARF). A subspace of the feature space is considered at each split attempt, as ARF does, and online bagging or subbagging can also be (optionally) used. Nonetheless, Extra Trees randomizes the split candidates evaluated by each leaf node (just a single split is tested by numerical feature, which brings significant speedups to the ensemble), and might also randomize the maximum depth of the forest members, as well as the size of the feature subspace processed by each of its trees' leaves.
+On the other hand, OXT suffers from a cold-start problem. As the splits are random, the predictive performance in small samples is usually worse than using a deterministic split approach, such as the one used by ARF.
+n_models
+Type → int
+Default → 10
The number of trees in the ensemble.
+max_features
+Type → bool | str | int
+Default → sqrt
Max number of attributes for each node split. - If int, then consider max_features at each split. - If float, then max_features is a percentage and int(max_features * n_features) features are considered per split. - If "sqrt", then max_features=sqrt(n_features). - If "log2", then max_features=log2(n_features). - If "random", then max_features will assume a different random number in the interval [2, n_features] for each tree leaf. - If None, then max_features=n_features.
resampling_strategy
+Type → str | None
+Default → subbagging
The chosen instance resampling strategy: - If None, no resampling will be done and the trees will process all instances. - If 'baggging', online bagging will be performed (sampling with replacement). - If 'subbagging', online subbagging will be performed (sampling without replacement).
resampling_rate
+Type → int | float
+Default → 0.5
Only valid if resampling_strategy is not None. Controls the parameters of the resampling strategy.. - If resampling_strategy='bagging', must be an integer greater than or equal to 1 that parameterizes the poisson distribution used to simulate bagging in online learning settings. It acts as the lambda parameter of Oza Bagging and Leveraging Bagging. - If resampling_strategy='subbagging', must be a float in the interval \((0, 1]\) that controls the chance of each instance being used by a tree for learning.
detection_mode
+Type → str
+Default → all
The concept drift detection mode in which the forest operates. Valid values are: - "all": creates both warning and concept drift detectors. If a warning is detected, an alternate tree starts being trained in the background. If the warning trigger escalates to a concept drift, the affected tree is replaced by the alternate tree. - "drop": only the concept drift detectors are created. If a drift is detected, the affected tree is dropped and replaced by a new tree. - "off": disables the concept drift adaptation capabilities. The forest will act as if the processed stream is stationary.
+warning_detector
+Type → base.DriftDetector | None
+Default → None
The detector that will be used to trigger concept drift warnings. Defaults to drift.ADWIN(0.01)`.
drift_detector
+Type → base.DriftDetector | None
+Default → None
The detector used to detect concept drifts. Defaults to drift.ADWIN(0.001)`.
max_depth
+Type → int | None
+Default → None
The maximum depth the ensemble members might reach. If None, the trees will grow indefinitely.
randomize_tree_depth
+Type → bool
+Default → False
Whether or not randomize the maximum depth of each tree in the ensemble. If max_depth is provided, it is going to act as an upper bound to generate the maximum depth for each tree.
track_metric
+Type → metrics.base.RegressionMetric | None
+Default → None
The performance metric used to weight predictions. Defaults to metrics.MAE()`.
disable_weighted_vote
+Type → bool
+Default → True
Defines whether or not to use predictions weighted by each trees' prediction performance.
+split_buffer_size
+Type → int
+Default → 5
Defines the size of the buffer used by the tree splitters when determining the feature range and a random split point in this interval.
+seed
+Type → int | None
+Default → None
Random seed to support reproducibility.
+grace_period
+Type → int
+Default → 50
[Tree parameter] Number of instances a leaf should observe between split attempts.
+delta
+Type → float
+Default → 0.01
[Tree parameter] Allowed error in split decision, a value closer to 0 takes longer to decide.
+tau
+Type → float
+Default → 0.05
[Tree parameter] Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → adaptive
[Tree parameter] Prediction mechanism used at leaves. - 'mean' - Target mean - 'model' - Uses the model defined in leaf_model - 'adaptive' - Chooses between 'mean' and 'model' dynamically
leaf_model
+Type → base.Regressor | None
+Default → None
[Tree parameter] The regression model used to provide responses if leaf_prediction='model'. If not provided, an instance of linear_model.LinearRegression with the default hyperparameters is used.
model_selector_decay
+Type → float
+Default → 0.95
[Tree parameter] The exponential decaying factor applied to the learning models' squared errors, that are monitored if leaf_prediction='adaptive'. Must be between 0 and 1. The closer to 1, the more importance is going to be given to past observations. On the other hand, if its value approaches 0, the recent observed errors are going to have more influence on the final decision.
nominal_attributes
+Type → list | None
+Default → None
[Tree parameter] List of Nominal attributes. If empty, then assume that all attributes are numerical.
+min_samples_split
+Type → int
+Default → 5
[Tree parameter] The minimum number of samples every branch resulting from a split candidate must have to be considered valid.
+binary_split
+Type → bool
+Default → False
[Tree parameter] If True, only allow binary splits.
+max_size
+Type → int
+Default → 500
[Tree parameter] Maximum memory (MB) consumed by the tree.
+memory_estimate_period
+Type → int
+Default → 2000000
[Tree parameter] Number of instances between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
[Tree parameter] If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
[Tree parameter] If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
[Tree parameter] If True, enable merit-based tree pre-pruning.
+instances_per_tree
+The number of instances processed by each one of the current forest members. Each time a concept drift is detected, the count corresponding to the affected tree is reset.
+models
+n_drifts
+The number of concept drifts detected per ensemble member.
+n_tree_swaps
+The number of performed alternate tree swaps. Not applicable if the warning detectors are disabled.
+n_warnings
+The number of warnings detected per ensemble member.
+total_instances
+The total number of instances processed by the ensemble.
+from river import datasets
+from river import evaluate
+from river import metrics
+from river import forest
+
+dataset = datasets.synth.Friedman(seed=42).take(5000)
+
+model = forest.OXTRegressor(n_models=3, seed=42)
+
+metric = metrics.RMSE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+RMSE: 3.127311
+Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++
As the Online Extra Trees change the way in which Hoeffding Trees perform split attempts +and monitor numerical input features, some of the parameters of the vanilla Hoeffding Tree +algorithms are not available.
+Mastelini, S. M., Nakano, F. K., Vens, C., & de Leon Ferreira, A. C. P. (2022). +Online Extra Trees Regressor. IEEE Transactions on Neural Networks and Learning Systems. ↩
+Over-sampling for imbalanced regression using Chebyshev's inequality.
+Chebyshev's inequality can be used to define the probability of target observations being frequent values (w.r.t. the distribution mean).
+Let \(Y\) be a random variable with finite expected value \(\overline{y}\) and non-zero variance \(\sigma^2\). For any real number \(t > 0\), the Chebyshev's inequality states that, for a wide class of unimodal probability distributions: \(Pr(|y-\overline{y}| \ge t\sigma) \le \dfrac{1}{t^2}\).
+Taking \(t=\dfrac{|y-\overline{y}|}{\sigma}\), and assuming \(t > 1\), the Chebyshev’s inequality for an observation \(y\) becomes: \(P(|y - \overline{y}|=t) = \dfrac{\sigma^2}{|y-\overline{y}|}\).
+Alternatively, one can use \(t\) directly to estimate a frequency weight \(\kappa = \lceil t\rceil\) and define an over-sampling strategy for extreme and rare target values1. Each incoming instance is used \(\kappa\) times to update the underlying regressor. Frequent target values contribute only once to the underlying regressor, whereas rares cases are used multiple times for training.
+regressor
+Type → base.Regressor
+The regression model that will receive the biased sample.
+from river import datasets
+from river import evaluate
+from river import imblearn
+from river import metrics
+from river import preprocessing
+from river import rules
+
+model = (
+ preprocessing.StandardScaler() |
+ imblearn.ChebyshevOverSampler(
+ regressor=rules.AMRules(
+ n_min=50, delta=0.01
+ )
+ )
+)
+
+evaluate.progressive_val_score(
+ datasets.TrumpApproval(),
+ model,
+ metrics.MAE(),
+ print_every=500
+)
+[500] MAE: 1.673902
+[1,000] MAE: 1.743046
+[1,001] MAE: 1.741335
+MAE: 1.741335
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++
Aminian, Ehsan, Rita P. Ribeiro, and João Gama. "Chebyshev approaches for imbalanced data +streams regression models." Data Mining and Knowledge Discovery 35.6 (2021): 2389-2466. ↩
+Under-sampling for imbalanced regression using Chebyshev's inequality.
+Chebyshev's inequality can be used to define the probability of target observations being frequent values (w.r.t. the distribution mean).
+Let \(Y\) be a random variable with finite expected value \(\overline{y}\) and non-zero variance \(\sigma^2\). For any real number \(t > 0\), the Chebyshev's inequality states that, for a wide class of unimodal probability distributions: \(Pr(|y-\overline{y}| \ge t\sigma) \le \dfrac{1}{t^2}\).
+Taking \(t=\dfrac{|y-\overline{y}|}{\sigma}\), and assuming \(t > 1\), the Chebyshev’s inequality for an observation \(y\) becomes: \(P(|y - \overline{y}|=t) = \dfrac{\sigma^2}{|y-\overline{y}|}\). The reciprocal of this probability is used for under-sampling1 the most frequent cases. Extreme valued or rare cases have higher probabilities of selection, whereas the most frequent cases are likely to be discarded. Still, frequent cases have a small chance of being selected (controlled via the sp parameter) in case few rare instances were observed.
regressor
+Type → base.Regressor
+The regression model that will receive the biased sample.
+sp
+Type → float
+Default → 0.15
Second chance probability. Even if an example is not initially selected for training, it still has a small chance of being selected in case the number of rare case observed so far is small.
+seed
+Type → int | None
+Default → None
Random seed to support reproducibility.
+from river import datasets
+from river import evaluate
+from river import imblearn
+from river import metrics
+from river import preprocessing
+from river import rules
+
+model = (
+ preprocessing.StandardScaler() |
+ imblearn.ChebyshevUnderSampler(
+ regressor=rules.AMRules(
+ n_min=50, delta=0.01,
+ ),
+ seed=42
+ )
+)
+
+evaluate.progressive_val_score(
+ datasets.TrumpApproval(),
+ model,
+ metrics.MAE(),
+ print_every=500
+)
+[500] MAE: 1.787162
+[1,000] MAE: 1.515711
+[1,001] MAE: 1.515236
+MAE: 1.515236
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++
Aminian, Ehsan, Rita P. Ribeiro, and João Gama. "Chebyshev approaches for imbalanced data +streams regression models." Data Mining and Knowledge Discovery 35.6 (2021): 2389-2466. ↩
+Hard sampling classifier.
+This wrapper enables a model to retrain on past samples who's output was hard to predict. This works by storing the hardest samples in a buffer of a fixed size. When a new sample arrives, the wrapped model is either trained on one of the buffered samples with a probability p or on the new sample with a probability (1 - p).
+The hardness of an observation is evaluated with a loss function that compares the sample's ground truth with the wrapped model's prediction. If the buffer is not full, then the sample is added to the buffer. If the buffer is full and the new sample has a bigger loss than the lowest loss in the buffer, then the sample takes it's place.
+classifier
+Type → base.Classifier
+size
+Type → int
+Size of the buffer.
+p
+Type → float
+Probability of updating the model with a sample from the buffer instead of a new incoming sample.
+loss
+Type → optim.losses.BinaryLoss | optim.losses.MultiClassLoss | None
+Default → None
Criterion used to evaluate the hardness of a sample.
+seed
+Type → int | None
+Default → None
Random seed.
+from river import datasets
+from river import evaluate
+from river import imblearn
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+model = (
+ preprocessing.StandardScaler() |
+ imblearn.HardSamplingClassifier(
+ classifier=linear_model.LogisticRegression(),
+ p=0.1,
+ size=40,
+ seed=42,
+ )
+)
+
+evaluate.progressive_val_score(
+ dataset=datasets.Phishing(),
+ model=model,
+ metric=metrics.ROCAUC(),
+ print_every=500,
+)
+[500] ROCAUC: 92.78%
+[1,000] ROCAUC: 94.76%
+[1,250] ROCAUC: 95.06%
+ROCAUC: 95.06%
+Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Hard sampling regressor.
+This wrapper enables a model to retrain on past samples who's output was hard to predict. This works by storing the hardest samples in a buffer of a fixed size. When a new sample arrives, the wrapped model is either trained on one of the buffered samples with a probability p or on the new sample with a probability (1 - p).
+The hardness of an observation is evaluated with a loss function that compares the sample's ground truth with the wrapped model's prediction. If the buffer is not full, then the sample is added to the buffer. If the buffer is full and the new sample has a bigger loss than the lowest loss in the buffer, then the sample takes it's place.
+regressor
+Type → base.Regressor
+size
+Type → int
+Size of the buffer.
+p
+Type → float
+Probability of updating the model with a sample from the buffer instead of a new incoming sample.
+loss
+Type → optim.losses.RegressionLoss | None
+Default → None
Criterion used to evaluate the hardness of a sample.
+seed
+Type → int | None
+Default → None
Random seed.
+from river import datasets
+from river import evaluate
+from river import imblearn
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+model = (
+ preprocessing.StandardScaler() |
+ imblearn.HardSamplingRegressor(
+ regressor=linear_model.LinearRegression(),
+ p=.2,
+ size=30,
+ seed=42,
+ )
+)
+
+evaluate.progressive_val_score(
+ datasets.TrumpApproval(),
+ model,
+ metrics.MAE(),
+ print_every=500
+)
+[500] MAE: 2.274021
+[1,000] MAE: 1.392399
+[1,001] MAE: 1.391246
+MAE: 1.391246
+Random over-sampling.
+This is a wrapper for classifiers. It will train the provided classifier by over-sampling the stream of given observations so that the class distribution seen by the classifier follows a given desired distribution. The implementation is a discrete version of reverse rejection sampling.
+See Working with imbalanced data for example usage.
+classifier
+Type → base.Classifier
+desired_dist
+Type → dict
+The desired class distribution. The keys are the classes whilst the values are the desired class percentages. The values must sum up to 1.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+from river import datasets
+from river import evaluate
+from river import imblearn
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+model = imblearn.RandomOverSampler(
+ (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+ ),
+ desired_dist={False: 0.4, True: 0.6},
+ seed=42
+)
+
+dataset = datasets.CreditCard().take(3000)
+
+metric = metrics.LogLoss()
+
+evaluate.progressive_val_score(dataset, model, metric)
+LogLoss: 0.0457...
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Random sampling by mixing under-sampling and over-sampling.
+This is a wrapper for classifiers. It will train the provided classifier by both under-sampling and over-sampling the stream of given observations so that the class distribution seen by the classifier follows a given desired distribution.
+See Working with imbalanced data for example usage.
+classifier
+Type → base.Classifier
+desired_dist
+Type → dict
+The desired class distribution. The keys are the classes whilst the values are the desired class percentages. The values must sum up to 1. If set to None, then the observations will be sampled uniformly at random, which is stricly equivalent to using ensemble.BaggingClassifier.
sampling_rate
+Default → 1.0
The desired ratio of data to sample.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+from river import datasets
+from river import evaluate
+from river import imblearn
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+model = imblearn.RandomSampler(
+ (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+ ),
+ desired_dist={False: 0.4, True: 0.6},
+ sampling_rate=0.8,
+ seed=42
+)
+
+dataset = datasets.CreditCard().take(3000)
+
+metric = metrics.LogLoss()
+
+evaluate.progressive_val_score(dataset, model, metric)
+LogLoss: 0.09...
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Random under-sampling.
+This is a wrapper for classifiers. It will train the provided classifier by under-sampling the stream of given observations so that the class distribution seen by the classifier follows a given desired distribution. The implementation is a discrete version of rejection sampling.
+See Working with imbalanced data for example usage.
+classifier
+Type → base.Classifier
+desired_dist
+Type → dict
+The desired class distribution. The keys are the classes whilst the values are the desired class percentages. The values must sum up to 1.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+from river import datasets
+from river import evaluate
+from river import imblearn
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+model = imblearn.RandomUnderSampler(
+ (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+ ),
+ desired_dist={False: 0.4, True: 0.6},
+ seed=42
+)
+
+dataset = datasets.CreditCard().take(3000)
+
+metric = metrics.LogLoss()
+
+evaluate.progressive_val_score(dataset, model, metric)
+LogLoss: 0.0336...
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + + +
Approximate Large Margin Algorithm (ALMA).
+p
+Default → 2
alpha
+Default → 0.9
B
+Default → 1.1111111111111112
C
+Default → 1.4142135623730951
w (collections.defaultdict)
+The current weights.
+k (int)
+The number of instances seen during training.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.Phishing()
+
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.ALMAClassifier()
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 82.56%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++ + + + + + + + + +
Bayesian linear regression.
+An advantage of Bayesian linear regression over standard linear regression is that features do not have to scaled beforehand. Another attractive property is that this flavor of linear regression is somewhat insensitive to its hyperparameters. Finally, this model can output instead a predictive distribution rather than just a point estimate.
+The downside is that the learning step runs in O(n^2) time, whereas the learning step of standard linear regression takes O(n) time.
alpha
+Default → 1
Prior parameter.
+beta
+Default → 1
Noise parameter.
+smoothing
+Type → float
+Default → None
Smoothing allows the model to gradually "forget" the past, and focus on the more recent data. It thus enables the model to deal with concept drift. Due to the current implementation, activating smoothing may slow down the model.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+
+dataset = datasets.TrumpApproval()
+model = linear_model.BayesianLinearRegression()
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.586...
+x, _ = next(iter(dataset))
+model.predict_one(x)
+43.852...
+model.predict_one(x, with_dist=True)
+𝒩(μ=43.85..., σ=1.00...)
+The smoothing parameter can be set to make the model robust to drift. The parameter is
+expected to be between 0 and 1. To exemplify, let's generate some simulation data with an
+abrupt concept drift right in the middle.
import itertools
+import random
+
+def random_data(coefs, n, seed=42):
+ rng = random.Random(seed)
+ for _ in range(n):
+ x = {i: rng.random() for i, c in enumerate(coefs)}
+ y = sum(c * xi for c, xi in zip(coefs, x.values()))
+ yield x, y
+Here's how the model performs without any smoothing:
+model = linear_model.BayesianLinearRegression()
+dataset = itertools.chain(
+ random_data([0.1, 3], 100),
+ random_data([10, -2], 100)
+)
+metric = metrics.MAE()
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 1.284...
+And here's how it performs with some smoothing:
+model = linear_model.BayesianLinearRegression(smoothing=0.8)
+dataset = itertools.chain(
+ random_data([0.1, 3], 100),
+ random_data([10, -2], 100)
+)
+metric = metrics.MAE()
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.159...
+Smoothing allows the model to gradually "forget" the past, and focus on the more recent data.
+Note how this works better than standard linear regression, even when using an aggressive +learning rate.
+from river import optim
+model = linear_model.LinearRegression(optimizer=optim.SGD(0.5))
+dataset = itertools.chain(
+ random_data([0.1, 3], 100),
+ random_data([10, -2], 100)
+)
+metric = metrics.MAE()
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.242...
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+False Returns
+base.typing.RegTarget: The prediction.
++ + + + + + + + + +
Linear regression.
+This estimator supports learning with mini-batches. On top of the single instance methods, it provides the following methods: learn_many, predict_many, predict_proba_many. Each method takes as input a pandas.DataFrame where each column represents a feature.
It is generally a good idea to scale the data beforehand in order for the optimizer to converge. You can do this online with a preprocessing.StandardScaler.
optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the weights. Note that the intercept updates are handled separately.
+loss
+Type → optim.losses.RegressionLoss | None
+Default → None
The loss function to optimize for.
+l2
+Default → 0.0
Amount of L2 regularization used to push weights towards 0. For now, only one type of penalty can be used. The joint use of L1 and L2 is not explicitly supported.
+l1
+Default → 0.0
Amount of L1 regularization used to push weights towards 0. For now, only one type of penalty can be used. The joint use of L1 and L2 is not explicitly supported.
+intercept_init
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → optim.base.Scheduler | float
+Default → 0.01
Learning rate scheduler used for updating the intercept. A optim.schedulers.Constant is used if a float is provided. The intercept is not updated when this is set to 0.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+initializer
+Type → optim.base.Initializer | None
+Default → None
Weights initialization scheme.
+weights (dict)
+The current weights.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression(intercept_lr=.1)
+)
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.558735
+model['LinearRegression'].intercept
+35.617670
+You can call the debug_one method to break down a prediction. This works even if the
+linear regression is part of a pipeline.
x, y = next(iter(dataset))
+report = model.debug_one(x)
+print(report)
+0. Input
+--------
+gallup: 43.84321 (float)
+ipsos: 46.19925 (float)
+morning_consult: 48.31875 (float)
+ordinal_date: 736389 (int)
+rasmussen: 44.10469 (float)
+you_gov: 43.63691 (float)
+<BLANKLINE>
+1. StandardScaler
+-----------------
+gallup: 1.18810 (float)
+ipsos: 2.10348 (float)
+morning_consult: 2.73545 (float)
+ordinal_date: -1.73032 (float)
+rasmussen: 1.26872 (float)
+you_gov: 1.48391 (float)
+<BLANKLINE>
+2. LinearRegression
+-------------------
+Name Value Weight Contribution
+ Intercept 1.00000 35.61767 35.61767
+ ipsos 2.10348 0.62689 1.31866
+morning_consult 2.73545 0.24180 0.66144
+ gallup 1.18810 0.43568 0.51764
+ rasmussen 1.26872 0.28118 0.35674
+ you_gov 1.48391 0.03123 0.04634
+ ordinal_date -1.73032 3.45162 -5.97242
+<BLANKLINE>
+Prediction: 32.54607
+Debugs the output of the linear regression.
+Parameters
+5 Returns
+str: A table which explains the output.
++
Update the model with a mini-batch of features X and real-valued targets y.
Parameters
+1 Returns
+MiniBatchRegressor: self
++
Fits to a set of features x and a real-valued target y.
Parameters
+1.0 Returns
+Regressor: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+The predicted outcomes.
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Logistic regression.
+This estimator supports learning with mini-batches. On top of the single instance methods, it provides the following methods: learn_many, predict_many, predict_proba_many. Each method takes as input a pandas.DataFrame where each column represents a feature.
It is generally a good idea to scale the data beforehand in order for the optimizer to converge. You can do this online with a preprocessing.StandardScaler.
optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the weights. Note that the intercept is handled separately.
+loss
+Type → optim.losses.BinaryLoss | None
+Default → None
The loss function to optimize for. Defaults to optim.losses.Log.
l2
+Default → 0.0
Amount of L2 regularization used to push weights towards 0. For now, only one type of penalty can be used. The joint use of L1 and L2 is not explicitly supported.
+l1
+Default → 0.0
Amount of L1 regularization used to push weights towards 0. For now, only one type of penalty can be used. The joint use of L1 and L2 is not explicitly supported.
+intercept_init
+Default → 0.0
Initial intercept value.
+intercept_lr
+Type → float | optim.base.Scheduler
+Default → 0.01
Learning rate scheduler used for updating the intercept. A optim.schedulers.Constant is used if a float is provided. The intercept is not updated when this is set to 0.
clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+initializer
+Type → optim.base.Initializer | None
+Default → None
Weights initialization scheme.
+weights
+The current weights.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer=optim.SGD(.1))
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 88.96%
+Update the model with a mini-batch of features X and boolean targets y.
Parameters
+1 Returns
+MiniBatchClassifier: self
++
Update the model with a set of features x and a label y.
Parameters
+1.0 Returns
+Classifier: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+pd.Series: The predicted labels.
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the outcome probabilities for each given sample.
+Parameters
+Returns
+pd.DataFrame: A dataframe with probabilities of True and False for each sample.
+
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Passive-aggressive learning for classification.
+C
+Default → 1.0
mode
+Default → 1
learn_intercept
+Default → True
The following example is taken from this blog post.
+from river import linear_model
+from river import metrics
+from river import stream
+import numpy as np
+from sklearn import datasets
+from sklearn import model_selection
+
+np.random.seed(1000)
+X, y = datasets.make_classification(
+ n_samples=5000,
+ n_features=4,
+ n_informative=2,
+ n_redundant=0,
+ n_repeated=0,
+ n_classes=2,
+ n_clusters_per_class=2
+)
+
+X_train, X_test, y_train, y_test = model_selection.train_test_split(
+ X,
+ y,
+ test_size=0.35,
+ random_state=1000
+)
+
+model = linear_model.PAClassifier(
+ C=0.01,
+ mode=1
+)
+
+for xi, yi in stream.iter_array(X_train, y_train):
+ y_pred = model.learn_one(xi, yi)
+
+metric = metrics.Accuracy() + metrics.LogLoss()
+
+for xi, yi in stream.iter_array(X_test, y_test):
+ metric = metric.update(yi, model.predict_proba_one(xi))
+
+print(metric)
+Accuracy: 88.46%, LogLoss: 0.325727
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + + +
Passive-aggressive learning for regression.
+C
+Default → 1.0
mode
+Default → 1
eps
+Default → 0.1
learn_intercept
+Default → True
The following example is taken from this blog post.
+from river import linear_model
+from river import metrics
+from river import stream
+import numpy as np
+from sklearn import datasets
+
+np.random.seed(1000)
+X, y = datasets.make_regression(n_samples=500, n_features=4)
+
+model = linear_model.PARegressor(
+ C=0.01,
+ mode=2,
+ eps=0.1,
+ learn_intercept=False
+)
+metric = metrics.MAE() + metrics.MSE()
+
+for xi, yi in stream.iter_array(X, y):
+ y_pred = model.predict_one(xi)
+ model = model.learn_one(xi, yi)
+ metric = metric.update(yi, y_pred)
+
+print(metric)
+MAE: 9.809402, MSE: 472.393532
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + + +
Perceptron classifier.
+In this implementation, the Perceptron is viewed as a special case of the logistic regression. The loss function that is used is the Hinge loss with a threshold set to 0, whilst the learning rate of the stochastic gradient descent procedure is set to 1 for both the weights and the intercept.
+l2
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme.
+weights
+The current weights.
+from river import datasets
+from river import evaluate
+from river import linear_model as lm
+from river import metrics
+from river import preprocessing as pp
+
+dataset = datasets.Phishing()
+
+model = pp.StandardScaler() | lm.Perceptron()
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 85.84%
+Update the model with a mini-batch of features X and boolean targets y.
Parameters
+1 Returns
+MiniBatchClassifier: self
++
Update the model with a set of features x and a label y.
Parameters
+1.0 Returns
+Classifier: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+pd.Series: The predicted labels.
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the outcome probabilities for each given sample.
+Parameters
+Returns
+pd.DataFrame: A dataframe with probabilities of True and False for each sample.
+
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Softmax regression is a generalization of logistic regression to multiple classes.
+Softmax regression is also known as "multinomial logistic regression". There are a set weights for each class, hence the weights attribute is a nested collections.defaultdict. The main advantage of using this instead of a one-vs-all logistic regression is that the probabilities will be calibrated. Moreover softmax regression is more robust to outliers.
optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used to tune the weights.
+loss
+Type → optim.losses.MultiClassLoss | None
+Default → None
The loss function to optimize for.
+l2
+Default → 0
Amount of L2 regularization used to push weights towards 0.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.ImageSegments()
+
+model = preprocessing.StandardScaler()
+model |= linear_model.SoftmaxRegression()
+
+metric = metrics.MacroF1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MacroF1: 81.88%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++ + + + + + + + + +
Generalized Linear Model.
+This serves as a base class for linear and logistic regression.
+optimizer
+The sequential optimizer used for updating the weights. Note that the intercept updates are handled separately.
+loss
+The loss function to optimize for.
+l2
+Amount of L2 regularization used to push weights towards 0. For now, only one type of penalty can be used. The joint use of L1 and L2 is not explicitly supported.
+l1
+Amount of L1 regularization used to push weights towards 0. For now, only one type of penalty can be used. The joint use of L1 and L2 is not explicitly supported.
+intercept_init
+Initial intercept value.
+intercept_lr
+Learning rate scheduler used for updating the intercept. A optim.schedulers.Constant is used if a float is provided. The intercept is not updated when this is set to 0.
clip_gradient
+Clips the absolute value of each gradient value.
+initializer
+Weights initialization scheme.
+Accuracy score, which is the percentage of exact matches.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [True, False, True, True, True]
+y_pred = [True, True, False, True, True]
+
+metric = metrics.Accuracy()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+Accuracy: 60.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Adjusted Mutual Information between two clusterings.
+Adjusted Mutual Information (AMI) is an adjustment of the Mutual Information score that accounts for chance. It corrects the effect of agreement solely due to chance between clusterings, similar to the way the Adjusted Rand Index corrects the Rand Index. It is closely related to variation of information. The adjusted measure, however, is no longer metrical.
+For two clusterings \(U\) and \(V\), the Adjusted Mutual Information is calculated as:
+This metric is independent of the permutation of the class or cluster label values; furthermore, it is also symmetric. This can be useful to measure the agreement of two label assignments strategies on the same dataset, regardless of the ground truth.
+However, due to the complexity of the Expected Mutual Info Score, the computation of this metric is an order of magnitude slower than most other metrics, in general.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+average_method
+Default → arithmetic
This parameter defines how to compute the normalizer in the denominator. Possible options include min, max, arithmetic and geometric.
bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [1, 1, 2, 2, 3, 3]
+y_pred = [1, 1, 1, 2, 2, 2]
+
+metric = metrics.AdjustedMutualInfo()
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+1.0
+1.0
+0.0
+0.0
+0.105891
+0.298792
+metric
+AdjustedMutualInfo: 0.298792
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Wikipedia contributors. (2021, March 17). Mutual information. + In Wikipedia, The Free Encyclopedia, + from https://en.wikipedia.org/w/index.php?title=Mutual_information&oldid=1012714929 ↩
+Adjusted Rand Index.
+The Adjusted Rand Index is the corrected-for-chance version of the Rand Index 1 2. Such a correction for chance establishes a baseline by using the expected similarity of all pair-wise comparisions between clusterings specified by a random model.
+Traditionally, the Rand Index was corrected using the Permutation Model for Clustering. However, the premises of the permutation model are frequently violated; in many clustering scenarios, either the number of clusters or the size distribution of those clusters vary drastically. Variations of the adjusted Rand Index account for different models of random clusterings.
+Though the Rand Index may only yield a value between 0 and 1, the Adjusted Rand index can yield negative values if the index is less than the expected index.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 0, 0, 1, 1, 1]
+y_pred = [0, 0, 1, 1, 2, 2]
+
+metric = metrics.AdjustedRand()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+1.0
+1.0
+0.0
+0.0
+0.09090909090909091
+0.24242424242424243
+metric
+AdjustedRand: 0.242424
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Wikipedia contributors. (2021, January 13). Rand index. + In Wikipedia, The Free Encyclopedia, + from https://en.wikipedia.org/w/index.php?title=Rand_index&oldid=1000098911 ↩
+W. M. Rand (1971). "Objective criteria for the evaluation of clustering methods". + Journal of the American Statistical Association. American Statistical Association. + 66 (336): 846–850. arXiv:1704.01036. doi:10.2307/2284239. JSTOR 2284239. ↩
+Balanced accuracy.
+Balanced accuracy is the average of recall obtained on each class. It is used to deal with imbalanced datasets in binary and multi-class classification problems.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+y_true = [True, False, True, True, False, True]
+y_pred = [True, False, True, True, True, False]
+
+metric = metrics.BalancedAccuracy()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+BalancedAccuracy: 62.50%
+y_true = [0, 1, 0, 0, 1, 0]
+y_pred = [0, 1, 0, 0, 0, 1]
+metric = metrics.BalancedAccuracy()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+BalancedAccuracy: 62.50%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
A report for monitoring a classifier.
+This class maintains a set of metrics and updates each of them every time update is called. You can print this class at any time during a model's lifetime to get a tabular visualization of various metrics.
You can wrap a metrics.ClassificationReport with utils.Rolling in order to obtain a classification report over a window of observations. You can also wrap it with utils.TimeRolling to obtain a report over a period of time.
decimals
+Default → 2
The number of decimals to display in each cell.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = ['pear', 'apple', 'banana', 'banana', 'banana']
+y_pred = ['apple', 'pear', 'banana', 'banana', 'apple']
+
+report = metrics.ClassificationReport()
+
+for yt, yp in zip(y_true, y_pred):
+ report = report.update(yt, yp)
+
+print(report)
+ Precision Recall F1 Support
+<BLANKLINE>
+ apple 0.00% 0.00% 0.00% 1
+ banana 100.00% 66.67% 80.00% 3
+ pear 0.00% 0.00% 0.00% 1
+<BLANKLINE>
+ Macro 33.33% 22.22% 26.67%
+ Micro 40.00% 40.00% 40.00%
+Weighted 60.00% 40.00% 48.00%
+<BLANKLINE>
+ 40.00% accuracy
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Cohen's Kappa score.
+Cohen's Kappa expresses the level of agreement between two annotators on a classification problem. It is defined as
+where \(p_o\) is the empirical probability of agreement on the label assigned to any sample (prequential accuracy), and \(p_e\) is the expected agreement when both annotators assign labels randomly.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = ['cat', 'ant', 'cat', 'cat', 'ant', 'bird']
+y_pred = ['ant', 'ant', 'cat', 'cat', 'ant', 'cat']
+
+metric = metrics.CohenKappa()
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+CohenKappa: 42.86%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
J. Cohen (1960). "A coefficient of agreement for nominal scales". Educational and Psychological Measurement 20(1):37-46. doi:10.1177/001316446002000104. ↩
+Completeness Score.
+Completeness 1 is symmetrical to homogeneity. In order to satisfy the completeness criteria, a clustering must assign all of those datapoints that are members of a single class to a single cluster. To evaluate completeness, we examine the distribution cluster assignments within each class. In a perfectly complete clustering solution, each of these distributions will be completely skewed to a single cluster.
+We can evaluate this degree of skew by calculating the conditional entropy of the proposed cluster distribution given the class of the component data points. However, in the worst case scenario, each class is represented by every cluster with a distribution equal to the distribution of cluster sizes. Therefore, symmetric to the claculation above, we define completeness as:
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [1, 1, 2, 2, 3, 3]
+y_pred = [1, 1, 1, 2, 2, 2]
+
+metric = metrics.Completeness()
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+1.0
+1.0
+1.0
+0.3836885465963443
+0.5880325916843805
+0.6666666666666667
+metric
+Completeness: 66.67%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Andrew Rosenberg and Julia Hirschberg (2007). + V-Measure: A conditional entropy-based external cluster evaluation measure. + Proceedings of the 2007 Joing Conference on Empirical Methods in Natural Language + Processing and Computational Natural Language Learning, pp. 410 - 420, + Prague, June 2007. ↩
+Confusion Matrix for binary and multi-class classification.
+classes
+Default → None
The initial set of classes. This is optional and serves only for displaying purposes.
+classes
+total_false_negatives
+total_false_positives
+total_true_negatives
+total_true_positives
+from river import metrics
+
+y_true = ['cat', 'ant', 'cat', 'cat', 'ant', 'bird']
+y_pred = ['ant', 'ant', 'cat', 'cat', 'ant', 'cat']
+
+cm = metrics.ConfusionMatrix()
+
+for yt, yp in zip(y_true, y_pred):
+ cm = cm.update(yt, yp)
+
+cm
+ ant bird cat
+ ant 2 0 0
+bird 0 0 1
+ cat 1 0 2
+cm['bird']['cat']
+1.0
+This confusion matrix is a 2D matrix of shape (n_classes, n_classes), corresponding
+to a single-target (binary and multi-class) classification task.
Each row represents true (actual) class-labels, while each column corresponds
+to the predicted class-labels. For example, an entry in position [1, 2] means
+that the true class-label is 1, and the predicted class-label is 2 (incorrect prediction).
This structure is used to keep updated statistics about a single-output classifier's +performance and to compute multiple evaluation metrics.
+ + + + + + + + +Multiclass generalization of the logarithmic loss.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2]
+y_pred = [
+ {0: 0.29450637, 1: 0.34216758, 2: 0.36332605},
+ {0: 0.21290077, 1: 0.32728332, 2: 0.45981591},
+ {0: 0.42860913, 1: 0.33380113, 2: 0.23758974},
+ {0: 0.44941979, 1: 0.32962558, 2: 0.22095463}
+]
+
+metric = metrics.CrossEntropy()
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+ print(metric.get())
+1.222454
+1.169691
+1.258864
+1.321597
+metric
+CrossEntropy: 1.321598
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Binary F1 score.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [False, False, False, True, True, True]
+y_pred = [False, False, True, True, False, False]
+
+metric = metrics.F1()
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+F1: 40.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Binary F-Beta score.
+The FBeta score is a weighted harmonic mean between precision and recall. The higher the beta value, the higher the recall will be taken into account. When beta equals 1, precision and recall and equivalently weighted, which results in the F1 score (see metrics.F1).
beta
+Type → float
+Weight of precision in the harmonic mean.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+pos_val
+Default → True
Value to treat as "positive".
+precision (metrics.Precision)
+recall (metrics.Recall)
+from river import metrics
+
+y_true = [False, False, False, True, True, True]
+y_pred = [False, False, True, True, False, False]
+
+metric = metrics.FBeta(beta=2)
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+FBeta: 35.71%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Fowlkes-Mallows Index.
+The Fowlkes-Mallows Index 1 2 is an external evaluation method that is used to determine the similarity between two clusterings, and also a metric to measure confusion matrices. The measure of similarity could be either between two hierarchical clusterings or a clustering and a benchmark classification. A higher value for the Fowlkes-Mallows index indicates a greater similarity between the clusters and the benchmark classifications.
+The Fowlkes-Mallows Index, for two cluster algorithms, is defined as:
+where
+TP, FP, FN are respectively the number of true positives, false positives and false negatives;
+TPR is the True Positive Rate (or Sensitivity/Recall), PPV is the Positive Predictive Rate (or Precision).
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 0, 0, 1, 1, 1]
+y_pred = [0, 0, 1, 1, 2, 2]
+
+metric = metrics.FowlkesMallows()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+FowlkesMallows: 0.00%
+FowlkesMallows: 100.00%
+FowlkesMallows: 57.74%
+FowlkesMallows: 40.82%
+FowlkesMallows: 35.36%
+FowlkesMallows: 47.14%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Wikipedia contributors. (2020, December 22). + Fowlkes–Mallows index. In Wikipedia, The Free Encyclopedia, + from https://en.wikipedia.org/w/index.php?title=Fowlkes%E2%80%93Mallows_index&oldid=995714222 ↩
+E. B. Fowkles and C. L. Mallows (1983). + “A method for comparing two hierarchical clusterings”. + Journal of the American Statistical Association ↩
+Geometric mean score.
+The geometric mean is a good indicator of a classifier's performance in the presence of class imbalance because it is independent of the distribution of examples between classes. This implementation computes the geometric mean of class-wise sensitivity (recall).
+where \(s_i\) is the sensitivity (recall) of class \(i\) and \(n\) is the number of classes.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = ['cat', 'ant', 'cat', 'cat', 'ant', 'bird', 'bird']
+y_pred = ['ant', 'ant', 'cat', 'cat', 'ant', 'cat', 'bird']
+
+metric = metrics.GeometricMean()
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+GeometricMean: 69.34%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Barandela, R. et al. “Strategies for learning in class imbalance problems”, Pattern Recognition, 36(3), (2003), pp 849-851. ↩
+Homogeneity Score.
+Homogeneity metric 1 of a cluster labeling given a ground truth.
+In order to satisfy the homogeneity criteria, a clustering must assign only those data points that are members of a single class to a single cluster. That is, the class distribution within each cluster should be skewed to a single class, that is, zero entropy. We determine how close a given clustering is to this ideal by examining the conditional entropy of the class distribution given the proposed clustering.
+However, in an imperfect situation, the size of this value is dependent on the size of the dataset and the distribution of class sizes. Therefore, instead of taking the raw conditional entropy, we normalize by the maximum reduction in entropy the clustering information could provide.
+As such, we define homogeneity as:
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [1, 1, 2, 2, 3, 3]
+y_pred = [1, 1, 1, 2, 2, 2]
+
+metric = metrics.Homogeneity()
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+1.0
+1.0
+0.0
+0.311278
+0.37515
+0.42062
+metric
+Homogeneity: 42.06%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Andrew Rosenberg and Julia Hirschberg (2007). + V-Measure: A conditional entropy-based external cluster evaluation measure. + Proceedings of the 2007 Joing Conference on Empirical Methods in Natural Language + Processing and Computational Natural Language Learning, pp. 410 - 420, + Prague, June 2007. ↩
+Jaccard score.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [False, True, True]
+y_pred = [True, True, True]
+
+metric = metrics.Jaccard()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+Jaccard: 0.00%
+Jaccard: 50.00%
+Jaccard: 66.67%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Binary logarithmic loss.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [True, False, False, True]
+y_pred = [0.9, 0.1, 0.2, 0.65]
+
+metric = metrics.LogLoss()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+ print(metric.get())
+0.105360
+0.105360
+0.144621
+0.216161
+metric
+LogLoss: 0.216162
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mean absolute error.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [3, -0.5, 2, 7]
+y_pred = [2.5, 0.0, 2, 8]
+
+metric = metrics.MAE()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+0.5
+0.5
+0.333
+0.5
+metric
+MAE: 0.5
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mean absolute percentage error.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [3, -0.5, 2, 7]
+y_pred = [2.5, 0.0, 2, 8]
+
+metric = metrics.MAPE()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+MAPE: 32.738095
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Matthews correlation coefficient.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [True, True, True, False]
+y_pred = [True, False, True, True]
+
+mcc = metrics.MCC()
+
+for yt, yp in zip(y_true, y_pred):
+ mcc = mcc.update(yt, yp)
+
+mcc
+MCC: -0.333333
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Mean squared error.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [3, -0.5, 2, 7]
+y_pred = [2.5, 0.0, 2, 8]
+
+metric = metrics.MSE()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+0.25
+0.25
+0.1666
+0.375
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Macro-average F1 score.
+This works by computing the F1 score per class, and then performs a global average.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MacroF1()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MacroF1: 100.00%
+MacroF1: 33.33%
+MacroF1: 55.56%
+MacroF1: 55.56%
+MacroF1: 48.89%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Macro-average F-Beta score.
+This works by computing the F-Beta score per class, and then performs a global average.
+beta
+Weight of precision in harmonic mean.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MacroFBeta(beta=.8)
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MacroFBeta: 100.00%
+MacroFBeta: 31.06%
+MacroFBeta: 54.04%
+MacroFBeta: 54.04%
+MacroFBeta: 48.60%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Macro-average Jaccard score.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MacroJaccard()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MacroJaccard: 100.00%
+MacroJaccard: 25.00%
+MacroJaccard: 50.00%
+MacroJaccard: 50.00%
+MacroJaccard: 38.89%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Macro-average precision score.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MacroPrecision()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MacroPrecision: 100.00%
+MacroPrecision: 25.00%
+MacroPrecision: 50.00%
+MacroPrecision: 50.00%
+MacroPrecision: 50.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Macro-average recall score.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MacroRecall()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MacroRecall: 100.00%
+MacroRecall: 50.00%
+MacroRecall: 66.67%
+MacroRecall: 66.67%
+MacroRecall: 55.56%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Micro-average F1 score.
+This computes the F1 score by merging all the predictions and true labels, and then computes a global F1 score.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 0]
+y_pred = [0, 1, 1, 2, 1]
+
+metric = metrics.MicroF1()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+MicroF1: 60.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + + +
Micro-average F-Beta score.
+This computes the F-Beta score by merging all the predictions and true labels, and then computes a global F-Beta score.
+beta
+Type → float
+Weight of precision in the harmonic mean.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 0]
+y_pred = [0, 1, 1, 2, 1]
+
+metric = metrics.MicroFBeta(beta=2)
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+MicroFBeta: 60.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++1. Why are precision, recall and F1 score equal when using micro averaging in a multi-class problem?
+ + + + + + + + +Micro-average Jaccard score.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MicroJaccard()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MicroJaccard: 100.00%
+MicroJaccard: 33.33%
+MicroJaccard: 50.00%
+MicroJaccard: 60.00%
+MicroJaccard: 42.86%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Micro-average precision score.
+The micro-average precision score is exactly equivalent to the micro-average recall as well as the micro-average F1 score.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MicroPrecision()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MicroPrecision: 100.00%
+MicroPrecision: 50.00%
+MicroPrecision: 66.67%
+MicroPrecision: 75.00%
+MicroPrecision: 60.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + + +
Micro-average recall score.
+The micro-average recall is exactly equivalent to the micro-average precision as well as the micro-average F1 score.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MicroRecall()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MicroRecall: 100.00%
+MicroRecall: 50.00%
+MicroRecall: 66.67%
+MicroRecall: 75.00%
+MicroRecall: 60.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + + +
Multi-class F-Beta score with different betas per class.
+The multiclass F-Beta score is the arithmetic average of the binary F-Beta scores of each class. The mean can be weighted by providing class weights.
+betas
+Weight of precision in the harmonic mean of each class.
+weights
+Class weights. If not provided then uniform weights will be used.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.MultiFBeta(
+ betas={0: 0.25, 1: 1, 2: 4},
+ weights={0: 1, 1: 1, 2: 2}
+)
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+MultiFBeta: 100.00%
+MultiFBeta: 25.76%
+MultiFBeta: 62.88%
+MultiFBeta: 62.88%
+MultiFBeta: 46.88%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mutual Information between two clusterings.
+The Mutual Information 1 is a measure of the similarity between two labels of the same data. Where \(|U_i|\) is the number of samples in cluster \(U_i\) and \(|V_j|\) is the number of the samples in cluster \(V_j\), the Mutual Information between clusterings \(U\) and \(V\) can be calculated as:
+This metric is independent of the absolute values of the labels: a permutation of the class or cluster label values won't change the score.
+This metric is furthermore symmetric: switching y_true and y_pred will return the same score value. This can be useful to measure the agreement of two independent label assignments strategies on the same dataset when the real ground truth is not known.
The Mutual Information can be equivalently expressed as:
+where \(H(U)\) and \(H(V)\) are the marginal entropies, \(H(U | V)\) and \(H(V | U)\) are the conditional entropies.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [1, 1, 2, 2, 3, 3]
+y_pred = [1, 1, 1, 2, 2, 2]
+
+metric = metrics.MutualInfo()
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+0.0
+0.0
+0.0
+0.215761
+0.395752
+0.462098
+metric
+MutualInfo: 0.462098
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Wikipedia contributors. (2021, March 17). Mutual information. + In Wikipedia, The Free Encyclopedia, + from https://en.wikipedia.org/w/index.php?title=Mutual_information&oldid=1012714929 ↩
+Normalized Mutual Information between two clusterings.
+Normalized Mutual Information (NMI) is a normalized version of the Mutual Information (MI) score to scale the results between the range of 0 (no mutual information) and 1 (perfectly mutual information). In the formula, the mutual information will be normalized by a generalized mean of the entropy of true and predicted labels, defined by the average_method.
We note that this measure is not adjusted for chance (i.e corrected the effect of result agreement solely due to chance); as a result, the Adjusted Mutual Info Score will mostly be preferred. However, this metric is still symmetric, which means that switching true and predicted labels will not alter the score value. This fact can be useful when the metric is used to measure the agreement between two indepedent label solutions on the same dataset, when the ground truth remains unknown.
+Another advantage of the metric is that as it is based on the calculation of entropy-related measures, it is independent of the permutation of class/cluster labels.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+average_method
+Default → arithmetic
This parameter defines how to compute the normalizer in the denominator. Possible options include min, max, arithmetic and geometric.
bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [1, 1, 2, 2, 3, 3]
+y_pred = [1, 1, 1, 2, 2, 2]
+
+metric = metrics.NormalizedMutualInfo()
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+1.0
+1.0
+0.0
+0.343711
+0.458065
+0.515803
+metric
+NormalizedMutualInfo: 0.515804
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Wikipedia contributors. (2021, March 17). Mutual information. + In Wikipedia, The Free Encyclopedia, + from https://en.wikipedia.org/w/index.php?title=Mutual_information&oldid=1012714929 ↩
+Binary precision score.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [True, False, True, True, True]
+y_pred = [True, True, False, True, True]
+
+metric = metrics.Precision()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+Precision: 100.00%
+Precision: 50.00%
+Precision: 50.00%
+Precision: 66.67%
+Precision: 75.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Coefficient of determination (\(R^2\)) score
+The coefficient of determination, denoted \(R^2\) or \(r^2\), is the proportion of the variance in the dependent variable that is predictable from the independent variable(s). 1
+Best possible score is 1.0 and it can be negative (because the model can be arbitrarily worse). A constant model that always predicts the expected value of \(y\), disregarding the input features, would get a \(R^2\) score of 0.0.
+\(R^2\) is not defined when less than 2 samples have been observed. This implementation returns 0.0 in this case.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [3, -0.5, 2, 7]
+y_pred = [2.5, 0.0, 2, 8]
+
+metric = metrics.R2()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+0.0
+0.9183
+0.9230
+0.9486
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Root mean squared error.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [3, -0.5, 2, 7]
+y_pred = [2.5, 0.0, 2, 8]
+
+metric = metrics.RMSE()
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+0.5
+0.5
+0.408248
+0.612372
+metric
+RMSE: 0.612372
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Root mean squared logarithmic error.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [3, -0.5, 2, 7]
+y_pred = [2.5, 0.0, 2, 8]
+
+metric = metrics.RMSLE()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+RMSLE: 0.357826
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Receiving Operating Characteristic Area Under the Curve.
+This metric is an approximation of the true ROC AUC. Computing the true ROC AUC would require storing all the predictions and ground truths, which isn't desirable. The approximation error is not significant as long as the predicted probabilities are well calibrated. In any case, this metric can still be used to reliably compare models between each other.
+n_thresholds
+Default → 10
The number of thresholds used for discretizing the ROC curve. A higher value will lead to more accurate results, but will also cost more time and memory.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [ 0, 0, 1, 1]
+y_pred = [.1, .4, .35, .8]
+
+metric = metrics.ROCAUC()
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+ROCAUC: 87.50%
+The true ROC AUC is in fact 0.75. We can improve the accuracy by increasing the amount +of thresholds. This comes at the cost more computation time and more memory usage.
+metric = metrics.ROCAUC(n_thresholds=20)
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+ROCAUC: 75.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Rand Index.
+The Rand Index 1 2 is a measure of the similarity between two data clusterings. Given a set of elements S and two partitions of S to compare, X and Y, define the following:
a, the number of pairs of elements in S that are in the same subset in X and in the same subset in Y
b, the number of pairs of elements in S that are in the different subset in X and in different subsets in Y
c, the number of pairs of elements in S that are in the same subset in X and in different subsets in Y
d, the number of pairs of elements in S that are in the different subset in X and in the same subset in Y
The Rand index, R, is
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 0, 0, 1, 1, 1]
+y_pred = [0, 0, 1, 1, 2, 2]
+
+metric = metrics.Rand()
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+Rand: 0.666667
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Wikipedia contributors. (2021, January 13). Rand index. + In Wikipedia, The Free Encyclopedia, + from https://en.wikipedia.org/w/index.php?title=Rand_index&oldid=1000098911 ↩
+W. M. Rand (1971). "Objective criteria for the evaluation of clustering methods". + Journal of the American Statistical Association. American Statistical Association. + 66 (336): 846–850. arXiv:1704.01036. doi:10.2307/2284239. JSTOR 2284239. ↩
+Binary recall score.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [True, False, True, True, True]
+y_pred = [True, True, False, True, True]
+
+metric = metrics.Recall()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+Recall: 100.00%
+Recall: 100.00%
+Recall: 50.00%
+Recall: 66.67%
+Recall: 75.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Rolling version of the Receiving Operating Characteristic Area Under the Curve.
+The RollingROCAUC calculates the metric using the instances in its window of size S. It keeps a queue of the instances, when an instance is added and the queue length is equal to S, the last instance is removed. The metric has a tree with ordered instances, in order to calculate the AUC efficiently. It was implemented based on the algorithm presented in Brzezinski and Stefanowski, 2017.
+The difference between this metric and the standard ROCAUC is that the latter calculates an approximation of the real metric considering all data from the beginning of the stream, while the RollingROCAUC calculates the exact value considering only the last S instances. This approach may be beneficial if it's necessary to evaluate the model's performance over time, since calculating the metric using the entire stream may hide the current performance of the classifier.
+window_size
+Default → 1000
The max length of the window.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [ 0, 1, 0, 1, 0, 1, 0, 0, 1, 1]
+y_pred = [.3, .5, .5, .7, .1, .3, .1, .4, .35, .8]
+
+metric = metrics.RollingROCAUC(window_size=4)
+
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+RollingROCAUC: 75.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
++
Update the metric.
+Parameters
++
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Symmetric mean absolute percentage error.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 0.07533, 0.07533, 0.07533, 0.07533, 0.07533, 0.07533, 0.0672, 0.0672]
+y_pred = [0, 0.102, 0.107, 0.047, 0.1, 0.032, 0.047, 0.108, 0.089]
+
+metric = metrics.SMAPE()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+SMAPE: 37.869392
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Silhouette coefficient 1, roughly speaking, is the ratio between cohesion and the average distances from the points to their second-closest centroid. It rewards the clustering algorithm where points are very close to their assigned centroids and far from any other centroids, that is, clustering results with good cohesion and good separation.
+It rewards clusterings where points are very close to their assigned centroids and far from any other centroids, that is clusterings with good cohesion and good separation. 2
+The definition of Silhouette coefficient for online clustering evaluation is different from that of batch learning. It does not store information and calculate pairwise distances between all points at the same time, since the practice is too expensive for an incremental metric.
+bigger_is_better
+Indicates if a high value is better than a low one or not.
+from river import cluster
+from river import stream
+from river import metrics
+
+X = [
+ [1, 2],
+ [1, 4],
+ [1, 0],
+ [4, 2],
+ [4, 4],
+ [4, 0],
+ [-2, 2],
+ [-2, 4],
+ [-2, 0]
+]
+
+k_means = cluster.KMeans(n_clusters=3, halflife=0.4, sigma=3, seed=0)
+metric = metrics.Silhouette()
+
+for x, _ in stream.iter_array(X):
+ k_means = k_means.learn_one(x)
+ y_pred = k_means.predict_one(x)
+ metric = metric.update(x, y_pred, k_means.centers)
+
+metric
+Silhouette: 0.568058
+Return the current value of the metric.
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + + +
VBeta.
+VBeta (or V-Measure) 1 is an external entropy-based cluster evaluation measure. It provides an elegant solution to many problems that affect previously defined cluster evaluation measures including
+Dependance of clustering algorithm or dataset,
+The "problem of matching", where the clustering of only a portion of data points are evaluated, and
+Accurate evaluation and combination of two desirable aspects of clustering, homogeneity and completeness.
+Based upon the calculations of homogeneity and completeness, a clustering solution's V-measure is calculated by computing the weighted harmonic mean of homogeneity and completeness,
+beta
+Type → float
+Default → 1.0
Weight of Homogeneity in the harmonic mean.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [1, 1, 2, 2, 3, 3]
+y_pred = [1, 1, 1, 2, 2, 2]
+
+metric = metrics.VBeta(beta=1.0)
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp).get())
+1.0
+1.0
+0.0
+0.3437110184854507
+0.4580652856440158
+0.5158037429793888
+metric
+VBeta: 51.58%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++
Andrew Rosenberg and Julia Hirschberg (2007). + V-Measure: A conditional entropy-based external cluster evaluation measure. + Proceedings of the 2007 Joing Conference on Empirical Methods in Natural Language + Processing and Computational Natural Language Learning, pp. 410 - 420, + Prague, June 2007. ↩
+Weighted-average F1 score.
+This works by computing the F1 score per class, and then performs a global weighted average by using the support of each class.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.WeightedF1()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+WeightedF1: 100.00%
+WeightedF1: 33.33%
+WeightedF1: 55.56%
+WeightedF1: 66.67%
+WeightedF1: 61.33%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Weighted-average F-Beta score.
+This works by computing the F-Beta score per class, and then performs a global weighted average according to the support of each class.
+beta
+Weight of precision in the harmonic mean.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.WeightedFBeta(beta=0.8)
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+WeightedFBeta: 100.00%
+WeightedFBeta: 31.06%
+WeightedFBeta: 54.04%
+WeightedFBeta: 65.53%
+WeightedFBeta: 62.63%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Weighted average Jaccard score.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.WeightedJaccard()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+WeightedJaccard: 100.00%
+WeightedJaccard: 25.00%
+WeightedJaccard: 50.00%
+WeightedJaccard: 62.50%
+WeightedJaccard: 50.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Weighted-average precision score.
+This uses the support of each label to compute an average score, whereas metrics.MacroPrecision ignores the support.
cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.WeightedPrecision()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+WeightedPrecision: 100.00%
+WeightedPrecision: 25.00%
+WeightedPrecision: 50.00%
+WeightedPrecision: 62.50%
+WeightedPrecision: 70.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Weighted-average recall score.
+This uses the support of each label to compute an average score, whereas MacroRecall ignores the support.
cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [0, 1, 2, 2, 2]
+y_pred = [0, 0, 2, 2, 1]
+
+metric = metrics.WeightedRecall()
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+WeightedRecall: 100.00%
+WeightedRecall: 50.00%
+WeightedRecall: 66.67%
+WeightedRecall: 75.00%
+WeightedRecall: 60.00%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mother class for all binary classification metrics.
+cm
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+pos_val
+Default → True
Value to treat as "positive".
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mother class for all classification metrics.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mother class for all metrics.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
++
Update the metric.
+Parameters
++
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
A container class for handling multiple metrics at once.
+metrics
+str_sep
+Default → ,
bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mother class for all multi-class classification metrics.
+cm
+Type → confusion.ConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+Indicates if labels are required, rather than probabilities.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mother class for all regression metrics.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
++
Update the metric.
+Parameters
++
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
bigger_is_better
+Indicate if a high value is better than a low one or not.
+metric
+Gives access to the wrapped metric.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
++
Update the metric.
+Parameters
++
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Exact match score.
+This is the most strict multi-label metric, defined as the number of samples that have all their labels correctly classified, divided by the total number of samples.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [
+ {0: False, 1: True, 2: True},
+ {0: True, 1: True, 2: False},
+ {0: True, 1: True, 2: False},
+]
+
+y_pred = [
+ {0: True, 1: True, 2: True},
+ {0: True, 1: False, 2: False},
+ {0: True, 1: True, 2: False},
+]
+
+metric = metrics.multioutput.ExactMatch()
+for yt, yp in zip(y_true, y_pred):
+ metric = metric.update(yt, yp)
+
+metric
+ExactMatch: 33.33%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Macro-average wrapper.
+A copy of the provided metric is made for each output. The arithmetic average of all the metrics is returned.
+metric
+A classification or a regression metric.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+metric
+Gives access to the wrapped metric.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Micro-average wrapper.
+The provided metric is updated with the value of each output.
+metric
+A classification or a regression metric.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+metric
+Gives access to the wrapped metric.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Multi-label confusion matrix.
+Under the hood, this stores one metrics.ConfusionMatrix for each output.
from river import metrics
+
+cm = metrics.multioutput.MultiLabelConfusionMatrix()
+
+y_true = [
+ {0: False, 1: True, 2: True},
+ {0: True, 1: True, 2: False}
+]
+
+y_pred = [
+ {0: True, 1: True, 2: True},
+ {0: True, 1: False, 2: False}
+]
+
+for yt, yp in zip(y_true, y_pred):
+ cm = cm.update(yt, yp)
+
+cm
+0
+ False True
+ False 0 1
+ True 0 1
+<BLANKLINE>
+1
+ False True
+ False 0 0
+ True 1 1
+<BLANKLINE>
+2
+ False True
+ False 1 0
+ True 0 1
+Per-output wrapper.
+A copy of the metric is maintained for each output.
+metric
+A classification or a regression metric.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+metric
+Gives access to the wrapped metric.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Sample-average wrapper.
+The provided metric is evaluate on each sample. The arithmetic average over all the samples is returned. This is equivalent to using average='samples' in scikit-learn.
metric
+A classification or a regression metric.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+metric
+Gives access to the wrapped metric.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+from river import metrics
+
+y_true = [
+ {0: False, 1: True, 2: True},
+ {0: True, 1: True, 2: False}
+]
+y_pred = [
+ {0: True, 1: True, 2: True},
+ {0: True, 1: False, 2: False}
+]
+
+sample_jaccard = metrics.multioutput.SampleAverage(metrics.Jaccard())
+
+for yt, yp in zip(y_true, y_pred):
+ sample_jaccard = sample_jaccard.update(yt, yp)
+sample_jaccard
+SampleAverage(Jaccard): 58.33%
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mother class for all multi-output classification metrics.
+cm
+Type → MultiLabelConfusionMatrix | None
+Default → None
This parameter allows sharing the same confusion matrix between multiple metrics. Sharing a confusion matrix reduces the amount of storage and computation time.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+requires_labels
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
+1.0 +
Update the metric.
+Parameters
+1.0 +
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Mother class for all multi-output regression metrics.
+bigger_is_better
+Indicate if a high value is better than a low one or not.
+works_with_weights
+Indicate whether the model takes into consideration the effect of sample weights
+Return the current value of the metric.
++
Indicate if the current metric is better than another one.
+Parameters
++
Revert the metric.
+Parameters
++
Update the metric.
+Parameters
++
Indicates whether or not a metric can work with a given model.
+Parameters
++ + + + + + + + +
Sliding Discrete Fourier Transform (SDFT).
+Initially, the coefficients are all equal to 0, up until enough values have been seen. A call to numpy.fft.fft is triggered once window_size values have been seen. Subsequent values will update the coefficients online. This is much faster than recomputing an FFT from scratch for every new value.
window_size
+The size of the window.
+import numpy as np
+from river import misc
+
+X = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+
+window_size = 5
+sdft = misc.SDFT(window_size)
+
+for i, x in enumerate(X):
+ sdft = sdft.update(x)
+
+ if i + 1 >= window_size:
+ assert np.allclose(sdft.coefficients, np.fft.fft(X[i+1 - window_size:i+1]))
+A skyline is set of points which is not dominated by any other point.
+This implementation uses a block nested loop. Identical observations are all part of the skyline if applicable.
+minimize
+Type → list | None
+Default → None
A list of features for which the values need to be minimized. Can be omitted as long as maximize is specified.
maximize
+Type → list | None
+Default → None
A list of features for which the values need to be maximized. Can be omitted as long as minimize is specified.
Here is an example taken from this blog post.
+import random
+from river import misc
+
+city_prices = {
+ 'Bordeaux': 4045,
+ 'Lyon': 4547,
+ 'Toulouse': 3278
+}
+
+def random_house():
+ city = random.choice(['Bordeaux', 'Lyon', 'Toulouse'])
+ size = round(random.gauss(200, 50))
+ price = round(random.uniform(0.8, 1.2) * city_prices[city] * size)
+ return {'city': city, 'size': size, 'price': price}
+
+skyline = misc.Skyline(minimize=['price'], maximize=['size'])
+
+random.seed(42)
+
+for _ in range(100):
+ house = random_house()
+ skyline = skyline.update(house)
+
+print(len(skyline))
+13
+print(skyline[0])
+{'city': 'Toulouse', 'size': 280, 'price': 763202}
+Here is another example using the kart data from Mario Kart: Double Dash!!.
+import collections
+from river import misc
+
+Kart = collections.namedtuple(
+ 'Kart',
+ 'name speed off_road acceleration weight turbo'
+)
+
+karts = [
+ Kart('Red Fire', 5, 4, 4, 5, 2),
+ Kart('Green Fire', 7, 3, 3, 4, 2),
+ Kart('Heart Coach', 4, 6, 6, 5, 2),
+ Kart('Bloom Coach', 6, 4, 5, 3, 2),
+ Kart('Turbo Yoshi', 4, 5, 6, 6, 2),
+ Kart('Turbo Birdo', 6, 4, 4, 7, 2),
+ Kart('Goo-Goo Buggy', 1, 9, 9, 2, 3),
+ Kart('Rattle Buggy', 2, 9, 8, 2, 3),
+ Kart('Toad Kart', 3, 9, 7, 2, 3),
+ Kart('Toadette Kart', 1, 9, 9, 2, 3),
+ Kart('Koopa Dasher', 2, 8, 8, 3, 3),
+ Kart('Para-Wing', 1, 8, 9, 3, 3),
+ Kart('DK Jumbo', 8, 2, 2, 8, 1),
+ Kart('Barrel Train', 8, 7, 3, 5, 3),
+ Kart('Koopa King', 9, 1, 1, 9, 1),
+ Kart('Bullet Blaster', 8, 1, 4, 1, 3),
+ Kart('Wario Car', 7, 3, 3, 7, 1),
+ Kart('Waluigi Racer', 5, 9, 5, 6, 2),
+ Kart('Piranha Pipes', 8, 7, 2, 9, 1),
+ Kart('Boo Pipes', 2, 9, 8, 9, 1),
+ Kart('Parade Kart', 7, 3, 4, 7, 3)
+]
+
+skyline = misc.Skyline(
+ maximize=['speed', 'off_road', 'acceleration', 'turbo'],
+ minimize=['weight']
+)
+
+for kart in karts:
+ skyline = skyline.update(kart._asdict())
+
+best_cart_names = [kart['name'] for kart in skyline]
+for name in best_cart_names:
+ print(f'- {name}')
+- Green Fire
+- Heart Coach
+- Bloom Coach
+- Goo-Goo Buggy
+- Rattle Buggy
+- Toad Kart
+- Toadette Kart
+- Barrel Train
+- Koopa King
+- Bullet Blaster
+- Waluigi Racer
+- Parade Kart
+for name in sorted(set(kart.name for kart in karts) - set(best_cart_names)):
+ print(f'- {name}')
+- Boo Pipes
+- DK Jumbo
+- Koopa Dasher
+- Para-Wing
+- Piranha Pipes
+- Red Fire
+- Turbo Birdo
+- Turbo Yoshi
+- Wario Car
+Borzsony, S., Kossmann, D. and Stocker, K., 2001, April. The skyline operator. In Proceedings 17th international conference on data engineering (pp. 421-430). IEEE. ↩
+Tao, Y. and Papadias, D., 2006. Maintaining sliding window skylines on data streams. IEEE Transactions on Knowledge and Data Engineering, 18(3), pp.377-391. ↩
+Bandit-based model selection for classification.
+Each model is associated with an arm. At each learn_one call, the policy decides which arm/model to pull. The reward is the performance of the model on the provided sample. The predict_one and predict_proba_one methods use the current best model.
models
+The models to select from.
+metric
+Type → metrics.base.ClassificationMetric
+The metric that is used to measure the performance of each model.
+policy
+Type → bandit.base.Policy
+The bandit policy to use.
+best_model
+models
+from river import bandit
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import model_selection
+from river import optim
+from river import preprocessing
+
+models = [
+ linear_model.LogisticRegression(optimizer=optim.SGD(lr=lr))
+ for lr in [0.0001, 0.001, 1e-05, 0.01]
+]
+
+dataset = datasets.Phishing()
+model = (
+ preprocessing.StandardScaler() |
+ model_selection.BanditClassifier(
+ models,
+ metric=metrics.Accuracy(),
+ policy=bandit.EpsilonGreedy(
+ epsilon=0.1,
+ decay=0.001,
+ burn_in=20,
+ seed=42
+ )
+ )
+)
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 88.96%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Bandit-based model selection for regression.
+Each model is associated with an arm. At each learn_one call, the policy decides which arm/model to pull. The reward is the performance of the model on the provided sample. The predict_one method uses the current best model.
models
+The models to select from.
+metric
+Type → metrics.base.RegressionMetric
+The metric that is used to measure the performance of each model.
+policy
+Type → bandit.base.Policy
+The bandit policy to use.
+best_model
+models
+from river import bandit
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import model_selection
+from river import optim
+from river import preprocessing
+
+models = [
+ linear_model.LinearRegression(optimizer=optim.SGD(lr=lr))
+ for lr in [0.0001, 0.001, 1e-05, 0.01]
+]
+
+dataset = datasets.TrumpApproval()
+model = (
+ preprocessing.StandardScaler() |
+ model_selection.BanditRegressor(
+ models,
+ metric=metrics.MAE(),
+ policy=bandit.EpsilonGreedy(
+ epsilon=0.1,
+ decay=0.001,
+ burn_in=100,
+ seed=42
+ )
+ )
+)
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 3.134089
+Here's another example using the UCB policy. The latter is more sensitive to the target scale, +and usually works better when the target is rescaled.
+models = [
+ linear_model.LinearRegression(optimizer=optim.SGD(lr=lr))
+ for lr in [0.0001, 0.001, 1e-05, 0.01]
+]
+
+model = (
+ preprocessing.StandardScaler() |
+ preprocessing.TargetStandardScaler(
+ model_selection.BanditRegressor(
+ models,
+ metric=metrics.MAE(),
+ policy=bandit.UCB(
+ delta=1,
+ burn_in=100
+ )
+ )
+ )
+)
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.875333
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Greedy selection regressor.
+This selection method simply updates each model at each time step. The current best model is used to make predictions. It's greedy in the sense that updating each model can be costly. On the other hand, bandit-like algorithms are more temperate in that only update a subset of the models at each step.
+models
+Type → list[base.Regressor]
+The models to select from.
+metric
+Type → metrics.base.RegressionMetric | None
+Default → None
The metric that is used to measure the performance of each model.
+best_model
+The current best model.
+models
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import model_selection
+from river import optim
+from river import preprocessing
+
+models = [
+ linear_model.LinearRegression(optimizer=optim.SGD(lr=lr))
+ for lr in [1e-5, 1e-4, 1e-3, 1e-2]
+]
+
+dataset = datasets.TrumpApproval()
+metric = metrics.MAE()
+model = (
+ preprocessing.StandardScaler() |
+ model_selection.GreedyRegressor(models, metric)
+)
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 1.319678
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Successive halving algorithm for classification.
+Successive halving is a method for performing model selection without having to train each model on all the dataset. At certain points in time (called "rungs"), the worst performing will be discarded and the best ones will keep competing between each other. The rung values are designed so that at most budget model updates will be performed in total.
If you have k combinations of hyperparameters and that your dataset contains n observations, then the maximal budget you can allocate is:
It is recommended that you check this beforehand. This bound can't be checked by the function because the size of the dataset is not known. In fact it is potentially infinite, in which case the algorithm will terminate once all the budget has been spent.
+If you have a budget of B, and that your dataset contains n observations, then the number of hyperparameter combinations that will spend all the budget and go through all the data is:
models
+The models to compare.
+metric
+Type → metrics.base.Metric
+Metric used for comparing models with.
+budget
+Type → int
+Total number of model updates you wish to allocate.
+eta
+Default → 2
Rate of elimination. At every rung, math.ceil(k / eta) models are kept, where k is the number of models that have reached the rung. A higher eta value will focus on less models but will allocate more iterations to the best models.
verbose
+Default → False
Whether to display progress or not.
+print_kwargs
+Extra keyword arguments are passed to the print function. For instance, this allows providing a file argument, which indicates where to output progress.
best_model
+The current best model.
+models
+As an example, let's use successive halving to tune the optimizer of a logistic regression. +We'll first define the model.
+from river import linear_model
+from river import preprocessing
+
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression()
+)
+Let's now define a grid of parameters which we would like to compare. We'll try +different optimizers with various learning rates.
+from river import utils
+from river import optim
+
+models = utils.expand_param_grid(model, {
+ 'LogisticRegression': {
+ 'optimizer': [
+ (optim.SGD, {'lr': [.1, .01, .005]}),
+ (optim.Adam, {'beta_1': [.01, .001], 'lr': [.1, .01, .001]}),
+ (optim.Adam, {'beta_1': [.1], 'lr': [.001]}),
+ ]
+ }
+})
+We can check how many models we've created.
+len(models)
+10
+We can now pass these models to a SuccessiveHalvingClassifier. We also need to pick a
+metric to compare the models, and a budget which indicates how many iterations to run
+before picking the best model and discarding the rest.
from river import model_selection
+
+sh = model_selection.SuccessiveHalvingClassifier(
+ models,
+ metric=metrics.Accuracy(),
+ budget=2000,
+ eta=2,
+ verbose=True
+)
+A SuccessiveHalvingClassifier is also a classifier with a learn_one and a
+predict_proba_one method. We can therefore evaluate it like any other classifier with
+evaluate.progressive_val_score.
from river import datasets
+from river import evaluate
+from river import metrics
+
+evaluate.progressive_val_score(
+ dataset=datasets.Phishing(),
+ model=sh,
+ metric=metrics.ROCAUC()
+)
+[1] 5 removed 5 left 50 iterations budget used: 500 budget left: 1500 best Accuracy: 80.00%
+[2] 2 removed 3 left 100 iterations budget used: 1000 budget left: 1000 best Accuracy: 84.00%
+[3] 1 removed 2 left 166 iterations budget used: 1498 budget left: 502 best Accuracy: 86.14%
+[4] 1 removed 1 left 250 iterations budget used: 1998 budget left: 2 best Accuracy: 84.80%
+ROCAUC: 95.22%
+We can now view the best model.
+sh.best_model
+Pipeline (
+ StandardScaler (
+ with_std=True
+ ),
+ LogisticRegression (
+ optimizer=Adam (
+ lr=Constant (
+ learning_rate=0.01
+ )
+ beta_1=0.01
+ beta_2=0.999
+ eps=1e-08
+ )
+ loss=Log (
+ weight_pos=1.
+ weight_neg=1.
+ )
+ l2=0.
+ l1=0.
+ intercept_init=0.
+ intercept_lr=Constant (
+ learning_rate=0.01
+ )
+ clip_gradient=1e+12
+ initializer=Zeros ()
+ )
+)
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Jamieson, K. and Talwalkar, A., 2016, May. Non-stochastic best arm identification and hyperparameter optimization. In Artificial Intelligence and Statistics (pp. 240-248). ↩
+Li, L., Jamieson, K., Rostamizadeh, A., Gonina, E., Hardt, M., Recht, B. and Talwalkar, A., 2018. Massively parallel hyperparameter tuning. arXiv preprint arXiv:1810.05934. ↩
+Li, L., Jamieson, K., DeSalvo, G., Rostamizadeh, A. and Talwalkar, A., 2017. Hyperband: A novel bandit-based approach to hyperparameter optimization. The Journal of Machine Learning Research, 18(1), pp.6765-6816. ↩
+Successive halving algorithm for regression.
+Successive halving is a method for performing model selection without having to train each model on all the dataset. At certain points in time (called "rungs"), the worst performing will be discarded and the best ones will keep competing between each other. The rung values are designed so that at most budget model updates will be performed in total.
If you have k combinations of hyperparameters and that your dataset contains n observations, then the maximal budget you can allocate is:
It is recommended that you check this beforehand. This bound can't be checked by the function because the size of the dataset is not known. In fact it is potentially infinite, in which case the algorithm will terminate once all the budget has been spent.
+If you have a budget of B, and that your dataset contains n observations, then the number of hyperparameter combinations that will spend all the budget and go through all the data is:
models
+The models to compare.
+metric
+Type → metrics.base.Metric
+Metric used for comparing models with.
+budget
+Type → int
+Total number of model updates you wish to allocate.
+eta
+Default → 2
Rate of elimination. At every rung, math.ceil(k / eta) models are kept, where k is the number of models that have reached the rung. A higher eta value will focus on less models but will allocate more iterations to the best models.
verbose
+Default → False
Whether to display progress or not.
+print_kwargs
+Extra keyword arguments are passed to the print function. For instance, this allows providing a file argument, which indicates where to output progress.
best_model
+The current best model.
+models
+As an example, let's use successive halving to tune the optimizer of a linear regression. +We'll first define the model.
+from river import linear_model
+from river import preprocessing
+
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression(intercept_lr=.1)
+)
+Let's now define a grid of parameters which we would like to compare. We'll try +different optimizers with various learning rates.
+from river import optim
+from river import utils
+
+models = utils.expand_param_grid(model, {
+ 'LinearRegression': {
+ 'optimizer': [
+ (optim.SGD, {'lr': [.1, .01, .005]}),
+ (optim.Adam, {'beta_1': [.01, .001], 'lr': [.1, .01, .001]}),
+ (optim.Adam, {'beta_1': [.1], 'lr': [.001]}),
+ ]
+ }
+})
+We can check how many models we've created.
+len(models)
+10
+We can now pass these models to a SuccessiveHalvingRegressor. We also need to pick a
+metric to compare the models, and a budget which indicates how many iterations to run
+before picking the best model and discarding the rest.
from river import model_selection
+
+sh = model_selection.SuccessiveHalvingRegressor(
+ models,
+ metric=metrics.MAE(),
+ budget=2000,
+ eta=2,
+ verbose=True
+)
+A SuccessiveHalvingRegressor is also a regressor with a learn_one and a predict_one
+method. We can therefore evaluate it like any other classifier with
+evaluate.progressive_val_score.
from river import datasets
+from river import evaluate
+from river import metrics
+
+evaluate.progressive_val_score(
+ dataset=datasets.TrumpApproval(),
+ model=sh,
+ metric=metrics.MAE()
+)
+[1] 5 removed 5 left 50 iterations budget used: 500 budget left: 1500 best MAE: 4.419643
+[2] 2 removed 3 left 100 iterations budget used: 1000 budget left: 1000 best MAE: 2.392266
+[3] 1 removed 2 left 166 iterations budget used: 1498 budget left: 502 best MAE: 1.541383
+[4] 1 removed 1 left 250 iterations budget used: 1998 budget left: 2 best MAE: 1.112122
+MAE: 0.490688
+We can now view the best model.
+sh.best_model
+Pipeline (
+ StandardScaler (
+ with_std=True
+ ),
+ LinearRegression (
+ optimizer=Adam (
+ lr=Constant (
+ learning_rate=0.1
+ )
+ beta_1=0.01
+ beta_2=0.999
+ eps=1e-08
+ )
+ loss=Squared ()
+ l2=0.
+ l1=0.
+ intercept_init=0.
+ intercept_lr=Constant (
+ learning_rate=0.1
+ )
+ clip_gradient=1e+12
+ initializer=Zeros ()
+ )
+)
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++
Jamieson, K. and Talwalkar, A., 2016, May. Non-stochastic best arm identification and hyperparameter optimization. In Artificial Intelligence and Statistics (pp. 240-248). ↩
+Li, L., Jamieson, K., Rostamizadeh, A., Gonina, E., Hardt, M., Recht, B. and Talwalkar, A., 2018. Massively parallel hyperparameter tuning. arXiv preprint arXiv:1810.05934. ↩
+Li, L., Jamieson, K., DeSalvo, G., Rostamizadeh, A. and Talwalkar, A., 2017. Hyperband: A novel bandit-based approach to hyperparameter optimization. The Journal of Machine Learning Research, 18(1), pp.6765-6816. ↩
+A model selector for classification.
+models
+Type → Iterator[base.Estimator]
+metric
+Type → metrics.base.Metric
+best_model
+The current best model.
+models
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
A model selector for regression.
+models
+Type → Iterator[base.Estimator]
+metric
+Type → metrics.base.Metric
+best_model
+The current best model.
+models
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
One-vs-One (OvO) multiclass strategy.
+This strategy consists in fitting one binary classifier for each pair of classes. Because we are in a streaming context, the number of classes isn't known from the start, hence new classifiers are instantiated on the fly.
+The number of classifiers is k * (k - 1) / 2, where k is the number of classes. However, each call to learn_one only requires training k - 1 models. Indeed, only the models that pertain to the given label have to be trained. Meanwhile, making a prediction requires going through each and every model.
classifier
+A binary classifier, although a multi-class classifier will work too.
+classifiers (dict)
+A mapping between pairs of classes and classifiers. The keys are tuples which contain a pair of classes. Each pair is sorted in lexicographical order.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import multiclass
+from river import preprocessing
+
+dataset = datasets.ImageSegments()
+
+scaler = preprocessing.StandardScaler()
+ovo = multiclass.OneVsOneClassifier(linear_model.LogisticRegression())
+model = scaler | ovo
+
+metric = metrics.MacroF1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MacroF1: 80.76%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++ + + + + + + + +
One-vs-the-rest (OvR) multiclass strategy.
+This strategy consists in fitting one binary classifier per class. Because we are in a streaming context, the number of classes isn't known from the start. Hence, new classifiers are instantiated on the fly. Likewise, the predicted probabilities will only include the classes seen up to a given point in time.
+Note that this classifier supports mini-batches as well as single instances.
+The computational complexity for both learning and predicting grows linearly with the number of classes. If you have a very large number of classes, then you might want to consider using an multiclass.OutputCodeClassifier instead.
classifier
+Type → base.Classifier
+A binary classifier, although a multi-class classifier will work too.
+classifiers (dict)
+A mapping between classes and classifiers.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import multiclass
+from river import preprocessing
+
+dataset = datasets.ImageSegments()
+
+scaler = preprocessing.StandardScaler()
+ovr = multiclass.OneVsRestClassifier(linear_model.LogisticRegression())
+model = scaler | ovr
+
+metric = metrics.MacroF1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MacroF1: 77.46%
+This estimator also also supports mini-batching.
+for X in pd.read_csv(dataset.path, chunksize=64):
+ y = X.pop('category')
+ y_pred = model.predict_many(X)
+ model = model.learn_many(X, y)
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + +
Output-code multiclass strategy.
+This also referred to as "error-correcting output codes".
+This class allows to learn a multi-class classification problem with a binary classifier. Each class is converted to a code of 0s and 1s. The length of the code is called the code size. A copy of the classifier made for code. The codes associated with the classes are stored in a code book.
+When a new sample arrives, the label's code is retrieved from the code book. Then, each classifier is trained on the relevant part of code, which is either a 0 or a 1.
+For predicting, each classifier outputs a probability. These are then compared to each code in the code book, and the label which is the "closest" is chosen as the most likely class. Closeness is determined in terms of Manhattan distance.
+One specificity of online learning is that we don't how many classes there are initially. Therefore, a random procedure generates random codes on the fly whenever a previously unseed label appears.
+classifier
+Type → base.Classifier
+A binary classifier, although a multi-class classifier will work too.
+code_size
+Type → int
+The code size, which dictates how many copies of the provided classifiers to train. Must be strictly positive.
+coding_method
+Type → str
+Default → random
The method used to generate the codes. Can be either 'exact' or 'random'. The 'exact' method generates all possible codes of a given size in memory, and streams them in a random order. The 'random' method generates random codes of a given size on the fly. The 'exact' method necessarily generates different codes for each class, but requires more memory. The 'random' method can generate duplicate codes for different classes, but requires less memory.
+seed
+Type → int | None
+Default → None
A random seed number that can be set for reproducibility.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import multiclass
+from river import preprocessing
+
+dataset = datasets.ImageSegments()
+
+scaler = preprocessing.StandardScaler()
+ooc = multiclass.OutputCodeClassifier(
+ classifier=linear_model.LogisticRegression(),
+ code_size=10,
+ coding_method='random',
+ seed=1
+)
+model = scaler | ooc
+
+metric = metrics.MacroF1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MacroF1: 79.58%
+Update the model with a set of features x and a label y.
Parameters
+Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++
Dietterich, T.G. and Bakiri, G., 1994. Solving multiclass learning problems via error-correcting output codes. Journal of artificial intelligence research, 2, pp.263-286. ↩
+James, G. and Hastie, T., 1998. The error coding method and PICTs. Journal of Computational and Graphical statistics, 7(3), pp.377-387. ↩
+A multi-output model that arranges classifiers into a chain.
+This will create one model per output. The prediction of the first output will be used as a feature in the second model. The prediction for the second output will be used as a feature for the third model, etc. This "chain model" is therefore capable of capturing dependencies between outputs.
+model
+Type → base.Classifier
+A classifier model used for each label.
+order
+Type → list | None
+Default → None
A list with the targets order in which to construct the chain. If None then the order will be inferred from the order of the keys in the target.
from river import feature_selection
+from river import linear_model
+from river import metrics
+from river import multioutput
+from river import preprocessing
+from river import stream
+from sklearn import datasets
+
+dataset = stream.iter_sklearn_dataset(
+ dataset=datasets.fetch_openml('yeast', version=4, parser='auto', as_frame=False),
+ shuffle=True,
+ seed=42
+)
+
+model = feature_selection.VarianceThreshold(threshold=0.01)
+model |= preprocessing.StandardScaler()
+model |= multioutput.ClassifierChain(
+ model=linear_model.LogisticRegression(),
+ order=list(range(14))
+)
+
+metric = metrics.multioutput.MicroAverage(metrics.Jaccard())
+
+for x, y in dataset:
+ # Convert y values to booleans
+ y = {i: yi == 'TRUE' for i, yi in y.items()}
+ y_pred = model.predict_one(x)
+ metric = metric.update(y, y_pred)
+ model = model.learn_one(x, y)
+
+metric
+MicroAverage(Jaccard): 41.81%
+Update the model with a set of features x and the labels y.
Parameters
+Returns
+self
++
Predict the labels of a set of features x.
Parameters
+Returns
+dict[FeatureName, bool]: The predicted labels.
++
Predict the probability of each label appearing given dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++ + + + + + + + + +
Monte Carlo Sampling Classifier Chains.
+Probabilistic Classifier Chains using Monte Carlo sampling, as described in 1.
+m samples are taken from the posterior distribution. Therefore we need a probabilistic interpretation of the output, and thus, this is a particular variety of ProbabilisticClassifierChain.
+model
+Type → base.Classifier
+m
+Type → int
+Default → 10
Number of samples to take from the posterior distribution.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+from river import feature_selection
+from river import linear_model
+from river import metrics
+from river import multioutput
+from river import preprocessing
+from river.datasets import synth
+
+dataset = synth.Logical(seed=42, n_tiles=100)
+
+model = multioutput.MonteCarloClassifierChain(
+ model=linear_model.LogisticRegression(),
+ m=10,
+ seed=42
+)
+
+metric = metrics.multioutput.MicroAverage(metrics.Jaccard())
+
+for x, y in dataset:
+ y_pred = model.predict_one(x)
+ y_pred = {k: y_pred.get(k, 0) for k in y}
+ metric = metric.update(y, y_pred)
+ model = model.learn_one(x, y)
+
+metric
+MicroAverage(Jaccard): 51.79%
+Update the model with a set of features x and the labels y.
Parameters
+Returns
+self
++
Predict the labels of a set of features x.
Parameters
+Returns
+dict[FeatureName, bool]: The predicted labels.
++
Predict the probability of each label appearing given dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Read, J., Martino, L., & Luengo, D. (2014). Efficient monte carlo + methods for multi-dimensional learning with classifier chains. + Pattern Recognition, 47(3), 1535-1546. ↩
+Convert a multi-label task into multiclass.
+Assigns a class to each unique combination of labels, and proceeds with training the supplied multi-class classifier.
+The transformation is done by converting the label set, which could be seen as a binary number, into an integer representing a class. At prediction time, the predicted integer is converted back to a binary number which is the predicted label set.
+model
+Type → base.Classifier
+The classifier used for learning.
+from river import forest
+from river import metrics
+from river import multioutput
+from river.datasets import synth
+
+dataset = synth.Logical(seed=42, n_tiles=100)
+
+model = multioutput.MultiClassEncoder(
+ model=forest.ARFClassifier(seed=7)
+)
+
+metric = metrics.multioutput.MicroAverage(metrics.Jaccard())
+
+for x, y in dataset:
+ y_pred = model.predict_one(x)
+ y_pred = {k: y_pred.get(k, 0) for k in y}
+ metric = metric.update(y, y_pred)
+ model = model.learn_one(x, y)
+
+metric
+MicroAverage(Jaccard): 95.10%
+Update the model with a set of features x and the labels y.
Parameters
+Returns
+MultiLabelClassifier: self
++
Predict the labels of a set of features x.
Parameters
+Returns
+dict[FeatureName, bool]: The predicted labels.
++
Predict the probability of each label appearing given dictionary of features x.
Parameters
+Returns
+dict[FeatureName, dict[bool, float]]: A dictionary that associates a probability which each label.
++ + + + + + + + +
Probabilistic Classifier Chains.
+The Probabilistic Classifier Chains (PCC) 1 is a Bayes-optimal method based on the Classifier Chains (CC).
+Consider the concept of chaining classifiers as searching a path in a binary tree whose leaf nodes are associated with a label \(y \in Y\). While CC searches only a single path in the aforementioned binary tree, PCC looks at each of the \(2^l\) paths, where \(l\) is the number of labels. This limits the applicability of the method to data sets with a small to moderate number of labels. The authors recommend no more than about 15 labels for real-world applications.
+model
+Type → base.Classifier
+from river import linear_model
+from river import metrics
+from river import multioutput
+from river.datasets import synth
+
+dataset = synth.Logical(seed=42, n_tiles=100)
+
+model = multioutput.ProbabilisticClassifierChain(
+ model=linear_model.LogisticRegression()
+)
+
+metric = metrics.multioutput.MicroAverage(metrics.Jaccard())
+
+for x, y in dataset:
+ y_pred = model.predict_one(x)
+ y_pred = {k: y_pred.get(k, 0) for k in y}
+ metric = metric.update(y, y_pred)
+ model = model.learn_one(x, y)
+
+metric
+MicroAverage(Jaccard): 51.84%
+Update the model with a set of features x and the labels y.
Parameters
+Returns
+self
++
Predict the labels of a set of features x.
Parameters
+Returns
+dict[FeatureName, bool]: The predicted labels.
++
Predict the probability of each label appearing given dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Cheng, W., Hüllermeier, E., & Dembczynski, K. J. (2010). + Bayes optimal multilabel classification via probabilistic classifier + chains. In Proceedings of the 27th international conference on + machine learning (ICML-10) (pp. 279-286). ↩
+A multi-output model that arranges regressors into a chain.
+This will create one model per output. The prediction of the first output will be used as a feature in the second output. The prediction for the second output will be used as a feature for the third, etc. This "chain model" is therefore capable of capturing dependencies between outputs.
+model
+Type → base.Regressor
+The regression model used to make predictions for each target.
+order
+Type → list | None
+Default → None
A list with the targets order in which to construct the chain. If None then the order will be inferred from the order of the keys in the target.
from river import evaluate
+from river import linear_model
+from river import metrics
+from river import multioutput
+from river import preprocessing
+from river import stream
+
+from sklearn import datasets
+
+dataset = stream.iter_sklearn_dataset(
+ dataset=datasets.load_linnerud(),
+ shuffle=True,
+ seed=42
+)
+
+model = multioutput.RegressorChain(
+ model=(
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression(intercept_lr=0.3)
+ ),
+ order=[0, 1, 2]
+)
+
+metric = metrics.multioutput.MicroAverage(metrics.MAE())
+
+evaluate.progressive_val_score(dataset, model, metric)
+MicroAverage(MAE): 12.733525
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the outputs of features x.
Parameters
+Returns
+The predictions.
++ + + + + + + + +
Bernoulli Naive Bayes.
+Bernoulli Naive Bayes model learns from occurrences between features such as word counts and discrete classes. The input vector must contain positive values, such as counts or TF-IDF values.
+alpha
+Default → 1.0
Additive (Laplace/Lidstone) smoothing parameter (use 0 for no smoothing).
+true_threshold
+Default → 0.0
Threshold for binarizing (mapping to booleans) features.
+class_counts (collections.Counter)
+Number of times each class has been seen.
+feature_counts (collections.defaultdict)
+Total frequencies per feature and class.
+import pandas as pd
+from river import compose
+from river import feature_extraction
+from river import naive_bayes
+
+docs = [
+ ("Chinese Beijing Chinese", "yes"),
+ ("Chinese Chinese Shanghai", "yes"),
+ ("Chinese Macao", "yes"),
+ ("Tokyo Japan Chinese", "no")
+]
+
+model = compose.Pipeline(
+ ("tokenize", feature_extraction.BagOfWords(lowercase=False)),
+ ("nb", naive_bayes.BernoulliNB(alpha=1))
+)
+
+for sentence, label in docs:
+ model = model.learn_one(sentence, label)
+
+model["nb"].p_class("yes")
+0.75
+model["nb"].p_class("no")
+0.25
+model.predict_proba_one("test")
+{'yes': 0.8831539823829913, 'no': 0.11684601761700895}
+model.predict_one("test")
+'yes'
+You can train the model and make predictions in mini-batch mode using the class methods
+learn_many and predict_many.
df_docs = pd.DataFrame(docs, columns = ["docs", "y"])
+
+X = pd.Series([
+ "Chinese Beijing Chinese",
+ "Chinese Chinese Shanghai",
+ "Chinese Macao",
+ "Tokyo Japan Chinese"
+])
+
+y = pd.Series(["yes", "yes", "yes", "no"])
+
+model = compose.Pipeline(
+ ("tokenize", feature_extraction.BagOfWords(lowercase=False)),
+ ("nb", naive_bayes.BernoulliNB(alpha=1))
+)
+
+model = model.learn_many(X, y)
+
+unseen = pd.Series(["Taiwanese Taipei", "Chinese Shanghai"])
+
+model.predict_proba_many(unseen)
+ no yes
+0 0.116846 0.883154
+1 0.047269 0.952731
+model.predict_many(unseen)
+0 yes
+1 yes
+dtype: object
+Computes the joint log likelihood of input features.
+Parameters
+Returns
+float: Mapping between classes and joint log likelihood.
++
Computes the joint log likelihood of input features.
+Parameters
+Returns
+pd.DataFrame: Input samples joint log likelihood.
++
Learn from a batch of count vectors.
+Parameters
+Returns
+MiniBatchClassifier: self
++
Updates the model with a single observation.
+Parameters
+Returns
+Classifier: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+pd.Series: The predicted labels.
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Return probabilities using the log-likelihoods in mini-batchs setting.
+Parameters
++
Return probabilities using the log-likelihoods.
+Parameters
++
Naive Bayes classifier for multinomial models.
+Complement Naive Bayes model learns from occurrences between features such as word counts and discrete classes. ComplementNB is suitable for imbalance dataset. The input vector must contain positive values, such as counts or TF-IDF values.
+alpha
+Default → 1.0
Additive (Laplace/Lidstone) smoothing parameter (use 0 for no smoothing).
+class_dist (proba.Multinomial)
+Class prior probability distribution.
+feature_counts (collections.defaultdict)
+Total frequencies per feature and class.
+class_totals (collections.Counter)
+Total frequencies per class.
+import pandas as pd
+from river import compose
+from river import feature_extraction
+from river import naive_bayes
+
+docs = [
+ ("Chinese Beijing Chinese", "yes"),
+ ("Chinese Chinese Shanghai", "yes"),
+ ("Chinese Macao", "maybe"),
+ ("Tokyo Japan Chinese", "no")
+]
+
+model = compose.Pipeline(
+ ("tokenize", feature_extraction.BagOfWords(lowercase=False)),
+ ("nb", naive_bayes.ComplementNB(alpha=1))
+)
+
+for sentence, label in docs:
+ model = model.learn_one(sentence, label)
+
+model["nb"].p_class("yes")
+0.5
+model["nb"].p_class("no")
+0.25
+model["nb"].p_class("maybe")
+0.25
+model.predict_proba_one("test")
+{'yes': 0.275, 'maybe': 0.375, 'no': 0.35}
+model.predict_one("test")
+'maybe'
+You can train the model and make predictions in mini-batch mode using the class methods
+learn_many and predict_many.
df_docs = pd.DataFrame(docs, columns = ["docs", "y"])
+
+X = pd.Series([
+ "Chinese Beijing Chinese",
+ "Chinese Chinese Shanghai",
+ "Chinese Macao",
+ "Tokyo Japan Chinese"
+])
+
+y = pd.Series(["yes", "yes", "maybe", "no"])
+
+model = compose.Pipeline(
+ ("tokenize", feature_extraction.BagOfWords(lowercase=False)),
+ ("nb", naive_bayes.ComplementNB(alpha=1))
+)
+
+model = model.learn_many(X, y)
+
+unseen = pd.Series(["Taiwanese Taipei", "Chinese Shanghai"])
+
+model.predict_proba_many(unseen)
+ maybe no yes
+0 0.415129 0.361624 0.223247
+1 0.248619 0.216575 0.534807
+model.predict_many(unseen)
+0 maybe
+1 yes
+dtype: object
+Computes the joint log likelihood of input features.
+Parameters
+Returns
+float: Mapping between classes and joint log likelihood.
++
Computes the joint log likelihood of input features.
+Parameters
+Returns
+pd.DataFrame: Input samples joint log likelihood.
++
Learn from a batch of count vectors.
+Parameters
+Returns
+MiniBatchClassifier: self
++
Updates the model with a single observation.
+Parameters
+Returns
+Classifier: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+pd.Series: The predicted labels.
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Return probabilities using the log-likelihoods in mini-batchs setting.
+Parameters
++
Return probabilities using the log-likelihoods.
+Parameters
++ + + + + + + + + +
Gaussian Naive Bayes.
+A Gaussian distribution \(G_{cf}\) is maintained for each class \(c\) and each feature \(f\). Each Gaussian is updated using the amount associated with each feature; the details can be be found in proba.Gaussian. The joint log-likelihood is then obtained by summing the log probabilities of each feature associated with each class.
from river import naive_bayes
+from river import stream
+import numpy as np
+
+X = np.array([[-1, -1], [-2, -1], [-3, -2], [1, 1], [2, 1], [3, 2]])
+Y = np.array([1, 1, 1, 2, 2, 2])
+
+model = naive_bayes.GaussianNB()
+
+for x, y in stream.iter_array(X, Y):
+ _ = model.learn_one(x, y)
+
+model.predict_one({0: -0.8, 1: -1})
+1
+Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Return probabilities using the log-likelihoods.
+Parameters
++ + + + + + + + +
Naive Bayes classifier for multinomial models.
+Multinomial Naive Bayes model learns from occurrences between features such as word counts and discrete classes. The input vector must contain positive values, such as counts or TF-IDF values.
+alpha
+Default → 1.0
Additive (Laplace/Lidstone) smoothing parameter (use 0 for no smoothing).
+class_dist (proba.Multinomial)
+Class prior probability distribution.
+feature_counts (collections.defaultdict)
+Total frequencies per feature and class.
+class_totals (collections.Counter)
+Total frequencies per class.
+import pandas as pd
+from river import compose
+from river import feature_extraction
+from river import naive_bayes
+
+docs = [
+ ("Chinese Beijing Chinese", "yes"),
+ ("Chinese Chinese Shanghai", "yes"),
+ ("Chinese Macao", "maybe"),
+ ("Tokyo Japan Chinese", "no")
+]
+
+model = compose.Pipeline(
+ ("tokenize", feature_extraction.BagOfWords(lowercase=False)),
+ ("nb", naive_bayes.MultinomialNB(alpha=1))
+)
+
+for sentence, label in docs:
+ model = model.learn_one(sentence, label)
+
+model["nb"].p_class("yes")
+0.5
+model["nb"].p_class("no")
+0.25
+model["nb"].p_class("maybe")
+0.25
+model.predict_proba_one("test")
+{'yes': 0.413, 'maybe': 0.310, 'no': 0.275}
+model.predict_one("test")
+'yes'
+You can train the model and make predictions in mini-batch mode using the class methods
+learn_many and predict_many.
df_docs = pd.DataFrame(docs, columns = ["docs", "y"])
+
+X = pd.Series([
+ "Chinese Beijing Chinese",
+ "Chinese Chinese Shanghai",
+ "Chinese Macao",
+ "Tokyo Japan Chinese"
+])
+
+y = pd.Series(["yes", "yes", "maybe", "no"])
+
+model = compose.Pipeline(
+ ("tokenize", feature_extraction.BagOfWords(lowercase=False)),
+ ("nb", naive_bayes.MultinomialNB(alpha=1))
+)
+
+model = model.learn_many(X, y)
+
+unseen = pd.Series(["Taiwanese Taipei", "Chinese Shanghai"])
+
+model.predict_proba_many(unseen)
+ maybe no yes
+0 0.373272 0.294931 0.331797
+1 0.160396 0.126733 0.712871
+model.predict_many(unseen)
+0 maybe
+1 yes
+dtype: object
+Computes the joint log likelihood of input features.
+Parameters
+Returns
+float: Mapping between classes and joint log likelihood.
++
Computes the joint log likelihood of input features.
+Parameters
+Returns
+pd.DataFrame: Input samples joint log likelihood.
++
Learn from a batch of count vectors.
+Parameters
+Returns
+MiniBatchClassifier: self
++
Updates the model with a single observation.
+Parameters
+Returns
+Classifier: self
++
Predict the outcome for each given sample.
+Parameters
+Returns
+pd.Series: The predicted labels.
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Return probabilities using the log-likelihoods in mini-batchs setting.
+Parameters
++
Return probabilities using the log-likelihoods.
+Parameters
++
K-Nearest Neighbors (KNN) for classification.
+Samples are stored using a first-in, first-out strategy. The strategy to perform search queries in the data buffer is defined by the engine parameter.
n_neighbors
+Type → int
+Default → 5
The number of nearest neighbors to search for.
+engine
+Type → BaseNN | None
+Default → None
The search engine used to store the instances and perform search queries. Depending on the choose engine, search will be exact or approximate. Please, consult the documentation of each available search engine for more details on its usage. By default, use the SWINN search engine for approximate search queries.
weighted
+Type → bool
+Default → True
Weight the contribution of each neighbor by it's inverse distance.
+cleanup_every
+Type → int
+Default → 0
This determines at which rate old classes are cleaned up. Classes that have been seen in the past but that are not present in the current window are dropped. Classes are never dropped when this is set to 0.
+softmax
+Type → bool
+Default → False
Whether or not to use softmax normalization to normalize the neighbors contributions. Votes are divided by the total number of votes if this is False.
import functools
+from river import datasets
+from river import evaluate
+from river import metrics
+from river import neighbors
+from river import preprocessing
+from river import utils
+
+dataset = datasets.Phishing()
+To select a custom distance metric which takes one or several parameter, you can wrap your
+chosen distance using functools.partial:
l1_dist = functools.partial(utils.math.minkowski_distance, p=1)
+
+model = (
+ preprocessing.StandardScaler() |
+ neighbors.KNNClassifier(
+ engine=neighbors.SWINN(
+ dist_func=l1_dist,
+ seed=42
+ )
+ )
+)
+
+evaluate.progressive_val_score(dataset, model, metrics.Accuracy())
+Accuracy: 89.67%
+Clean up classes added to the window.
+Classes that are added (and removed) from the window may no longer be valid. This method cleans up the window and and ensures only known classes are added, and we do not consider "None" a class. It is called every cleanup_every step, or can be called manually.
+
Update the model with a set of features x and a label y.
Parameters
+Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++
Note that since the window is moving and we keep track of all classes that
+are added at some point, a class might be returned in a result (with a
+value of 0) if it is no longer in the window. You can call
+model.clean_up_classes(), or set cleanup_every to a non-zero value.
K-Nearest Neighbors regressor.
+Samples are stored using a first-in, first-out strategy. The strategy to perform search queries in the data buffer is defined by the engine parameter. Predictions are obtained by aggregating the values of the closest n_neighbors stored samples with respect to a query sample.
n_neighbors
+Type → int
+Default → 5
The number of nearest neighbors to search for.
+engine
+Type → BaseNN | None
+Default → None
The search engine used to store the instances and perform search queries. Depending on the choose engine, search will be exact or approximate. Please, consult the documentation of each available search engine for more details on its usage. By default, use the SWINN search engine for approximate search queries.
aggregation_method
+Type → str
+Default → mean
The method to aggregate the target values of neighbors. | 'mean' | 'median' | 'weighted_mean'
+from river import datasets
+from river import evaluate
+from river import metrics
+from river import neighbors
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+
+model = neighbors.KNNRegressor()
+evaluate.progressive_val_score(dataset, model, metrics.RMSE())
+RMSE: 1.427743
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++ + + + + + + + +
Exact nearest neighbors using a lazy search estrategy.
+window_size
+Type → int
+Default → 50
Size of the sliding window use to search neighbors with.
+min_distance_keep
+Type → float
+Default → 0.0
The minimum distance (similarity) to consider adding a point to the window. E.g., a value of 0.0 will add even exact duplicates.
+dist_func
+Type → DistanceFunc | FunctionWrapper | None
+Default → None
A distance function which accepts two input items to compare. If not set, use the Minkowski distance with p=2.
Add a point to the window, optionally with extra metadata.
+Parameters
+None +
Find the n_neighbors closest points to item, along with their distances.
Parameters
++
Update the window with a new point, only added if > min distance.
+If min distance is 0, we do not need to do the calculation. The item (and extra metadata) will not be added to the window if it is too close to an existing point.
+Parameters
+1 None Returns
+A boolean (true/false) to indicate if the point was added.
++
Updates are by default stored by the FIFO (first in first out) method, +which means that when the size limit is reached, old samples are dumped to +give room for new samples. This is circular, meaning that older points +are dumped first. This also gives the implementation a temporal aspect, +because older samples are replaced with newer ones.
+The parameter min_dinstance_keep controls the addition of new items to the
+window - items that are far enough away (> min_distance_keep) are added to
+the window. Thus a value of 0 indicates that we add all points, and
+increasing from 0 makes it less likely we will keep a new item.
Sliding WIndow-based Nearest Neighbor (SWINN) search using Graphs.
+Extends the NNDescent algorithm1 to handle vertex addition and removal in a FIFO data ingestion policy. SWINN builds and keeps a directed graph where edges connect the nearest neighbors. Any distance metric can be used to build the graph. By using a directed graph, the user must set the desired number of neighbors. More neighbors imply more accurate search queries at the cost of increased running time and memory usage. Note that although the number of directed neighbors is limited by the user, there is no direct control on the number of reverse neighbors, i.e., the number of vertices that have an edge to a given vertex.
+The basic idea of SWINN and NNDescent is that "the neighbor of my neighbors might as well be my neighbor". Hence, the connections are constantly revisited to improve the graph structure. The algorithm for creating and maintaining the search graph can be described in general lines as follows:
+Start with a random neighborhood graph;
+For each node in the search graph: refine the current neighborhood by checking if there are better neighborhood options among the neighbors of the current neighbors;
+If the total number of neighborhood changes is smaller than a given stopping criterion, then stop.
+SWINN adds strategies to remove vertices from the search graph and pruning redundant edges. SWINN is more efficient when the selected maxlen is greater than 500. For small sized data windows, using the lazy/exhaustive search, i.e., neighbors.LazySearch might be a better idea.
graph_k
+Type → int
+Default → 20
The maximum number of direct nearest neighbors each node has.
+dist_func
+Type → DistanceFunc | FunctionWrapper | None
+Default → None
The distance function used to compare two items. If not set, use the Minkowski distance with p=2.
maxlen
+Type → int
+Default → 1000
The maximum size of the data buffer.
+warm_up
+Type → int
+Default → 500
How many data instances to observe before starting the search graph.
+max_candidates
+Type → int
+Default → None
The maximum number of vertices to consider when performing local neighborhood joins. If not set SWINN will use min(50, max(50, self.graph_k)).
delta
+Type → float
+Default → 0.0001
Early stop parameter for the neighborhood refinement procedure. NNDescent will stop running if the maximum number of iterations is reached or the number of edge changes after an iteration is smaller than or equal to delta * graph_k * n_nodes. In the last expression, n_nodes refers to the number of graph nodes involved in the (local) neighborhood refinement.
prune_prob
+Type → float
+Default → 0.0
The probability of removing redundant edges. Must be between 0 and 1. If set to zero, no edge will be pruned. When set to one, every potentially redundant edge will be dropped.
n_iters
+Type → int
+Default → 10
The maximum number of NNDescent iterations to perform to refine the search index.
+seed
+Type → int
+Default → None
Random seed for reproducibility.
+Add a new item to the search index.
+Data is stored using the FIFO strategy. Both the data buffer and the search graph are updated. The addition of a new item will trigger the removal of the oldest item, if the maximum size was reached. All edges of the removed node are also dropped and safety procedures are applied to ensure its neighbors keep accessible. The addition of a new item also trigger local neighborhood refinement procedures, to ensure the search index is effective and the node degree constraints are met.
+Parameters
++
Get a list with the size of each connected component in the search graph.
+This metric provides an overview of reachability in the search index by using Kruskal's algorithm to build a forest of connected components. We want our search index to have a single connected component, i.e., the case where we get a list containing a single number which is equal to maxlen. If that is not the case, not every node in the search graph can be reached from any given starting point. You may want to try increasing graph_k to improve connectivity. However, keep in mind the following aspects: 1) computing this metric is a costly operation (\(O(E\log V)\)), where \(E\) and \(V\) are, respectively, the number of edges and vertices in the search graph; 2) often, connectivity comes at the price of increased computational costs. Tweaking the sample_rate might help in such situations. The best possible scenario is to decrease the value of graph_k while keeping a single connected component.
Returns
+list[int]: A list of the number of elements in each connected component of the graph.
++
Search the underlying nearest neighbor graph given a query item.
+In case not enough samples were observed, i.e., the number of stored samples is smaller than warm_up, then the search switches to a brute force strategy.
Parameters
+0.1 Returns
+tuple[list, list]: neighbors, dists
++
There is an accuracy/speed trade-off between graph_k and sample_rate. To ensure a single
+connected component, and thus an effective search index, one can increase graph_k. The
+connectivity method is a helper to determine whether the search index has a single connected component.
+However, search accuracy might come at the cost of increased memory usage and slow processing. To alleviate
+that, one can rely on decreasing the sample_rate to avoid exploring all the undirected edges of a node
+during search queries and local graph refinements. Moreover, the edge pruning procedures also help
+decreasing the computational costs. Note that, anything that limits the number of explored neighbors or
+prunes edges might have a negative impact on search accuracy.
Dong, W., Moses, C., & Li, K. (2011, March). Efficient k-nearest neighbor graph construction for +generic similarity measures. In Proceedings of the 20th international conference on World wide web (pp. 577-586). ↩
+Multi-layer Perceptron for regression.
+This model is still work in progress. Here are some features that still need implementing:
+learn_one and predict_one just cast the input dict to a single row dataframe and then
call learn_many and predict_many respectively. This is very inefficient. - Not all of the optimizers in the optim module can be used as they are not all vectorised.
Emerging and disappearing features are not supported. Each instance/batch has to have the
+same features. - The gradient haven't been numerically checked.
+hidden_dims
+The dimensions of the hidden layers. For example, specifying (10, 20) means that there are two hidden layers with 10 and 20 neurons, respectively. Note that the number of layers the network contains is equal to the number of hidden layers plus two (to account for the input and output layers).
activations
+The activation functions to use at each layer, including the input and output layers. Therefore you need to specify three activation if you specify one hidden layer.
+loss
+Type → optim.losses.Loss | None
+Default → None
Loss function. Defaults to optim.losses.Squared.
optimizer
+Type → optim.base.Optimizer | None
+Default → None
Optimizer. Defaults to optim.SGD with the learning rate set to 0.01.
seed
+Type → int | None
+Default → None
Random number generation seed. Set this for reproducibility.
+n_layers
+Return the number of layers in the network. The number of layers is equal to the number of hidden layers plus 2. The 2 accounts for the input layer and the output layer.
+from river import datasets
+from river import evaluate
+from river import neural_net as nn
+from river import optim
+from river import preprocessing as pp
+from river import metrics
+
+model = (
+ pp.StandardScaler() |
+ nn.MLPRegressor(
+ hidden_dims=(5,),
+ activations=(
+ nn.activations.ReLU,
+ nn.activations.ReLU,
+ nn.activations.Identity
+ ),
+ optimizer=optim.SGD(1e-3),
+ seed=42
+ )
+)
+
+dataset = datasets.TrumpApproval()
+
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 1.580578
+You can also use this to process mini-batches of data.
+model = (
+ pp.StandardScaler() |
+ nn.MLPRegressor(
+ hidden_dims=(10,),
+ activations=(
+ nn.activations.ReLU,
+ nn.activations.ReLU,
+ nn.activations.ReLU
+ ),
+ optimizer=optim.SGD(1e-4),
+ seed=42
+ )
+)
+
+dataset = datasets.TrumpApproval()
+batch_size = 32
+
+for epoch in range(10):
+ for xb in pd.read_csv(dataset.path, chunksize=batch_size):
+ yb = xb.pop('five_thirty_eight')
+ y_pred = model.predict_many(xb)
+ model = model.learn_many(xb, yb)
+
+model.predict_many(xb)
+ five_thirty_eight
+992 39.405231
+993 46.447481
+994 42.121865
+995 40.251148
+996 40.836378
+997 40.893153
+998 40.949927
+999 48.416504
+1000 42.077830
+Make predictions.
+Parameters
++
Train the network.
+Parameters
++
Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++ + + + + + + + +
AMSGrad optimizer.
+lr
+Type → int | float | optim.base.Scheduler
+Default → 0.1
The learning rate.
+beta_1
+Default → 0.9
beta_2
+Default → 0.999
eps
+Default → 1e-08
correct_bias
+Default → True
m (collections.defaultdict)
+v (collections.defaultdict)
+v_hat (collections.defaultdict)
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.AMSGrad()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 86.60%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
AdaBound optimizer.
+lr
+Default → 0.001
The learning rate.
+beta_1
+Default → 0.9
beta_2
+Default → 0.999
eps
+Default → 1e-08
gamma
+Default → 0.001
final_lr
+Default → 0.1
m (collections.defaultdict)
+s (collections.defaultdict)
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.AdaBound()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 88.06%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
AdaDelta optimizer.
+rho
+Default → 0.95
eps
+Default → 1e-08
g2 (collections.defaultdict)
+s2 (collections.defaultdict)
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.AdaDelta()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 80.56%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
AdaGrad optimizer.
+lr
+Default → 0.1
eps
+Default → 1e-08
from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.AdaGrad()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 88.01%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
AdaMax optimizer.
+lr
+Default → 0.1
beta_1
+Default → 0.9
beta_2
+Default → 0.999
eps
+Default → 1e-08
m (collections.defaultdict)
+v (collections.defaultdict)
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.AdaMax()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.61%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
Adam optimizer.
+lr
+Default → 0.1
beta_1
+Default → 0.9
beta_2
+Default → 0.999
eps
+Default → 1e-08
m (collections.defaultdict)
+v (collections.defaultdict)
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.Adam()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 86.52%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
Averaged stochastic gradient descent.
+This is a wrapper that can be applied to any stochastic gradient descent optimiser. Note that this implementation differs than what may be found elsewhere. Essentially, the average of the weights is usually only used at the end of the optimisation, once all the data has been seen. However, in this implementation the optimiser returns the current averaged weights.
+optimizer
+Type → optim.base.Optimizer
+An optimizer for which the produced weights will be averaged.
+start
+Type → int
+Default → 0
Indicates the number of iterations to wait before starting the average. Essentially, nothing happens differently before the number of iterations reaches this value.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.Averager(optim.SGD(0.01), 100)
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.97%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++
Bottou, L., 2010. Large-scale machine learning with stochastic gradient descent. In Proceedings of COMPSTAT'2010 (pp. 177-186). Physica-Verlag HD. ↩
+Stochastic Algorithms for One-Pass Learning slides by Léon Bottou ↩
+Xu, W., 2011. Towards optimal one pass large scale learning with averaged stochastic gradient descent. arXiv preprint arXiv:1107.2490. ↩
+FTRL-Proximal optimizer.
+alpha
+Default → 0.05
beta
+Default → 1.0
l1
+Default → 0.0
l2
+Default → 1.0
z (collections.defaultdict)
+n (collections.defaultdict)
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.FTRLProximal()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.56%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++
McMahan, H.B., Holt, G., Sculley, D., Young, M., Ebner, D., Grady, J., Nie, L., Phillips, T., Davydov, E., Golovin, D. and Chikkerur, S., 2013, August. Ad click prediction: a view from the trenches. In Proceedings of the 19th ACM SIGKDD international conference on Knowledge discovery and data mining (pp. 1222-1230) ↩
+Momentum optimizer.
+lr
+Default → 0.1
rho
+Default → 0.9
from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.Momentum()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 84.09%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + +
Nadam optimizer.
+lr
+Default → 0.1
beta_1
+Default → 0.9
beta_2
+Default → 0.999
eps
+Default → 1e-08
from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.Nadam()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 86.60%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++
Nesterov Momentum optimizer.
+lr
+Default → 0.1
rho
+Default → 0.9
from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.NesterovMomentum()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 84.22%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + +
RMSProp optimizer.
+lr
+Default → 0.1
rho
+Default → 0.9
eps
+Default → 1e-08
from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.RMSProp()
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.24%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
Plain stochastic gradient descent.
+lr
+Default → 0.01
from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import optim
+from river import preprocessing
+
+dataset = datasets.Phishing()
+optimizer = optim.SGD(0.1)
+model = (
+ preprocessing.StandardScaler() |
+ linear_model.LogisticRegression(optimizer)
+)
+metric = metrics.F1()
+
+evaluate.progressive_val_score(dataset, model, metric)
+F1: 87.85%
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + + +
Base class for all loss functions.
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Optimizer interface.
+Every optimizer inherits from this base interface.
+lr
+Type → int | float | Scheduler
+learning_rate (float)
+Returns the current learning rate value.
+Updates a weight vector before a prediction is made.
+Parameters: w (dict): A dictionary of weight parameters. The weights are modified in-place. Returns: The updated weights.
+Parameters
++
Updates a weight vector given a gradient.
+Parameters
+Returns
+dict | VectorLike: The updated weights.
++ + + + + + + + +
Can be used to program the learning rate schedule of an optim.base.Optimizer.
Returns the learning rate at a given iteration.
+Parameters
++ + + + + + + + +
Constant initializer which always returns the same value.
+value
+Type → float
+from river import optim
+
+init = optim.initializers.Constant(value=3.14)
+
+init(shape=1)
+3.14
+init(shape=2)
+array([3.14, 3.14])
+Returns a fresh set of weights.
+Parameters
+1 + + + + + + + + +
Random normal initializer which simulate a normal distribution with specified parameters.
+mu
+Default → 0.0
The mean of the normal distribution
+sigma
+Default → 1.0
The standard deviation of the normal distribution
+seed
+Type → int | None
+Default → None
Random number generation seed that can be set for reproducibility.
+from river import optim
+
+init = optim.initializers.Normal(mu=0, sigma=1, seed=42)
+
+init(shape=1)
+0.496714
+init(shape=2)
+array([-0.1382643 , 0.64768854])
+Returns a fresh set of weights.
+Parameters
+1 + + + + + + + + +
Constant initializer which always returns zeros.
+from river import optim
+
+init = optim.initializers.Zeros()
+
+init(shape=1)
+0.0
+init(shape=2)
+array([0., 0.])
+Returns a fresh set of weights.
+Parameters
+1 + + + + + + + + +
Absolute loss, also known as the mean absolute error or L1 loss.
+Mathematically, it is defined as
+It's gradient w.r.t. to \(p_i\) is
+from river import optim
+
+loss = optim.losses.Absolute()
+loss(-42, 42)
+84
+loss.gradient(1, 2)
+1
+loss.gradient(2, 1)
+-1
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Binary focal loss.
+This implements the "star" algorithm from the appendix of the focal loss paper.
+gamma
+Default → 2
beta
+Default → 1
Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
+A loss appropriate for binary classification tasks.
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Cauchy loss function.
+C
+Default → 80
Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++
Cross entropy loss.
+This is a generalization of logistic loss to multiple classes.
+class_weight
+Type → dict[base.typing.ClfTarget, float] | None
+Default → None
A dictionary that indicates what weight to associate with each class.
+from river import optim
+
+y_true = [0, 1, 2, 2]
+y_pred = [
+ {0: 0.29450637, 1: 0.34216758, 2: 0.36332605},
+ {0: 0.21290077, 1: 0.32728332, 2: 0.45981591},
+ {0: 0.42860913, 1: 0.33380113, 2: 0.23758974},
+ {0: 0.44941979, 1: 0.32962558, 2: 0.22095463}
+]
+
+loss = optim.losses.CrossEntropy()
+
+for yt, yp in zip(y_true, y_pred):
+ print(loss(yt, yp))
+1.222454
+1.116929
+1.437209
+1.509797
+for yt, yp in zip(y_true, y_pred):
+ print(loss.gradient(yt, yp))
+{0: -0.70549363, 1: 0.34216758, 2: 0.36332605}
+{0: 0.21290077, 1: -0.67271668, 2: 0.45981591}
+{0: 0.42860913, 1: 0.33380113, 2: -0.76241026}
+{0: 0.44941979, 1: 0.32962558, 2: -0.77904537}
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + + +
Epsilon-insensitive hinge loss.
+eps
+Default → 0.1
Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Computes the hinge loss.
+Mathematically, it is defined as
+It's gradient w.r.t. to \(p_i\) is
+threshold
+Default → 1.0
Margin threshold. 1 yield the loss used in SVMs, whilst 0 is equivalent to the loss used in the Perceptron algorithm.
+from river import optim
+
+loss = optim.losses.Hinge(threshold=1)
+loss(1, .2)
+0.8
+loss.gradient(1, .2)
+-1
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Huber loss.
+Variant of the squared loss that is robust to outliers.
+epsilon
+Default → 0.1
Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
+Logarithmic loss.
+This loss function expects each provided y_pred to be a logit. In other words if must be the raw output of a linear model or a neural network.
weight_pos
+Default → 1.0
weight_neg
+Default → 1.0
Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++
A loss appropriate for multi-class classification tasks.
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Poisson loss.
+The Poisson loss is usually more suited for regression with count data than the squared loss.
+Mathematically, it is defined as
+It's gradient w.r.t. to \(p_i\) is
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Quantile loss.
+alpha
+Default → 0.5
Desired quantile to attain.
+from river import optim
+
+loss = optim.losses.Quantile(0.5)
+loss(1, 3)
+1.0
+loss.gradient(1, 3)
+0.5
+loss.gradient(3, 1)
+-0.5
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++
A loss appropriate for regression tasks.
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Squared loss, also known as the L2 loss.
+Mathematically, it is defined as
+It's gradient w.r.t. to \(p_i\) is
+One thing to note is that this convention is consistent with Vowpal Wabbit and PyTorch, but not with scikit-learn. Indeed, scikit-learn divides the loss by 2, making the 2 disappear in the gradient.
+from river import optim
+
+loss = optim.losses.Squared()
+loss(-4, 5)
+81
+loss.gradient(-4, 5)
+18
+loss.gradient(5, -4)
+-18
+Returns the loss.
+Parameters
+Returns
+The loss(es).
++
Return the gradient with respect to y_pred.
+Parameters
+Returns
+The gradient(s).
++
Mean function.
+This is the inverse of the link function. Typically, a loss function takes as input the raw output of a model. In the case of classification, the raw output would be logits. The mean function can be used to convert the raw output into a value that makes sense to the user, such as a probability.
+Parameters
+Returns
+The adjusted prediction(s).
++ + + + + + + + +
Reduces the learning rate using a power schedule.
+Assuming an initial learning rate \(\eta\), the learning rate at step \(t\) is:
+where \(p\) is a user-defined parameter.
+learning_rate
+Type → float
+power
+Default → 0.5
Returns the learning rate at a given iteration.
+Parameters
++ + + + + + + + +
Optimal learning schedule as proposed by Léon Bottou.
+loss
+Type → optim.losses.Loss
+alpha
+Default → 0.0001
Returns the learning rate at a given iteration.
+Parameters
++ + + + + + + + + +
Online active learning.
+ +Anomaly detection.
+Estimators in the anomaly module have a bespoke API. Each anomaly detector has a score_one
+method instead of a predict_one method. This method returns an anomaly score. Normal observations
+should have a low score, whereas anomalous observations should have a high score. The range of the
+scores is relative to each estimator.
Anomaly detectors are usually unsupervised, in that they analyze the distribution of the features +they are shown. But River also has a notion of supervised anomaly detectors. These analyze the +distribution of a target variable, and optionally include the distribution of the features as well. They are useful for detecting labelling anomalies, which can be detrimental if they learned by a +model.
+ +Multi-armed bandit (MAB) policies.
+The bandit policies in River have a generic API. This allows them to be used in a variety of
+situations. For instance, they can be used for model selection
+(see model_selection.BanditRegressor).
Classes
+ +Functions
+ +Base interfaces.
+Every estimator in River is a class, and as such inherits from at least one base interface. +These are used to categorize, organize, and standardize the many estimators that River +contains.
+This module contains mixin classes, which are all suffixed by Mixin. Their purpose is to
+provide additional functionality to an estimator, and thus need to be used in conjunction with a
+non-mixin base class.
This module also contains utilities for type hinting and tagging estimators.
+Unsupervised clustering.
+ +Compatibility tools.
+This module contains adapters for making River estimators compatible with other libraries, and
+vice-versa whenever possible. The relevant adapters will only be usable if you have installed the
+necessary library. For instance, you have to install scikit-learn in order to use the
+compat.convert_sklearn_to_river function.
Classes
+Functions
+ +Model composition.
+This module contains utilities for merging multiple modeling steps into a single pipeline. Although +pipelines are not the only way to process a stream of data, we highly encourage you to use them.
+Classes
+Functions
+ +Conformal predictions. This modules contains wrappers to enable conformal predictions on any +regressor or classifier.
+ +Online estimation of covariance and precision matrices.
+ +Datasets.
+This module contains a collection of datasets for multiple tasks: classification, regression, etc.
+The data corresponds to popular datasets and are conveniently wrapped to easily iterate over
+the data in a stream fashion. All datasets have fixed size. Please refer to river.synth if you
+are interested in infinite synthetic data generators.
Regression
+| Name | +Samples | +Features | +
|---|---|---|
| AirlinePassengers | +144 | +1 | +
| Bikes | +182,470 | +8 | +
| ChickWeights | +578 | +3 | +
| MovieLens100K | +100,000 | +10 | +
| Restaurants | +252,108 | +7 | +
| Taxis | +1,458,644 | +8 | +
| TrumpApproval | +1,001 | +6 | +
| WaterFlow | +1,268 | +1 | +
Binary classification
+| Name | +Samples | +Features | +Sparse | +
|---|---|---|---|
| Bananas | +5,300 | +2 | ++ |
| CreditCard | +284,807 | +30 | ++ |
| Elec2 | +45,312 | +8 | ++ |
| Higgs | +11,000,000 | +28 | ++ |
| HTTP | +567,498 | +3 | ++ |
| MaliciousURL | +2,396,130 | +3,231,961 | +✔️ | +
| Phishing | +1,250 | +9 | ++ |
| SMSSpam | +5,574 | +1 | ++ |
| SMTP | +95,156 | +3 | ++ |
| TREC07 | +75,419 | +5 | ++ |
Multi-class classification
+| Name | +Samples | +Features | +Classes | +
|---|---|---|---|
| ImageSegments | +2,310 | +18 | +7 | +
| Insects | +52,848 | +33 | +6 | +
| Keystroke | +20,400 | +31 | +51 | +
Multi-output binary classification
+| Name | +Samples | +Features | +Outputs | +
|---|---|---|---|
| Music | +593 | +72 | +6 | +
Multi-output regression
+| Name | +Samples | +Features | +Outputs | +
|---|---|---|---|
| SolarFlare | +1,066 | +10 | +3 | +
Synthetic datasets.
+Each synthetic dataset is a stream generator. The benefit of using a generator is that they do not +store the data and each data sample is generated on the fly. Except for a couple of methods, +the majority of these methods are infinite data generators.
+Binary classification
+| Name | +Features | +
|---|---|
| Agrawal | +9 | +
| AnomalySine | +2 | +
| ConceptDriftStream | +9 | +
| Hyperplane | +10 | +
| Mixed | +4 | +
| SEA | +3 | +
| Sine | +2 | +
| STAGGER | +3 | +
Regression
+| Name | +Features | +
|---|---|
| Friedman | +10 | +
| FriedmanDrift | +10 | +
| Mv | +10 | +
| Planes2D | +10 | +
Multi-class classification
+| Name | +Features | +Classes | +
|---|---|---|
| LED | +7 | +10 | +
| LEDDrift | +7 | +10 | +
| RandomRBF | +10 | +2 | +
| RandomRBFDrift | +10 | +2 | +
| RandomTree | +10 | +2 | +
| Waveform | +21 | +3 | +
Multi-output binary classification
+| Name | +Features | +Outputs | +
|---|---|---|
| Logical | +2 | +3 | +
Concept Drift Detection.
+This module contains concept drift detection methods. The purpose of a drift detector is to raise +an alarm if the data distribution changes. A good drift detector method is the one that maximizes +the true positives while keeping the number of false positives to a minimum.
+ +Drift detection for binary data.
+ +Dummy estimators.
+This module is here for testing purposes, as well as providing baseline performances.
+ +Ensemble learning.
+Broadly speaking, there are two kinds of ensemble approaches. There are those that copy a single +model several times and aggregate the predictions of said copies. This includes bagging as well as +boosting. Then there are those that are composed of an arbitrary list of models, and can therefore +aggregate predictions from different kinds of models.
+Model evaluation.
+This module provides utilities to evaluate an online model. The goal is to reproduce a real-world
+scenario with high fidelity. The core function of this module is progressive_val_score, which
+allows to evaluate a model via progressive validation.
This module also exposes "tracks". A track is a predefined combination of a dataset and one or more
+metrics. This allows a principled manner to compare models with each other. For instance,
+the RegressionTrack contains several datasets and metrics to evaluate regression models. There is
+also a bare Track class to implement a custom track. The benchmarks directory at the root of
+the River repository uses these tracks.
Classes
+ +Functions
+ +Factorization machines.
+Feature extraction.
+This module can be used to extract information from raw features. This includes encoding
+categorical data as well as looking at interactions between existing features. This differs from
+the preprocessing module, in that the latter's purpose is rather to clean the data so that it may
+be processed by a particular machine learning algorithm.
Feature selection.
+ +This module implements forest-based classifiers and regressors.
+ +Sampling methods.
+Linear models.
+Evaluation metrics.
+All the metrics are updated one sample at a time. This way we can track performance of +predictive methods over time.
+Note that all metrics have a revert method, enabling them to be wrapped in utils.Rolling.
+This allows computirng rolling metrics:
from river import metrics, utils
+
+y_true = [True, False, True, True]
+y_pred = [False, False, True, True]
+
+metric = utils.Rolling(metrics.Accuracy(), window_size=3)
+
+for yt, yp in zip(y_true, y_pred):
+ print(metric.update(yt, yp))
+Accuracy: 0.00%
+Accuracy: 50.00%
+Accuracy: 66.67%
+Accuracy: 100.00%
+Metrics for multi-output learning.
+ +Miscellaneous.
+This module essentially regroups some implementations that have nowhere else to go.
+ +Model selection.
+This module regroups a variety of methods that may be used for performing model selection. An +model selector is provided with a list of models. These are called "experts" in the expert learning +literature. The model selector's goal is to perform at least as well as the best model. Indeed, +initially, the best model is not known. The performance of each model becomes more apparent as time +goes by. Different strategies are possible, each one offering a different tradeoff in terms of +accuracy and computational performance.
+Model selection can be used for tuning the hyperparameters of a model. This may be done by creating
+a copy of the model for each set of hyperparameters, and treating each copy as a separate model.
+The utils.expand_param_grid function can be used for this purpose.
Multi-class classification.
+ +Multi-output models.
+Naive Bayes algorithms.
+ +Neighbors-based learning.
+Also known as lazy methods. In these methods, generalisation of the training data is delayed +until a query is received.
+ +Neural networks.
+Stochastic optimization.
+Weight initializers.
+ +Loss functions.
+Each loss function is intended to work with both single values as well as numpy vectors.
+Learning rate schedulers.
+ +Feature preprocessing.
+The purpose of this module is to modify an existing set of features so that they can be processed
+by a machine learning algorithm. This may be done by scaling numeric parts of the data or by
+one-hot encoding categorical features. The difference with the feature_extraction module is that
+the latter extracts new information from the data
Probability distributions.
+ +Recommender systems module.
+Recommender systems (recsys for short) is a large topic. This module is far from comprehensive. It +simply provides models which can contribute towards building a recommender system.
+A typical recommender system is made up of a retrieval phase, followed by a ranking phase. The +output of the retrieval phase is a shortlist of the catalogue of items. The items in the shortlist +are then usually ranked according to the expected preference the user will have for each item. This +module focuses on the ranking phase.
+Models which inherit from the Ranker class have a rank method. This allows sorting a set of
+items for a given user. Each model also has a learn_one(user, item, y, context) which allows
+learning user preferences. The y parameter is a reward value, the nature of which depends is
+specific to each and every recommendation task. Typically the reward is a number or a boolean
+value. It is up to the user to determine how to translate a user session into training data.
Decision rules-based algorithms.
+Data containers and collections for sequential data.
+This module has summary and sketch structures that operate with constrained amounts +of memory and processing time.
+Running statistics
+Streaming utilities.
+The module includes tools to iterate over data streams.
+Classes
+ +Functions
+Time series forecasting.
+Classes
+ +Functions
+ +This module implements incremental Decision Tree (iDT) algorithms for handling classification +and regression tasks.
+Each family of iDT will be presented in a dedicated section.
+At any moment, iDT might face situations where an input feature previously used to make +a split decision is missing in an incoming sample. In this case, the most traversed path is +selected to pass down the instance. Moreover, in the case of nominal features, if a new category +arises and the feature is used in a decision node, a new branch is created to accommodate the new +value.
+1. Hoeffding Trees
+This family of iDT algorithms use the Hoeffding Bound to determine whether or not the +incrementally computed best split candidates would be equivalent to the ones obtained in a +batch-processing fashion.
+All the available Hoeffding Tree (HT) implementation share some common functionalities:
+Set the maximum tree depth allowed (max_depth).
Handle Active and Inactive nodes: Active learning nodes update their own
+internal state to improve predictions and monitor input features to perform split
+attempts. Inactive learning nodes do not update their internal state and only keep the
+predictors; they are used to save memory in the tree (max_size).
Enable/disable memory management.
+Define strategies to sort leaves according to how likely they are going to be split. +This enables deactivating non-promising leaves to save memory.
+Disabling ‘poor’ attributes to save memory and speed up tree construction. +A poor attribute is an input feature whose split merit is much smaller than the current +best candidate. Once a feature is disabled, the tree stops saving statistics necessary +to split such a feature.
+Define properties to access leaf prediction strategies, split criteria, and other +relevant characteristics.
+2. Stochastic Gradient Trees
+Stochastic Gradient Trees (SGT) directly optimize a loss function, rather than relying on split +heuristics to guide the tree growth. F-tests are performed do decide whether a leaf should be +expanded or its prediction value should be updated.
+SGTs can deal with binary classification and single-target regression. They also support +dynamic and static feature quantizers to deal with numerical inputs.
+This module defines generic branch and leaf implementations. These should be used in River by each +tree-based model. Using these classes makes the code more DRY. The only exception for not doing so +would be for performance, whereby a tree-based model uses a bespoke implementation.
+This module defines a bunch of methods to ease the manipulation and diagnostic of trees. Its +intention is to provide utilities for walking over a tree and visualizing it.
+ +This module implements the Attribute Observers (AO) (or tree splitters) that are used by the +Hoeffding Trees (HT). It also implements the feature quantizers (FQ) used by Stochastic Gradient +Trees (SGT). AOs are a core aspect of the HTs construction, and might represent one of the major +bottlenecks when building the trees. The same holds for SGTs and FQs. The correct choice and setup +of a splitter might result in significant differences in the running time and memory usage of the +incremental decision trees.
+AOs for classification and regression trees can be differentiated by using the property
+is_target_class (True for splitters designed to classification tasks). An error will be raised
+if one tries to use a classification splitter in a regression tree and vice-versa.
+Lastly, AOs cannot be used in SGT and FQs cannot be used in Hoeffding Trees. So, care must be taken
+when choosing the correct feature splitter.
Shared utility classes and functions
+Classes
+ +Functions
+ +Mathematical utility functions (intended for internal purposes).
+A lot of this is experimental and has a high probability of changing in the future.
+Helper functions for making things readable by humans.
+ +Scales data using exponentially weighted moving average and variance.
+Under the hood, a exponentially weighted running mean and variance are maintained for each feature. This can potentially provide better results for drifting data in comparison to preprocessing.StandardScaler. Indeed, the latter computes a global mean and variance for each feature, whereas this scaler weights data in proportion to their recency.
fading_factor
+Default → 0.3
This parameter is passed to stats.EWVar. It is expected to be in [0, 1]. More weight is assigned to recent samples the closer fading_factor is to 1.
Consider the following series which contains a positive trend.
+import random
+
+random.seed(42)
+X = [
+ {'x': random.uniform(4 + i, 6 + i)}
+ for i in range(8)
+]
+for x in X:
+ print(x)
+{'x': 5.278}
+{'x': 5.050}
+{'x': 6.550}
+{'x': 7.446}
+{'x': 9.472}
+{'x': 10.353}
+{'x': 11.784}
+{'x': 11.173}
+This scaler works well with this kind of data because it uses statistics that assign higher +weight to more recent data.
+from river import preprocessing
+
+scaler = preprocessing.AdaptiveStandardScaler(fading_factor=.6)
+
+for x in X:
+ print(scaler.learn_one(x).transform_one(x))
+{'x': 0.0}
+{'x': -0.816}
+{'x': 0.812}
+{'x': 0.695}
+{'x': 0.754}
+{'x': 0.598}
+{'x': 0.651}
+{'x': 0.124}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Binarizes the data to 0 or 1 according to a threshold.
+threshold
+Default → 0.0
Values above this are replaced by 1 and the others by 0.
+dtype
+Default → <class 'bool'>
The desired data type to apply.
+import river
+import numpy as np
+
+rng = np.random.RandomState(42)
+X = [{'x1': v, 'x2': int(v)} for v in rng.uniform(low=-4, high=4, size=6)]
+
+binarizer = river.preprocessing.Binarizer()
+for x in X:
+ print(binarizer.learn_one(x).transform_one(x))
+{'x1': False, 'x2': False}
+{'x1': True, 'x2': True}
+{'x1': True, 'x2': True}
+{'x1': True, 'x2': False}
+{'x1': False, 'x2': False}
+{'x1': False, 'x2': False}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Implements the hashing trick.
+Each pair of (name, value) features is hashed into a random integer. A module operator is then used to make sure the hash is in a certain range. We use the Murmurhash implementation from scikit-learn.
+n_features
+Default → 1048576
The number by which each hash will be moduloed by.
+seed
+Type → int | None
+Default → None
Set the seed to produce identical results.
+import river
+
+hasher = river.preprocessing.FeatureHasher(n_features=10, seed=42)
+
+X = [
+ {'dog': 1, 'cat': 2, 'elephant': 4},
+ {'dog': 2, 'run': 5}
+]
+for x in X:
+ print(hasher.transform_one(x))
+Counter({1: 4, 9: 2, 8: 1})
+Counter({4: 5, 8: 2})
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + + +
Gaussian random projector.
+This transformer reduces the dimensionality of inputs through Gaussian random projection.
+The components of the random projections matrix are drawn from N(0, 1 / n_components).
n_components
+Default → 10
Number of components to project the data onto.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+model = preprocessing.GaussianRandomProjector(
+ n_components=3,
+ seed=42
+)
+
+for x, y in dataset:
+ x = model.transform_one(x)
+ print(x)
+ break
+{0: -61289.37139206629, 1: 141312.51039283074, 2: 279165.99370457436}
+model = (
+ preprocessing.GaussianRandomProjector(
+ n_components=5,
+ seed=42
+ ) |
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression()
+)
+evaluate.progressive_val_score(dataset, model, metrics.MAE())
+MAE: 0.933502
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++
Online Latent Dirichlet Allocation with Infinite Vocabulary.
+Latent Dirichlet allocation (LDA) is a probabilistic approach for exploring topics in document collections. The key advantage of this variant is that it assumes an infinite vocabulary, meaning that the set of tokens does not have to known in advance, as opposed to the implementation from sklearn The results produced by this implementation are identical to those from the original implementation proposed by the method's authors.
+This class takes as input token counts. Therefore, it requires you to tokenize beforehand. You can do so by using a feature_extraction.BagOfWords instance, as shown in the example below.
n_components
+Default → 10
Number of topics of the latent Drichlet allocation.
+number_of_documents
+Default → 1000000.0
Estimated number of documents.
+alpha_theta
+Default → 0.5
Hyper-parameter of the Dirichlet distribution of topics.
+alpha_beta
+Default → 100.0
Hyper-parameter of the Dirichlet process of distribution over words.
+tau
+Default → 64.0
Learning inertia to prevent premature convergence.
+kappa
+Default → 0.75
The learning rate kappa controls how quickly new parameters estimates replace the old ones. kappa ∈ (0.5, 1] is required for convergence.
+vocab_prune_interval
+Default → 10
Interval at which to refresh the words topics distribution.
+number_of_samples
+Default → 10
Number of iteration to computes documents topics distribution.
+ranking_smooth_factor
+Default → 1e-12
burn_in_sweeps
+Default → 5
Number of iteration necessaries while analyzing a document before updating document topics distribution.
+maximum_size_vocabulary
+Default → 4000
Maximum size of the stored vocabulary.
+seed
+Type → int | None
+Default → None
Random number seed used for reproducibility.
+counter (int)
+The current number of observed documents.
+truncation_size_prime (int)
+Number of distincts words stored in the vocabulary. Updated before processing a document.
+truncation_size (int)
+Number of distincts words stored in the vocabulary. Updated after processing a document.
+word_to_index (dict)
+Words as keys and indexes as values.
+index_to_word (dict)
+Indexes as keys and words as values.
+nu_1 (dict)
+Weights of the words. Component of the variational inference.
+nu_2 (dict)
+Weights of the words. Component of the variational inference.
+from river import compose
+from river import feature_extraction
+from river import preprocessing
+
+X = [
+ 'weather cold',
+ 'weather hot dry',
+ 'weather cold rainy',
+ 'weather hot',
+ 'weather cold humid',
+]
+
+lda = compose.Pipeline(
+ feature_extraction.BagOfWords(),
+ preprocessing.LDA(
+ n_components=2,
+ number_of_documents=60,
+ seed=42
+ )
+)
+
+for x in X:
+ lda = lda.learn_one(x)
+ topics = lda.transform_one(x)
+ print(topics)
+{0: 0.5, 1: 2.5}
+{0: 2.499..., 1: 1.5}
+{0: 0.5, 1: 3.5}
+{0: 0.5, 1: 2.5}
+{0: 1.5, 1: 2.5}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Equivalent to lda.learn_one(x).transform_one(x)s, but faster.
Parameters
+Returns
+dict: Component attributions for the input document.
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + + +
Scales the data to a [-1, 1] range based on absolute maximum.
+Under the hood a running absolute max is maintained. This scaler is meant for data that is already centered at zero or sparse data. It does not shift/center the data, and thus does not destroy any sparsity.
+abs_max (dict)
+Mapping between features and instances of stats.AbsMax.
import random
+from river import preprocessing
+
+random.seed(42)
+X = [{'x': random.uniform(8, 12)} for _ in range(5)]
+for x in X:
+ print(x)
+{'x': 10.557707}
+{'x': 8.100043}
+{'x': 9.100117}
+{'x': 8.892842}
+{'x': 10.945884}
+scaler = preprocessing.MaxAbsScaler()
+
+for x in X:
+ print(scaler.learn_one(x).transform_one(x))
+{'x': 1.0}
+{'x': 0.767216}
+{'x': 0.861940}
+{'x': 0.842308}
+{'x': 1.0}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Scales the data to a fixed range from 0 to 1.
+Under the hood a running min and a running peak to peak (max - min) are maintained.
+min (dict)
+Mapping between features and instances of stats.Min.
max (dict)
+Mapping between features and instances of stats.Max.
import random
+from river import preprocessing
+
+random.seed(42)
+X = [{'x': random.uniform(8, 12)} for _ in range(5)]
+for x in X:
+ print(x)
+{'x': 10.557707}
+{'x': 8.100043}
+{'x': 9.100117}
+{'x': 8.892842}
+{'x': 10.945884}
+scaler = preprocessing.MinMaxScaler()
+
+for x in X:
+ print(scaler.learn_one(x).transform_one(x))
+{'x': 0.0}
+{'x': 0.0}
+{'x': 0.406920}
+{'x': 0.322582}
+{'x': 1.0}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Scales a set of features so that it has unit norm.
+This is particularly useful when used after a feature_extraction.TFIDF.
order
+Default → 2
Order of the norm (e.g. 2 corresponds to the \(L^2\) norm).
+from river import preprocessing
+from river import stream
+
+scaler = preprocessing.Normalizer(order=2)
+
+X = [[4, 1, 2, 2],
+ [1, 3, 9, 3],
+ [5, 7, 5, 1]]
+
+for x, _ in stream.iter_array(X):
+ print(scaler.transform_one(x))
+{0: 0.8, 1: 0.2, 2: 0.4, 3: 0.4}
+{0: 0.1, 1: 0.3, 2: 0.9, 3: 0.3}
+{0: 0.5, 1: 0.7, 2: 0.5, 3: 0.1}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
One-hot encoding.
+This transformer will encode every feature it is provided with. If a list or set is provided, this transformer will encode every entry in the list/set. You can apply it to a subset of features by composing it with compose.Select or compose.SelectType.
drop_zeros
+Default → False
Whether or not 0s should be made explicit or not.
+drop_first
+Default → False
Whether to get k - 1 dummies out of k categorical levels by removing the first key. This is useful in some statistical models where perfectly collinear features cause problems.
Let us first create an example dataset.
+from pprint import pprint
+import random
+import string
+
+random.seed(42)
+alphabet = list(string.ascii_lowercase)
+X = [
+ {
+ 'c1': random.choice(alphabet),
+ 'c2': random.choice(alphabet),
+ }
+ for _ in range(4)
+]
+pprint(X)
+[{'c1': 'u', 'c2': 'd'},
+ {'c1': 'a', 'c2': 'x'},
+ {'c1': 'i', 'c2': 'h'},
+ {'c1': 'h', 'c2': 'e'}]
+e can now apply one-hot encoding. All the provided are one-hot encoded, there is therefore +no need to specify which features to encode.
+from river import preprocessing
+
+oh = preprocessing.OneHotEncoder()
+for x in X[:2]:
+ oh = oh.learn_one(x)
+ pprint(oh.transform_one(x))
+{'c1_u': 1, 'c2_d': 1}
+{'c1_a': 1, 'c1_u': 0, 'c2_d': 0, 'c2_x': 1}
+The drop_zeros parameter can be set to True if you don't want the past features to be included
+in the output. Otherwise, all the past features will be included in the output.
oh = preprocessing.OneHotEncoder(drop_zeros=True)
+for x in X:
+ oh = oh.learn_one(x)
+ pprint(oh.transform_one(x))
+{'c1_u': 1, 'c2_d': 1}
+{'c1_a': 1, 'c2_x': 1}
+{'c1_i': 1, 'c2_h': 1}
+{'c1_h': 1, 'c2_e': 1}
+You can encode only k - 1 features out of k by setting drop_first to True.
oh = preprocessing.OneHotEncoder(drop_first=True, drop_zeros=True)
+for x in X:
+ oh = oh.learn_one(x)
+ pprint(oh.transform_one(x))
+{'c2_d': 1}
+{'c2_x': 1}
+{'c2_h': 1}
+{'c2_e': 1}
+A subset of the features can be one-hot encoded by piping a compose.Select into the
+OneHotEncoder.
from river import compose
+
+pp = compose.Select('c1') | preprocessing.OneHotEncoder()
+
+for x in X:
+ pp = pp.learn_one(x)
+ pprint(pp.transform_one(x))
+{'c1_u': 1}
+{'c1_a': 1, 'c1_u': 0}
+{'c1_a': 0, 'c1_i': 1, 'c1_u': 0}
+{'c1_a': 0, 'c1_h': 1, 'c1_i': 0, 'c1_u': 0}
+You can preserve the c2 feature by using a union:
pp = compose.Select('c1') | preprocessing.OneHotEncoder()
+pp += compose.Select('c2')
+
+for x in X:
+ pp = pp.learn_one(x)
+ pprint(pp.transform_one(x))
+{'c1_u': 1, 'c2': 'd'}
+{'c1_a': 1, 'c1_u': 0, 'c2': 'x'}
+{'c1_a': 0, 'c1_i': 1, 'c1_u': 0, 'c2': 'h'}
+{'c1_a': 0, 'c1_h': 1, 'c1_i': 0, 'c1_u': 0, 'c2': 'e'}
+Similar to the above examples, we can also pass values as a list. This will one-hot +encode all of the entries individually.
+X = [{'c1': ['u', 'a'], 'c2': ['d']},
+ {'c1': ['a', 'b'], 'c2': ['x']},
+ {'c1': ['i'], 'c2': ['h', 'z']},
+ {'c1': ['h', 'b'], 'c2': ['e']}]
+
+oh = preprocessing.OneHotEncoder(drop_zeros=True)
+for x in X:
+ oh = oh.learn_one(x)
+ pprint(oh.transform_one(x))
+{'c1_a': 1, 'c1_u': 1, 'c2_d': 1}
+{'c1_a': 1, 'c1_b': 1, 'c2_x': 1}
+{'c1_i': 1, 'c2_h': 1, 'c2_z': 1}
+{'c1_b': 1, 'c1_h': 1, 'c2_e': 1}
+Processing mini-batches is also possible.
+from pprint import pprint
+import random
+import string
+
+random.seed(42)
+alphabet = list(string.ascii_lowercase)
+X = pd.DataFrame(
+ {
+ 'c1': random.choice(alphabet),
+ 'c2': random.choice(alphabet),
+ }
+ for _ in range(3)
+)
+X
+ c1 c2
+0 u d
+1 a x
+2 i h
+oh = preprocessing.OneHotEncoder(drop_zeros=True)
+df = oh.transform_many(X)
+df.sort_index(axis="columns")
+ c1_a c1_i c1_u c2_d c2_h c2_x
+0 0 0 1 1 0 0
+1 1 0 0 0 0 1
+2 0 1 0 0 1 0
+oh = preprocessing.OneHotEncoder(drop_zeros=True, drop_first=True)
+df = oh.transform_many(X)
+df.sort_index(axis="columns")
+ c1_i c1_u c2_d c2_h c2_x
+0 0 1 1 0 0
+1 0 0 0 0 1
+2 1 0 0 1 0
+Here's an example where the zeros are kept:
+oh = preprocessing.OneHotEncoder(drop_zeros=False)
+X_init = pd.DataFrame([{"c1": "Oranges", "c2": "Apples"}])
+oh = oh.learn_many(X_init)
+oh = oh.learn_many(X)
+
+df = oh.transform_many(X)
+df.sort_index(axis="columns")
+ c1_Oranges c1_a c1_i c1_u c2_Apples c2_d c2_h c2_x
+0 0 0 0 1 0 1 0 0
+1 0 1 0 0 0 0 0 1
+2 0 0 1 0 0 0 1 0
+df.dtypes.sort_index()
+c1_Oranges Sparse[uint8, 0]
+c1_a Sparse[uint8, 0]
+c1_i Sparse[uint8, 0]
+c1_u Sparse[uint8, 0]
+c2_Apples Sparse[uint8, 0]
+c2_d Sparse[uint8, 0]
+c2_h Sparse[uint8, 0]
+c2_x Sparse[uint8, 0]
+dtype: object
+Update with a mini-batch of features.
+A lot of transformers don't actually have to do anything during the learn_many step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_many can override this method.
Parameters
+Returns
+Transformer: self
++
Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a mini-batch of features.
+Parameters
+Returns
+pd.DataFrame: A new DataFrame.
++
Transform a set of features x.
Parameters
+None Returns
+dict: The transformed values.
++ + + + + + + + +
Ordinal encoder.
+This transformer maps each feature to integers. It can useful when a feature has string values (i.e. categorical variables).
+unknown_value
+Type → int | None
+Default → 0
The value to use for unknown categories seen during transform_one. Unknown categories will be mapped to an integer once they are seen during learn_one. This value can be set to None in order to categories to None if they've never been seen before.
none_value
+Type → int
+Default → -1
The value to encode None with.
categories
+A dict of dicts. The outer dict maps each feature to its inner dict. The inner dict maps each category to its code.
+from river import preprocessing
+
+X = [
+ {"country": "France", "place": "Taco Bell"},
+ {"country": None, "place": None},
+ {"country": "Sweden", "place": "Burger King"},
+ {"country": "France", "place": "Burger King"},
+ {"country": "Russia", "place": "Starbucks"},
+ {"country": "Russia", "place": "Starbucks"},
+ {"country": "Sweden", "place": "Taco Bell"},
+ {"country": None, "place": None},
+]
+
+encoder = preprocessing.OrdinalEncoder()
+for x in X:
+ print(encoder.transform_one(x))
+ encoder = encoder.learn_one(x)
+{'country': 0, 'place': 0}
+{'country': -1, 'place': -1}
+{'country': 0, 'place': 0}
+{'country': 1, 'place': 2}
+{'country': 0, 'place': 0}
+{'country': 3, 'place': 3}
+{'country': 2, 'place': 1}
+{'country': -1, 'place': -1}
+xb1 = pd.DataFrame(X[0:4], index=[0, 1, 2, 3])
+xb2 = pd.DataFrame(X[4:8], index=[4, 5, 6, 7])
+
+encoder = preprocessing.OrdinalEncoder()
+encoder.transform_many(xb1)
+ country place
+0 0 0
+1 -1 -1
+2 0 0
+3 0 0
+encoder = encoder.learn_many(xb1)
+encoder.transform_many(xb2)
+ country place
+4 0 0
+5 0 0
+6 2 1
+7 -1 -1
+Update with a mini-batch of features.
+A lot of transformers don't actually have to do anything during the learn_many step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_many can override this method.
Parameters
+None Returns
+Transformer: self
++
Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a mini-batch of features.
+Parameters
+Returns
+pd.DataFrame: A new DataFrame.
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Clips the target after predicting.
+regressor
+Type → base.Regressor
+Regressor model for which to clip the predictions.
+y_min
+Type → float
+minimum value.
+y_max
+Type → float
+maximum value.
+from river import linear_model
+from river import preprocessing
+
+dataset = (
+ ({'a': 2, 'b': 4}, 80),
+ ({'a': 3, 'b': 5}, 100),
+ ({'a': 4, 'b': 6}, 120)
+)
+
+model = preprocessing.PredClipper(
+ regressor=linear_model.LinearRegression(),
+ y_min=0,
+ y_max=200
+)
+
+for x, y in dataset:
+ _ = model.learn_one(x, y)
+
+model.predict_one({'a': -100, 'b': -200})
+0
+model.predict_one({'a': 50, 'b': 60})
+200
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Imputes missing values by using the most recent value.
+from river import preprocessing
+
+imputer = preprocessing.PreviousImputer()
+
+imputer = imputer.learn_one({'x': 1, 'y': 2})
+imputer.transform_one({'y': None})
+{'y': 2}
+imputer.transform_one({'x': None})
+{'x': 1}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Scale features using statistics that are robust to outliers.
+This Scaler removes the median and scales the data according to the interquantile range.
+with_centering
+Default → True
Whether to centre the data before scaling.
+with_scaling
+Default → True
Whether to scale data to IQR.
+q_inf
+Default → 0.25
Desired inferior quantile, must be between 0 and 1.
+q_sup
+Default → 0.75
Desired superior quantile, must be between 0 and 1.
+median (dict)
+Mapping between features and instances of stats.Quantile(0.5)`.
iqr (dict)
+Mapping between features and instances of stats.IQR.
from pprint import pprint
+import random
+from river import preprocessing
+
+random.seed(42)
+X = [{'x': random.uniform(8, 12)} for _ in range(5)]
+pprint(X)
+[{'x': 10.557707},
+ {'x': 8.100043},
+ {'x': 9.100117},
+ {'x': 8.892842},
+ {'x': 10.945884}]
+scaler = preprocessing.RobustScaler()
+
+for x in X:
+ print(scaler.learn_one(x).transform_one(x))
+ {'x': 0.0}
+ {'x': -1.0}
+ {'x': 0.0}
+ {'x': -0.12449923287875722}
+ {'x': 1.1086595155704708}
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Sparse random projector.
+This transformer reduces the dimensionality of inputs by projecting them onto a sparse random projection matrix.
+Ping Li et al. recommend using a minimum density of 1 / sqrt(n_features). The transformer is not aware of how many features will be seen, so the user must specify the density manually.
n_components
+Default → 10
Number of components to project the data onto.
+density
+Default → 0.1
Density of the random projection matrix. The density is defined as the ratio of non-zero components in the matrix. It is equal to 1 - sparsity.
seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+model = preprocessing.SparseRandomProjector(
+ n_components=3,
+ seed=42
+)
+
+for x, y in dataset:
+ x = model.transform_one(x)
+ print(x)
+ break
+{0: 92.89572746525327, 1: 1344540.5692342375, 2: 0}
+model = (
+ preprocessing.SparseRandomProjector(
+ n_components=5,
+ seed=42
+ ) |
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression()
+)
+evaluate.progressive_val_score(dataset, model, metrics.MAE())
+MAE: 1.292572
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++
D. Achlioptas. 2003. Database-friendly random projections: Johnson-Lindenstrauss with binary coins. Journal of Computer and System Sciences 66 (2003) 671-687 ↩
+Ping Li, Trevor J. Hastie, and Kenneth W. Church. 2006. Very sparse random projections. In Proceedings of the 12th ACM SIGKDD international conference on Knowledge discovery and data mining (KDD'06). ACM, New York, NY, USA, 287-296. ↩
+Scales the data so that it has zero mean and unit variance.
+Under the hood, a running mean and a running variance are maintained. The scaling is slightly different than when scaling the data in batch because the exact means and variances are not known in advance. However, this doesn't have a detrimental impact on performance in the long run.
+This transformer supports mini-batches as well as single instances. In the mini-batch case, the number of columns and the ordering of the columns are allowed to change between subsequent calls. In other words, this transformer will keep working even if you add and/or remove features every time you call learn_many and transform_many.
with_std
+Default → True
Whether or not each feature should be divided by its standard deviation.
+import random
+from river import preprocessing
+
+random.seed(42)
+X = [{'x': random.uniform(8, 12), 'y': random.uniform(8, 12)} for _ in range(6)]
+for x in X:
+ print(x)
+{'x': 10.557, 'y': 8.100}
+{'x': 9.100, 'y': 8.892}
+{'x': 10.945, 'y': 10.706}
+{'x': 11.568, 'y': 8.347}
+{'x': 9.687, 'y': 8.119}
+{'x': 8.874, 'y': 10.021}
+scaler = preprocessing.StandardScaler()
+
+for x in X:
+ print(scaler.learn_one(x).transform_one(x))
+{'x': 0.0, 'y': 0.0}
+{'x': -0.999, 'y': 0.999}
+{'x': 0.937, 'y': 1.350}
+{'x': 1.129, 'y': -0.651}
+{'x': -0.776, 'y': -0.729}
+{'x': -1.274, 'y': 0.992}
+This transformer also supports mini-batch updates. You can call learn_many and provide a
+pandas.DataFrame:
import pandas as pd
+X = pd.DataFrame.from_dict(X)
+
+scaler = preprocessing.StandardScaler()
+scaler = scaler.learn_many(X[:3])
+scaler = scaler.learn_many(X[3:])
+You can then call transform_many to scale a mini-batch of features:
scaler.transform_many(X)
+ x y
+0 0.444600 -0.933384
+1 -1.044259 -0.138809
+2 0.841106 1.679208
+3 1.477301 -0.685117
+4 -0.444084 -0.914195
+5 -1.274664 0.992296
+Update with a mini-batch of features.
+Note that the update formulas for mean and variance are slightly different than in the single instance case, but they produce exactly the same result.
+Parameters
++
Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Scale a mini-batch of features.
+Parameters
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++
Replaces missing values with a statistic.
+This transformer allows you to replace missing values with the value of a running statistic. During a call to learn_one, for each feature, a statistic is updated whenever a numeric feature is observed. When transform_one is called, each feature with a None value is replaced with the current value of the corresponding statistic.
imputers
+A list of tuples where each tuple has two elements. The first elements is a feature name and the second value is an instance of stats.base.Univariate. The second value can also be an arbitrary value, such as -1, in which case the missing values will be replaced with it.
from river import preprocessing
+from river import stats
+For numeric data, we can use a stats.Mean()` to replace missing values by the running
+average of the previously seen values:
X = [
+ {'temperature': 1},
+ {'temperature': 8},
+ {'temperature': 3},
+ {'temperature': None},
+ {'temperature': 4}
+]
+
+imp = preprocessing.StatImputer(('temperature', stats.Mean()))
+
+for x in X:
+ imp = imp.learn_one(x)
+ print(imp.transform_one(x))
+{'temperature': 1}
+{'temperature': 8}
+{'temperature': 3}
+{'temperature': 4.0}
+{'temperature': 4}
+For discrete/categorical data, a common practice is to stats.Mode to replace missing
+values by the most commonly seen value:
X = [
+ {'weather': 'sunny'},
+ {'weather': 'rainy'},
+ {'weather': 'sunny'},
+ {'weather': None},
+ {'weather': 'rainy'},
+ {'weather': 'rainy'},
+ {'weather': None}
+]
+
+imp = preprocessing.StatImputer(('weather', stats.Mode()))
+
+for x in X:
+ imp = imp.learn_one(x)
+ print(imp.transform_one(x))
+{'weather': 'sunny'}
+{'weather': 'rainy'}
+{'weather': 'sunny'}
+{'weather': 'sunny'}
+{'weather': 'rainy'}
+{'weather': 'rainy'}
+{'weather': 'rainy'}
+You can also choose to replace missing values with a constant value, as so:
+imp = preprocessing.StatImputer(('weather', 'missing'))
+
+for x in X:
+ imp = imp.learn_one(x)
+ print(imp.transform_one(x))
+{'weather': 'sunny'}
+{'weather': 'rainy'}
+{'weather': 'sunny'}
+{'weather': 'missing'}
+{'weather': 'rainy'}
+{'weather': 'rainy'}
+{'weather': 'missing'}
+Multiple imputers can be defined by providing a tuple for each feature which you want to +impute:
+X = [
+ {'weather': 'sunny', 'temperature': 8},
+ {'weather': 'rainy', 'temperature': 3},
+ {'weather': 'sunny', 'temperature': None},
+ {'weather': None, 'temperature': 4},
+ {'weather': 'snowy', 'temperature': -4},
+ {'weather': 'snowy', 'temperature': -3},
+ {'weather': 'snowy', 'temperature': -3},
+ {'weather': None, 'temperature': None}
+]
+
+imp = preprocessing.StatImputer(
+ ('temperature', stats.Mean()),
+ ('weather', stats.Mode())
+)
+
+for x in X:
+ imp = imp.learn_one(x)
+ print(imp.transform_one(x))
+{'weather': 'sunny', 'temperature': 8}
+{'weather': 'rainy', 'temperature': 3}
+{'weather': 'sunny', 'temperature': 5.5}
+{'weather': 'sunny', 'temperature': 4}
+{'weather': 'snowy', 'temperature': -4}
+{'weather': 'snowy', 'temperature': -3}
+{'weather': 'snowy', 'temperature': -3}
+{'weather': 'snowy', 'temperature': 0.8333}
+A sophisticated way to go about imputation is condition the statistics on a given feature. +For instance, we might want to replace a missing temperature with the average temperature +of a particular weather condition. As an example, consider the following dataset where the +temperature is missing, but not the weather condition:
+X = [
+ {'weather': 'sunny', 'temperature': 8},
+ {'weather': 'rainy', 'temperature': 3},
+ {'weather': 'sunny', 'temperature': None},
+ {'weather': 'rainy', 'temperature': 4},
+ {'weather': 'sunny', 'temperature': 10},
+ {'weather': 'sunny', 'temperature': None},
+ {'weather': 'sunny', 'temperature': 12},
+ {'weather': 'rainy', 'temperature': None}
+]
+Each missing temperature can be replaced with the average temperature of the corresponding +weather condition as so:
+from river import compose
+
+imp = compose.Grouper(
+ preprocessing.StatImputer(('temperature', stats.Mean())),
+ by='weather'
+)
+
+for x in X:
+ imp = imp.learn_one(x)
+ print(imp.transform_one(x))
+{'weather': 'sunny', 'temperature': 8}
+{'weather': 'rainy', 'temperature': 3}
+{'weather': 'sunny', 'temperature': 8.0}
+{'weather': 'rainy', 'temperature': 4}
+{'weather': 'sunny', 'temperature': 10}
+{'weather': 'sunny', 'temperature': 9.0}
+{'weather': 'sunny', 'temperature': 12}
+{'weather': 'rainy', 'temperature': 3.5}
+Note that you can also create a Grouper with the * operator:
imp = preprocessing.StatImputer(('temperature', stats.Mean())) * 'weather'
+Update with a set of features x.
A lot of transformers don't actually have to do anything during the learn_one step because they are stateless. For this reason the default behavior of this function is to do nothing. Transformers that however do something during the learn_one can override this method.
Parameters
+Returns
+Transformer: self
++
Transform a set of features x.
Parameters
+Returns
+dict: The transformed values.
++ + + + + + + + +
Applies min-max scaling to the target.
+regressor
+Type → base.Regressor
+Regression model to wrap.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+model = (
+ preprocessing.StandardScaler() |
+ preprocessing.TargetMinMaxScaler(
+ regressor=linear_model.LinearRegression(intercept_lr=0.15)
+ )
+)
+metric = metrics.MSE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MSE: 2.018905
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Applies standard scaling to the target.
+regressor
+Type → base.Regressor
+Regression model to wrap.
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+model = (
+ preprocessing.StandardScaler() |
+ preprocessing.TargetStandardScaler(
+ regressor=linear_model.LinearRegression(intercept_lr=0.15)
+ )
+)
+metric = metrics.MSE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MSE: 2.005999
+Fits to a set of features x and a real-valued target y.
Parameters
+Returns
+self
++
Predict the output of features x.
Parameters
+Returns
+The prediction.
++ + + + + + + + +
Beta distribution for binary data.
+A Beta distribution is very similar to a Bernoulli distribution in that it counts occurrences of boolean events. The differences lies in what is being measured. A Binomial distribution models the probability of an event occurring, whereas a Beta distribution models the probability distribution itself. In other words, it's a probability distribution over probability distributions.
+alpha
+Type → int
+Default → 1
Initial alpha parameter.
+beta
+Type → int
+Default → 1
Initial beta parameter.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+n_samples
+The number of observed samples.
+from river import proba
+
+successes = 81
+failures = 219
+beta = proba.Beta(successes, failures)
+
+beta(.21), beta(.35)
+(0.867..., 0.165...)
+for success in range(100):
+ beta = beta.update(True)
+for failure in range(200):
+ beta = beta.update(False)
+
+beta(.21), beta(.35)
+(2.525...e-05, 0.841...)
+beta.cdf(.35)
+0.994168...
+Probability mass/density function.
+Parameters
++
Cumulative density function, i.e. P(X <= x).
+Parameters
++
Reverts the parameters of the distribution for a given observation.
+Parameters
++
Sample a random value from the distribution.
++
Updates the parameters of the distribution given a new observation.
+Parameters
++
Normal distribution with parameters mu and sigma.
+seed
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+mu
+n_samples
+The number of observed samples.
+sigma
+from river import proba
+
+p = proba.Gaussian().update(6).update(7)
+
+p
+𝒩(μ=6.500, σ=0.707)
+p(6.5)
+0.564189
+p.revert(7)
+𝒩(μ=6.000, σ=0.000)
+Probability mass/density function.
+Parameters
++
Cumulative density function, i.e. P(X <= x).
+Parameters
++
Reverts the parameters of the distribution for a given observation.
+Parameters
+1.0 +
Sample a random value from the distribution.
++
Updates the parameters of the distribution given a new observation.
+Parameters
+1.0 + + + + + + + + +
Multinomial distribution for categorical data.
+events
+Type → dict | list | None
+Default → None
An optional list of events that already occurred.
+seed
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+n_samples
+The number of observed samples.
+from river import proba
+
+p = proba.Multinomial(['green'] * 3)
+p = p.update('red')
+
+p('red')
+0.25
+p = p.update('red').update('red')
+p('green')
+0.5
+p = p.revert('red').revert('red')
+p('red')
+0.25
+You can wrap this with a utils.Rolling to measure a distribution over a window:
from river import utils
+
+X = ['red', 'green', 'green', 'blue', 'blue']
+
+dist = utils.Rolling(
+ proba.Multinomial(),
+ window_size=3
+)
+
+for x in X:
+ dist = dist.update(x)
+ print(dist)
+ print()
+P(red) = 1.000
+<BLANKLINE>
+P(red) = 0.500
+P(green) = 0.500
+<BLANKLINE>
+P(green) = 0.667
+P(red) = 0.333
+<BLANKLINE>
+P(green) = 0.667
+P(blue) = 0.333
+P(red) = 0.000
+<BLANKLINE>
+P(blue) = 0.667
+P(green) = 0.333
+P(red) = 0.000
+<BLANKLINE>
+You can wrap this with a utils.Rolling to measure a distribution over a window of time:
import datetime as dt
+
+X = ['red', 'green', 'green', 'blue']
+days = [1, 2, 3, 4]
+
+dist = utils.TimeRolling(
+ proba.Multinomial(),
+ period=dt.timedelta(days=2)
+)
+
+for x, day in zip(X, days):
+ dist = dist.update(x, t=dt.datetime(2019, 1, day))
+ print(dist)
+ print()
+P(red) = 1.000
+<BLANKLINE>
+P(red) = 0.500
+P(green) = 0.500
+<BLANKLINE>
+P(green) = 1.000
+P(red) = 0.000
+<BLANKLINE>
+P(green) = 0.500
+P(blue) = 0.500
+P(red) = 0.000
+<BLANKLINE>
+Probability mass/density function.
+Parameters
++
Reverts the parameters of the distribution for a given observation.
+Parameters
++
Sample a random value from the distribution.
++
Updates the parameters of the distribution given a new observation.
+Parameters
++ + + + + + + + +
Multivariate normal distribution with parameters mu and var.
+seed
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+mu
+The mean value of the distribution.
+n_samples
+The number of observed samples.
+sigma
+The standard deviation of the distribution.
+var
+The variance of the distribution.
+import numpy as np
+import pandas as pd
+from river import proba
+
+np.random.seed(42)
+X = pd.DataFrame(
+ np.random.random((8, 3)),
+ columns=["red", "green", "blue"]
+)
+X
+ red green blue
+0 0.374540 0.950714 0.731994
+1 0.598658 0.156019 0.155995
+2 0.058084 0.866176 0.601115
+3 0.708073 0.020584 0.969910
+4 0.832443 0.212339 0.181825
+5 0.183405 0.304242 0.524756
+6 0.431945 0.291229 0.611853
+7 0.139494 0.292145 0.366362
+p = proba.MultivariateGaussian(seed=42)
+p.n_samples
+0.0
+for x in X.to_dict(orient="records"):
+ p = p.update(x)
+p.var
+ blue green red
+blue 0.076119 0.020292 -0.010128
+green 0.020292 0.112931 -0.053268
+red -0.010128 -0.053268 0.078961
+Retrieving current state in nice format is simple +
p
+𝒩(
+ μ=(0.518, 0.387, 0.416),
+ σ^2=(
+ [ 0.076 0.020 -0.010]
+ [ 0.020 0.113 -0.053]
+ [-0.010 -0.053 0.079]
+ )
+)
+To retrieve number of samples and mode:
+p.n_samples
+8.0
+p.mode
+{'blue': 0.5179..., 'green': 0.3866..., 'red': 0.4158...}
+To retrieve the PDF and CDF:
+p(x)
+0.97967...
+p.cdf(x)
+0.00787...
+To sample data from distribution:
+p.sample()
+{'blue': -0.179..., 'green': -0.051..., 'red': 0.376...}
+MultivariateGaussian works with utils.Rolling:
from river import utils
+
+p = utils.Rolling(MultivariateGaussian(), window_size=5)
+for x in X.to_dict(orient="records"):
+ p = p.update(x)
+p.var
+ blue green red
+blue 0.087062 -0.022873 0.007765
+green -0.022873 0.014279 -0.025181
+red 0.007765 -0.025181 0.095066
+MultivariateGaussian works with utils.TimeRolling:
from datetime import datetime as dt, timedelta as td
+X.index = [dt(2023, 3, 28, 0, 0, 0) + td(seconds=x) for x in range(8)]
+p = utils.TimeRolling(MultivariateGaussian(), period=td(seconds=5))
+for t, x in X.iterrows():
+ p = p.update(x.to_dict(), t=t)
+p.var
+ blue green red
+blue 0.087062 -0.022873 0.007765
+green -0.022873 0.014279 -0.025181
+red 0.007765 -0.025181 0.095066
+Variance on diagonal is consistent with proba.Gaussian.
multi = proba.MultivariateGaussian()
+single = proba.Gaussian()
+for x in X.to_dict(orient='records'):
+ multi = multi.update(x)
+ single = single.update(x['blue'])
+multi.mu['blue'] == single.mu
+True
+multi.sigma['blue']['blue'] == single.sigma
+True
+PDF(x) method.
+Parameters
++
Cumulative density function, i.e. P(X <= x).
+Parameters
++
Reverts the parameters of the distribution for a given observation.
+Parameters
++
Sample a random value from the distribution.
++
Updates the parameters of the distribution given a new observation.
+Parameters
++ + + + + + + + +
A probability distribution for discrete values.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+n_samples
+The number of observed samples.
+Probability mass/density function.
+Parameters
++
Reverts the parameters of the distribution for a given observation.
+Parameters
++
Sample a random value from the distribution.
++
Updates the parameters of the distribution given a new observation.
+Parameters
++ + + + + + + + +
A probability distribution for continuous values.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+n_samples
+The number of observed samples.
+Probability mass/density function.
+Parameters
++
Cumulative density function, i.e. P(X <= x).
+Parameters
++
Reverts the parameters of the distribution for a given observation.
+Parameters
++
Sample a random value from the distribution.
++
Updates the parameters of the distribution given a new observation.
+Parameters
++ + + + + + + + +
A probability distribution for discrete values.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+n_samples
+The number of observed samples.
+Probability mass/density function.
+Parameters
++
Reverts the parameters of the distribution for a given observation.
+Parameters
++
Sample a random value from the distribution.
++
Updates the parameters of the distribution given a new observation.
+Parameters
++ + + + + + + + +
General distribution.
+seed
+Type → int | None
+Default → None
Random number generator seed for reproducibility.
+mode
+The most likely value in the distribution.
+n_samples
+The number of observed samples.
+Probability mass/density function.
+Parameters
++
Sample a random value from the distribution.
++ + + + + + + + +
Baseline for recommender systems.
+A first-order approximation of the bias involved in target. The model equation is defined as:
+Where \(bu_{u}\) and \(bi_{i}\) are respectively the user and item biases.
+This model expects a dict input with a user and an item entries without any type constraint on their values (i.e. can be strings or numbers). Other entries are ignored.
optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the weights.
+loss
+Type → optim.losses.Loss | None
+Default → None
The loss function to optimize for.
+l2
+Default → 0.0
regularization amount used to push weights towards 0.
+initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme.
+clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Default → None
Random number generation seed. Set this for reproducibility.
+global_mean (stats.Mean)
+The target arithmetic mean.
+u_biases (collections.defaultdict)
+The user bias weights.
+i_biases (collections.defaultdict)
+The item bias weights.
+u_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the user bias weights.
+i_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the item bias weights.
+from river import optim
+from river import reco
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, 8),
+ ({'user': 'Alice', 'item': 'Terminator'}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars'}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter'}, 5),
+ ({'user': 'Bob', 'item': 'Superman'}, 8),
+ ({'user': 'Bob', 'item': 'Terminator'}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars'}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, 2)
+)
+
+model = reco.Baseline(optimizer=optim.SGD(0.005))
+
+for x, y in dataset:
+ _ = model.learn_one(**x, y=y)
+
+model.predict_one(user='Bob', item='Harry Potter')
+6.538120
+Fits a user-item pair and a real-valued target y.
Parameters
+None +
Predicts the target value of a set of features x.
Parameters
+None Returns
+Reward: The predicted preference from the user for the item.
++
Rank models by decreasing order of preference for a given user.
+Parameters
+None +
Biased Matrix Factorization for recommender systems.
+The model equation is defined as:
+Where \(bu_{u}\) and \(bi_{i}\) are respectively the user and item biases. The last term being simply the dot product between the latent vectors of the given user-item pair:
+where \(k\) is the number of latent factors.
+This model expects a dict input with a user and an item entries without any type constraint on their values (i.e. can be strings or numbers). Other entries are ignored.
n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+bias_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the bias weights.
+latent_optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent weights.
+loss
+Type → optim.losses.Loss | None
+Default → None
The loss function to optimize for.
+l2_bias
+Default → 0.0
Amount of L2 regularization used to push bias weights towards 0.
+l2_latent
+Default → 0.0
Amount of L2 regularization used to push latent weights towards 0.
+weight_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Weights initialization scheme.
+latent_initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme.
+clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Default → None
Random number generation seed. Set this for reproducibility.
+global_mean (stats.Mean)
+The target arithmetic mean.
+u_biases (collections.defaultdict)
+The user bias weights.
+i_biases (collections.defaultdict)
+The item bias weights.
+u_latents (collections.defaultdict)
+The user latent vectors randomly initialized.
+i_latents (collections.defaultdict)
+The item latent vectors randomly initialized.
+u_bias_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the user bias weights.
+i_bias_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the item bias weights.
+u_latent_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the user latent weights.
+i_latent_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the item latent weights.
+from river import optim
+from river import reco
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, 8),
+ ({'user': 'Alice', 'item': 'Terminator'}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars'}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter'}, 5),
+ ({'user': 'Bob', 'item': 'Superman'}, 8),
+ ({'user': 'Bob', 'item': 'Terminator'}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars'}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, 2)
+)
+
+model = reco.BiasedMF(
+ n_factors=10,
+ bias_optimizer=optim.SGD(0.025),
+ latent_optimizer=optim.SGD(0.025),
+ latent_initializer=optim.initializers.Normal(mu=0., sigma=0.1, seed=71)
+)
+
+for x, y in dataset:
+ _ = model.learn_one(**x, y=y)
+
+model.predict_one(user='Bob', item='Harry Potter')
+6.489025
+Fits a user-item pair and a real-valued target y.
Parameters
+None +
Predicts the target value of a set of features x.
Parameters
+None Returns
+Reward: The predicted preference from the user for the item.
++
Rank models by decreasing order of preference for a given user.
+Parameters
+None + + + + + + + + + +
Funk Matrix Factorization for recommender systems.
+The model equation is defined as:
+where \(k\) is the number of latent factors.
+This model expects a dict input with a user and an item entries without any type constraint on their values (i.e. can be strings or numbers). Other entries are ignored.
n_factors
+Default → 10
Dimensionality of the factorization or number of latent factors.
+optimizer
+Type → optim.base.Optimizer | None
+Default → None
The sequential optimizer used for updating the latent factors.
+loss
+Type → optim.losses.Loss | None
+Default → None
The loss function to optimize for.
+l2
+Default → 0.0
Amount of L2 regularization used to push weights towards 0.
+initializer
+Type → optim.initializers.Initializer | None
+Default → None
Latent factors initialization scheme.
+clip_gradient
+Default → 1000000000000.0
Clips the absolute value of each gradient value.
+seed
+Default → None
Random number generation seed. Set this for reproducibility.
+u_latents (collections.defaultdict)
+The user latent vectors randomly initialized.
+i_latents (collections.defaultdict)
+The item latent vectors randomly initialized.
+u_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the user latent weights.
+i_optimizer (optim.base.Optimizer)
+The sequential optimizer used for updating the item latent weights.
+from river import optim
+from river import reco
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, 8),
+ ({'user': 'Alice', 'item': 'Terminator'}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars'}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter'}, 5),
+ ({'user': 'Bob', 'item': 'Superman'}, 8),
+ ({'user': 'Bob', 'item': 'Terminator'}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars'}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, 2)
+)
+
+model = reco.FunkMF(
+ n_factors=10,
+ optimizer=optim.SGD(0.1),
+ initializer=optim.initializers.Normal(mu=0., sigma=0.1, seed=11),
+)
+
+for x, y in dataset:
+ _ = model.learn_one(**x, y=y)
+
+model.predict_one(user='Bob', item='Harry Potter')
+1.866272
+Fits a user-item pair and a real-valued target y.
Parameters
+None +
Predicts the target value of a set of features x.
Parameters
+None Returns
+Reward: The predicted preference from the user for the item.
++
Rank models by decreasing order of preference for a given user.
+Parameters
+None + + + + + + + + + +
Predicts random values sampled from a normal distribution.
+The parameters of the normal distribution are fitted with running statistics. They parameters are independent of the user, the item, or the context, and are instead fitted globally. This recommender therefore acts as a dummy model that any serious model should easily outperform.
+seed
+Default → None
Random number generation seed. Set this for reproducibility.
+mean
+ +variance
+ +from river import reco
+
+dataset = (
+ ({'user': 'Alice', 'item': 'Superman'}, 8),
+ ({'user': 'Alice', 'item': 'Terminator'}, 9),
+ ({'user': 'Alice', 'item': 'Star Wars'}, 8),
+ ({'user': 'Alice', 'item': 'Notting Hill'}, 2),
+ ({'user': 'Alice', 'item': 'Harry Potter'}, 5),
+ ({'user': 'Bob', 'item': 'Superman'}, 8),
+ ({'user': 'Bob', 'item': 'Terminator'}, 9),
+ ({'user': 'Bob', 'item': 'Star Wars'}, 8),
+ ({'user': 'Bob', 'item': 'Notting Hill'}, 2)
+)
+
+model = reco.RandomNormal(seed=42)
+
+for x, y in dataset:
+ _ = model.learn_one(**x, y=y)
+
+model.predict_one(user='Bob', item='Harry Potter')
+6.147299621751425
+Fits a user-item pair and a real-valued target y.
Parameters
+None +
Predicts the target value of a set of features x.
Parameters
+None Returns
+Reward: The predicted preference from the user for the item.
++
Rank models by decreasing order of preference for a given user.
+Parameters
+None + + + + + + + + +
Base class for ranking models.
+seed
+Type → int | None
+Default → None
Random number generation seed. Set this for reproducibility.
+Fits a user-item pair and a real-valued target y.
Parameters
+None +
Predicts the target value of a set of features x.
Parameters
+None Returns
+Reward: The predicted preference from the user for the item.
++
Rank models by decreasing order of preference for a given user.
+Parameters
+None + + + + + + + + +
Adaptive Model Rules.
+AMRules1 is a rule-based algorithm for incremental regression tasks. AMRules relies on the Hoeffding bound to build its rule set, similarly to Hoeffding Trees. The Variance-Ratio heuristic is used to evaluate rules' splits. Moreover, this rule-based regressor has additional capacities not usually found in decision trees.
+Firstly, each created decision rule has a built-in drift detection mechanism. Every time a drift is detected, the affected decision rule is removed. In addition, AMRules' rules also have anomaly detection capabilities. After a warm-up period, each rule tests whether or not the incoming instances are anomalies. Anomalous instances are not used for training.
+Every time no rule is covering an incoming example, a default rule is used to learn from it. A rule covers an instance when all of the rule's literals (tests joined by the logical operation and) match the input case. The default rule is also applied for predicting examples not covered by any rules from the rule set.
n_min
+Type → int
+Default → 200
The total weight that must be observed by a rule between expansion attempts.
+delta
+Type → float
+Default → 1e-07
The split test significance. The split confidence is given by 1 - delta.
tau
+Type → float
+Default → 0.05
The tie-breaking threshold.
+pred_type
+Type → str
+Default → adaptive
The prediction strategy used by the decision rules. Can be either: - "mean": outputs the target mean within the partitions defined by the decision rules. - "model": always use instances of the model passed pred_model to make predictions. - "adaptive": dynamically selects between "mean" and "model" for each incoming example. The most accurate option at the moment will be used.
pred_model
+Type → base.Regressor | None
+Default → None
The regression model that will be replicated for every rule when pred_type is either "model" or "adaptive".
splitter
+Type → spl.Splitter | None
+Default → None
The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.TEBSTSplitter is used if splitter is None.
drift_detector
+Type → base.DriftDetector | None
+Default → None
The drift detection model that is used by each rule. Care must be taken to avoid the triggering of too many false alarms or delaying too much the concept drift detection. By default, drift.ADWIN is used if drift_detector is None.
fading_factor
+Type → float
+Default → 0.99
The exponential decaying factor applied to the learning models' absolute errors, that are monitored if pred_type='adaptive'. Must be between 0 and 1. The closer to 1, the more importance is going to be given to past observations. On the other hand, if its value approaches 0, the recent observed errors are going to have more influence on the final decision.
anomaly_threshold
+Type → float
+Default → -0.75
The threshold below which instances will be considered anomalies by the rules.
+m_min
+Type → int
+Default → 30
The minimum total weight a rule must observe before it starts to skip anomalous instances during training.
+ordered_rule_set
+Type → bool
+Default → True
If True, only the first rule that covers an instance will be used for training or prediction. If False, all the rules covering an instance will be updated during training, and the predictions for an instance will be the average prediction of all rules covering that example.
min_samples_split
+Type → int
+Default → 5
The minimum number of samples each partition of a binary split candidate must have to be considered valid.
+n_drifts_detected
+The number of detected concept drifts.
+from river import datasets
+from river import drift
+from river import evaluate
+from river import metrics
+from river import preprocessing
+from river import rules
+
+dataset = datasets.TrumpApproval()
+
+model = (
+ preprocessing.StandardScaler() |
+ rules.AMRules(
+ delta=0.01,
+ n_min=50,
+ drift_detector=drift.ADWIN()
+ )
+)
+
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 1.119553
+Aggregated anomaly score computed using all the rules that cover the input instance.
+Returns the mean anomaly score, the standard deviation of the score, and the proportion of rules that cover the instance (support). If the support is zero, it means that the default rule was used (not other rule covered x).
Parameters
+Returns
+tuple[float, float, float]: mean_anomaly_score, std_anomaly_score, support
++
Return an explanation of how x is predicted
Parameters
+Returns
+str: A representation of the rules that cover the input and their prediction.
++
Fits to a set of features x and a real-valued target y.
Parameters
+1 Returns
+AMRules: self
++
Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++
AMRules treats all the non-numerical inputs as nominal features. All instances of
+numbers.Number will be treated as continuous, even if they represent integer categories.
+When using nominal features, pred_type should be set to "mean", otherwise errors will be
+thrown while trying to update the underlying rules' prediction models. Prediction strategies
+other than "mean" can be used, as long as the prediction model passed to pred_model supports
+nominal features.
Duarte, J., Gama, J. and Bifet, A., 2016. Adaptive model rules from high-speed data +streams. ACM Transactions on Knowledge Discovery from Data (TKDD), 10(3), pp.1-22. ↩
+Counting using the Count-Min Sketch (CMS) algorithm.
+Contrary to an exhaustive approach, e.g., using a collections.Counter, CMS uses a limited and fixed amount of memory. The CMS algorithm uses a sketch structure consisting of a matrix \(w \times d\).
These dimensions are obtained via:
+\(w = \lceil \frac{e}{\epsilon} \rceil\), where \(e\) is the Euler number.
+\(d = \lceil \ln\left(\frac{1}{\delta} \right) \rceil\).
+Decreasing the values of \(\epsilon\) (epsilon) and \(\delta\) (delta) increase the accuracy of the algorithm, at the cost of increased memory usage. The values of w and d control the hash tables' capability and the amount of hash collisions, respectively.
CMS works by keeping d hash tables with w slots each. Elements are mapped to a slot in each hash table. These tables store the counting estimates. This implementation assumes the turnstile case described in the paper, i.e., count values and updates can be negative.
The count values obtained by CMS are always overestimates. Suppose \(c_i\) and \(\hat{c}_i\) are the ground truth and estimated count values, respectively, for a given element \(i\). CMS guarantees that \(c_i \le \hat{c}_i\) and, with probability \(1 - \delta\), \(\hat{c}_i \le c_i + \epsilon||\mathbf{c}||_1\). In the expression, \(||\mathbf{c}||_1 = \sum_i |c_i|\).
+epsilon
+Type → float
+Default → 0.1
The approximation error parameter. The error in answering a query is within a factor of epsilon with probability delta.
delta
+Type → float
+Default → 0.05
A query estimates have a probability of 1 - delta of having errors which are a factor of epsilon. See the CMS description above for more details.
seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+n_slots
+The number of slots in each hash table.
+n_tables
+The number of stored hash tables.
+import collections
+from river import sketch
+
+cms = sketch.Counter(epsilon=0.005, seed=0)
+
+rng = random.Random(7)
+
+counter = collections.Counter()
+We can check the number of slots per hash table: +
cms.n_slots
+544
+And the number of hash tables: +
cms.n_tables
+3
+Let's compare the sketch against a brute force approach:
+vals = []
+for _ in range(10000):
+ v = rng.randint(-1000, 1000)
+ cms = cms.update(v)
+ counter[v] += 1
+ vals.append(v)
+Now, we can compare the estimates of CMS against the exhaustive counting strategy:
+counter[7]
+5
+cms[7]
+12
+counter[532]
+4
+cms[532]
+15
+Keep in mind that CMS is an approximate sketch algorithm. Couting estimates for unseen values +might not be always reliable:
+cms[1001]
+9
+We can check the number of elements stored by each approach:
+len(counter), len(cms)
+(1982, 1632)
+And also retrieve the total sum of counts:
+cms.total()
+10000
+We can decrease the error by allocating more memory in the CMS:
+cms_a = sketch.Counter(epsilon=0.001, delta=0.01, seed=0)
+for v in vals:
+ cms_a = cms_a.update(v)
+
+cms_a[7]
+5
+cms_a[532]
+4
+We can also obtain estimates of the dot product between two instances of river.collections.Counter. This could be useful,
+for instance, to estimate the cosine distance between the data monitored in two different counter sketch instances. Suppose we
+create another CMS instance (the number of slots and hash tables must match) that monitors another sample of the same data
+generating process:
cms_b = sketch.Counter(epsilon=0.001, delta=0.01, seed=7)
+
+for _ in range(10000):
+ v = rng.randint(-1000, 1000)
+ cms_b = cms_b.update(v)
+Now, we can define a cosine distance function:
+def cosine_dist(cms_a, cms_b):
+ num = cms_a @ cms_b
+ den = math.sqrt(cms_a @ cms_a) * math.sqrt(cms_b @ cms_b)
+ return num / den
+And use it to calculate the cosine distance between the elements monitored in cms_a and cms_b:
cosine_dist(cms_a, cms_b)
+0.175363...
+Return the total count.
++
Find the Heavy Hitters using the Lossy Count with Forgetting factor algorithm1.
+Keep track of the most frequent item(set)s in a data stream and apply a forgetting factor to discard previous frequent items that do not often appear anymore. This is an approximation algorithm designed to work with a limited amount of memory rather than accounting for every possible solution (thus using an unbounded memory footprint). Any hashable type can be passed as input, hence tuples or frozensets can also be monitored.
+Considering a data stream where n elements were observed so far, the Lossy Count algorithm has the following properties:
support * n are output. There are nofalse negatives;
+No item(set) whose true frequency is less than (support - epsilon) * n is outputted;
Estimated frequencies are less than the true frequencies by at most epsilon * n.
support
+Type → float
+Default → 0.001
The support threshold used to determine if an item is frequent. The value of support must be in \([0, 1]\). Elements whose frequency is higher than support times the number of observations seen so far are outputted.
epsilon
+Type → float
+Default → 0.005
Error parameter to control the accuracy-memory tradeoff. The value of epsilon must be in \((0, 1]\) and typically epsilon \(\ll\) support. The smaller the epsilon, the more accurate the estimates will be, but the count sketch will have an increased memory footprint.
fading_factor
+Type → float
+Default → 0.999
Forgetting factor applied to the frequency estimates to reduce the impact of old items. The value of fading_factor must be in \((0, 1]\).
import random
+import string
+from river import sketch
+
+rng = random.Random(42)
+hh = sketch.HeavyHitters()
+We will feed the counter with printable ASCII characters:
+for _ in range(10_000):
+ hh = hh.update(rng.choice(string.printable))
+We can retrieve estimates of the n top elements and their frequencies. Let's try n=3
+
hh.most_common(3)
+[(',', 122.099142...), ('[', 116.049510...), ('W', 115.013402...)]
+We can also access estimates of individual elements:
+hh['A']
+99.483575...
+Unobserved elements are handled just fine: +
hh[(1, 2, 3)]
+0.0
+Veloso, B., Tabassum, S., Martins, C., Espanha, R., Azevedo, R., & Gama, J. (2020). +Interconnect bypass fraud detection: a case study. Annals of Telecommunications, 75(9), 583-596. ↩
+Streaming histogram.
+max_bins
+Default → 256
Maximal number of bins.
+n
+Total number of seen values.
+from river import sketch
+import numpy as np
+
+np.random.seed(42)
+
+values = np.hstack((
+ np.random.normal(-3, 1, 1000),
+ np.random.normal(3, 1, 1000),
+))
+
+hist = sketch.Histogram(max_bins=15)
+
+for x in values:
+ hist = hist.update(x)
+
+for bin in hist:
+ print(bin)
+[-6.24127, -6.24127]: 1
+[-5.69689, -5.19881]: 8
+[-5.12390, -4.43014]: 57
+[-4.42475, -3.72574]: 158
+[-3.71984, -3.01642]: 262
+[-3.01350, -2.50668]: 206
+[-2.50329, -0.81020]: 294
+[-0.80954, 0.29677]: 19
+[0.40896, 0.82733]: 7
+[0.84661, 1.25147]: 24
+[1.26029, 2.30758]: 178
+[2.31081, 3.05701]: 284
+[3.05963, 3.69695]: 242
+[3.69822, 5.64434]: 258
+[6.13775, 6.19311]: 2
+Cumulative distribution function.
+Parameters
++
Yields CDF values for a sorted iterable of values.
+This is faster than calling cdf with many values.
Parameters
+False + + + + + + + + + +
Approximate tracking of observed items using Bloom filters.
+Bloom filters enable using a limited amount of memory to check whether a given item was already observed in a stream. They can be used similarly to Python's built-in sets with the difference that items are not explicitly stored. For that reason, element removal and set difference are not currently supported.
+Bloom filters store a bit array and map incoming items to k index positions in the such array. The selected positions are set to True. Therefore, a binary code representation is created for each item. Membership works by projecting the query item and checking if every position of its binary code is True. If that is not the case, the item was not observed yet. A nice property of Bloom filters is that they do not yield false negatives: unobserved items might be signalized as observed, but observed items are never signalized as unobserved.
If more than one item has the same binary code, i.e., hash collisions happen, the accuracy of the Bloom filter decreases, and false positives are produced. For instance, a previously unobserved item is signalized as observed. Increasing the size of the binary array and the value of k increase the filter's accuracy as hash collisions are avoided. Nonetheless, even using an increased number of hash functions, hash collisions will frequently happen if the array capacity is too small. The length of the bit array and the number of hash functions are inferred automatically from the supplied capacity and fp_rate.
capacity
+Type → int
+Default → 2048
The maximum capacity of the Bloom filter, i.e., the maximum number of distinct items to store given the selected fp_rate.
fp_rate
+Type → float
+Default → 0.01
The allowed rate of false positives. The probability of obtaining a true positive is 1 - fp_rate.
seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+n_bits
+Return the size of the binary array used by the Bloom filter.
+n_hash
+Return the number of used hash functions.
+import random
+from river import sketch
+
+rng = random.Random(42)
+s_set = sketch.Set(capacity=100, seed=0)
+We can retrieve the number of selected hash functions:
+s_set.n_hash
+7
+And the size of the binary array used by the Bloom filter: +
s_set.n_bits
+959
+We can add new items and check for membership using the same calls used by Python's +standard sets: +
for _ in range(1000):
+ s_set.add(rng.randint(0, 200))
+
+1 in s_set
+True
+False positives might happen if the capacity is not large enough: +
-10 in s_set
+True
+Iterables can also be supplied to perform multiple updates with a single call to update:
+
s_set = s_set.update([1, 2, 3, 4, 5, 6, 7])
+We can also combine instances of sketch.Set using the intersection and union operations, as long as
+they share the same hash functions and capability. In other words, all they hyperparameters match.
+Let's create two instances that will monitor different portions of a stream of random numbers:
s1 = sketch.Set(seed=8)
+s2 = sketch.Set(seed=8)
+
+for _ in range(1000):
+ s1.add(rng.randint(0, 5000))
+
+for _ in range(1000):
+ s2.add(rng.randint(0, 5000))
+
+43 in s1
+True
+43 in s2
+False
+We can get the intersection between the two instances by using:
+s_intersection = s1 & s2
+43 in s_intersection
+False
+We can also obtain the set union:
+s_union = s1 | s2
+
+43 in s_union
+True
+The same effect of the non-inplace dunder methods can be achieved via explicit method calls:
+43 in s1.intersection(s2)
+False
+43 in s1.union(s2)
+True
+Set intersection.
+Return a new instance that results from the set intersection between the current Set object and other. Dunder operators can be used to replace the method call, i.e., a &= b and a & b for inplace and non-inplace intersections, respectively.
Parameters
++
Set union.
+Return a new instance that results from the set union between the current Set object and other. Dunder operators can be used to replace the method call, i.e., a |= b and a | b for inplace and non-inplace unions, respectively.
Parameters
++
This implementation uses an integer to represent the binary array. Bitwise operations are performed in the +integer to reflect the Bloom filter updates.
+Running absolute max.
+abs_max (float)
+The current absolute max.
+from river import stats
+
+X = [1, -4, 3, -2, 5, -6]
+abs_max = stats.AbsMax()
+for x in X:
+ print(abs_max.update(x).get())
+1
+4
+4
+4
+5
+6
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Measures the serial correlation.
+This method computes the Pearson correlation between the current value and the value seen n steps before.
lag
+Type → int
+The following examples are taken from the pandas documentation.
+from river import stats
+
+auto_corr = stats.AutoCorr(lag=1)
+for x in [0.25, 0.5, 0.2, -0.05]:
+ print(auto_corr.update(x).get())
+0
+0
+-1.0
+0.103552
+auto_corr = stats.AutoCorr(lag=2)
+for x in [0.25, 0.5, 0.2, -0.05]:
+ print(auto_corr.update(x).get())
+0
+0
+0
+-1.0
+auto_corr = stats.AutoCorr(lag=1)
+for x in [1, 0, 0, 0]:
+ print(auto_corr.update(x).get())
+0
+0
+0
+0
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Estimates a mean using outside information.
+prior
+Type → float
+prior_weight
+Type → float
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++
Covariance.
+ddof
+Default → 1
Delta Degrees of Freedom.
+from river import stats
+
+x = [-2.1, -1, 4.3]
+y = [ 3, 1.1, 0.12]
+
+cov = stats.Cov()
+
+for xi, yi in zip(x, y):
+ print(cov.update(xi, yi).get())
+0.0
+-1.044999
+-4.286
+This class has a revert method, and can thus be wrapped by utils.Rolling:
from river import utils
+
+x = [-2.1, -1, 4.3, 1, -2.1, -1, 4.3]
+y = [ 3, 1.1, .12, 1, 3, 1.1, .12]
+
+rcov = utils.Rolling(stats.Cov(), window_size=3)
+
+for xi, yi in zip(x, y):
+ print(rcov.update(xi, yi).get())
+0.0
+-1.045
+-4.286
+-1.382
+-4.589
+-1.415
+-4.286
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
+1.0 +
The outcomes of the incremental and parallel updates are consistent with numpy's +batch processing when \(\text{ddof} \le 1\).
+Schubert, E. and Gertz, M., 2018, July. Numerically stable parallel computation of +(co-) variance. In Proceedings of the 30th International Conference on Scientific and +Statistical Database Management (pp. 1-12). ↩
+Exponentially weighted mean.
+fading_factor
+Default → 0.5
The closer fading_factor is to 1 the more the statistic will adapt to recent values.
mean (float)
+The running exponentially weighted mean.
+from river import stats
+
+X = [1, 3, 5, 4, 6, 8, 7, 9, 11]
+ewm = stats.EWMean(fading_factor=0.5)
+for x in X:
+ print(ewm.update(x).get())
+1.0
+2.0
+3.5
+3.75
+4.875
+6.4375
+6.71875
+7.859375
+9.4296875
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + + +
Exponentially weighted variance.
+To calculate the variance we use the fact that Var(X) = Mean(x^2) - Mean(x)^2 and internally we use the exponentially weighted mean of x/x^2 to calculate this.
+fading_factor
+Default → 0.5
The closer fading_factor is to 1 the more the statistic will adapt to recent values.
variance (float)
+The running exponentially weighted variance.
+from river import stats
+
+X = [1, 3, 5, 4, 6, 8, 7, 9, 11]
+ewv = stats.EWVar(fading_factor=0.5)
+for x in X:
+ print(ewv.update(x).get())
+0.0
+1.0
+2.75
+1.4375
+1.984375
+3.43359375
+1.7958984375
+2.198974609375
+3.56536865234375
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + + +
Running entropy.
+fading_factor
+Default → 1
Fading factor.
+eps
+Default → 1e-08
Small value that will be added to the denominator to avoid division by zero.
+entropy (float)
+The running entropy.
+n (int)
+The current number of observations.
+counter (collections.Counter)
+Count the number of times the values have occurred
+import math
+import random
+import numpy as np
+from scipy.stats import entropy
+from river import stats
+
+def entropy_list(labels, base=None):
+ value,counts = np.unique(labels, return_counts=True)
+ return entropy(counts, base=base)
+
+SEED = 42 * 1337
+random.seed(SEED)
+
+entro = stats.Entropy(fading_factor=1)
+
+list_animal = []
+for animal, num_val in zip(['cat', 'dog', 'bird'],[301, 401, 601]):
+ list_animal += [animal for i in range(num_val)]
+random.shuffle(list_animal)
+
+for animal in list_animal:
+ _ = entro.update(animal)
+
+print(f'{entro.get():.6f}')
+1.058093
+print(f'{entropy_list(list_animal):.6f}')
+1.058093
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + + +
Computes the interquartile range.
+q_inf
+Default → 0.25
Desired inferior quantile, must be between 0 and 1. Defaults to 0.25.
q_sup
+Default → 0.75
Desired superior quantile, must be between 0 and 1. Defaults to 0.75.
from river import stats
+
+iqr = stats.IQR(q_inf=0.25, q_sup=0.75)
+
+for i in range(0, 1001):
+ iqr = iqr.update(i)
+ if i % 100 == 0:
+ print(iqr.get())
+0.0
+50.0
+100.0
+150.0
+200.0
+250.0
+300.0
+350.0
+400.0
+450.0
+500.0
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running kurtosis using Welford's algorithm.
+bias
+Default → False
If False, then the calculations are corrected for statistical bias.
from river import stats
+import scipy.stats
+import numpy as np
+
+np.random.seed(42)
+X = np.random.normal(loc=0, scale=1, size=10)
+
+kurtosis = stats.Kurtosis(bias=False)
+for x in X:
+ print(kurtosis.update(x).get())
+-3.0
+-2.0
+-1.5
+1.4130027920707047
+0.15367976585756438
+0.46142633246812653
+-1.620647789230658
+-1.3540178492487054
+-1.2310268787102745
+-0.9490372374384453
+for i in range(2, len(X)+1):
+ print(scipy.stats.kurtosis(X[:i], bias=False))
+-2.0
+-1.4999999999999998
+1.4130027920707082
+0.15367976585756082
+0.46142633246812403
+-1.620647789230658
+-1.3540178492487063
+-1.2310268787102738
+-0.9490372374384459
+kurtosis = stats.Kurtosis(bias=True)
+for x in X:
+ print(kurtosis.update(x).get())
+-3.0
+-2.0
+-1.5
+-1.011599627723906
+-0.9615800585356089
+-0.6989395431537853
+-1.4252699121794408
+-1.311437071070812
+-1.246289111322894
+-1.082283689864171
+for i in range(2, len(X)+1):
+ print(scipy.stats.kurtosis(X[:i], bias=True))
+-2.0
+-1.4999999999999998
+-1.0115996277239057
+-0.9615800585356098
+-0.6989395431537861
+-1.425269912179441
+-1.3114370710708125
+-1.2462891113228936
+-1.0822836898641714
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + + +
A link joins two univariate statistics as a sequence.
+This can be used to pipe the output of one statistic to the input of another. This can be used, for instance, to calculate the mean of the variance of a variable. It can also be used to compute shifted statistics by piping statistics with an instance of stats.Shift.
Note that a link is not meant to be instantiated via this class definition. Instead, users can link statistics together via the | operator.
left
+Type → stats.base.Univariate
+right
+Type → stats.base.Univariate
+The output from left's get method is passed to right's update method if left's get method doesn't produce None.
from river import stats
+stat = stats.Shift(1) | stats.Mean()
+No values have been seen, therefore get defaults to the initial value of stats.Mean,
+which is 0.
stat.get()
+0.
+Let us now call update.
stat = stat.update(1)
+The output from get will still be 0. The reason is that stats.Shift has not enough
+values, and therefore outputs it's default value, which is None. The stats.Mean
+instance is therefore not updated.
stat.get()
+0.0
+On the next call to update, the stats.Shift instance has seen enough values, and
+therefore the mean can be updated. The mean is therefore equal to 1, because that's the
+only value from the past.
stat = stat.update(3)
+stat.get()
+1.0
+On the subsequent call to update, the mean will be updated with the value 3.
+stat = stat.update(4)
+stat.get()
+2.0
+Note that composing statistics returns a new statistic with it's own name.
+stat.name
+'mean_of_shift_1'
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Median Absolute Deviation (MAD).
+The median absolute deviation is the median of the absolute differences between each data point and the data's overall median. In an online setting, the median of the data is unknown beforehand. Therefore, both the median of the data and the median of the differences of the data with respect to the latter are updated online. To be precise, the median of the data is updated before the median of the differences. As a consequence, this online version of the MAD does not coincide exactly with its batch counterpart.
+median (stats.Median)
+The median of the data.
+from river import stats
+
+X = [4, 2, 5, 3, 0, 4]
+
+mad = stats.MAD()
+for x in X:
+ print(mad.update(x).get())
+0.0
+2.0
+1.0
+1.0
+1.0
+1.0
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++
Running max.
+max (float)
+The current max.
+from river import stats
+
+X = [1, -4, 3, -2, 5, -6]
+_max = stats.Max()
+for x in X:
+ print(_max.update(x).get())
+1
+1
+3
+3
+5
+5
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running mean.
+n (float)
+The current sum of weights. If each passed weight was 1, then this is equal to the number of seen observations.
+from river import stats
+
+X = [-5, -3, -1, 1, 3, 5]
+mean = stats.Mean()
+for x in X:
+ print(mean.update(x).get())
+-5.0
+-4.0
+-3.0
+-2.0
+-1.0
+0.0
+You can calculate a rolling average by wrapping a utils.Rolling around:
from river import utils
+
+X = [1, 2, 3, 4, 5, 6]
+rmean = utils.Rolling(stats.Mean(), window_size=2)
+
+for x in X:
+ print(rmean.update(x).get())
+1.0
+1.5
+2.5
+3.5
+4.5
+5.5
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
+1.0 +
West, D. H. D. (1979). Updating mean and variance estimates: An improved method. Communications of the ACM, 22(9), 532-535. ↩
+Finch, T., 2009. Incremental calculation of weighted mean and variance. University of Cambridge, 4(11-5), pp.41-42. ↩
+Chan, T.F., Golub, G.H. and LeVeque, R.J., 1983. Algorithms for computing the sample variance: Analysis and recommendations. The American Statistician, 37(3), pp.242-247. ↩
+Running mode.
+The mode is simply the most common value. An approximate mode can be computed by setting the number of first unique values to count.
+k
+Default → 25
Only the first k unique values will be included. If k equals -1, the exact mode is computed.
from river import stats
+
+X = ['sunny', 'cloudy', 'cloudy', 'rainy', 'rainy', 'rainy']
+mode = stats.Mode(k=2)
+for x in X:
+ print(mode.update(x).get())
+sunny
+sunny
+cloudy
+cloudy
+cloudy
+cloudy
+mode = stats.Mode(k=-1)
+for x in X:
+ print(mode.update(x).get())
+sunny
+sunny
+cloudy
+cloudy
+cloudy
+rainy
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Approximate number of unique values counter.
+This is basically an implementation of the HyperLogLog algorithm. Adapted from hypy. The code is a bit too terse but it will do for now.
error_rate
+Default → 0.01
Desired error rate. Memory usage is inversely proportional to this value.
+seed
+Type → int | None
+Default → None
Set the seed to produce identical results.
+n_bits (int)
+n_buckets (int)
+buckets (list)
+import string
+from river import stats
+
+alphabet = string.ascii_lowercase
+n_unique = stats.NUnique(error_rate=0.2, seed=42)
+
+n_unique.update('a').get()
+1
+n_unique.update('b').get()
+2
+for letter in alphabet:
+ n_unique = n_unique.update(letter)
+n_unique.get()
+31
+Lowering the error_rate parameter will increase the precision.
n_unique = stats.NUnique(error_rate=0.01, seed=42)
+for letter in alphabet:
+ n_unique = n_unique.update(letter)
+n_unique.get()
+26
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + + +
Running peak to peak (max - min).
+from river import stats
+
+X = [1, -4, 3, -2, 2, 4]
+ptp = stats.PeakToPeak()
+for x in X:
+ print(ptp.update(x).get())
+0.
+5.
+7.
+7.
+7.
+8.
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Online Pearson correlation.
+ddof
+Default → 1
Delta Degrees of Freedom.
+var_x (stats.Var)
+Running variance of x.
var_y (stats.Var)
+Running variance of y.
cov_xy (stats.Cov)
+Running covariance of x and y.
from river import stats
+
+x = [0, 0, 0, 1, 1, 1, 1]
+y = [0, 1, 2, 3, 4, 5, 6]
+
+pearson = stats.PearsonCorr()
+
+for xi, yi in zip(x, y):
+ print(pearson.update(xi, yi).get())
+0
+0
+0
+0.774596
+0.866025
+0.878310
+0.866025
+You can also do this in a rolling fashion:
+from river import utils
+
+x = [0, 0, 0, 1, 1, 1, 1]
+y = [0, 1, 2, 3, 4, 5, 6]
+
+pearson = utils.Rolling(stats.PearsonCorr(), window_size=4)
+
+for xi, yi in zip(x, y):
+ print(pearson.update(xi, yi).get())
+0
+0
+0
+0.7745966692414834
+0.8944271909999159
+0.7745966692414832
+-4.712160915387242e-09
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running quantile.
+Uses the P² algorithm, which is also known as the "Piecewise-Parabolic quantile estimator". The code is inspired by LiveStat's implementation 2.
+q
+Type → float
+Default → 0.5
Determines which quantile to compute, must be comprised between 0 and 1.
+from river import stats
+import numpy as np
+
+np.random.seed(42 * 1337)
+mu, sigma = 0, 1
+s = np.random.normal(mu, sigma, 500)
+
+median = stats.Quantile(0.5)
+for x in s:
+ _ = median.update(x)
+print(f'The estimated value of the 50th (median) quantile is {median.get():.4f}')
+The estimated value of the 50th (median) quantile is -0.0275
+print(f'The real value of the 50th (median) quantile is {np.median(s):.4f}')
+The real value of the 50th (median) quantile is -0.0135
+percentile_17 = stats.Quantile(0.17)
+for x in s:
+ _ = percentile_17.update(x)
+print(f'The estimated value of the 17th quantile is {percentile_17.get():.4f}')
+The estimated value of the 17th quantile is -0.8652
+print(f'The real value of the 17th quantile is {np.percentile(s,17):.4f}')
+The real value of the 17th quantile is -0.9072
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + + +
Running absolute max over a window.
+window_size
+Type → int
+Size of the rolling window.
+name
+window_size
+from river import stats
+
+X = [1, -4, 3, -2, 2, 1]
+rolling_absmax = stats.RollingAbsMax(window_size=2)
+for x in X:
+ print(rolling_absmax.update(x).get())
+1
+4
+4
+3
+2
+2
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Computes the rolling interquartile range.
+window_size
+Type → int
+Size of the window.
+q_inf
+Default → 0.25
Desired inferior quantile, must be between 0 and 1. Defaults to 0.25.
q_sup
+Default → 0.75
Desired superior quantile, must be between 0 and 1. Defaults to 0.75.
name
+window_size
+from river import stats
+rolling_iqr = stats.RollingIQR(
+ q_inf=0.25,
+ q_sup=0.75,
+ window_size=101
+)
+
+for i in range(0, 1001):
+ rolling_iqr = rolling_iqr.update(i)
+ if i % 100 == 0:
+ print(rolling_iqr.get())
+0.0
+50.0
+50.0
+50.0
+50.0
+50.0
+50.0
+50.0
+50.0
+50.0
+50.0
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running max over a window.
+window_size
+Type → int
+Size of the rolling window.
+name
+window_size
+from river import stats
+
+X = [1, -4, 3, -2, 2, 1]
+rolling_max = stats.RollingMax(window_size=2)
+for x in X:
+ print(rolling_max.update(x).get())
+1
+1
+3
+3
+2
+2
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running min over a window.
+window_size
+Type → int
+Size of the rolling window.
+name
+window_size
+from river import stats
+
+X = [1, -4, 3, -2, 2, 1]
+rolling_min = stats.RollingMin(2)
+for x in X:
+ print(rolling_min.update(x).get())
+1
+-4
+-4
+-2
+-2
+1
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running mode over a window.
+The mode is the most common value.
+window_size
+Type → int
+Size of the rolling window.
+counts (collections.defaultdict)
+Value counts.
+from river import stats
+
+X = ['sunny', 'sunny', 'sunny', 'rainy', 'rainy', 'rainy', 'rainy']
+rolling_mode = stats.RollingMode(window_size=2)
+for x in X:
+ print(rolling_mode.update(x).get())
+sunny
+sunny
+sunny
+sunny
+rainy
+rainy
+rainy
+rolling_mode = stats.RollingMode(window_size=5)
+for x in X:
+ print(rolling_mode.update(x).get())
+sunny
+sunny
+sunny
+sunny
+sunny
+rainy
+rainy
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running peak to peak (max - min) over a window.
+window_size
+Type → int
+Size of the rolling window.
+max (stats.RollingMax)
+The running rolling max.
+min (stats.RollingMin)
+The running rolling min.
+from river import stats
+
+X = [1, -4, 3, -2, 2, 1]
+ptp = stats.RollingPeakToPeak(window_size=2)
+for x in X:
+ print(ptp.update(x).get())
+0
+5
+7
+5
+4
+1
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running quantile over a window.
+q
+Type → float
+Determines which quantile to compute, must be comprised between 0 and 1.
+window_size
+Type → int
+Size of the window.
+name
+window_size
+from river import stats
+
+rolling_quantile = stats.RollingQuantile(
+ q=.5,
+ window_size=101,
+)
+
+for i in range(1001):
+ rolling_quantile = rolling_quantile.update(i)
+ if i % 100 == 0:
+ print(rolling_quantile.get())
+0.0
+50.0
+150.0
+250.0
+350.0
+450.0
+550.0
+650.0
+750.0
+850.0
+950.0
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++
Running standard error of the mean using Welford's algorithm.
+ddof
+Default → 1
Delta Degrees of Freedom. The divisor used in calculations is n - ddof, where n is the number of seen elements.
n (int)
+Number of observations.
+from river import stats
+
+X = [3, 5, 4, 7, 10, 12]
+
+sem = stats.SEM()
+for x in X:
+ print(sem.update(x).get())
+0.0
+1.0
+0.577350
+0.853912
+1.240967
+1.447219
+from river import utils
+
+X = [1, 4, 2, -4, -8, 0]
+
+rolling_sem = utils.Rolling(stats.SEM(ddof=1), window_size=3)
+for x in X:
+ print(rolling_sem.update(x).get())
+0.0
+1.5
+0.881917
+2.403700
+2.905932
+2.309401
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
+1.0 +
Shifts a data stream by returning past values.
+This can be used to compute statistics over past data. For instance, if you're computing daily averages, then shifting by 7 will be equivalent to computing averages from a week ago.
+Shifting values is useful when you're calculating an average over a target value. Indeed, in this case it's important to shift the values in order not to introduce leakage. The recommended way to do this is to feature_extraction.TargetAgg, which already takes care of shifting the target values once.
amount
+Default → 1
Shift amount. The get method will return the t - amount value, where t is the current moment.
fill_value
+Default → None
This value will be returned by the get method if not enough values have been observed.
It is rare to have to use Shift by itself. A more common usage is to compose it with
+other statistics. This can be done via the | operator.
from river import stats
+
+stat = stats.Shift(1) | stats.Mean()
+
+for i in range(5):
+ stat = stat.update(i)
+ print(stat.get())
+0.0
+0.0
+0.5
+1.0
+1.5
+A common usecase for using Shift is when computing statistics on shifted data. For
+instance, say you have a dataset which records the amount of sales for a set of shops. You
+might then have a shop field and a sales field. Let's say you want to look at the
+average amount of sales per shop. You can do this by using a feature_extraction.Agg. When
+you call transform_one, you're expecting it to return the average amount of sales,
+without including today's sales. You can do this by prepending an instance of
+stats.Mean with an instance of stats.Shift.
from river import feature_extraction
+
+agg = feature_extraction.Agg(
+ on='sales',
+ how=stats.Shift(1) | stats.Mean(),
+ by='shop'
+)
+Let's define a little example dataset.
+X = iter([
+ {'shop': 'Ikea', 'sales': 10},
+ {'shop': 'Ikea', 'sales': 15},
+ {'shop': 'Ikea', 'sales': 20}
+])
+Now let's call the learn_one method to update our feature extractor.
x = next(X)
+agg = agg.learn_one(x)
+At this point, the average defaults to the initial value of stats.Mean, which is 0.
agg.transform_one(x)
+{'sales_mean_of_shift_1_by_shop': 0.0}
+We can now update our feature extractor with the next data point and check the output.
+agg = agg.learn_one(next(X))
+agg.transform_one(x)
+{'sales_mean_of_shift_1_by_shop': 10.0}
+agg = agg.learn_one(next(X))
+agg.transform_one(x)
+{'sales_mean_of_shift_1_by_shop': 12.5}
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running skew using Welford's algorithm.
+bias
+Default → False
If False, then the calculations are corrected for statistical bias.
from river import stats
+import numpy as np
+
+np.random.seed(42)
+X = np.random.normal(loc=0, scale=1, size=10)
+
+skew = stats.Skew(bias=False)
+for x in X:
+ print(skew.update(x).get())
+0.0
+0.0
+-1.4802398132849872
+0.5127437186677888
+0.7803466510704751
+1.056115628922055
+0.5057840774320389
+0.3478402420400934
+0.4536710660918704
+0.4123070197493227
+skew = stats.Skew(bias=True)
+for x in X:
+ print(skew.update(x).get())
+0.0
+0.0
+-0.6043053732501439
+0.2960327239981376
+0.5234724473423674
+0.7712778043924866
+0.39022088752624845
+0.278892645224261
+0.37425953513864063
+0.3476878073823696
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + + +
Running sum.
+sum (float)
+The running sum.
+from river import stats
+
+X = [-5, -3, -1, 1, 3, 5]
+mean = stats.Sum()
+for x in X:
+ print(mean.update(x).get())
+-5.0
+-8.0
+-9.0
+-8.0
+-5.0
+0.0
+from river import utils
+
+X = [1, -4, 3, -2, 2, 1]
+rolling_sum = utils.Rolling(stats.Sum(), window_size=2)
+for x in X:
+ print(rolling_sum.update(x).get())
+1.0
+-3.0
+-1.0
+1.0
+0.0
+3.0
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
++ + + + + + + + +
Running variance using Welford's algorithm.
+ddof
+Default → 1
Delta Degrees of Freedom. The divisor used in calculations is n - ddof, where n represents the number of seen elements.
mean
+It is necessary to calculate the mean of the data in order to calculate its variance.
+from river import stats
+
+X = [3, 5, 4, 7, 10, 12]
+
+var = stats.Var()
+for x in X:
+ print(var.update(x).get())
+0.0
+2.0
+1.0
+2.916666
+7.7
+12.56666
+You can measure a rolling variance by using a utils.Rolling wrapper:
from river import utils
+
+X = [1, 4, 2, -4, -8, 0]
+rvar = utils.Rolling(stats.Var(ddof=1), window_size=3)
+for x in X:
+ print(rvar.update(x).get())
+0.0
+4.5
+2.333333
+17.333333
+25.333333
+16.0
+Return the current value of the statistic.
++
Update and return the called instance.
+Parameters
+1.0 +
The outcomes of the incremental and parallel updates are consistent with numpy's +batch processing when \(\text{ddof} \le 1\).
+Chan, T.F., Golub, G.H. and LeVeque, R.J., 1983. Algorithms for computing the sample variance: Analysis and recommendations. The American Statistician, 37(3), pp.242-247. ↩
+Schubert, E. and Gertz, M., 2018, July. Numerically stable parallel computation of +(co-)variance. In Proceedings of the 30th International Conference on Scientific and +Statistical Database Management (pp. 1-12). ↩
+Utility for caching iterables.
+This can be used to save a stream of data to the disk in order to iterate over it faster the following time. This can save time depending on the nature of stream. The more processing happens in a stream, the more time will be saved. Even in the case where no processing is done apart from reading the data, the cache will save some time because it is using the pickle binary protocol. It can thus improve the speed in common cases such as reading from a CSV file.
+directory
+Default → None
The path where to store the pickled data streams. If not provided, then it will be automatically inferred whenever possible, if not an exception will be raised.
+keys (set)
+The set of keys that are being cached.
+import time
+from river import datasets
+from river import stream
+
+dataset = datasets.Phishing()
+cache = stream.Cache()
+The cache can be used by wrapping it around an iterable. Because this is the first time +are iterating over the data, nothing is cached.
+tic = time.time()
+for x, y in cache(dataset, key='phishing'):
+ pass
+toc = time.time()
+print(toc - tic) # doctest: +SKIP
+0.012813
+If we do the same thing again, we can see the loop is now faster.
+tic = time.time()
+for x, y in cache(dataset, key='phishing'):
+ pass
+toc = time.time()
+print(toc - tic) # doctest: +SKIP
+0.001927
+We can see an overview of the cache. The first line indicates the location of the +cache.
+cache # doctest: +SKIP
+/tmp
+phishing - 125.2KiB
+Finally, we can clear the stream from the cache.
+cache.clear('phishing')
+cache # doctest: +SKIP
+/tmp
+There is also a clear_all method to remove all the items in the cache.
cache.clear_all()
+Call self as a function.
+Parameters
+None +
Delete the cached stream associated with the given key.
+Parameters
++
Delete all the cached streams.
++ + + + + + + + +
Twitch chat stream client.
+This client gives access to a live stream of chat messages in Twitch channels using IRC protocol. You need to have a Twitch account and receive an OAuth token from https://twitchapps.com/tmi/.
+nickname
+Type → str
+The nickname of your account.
+token
+Type → str
+OAuth token which has been generated.
+channels
+Type → list[str]
+A list of channel names like ["asmongold", "shroud"] you want to collect messages from.
buffer_size
+Type → int
+Default → 2048
Size of buffer in bytes used for receiving responses from Twitch with IRC (default 2 kB).
+timeout
+Type → int
+Default → 60
A timeout value in seconds for waiting response from Twitch (default 60s). It can be useful if all requested channels are offline or chat is not active enough.
+The live stream is instantiated by passing your Twitch account nickname, OAuth token and list of channels. Other parameters are optional.
+from river import stream
+
+twitch_chat = stream.TwitchChatStream(
+ nickname="twitch_user1",
+ token="oauth:okrip6j6fjio8n5xpy2oum1lph4fbve",
+ channels=["asmongold", "shroud"]
+)
+The stream can be iterated over like this:
+for item in twitch_chat:
+ print(item)
+Here's a single stream item example: +
{
+ 'dt': datetime.datetime(2022, 9, 14, 10, 33, 37, 989560),
+ 'channel': 'asmongold',
+ 'username': 'moojiejaa',
+ 'msg': 'damn this chat mod are wild'
+}
+Twitter API v2 live stream client.
+This client gives access to a live stream of Tweets. That is, Tweets that have just been published. This is different to stream.TwitterRecentStream, which also covers Tweets that have been published over recent days, and not necessarily in real-time.
A list of filtering rules has to be provided. For instance, this allows focusing on a subset of topics and/or users.
+Note
+Using this requires having the requests package installed.
rules
+See the documentation[^2] for a comprehensive overview of filtering rules.
+bearer_token
+A bearer token that is available in each account's developer portal.
+The live stream is instantiated by passing a list of filtering rules, as well as a bearer + token. For instance, we can listen to all the breaking news Tweets from the BBC and CNN.
+from river import stream
+
+tweets = stream.TwitterLiveStream(
+ rules=["from:BBCBreaking", "from:cnnbrk"],
+ bearer_token="<insert_bearer_token>"
+)
+The stream can then be iterated over, possibly in an infinite loop. This will listen to the
+live feed of Tweets and produce a Tweet right after it's been published.
+
+```py
+import logging
+
+while True:
+ try:
+ for tweet in tweets:
+ print(tweet)
+ except requests.exceptions.RequestException as e:
+ logging.warning(str(e))
+ time.sleep(10)
+```
+
+Here's a Tweet example:
+
+```py
+{
+ 'data': {
+ 'author_id': '428333',
+ 'created_at': '2022-08-26T12:59:48.000Z',
+ 'id': '1563149212774445058',
+ 'text': "Ukraine's Zaporizhzhia nuclear power plant, which is currently held by
+Russian forces, has been reconnected to Ukraine's electricity grid, according to the +country's nuclear operator https://t.co/xfylkBs4JR" + }, + 'includes': { + 'users': [ + { + 'created_at': '2007-01-02T01:48:14.000Z', + 'id': '428333', + 'name': 'CNN Breaking News', + 'username': 'cnnbrk' + } + ] + }, + 'matching_rules': [{'id': '1563148866333151233', 'tag': 'from:cnnbrk'}] + } + ``` + [^1]: Filtered stream introduction + [^2]: Building rules for filtered stream + [^3]: Stream Tweets in real-time
+ + + + + + + + +Iterates over rows from an ARFF file.
+filepath_or_buffer
+Either a string indicating the location of a file, or a buffer object that has a read method.
target
+Type → str | list[str] | None
+Default → None
Name(s) of the target field. If None, then the target field is ignored. If a list of names is passed, then a dictionary is returned instead of a single value.
compression
+Default → infer
For on-the-fly decompression of on-disk data. If this is set to 'infer' and filepath_or_buffer is a path, then the decompression method is inferred for the following extensions: '.gz', '.zip'.
sparse
+Default → False
Whether the data is sparse or not.
+cars = '''
+@relation CarData
+@attribute make {Toyota, Honda, Ford, Chevrolet}
+@attribute model string
+@attribute year numeric
+@attribute price numeric
+@attribute mpg numeric
+@data
+Toyota, Corolla, 2018, 15000, 30.5
+Honda, Civic, 2019, 16000, 32.2
+Ford, Mustang, 2020, 25000, 25.0
+Chevrolet, Malibu, 2017, 18000, 28.9
+Toyota, Camry, 2019, 22000, 29.8
+'''
+with open('cars.arff', mode='w') as f:
+ _ = f.write(cars)
+
+from river import stream
+
+for x, y in stream.iter_arff('cars.arff', target='price'):
+ print(x, y)
+{'make': 'Toyota', 'model': ' Corolla', 'year': 2018.0, 'mpg': 30.5} 15000.0
+{'make': 'Honda', 'model': ' Civic', 'year': 2019.0, 'mpg': 32.2} 16000.0
+{'make': 'Ford', 'model': ' Mustang', 'year': 2020.0, 'mpg': 25.0} 25000.0
+{'make': 'Chevrolet', 'model': ' Malibu', 'year': 2017.0, 'mpg': 28.9} 18000.0
+{'make': 'Toyota', 'model': ' Camry', 'year': 2019.0, 'mpg': 29.8} 22000.0
+Finally, let's delete the example file.
+import os; os.remove('cars.arff')
+ARFF files support sparse data. Let's create a sparse ARFF file.
+sparse = '''
+% traindata
+@RELATION "traindata: -C 6"
+@ATTRIBUTE y0 {0, 1}
+@ATTRIBUTE y1 {0, 1}
+@ATTRIBUTE y2 {0, 1}
+@ATTRIBUTE y3 {0, 1}
+@ATTRIBUTE y4 {0, 1}
+@ATTRIBUTE y5 {0, 1}
+@ATTRIBUTE X0 NUMERIC
+@ATTRIBUTE X1 NUMERIC
+@ATTRIBUTE X2 NUMERIC
+@DATA
+{ 3 1,6 0.863382,8 0.820094 }
+{ 2 1,6 0.659761 }
+{ 0 1,3 1,6 0.437881,8 0.818882 }
+{ 2 1,6 0.676477,7 0.724635,8 0.755123 }
+'''
+
+with open('sparse.arff', mode='w') as f:
+ _ = f.write(sparse)
+In addition, we'll specify that there are several target fields.
+arff_stream = stream.iter_arff(
+ 'sparse.arff',
+ target=['y0', 'y1', 'y2', 'y3', 'y4', 'y5'],
+ sparse=True
+)
+
+for x, y in arff_stream:
+ print(x)
+ print(y)
+{'X0': '0.863382', 'X2': '0.820094'}
+{'y0': 0, 'y1': 0, 'y2': 0, 'y3': '1', 'y4': 0, 'y5': 0}
+{'X0': '0.659761'}
+{'y0': 0, 'y1': 0, 'y2': '1', 'y3': 0, 'y4': 0, 'y5': 0}
+{'X0': '0.437881', 'X2': '0.818882'}
+{'y0': '1', 'y1': 0, 'y2': 0, 'y3': '1', 'y4': 0, 'y5': 0}
+{'X0': '0.676477', 'X1': '0.724635', 'X2': '0.755123'}
+{'y0': 0, 'y1': 0, 'y2': '1', 'y3': 0, 'y4': 0, 'y5': 0}
+This function can also deal with missing features in non-sparse data. These are indicated with +a question mark.
+data = '''
+@relation giveMeLoan-weka.filters.unsupervised.attribute.Remove-R1
+@attribute RevolvingUtilizationOfUnsecuredLines numeric
+@attribute age numeric
+@attribute NumberOfTime30-59DaysPastDueNotWorse numeric
+@attribute DebtRatio numeric
+@attribute MonthlyIncome numeric
+@attribute NumberOfOpenCreditLinesAndLoans numeric
+@attribute NumberOfTimes90DaysLate numeric
+@attribute NumberRealEstateLoansOrLines numeric
+@attribute NumberOfTime60-89DaysPastDueNotWorse numeric
+@attribute NumberOfDependents numeric
+@attribute isFraud {0,1}
+@data
+0.213179,74,0,0.375607,3500,3,0,1,0,1,0
+0.305682,57,0,5710,?,8,0,3,0,0,0
+0.754464,39,0,0.20994,3500,8,0,0,0,0,0
+0.116951,27,0,46,?,2,0,0,0,0,0
+0.189169,57,0,0.606291,23684,9,0,4,0,2,0
+'''
+
+with open('data.arff', mode='w') as f:
+ _ = f.write(data)
+
+for x, y in stream.iter_arff('data.arff', target='isFraud'):
+ print(len(x))
+10
+9
+10
+9
+10
+Iterates over the rows from an array of features and an array of targets.
+This method is intended to work with numpy arrays, but should also work with Python lists.
X
+Type → np.ndarray
+A 2D array of features. This can also be a 1D array of strings, which can be the case if you're working with text.
+y
+Type → np.ndarray | None
+Default → None
An optional array of targets.
+feature_names
+Type → list[base.typing.FeatureName] | None
+Default → None
An optional list of feature names. The features will be labeled with integers if no names are provided.
+target_names
+Type → list[base.typing.FeatureName] | None
+Default → None
An optional list of output names. The outputs will be labeled with integers if no names are provided. Only applies if there are multiple outputs, i.e. if y is a 2D array.
shuffle
+Type → bool
+Default → False
Indicates whether or not to shuffle the input arrays before iterating over them.
+seed
+Type → int | None
+Default → None
Random seed used for shuffling the data.
+from river import stream
+import numpy as np
+
+X = np.array([[1, 2, 3], [11, 12, 13]])
+Y = np.array([True, False])
+
+dataset = stream.iter_array(
+ X, Y,
+ feature_names=['x1', 'x2', 'x3']
+)
+for x, y in dataset:
+ print(x, y)
+{'x1': 1, 'x2': 2, 'x3': 3} True
+{'x1': 11, 'x2': 12, 'x3': 13} False
+This also works with a array of texts:
+X = ["foo", "bar"]
+dataset = stream.iter_array(
+ X, Y,
+ feature_names=['x1', 'x2', 'x3']
+)
+for x, y in dataset:
+ print(x, y)
+foo True
+bar False
+Iterates over rows from a CSV file.
+Reading CSV files can be quite slow. If, for whatever reason, you're going to loop through the same file multiple times, then we recommend that you to use the stream.Cache utility.
filepath_or_buffer
+Either a string indicating the location of a file, or a buffer object that has a read method.
target
+Type → str | list[str] | None
+Default → None
A single target column is assumed if a string is passed. A multiple output scenario is assumed if a list of strings is passed. A None value will be assigned to each y if this parameter is omitted.
converters
+Type → dict | None
+Default → None
All values in the CSV are interpreted as strings by default. You can use this parameter to cast values to the desired type. This should be a dict mapping feature names to callables used to parse their associated values. Note that a callable may be a type, such as float and int.
parse_dates
+Type → dict | None
+Default → None
A dict mapping feature names to a format passed to the datetime.datetime.strptime method.
drop
+Type → list[str] | None
+Default → None
Fields to ignore.
+drop_nones
+Default → False
Whether or not to drop fields where the value is a None.
fraction
+Default → 1.0
Sampling fraction.
+compression
+Default → infer
For on-the-fly decompression of on-disk data. If this is set to 'infer' and filepath_or_buffer is a path, then the decompression method is inferred for the following extensions: '.gz', '.zip'.
seed
+Type → int | None
+Default → None
If specified, the sampling will be deterministic.
+field_size_limit
+Type → int | None
+Default → None
If not None, this will be passed to the csv.field_size_limit function.
kwargs
+All other keyword arguments are passed to the underlying csv.DictReader.
Although this function is designed to handle different kinds of inputs, the most common +use case is to read a file on the disk. We'll first create a little CSV file to illustrate.
+tv_shows = '''name,year,rating
+Planet Earth II,2016,9.5
+Planet Earth,2006,9.4
+Band of Brothers,2001,9.4
+Breaking Bad,2008,9.4
+Chernobyl,2019,9.4
+'''
+with open('tv_shows.csv', mode='w') as f:
+ _ = f.write(tv_shows)
+We can now go through the rows one by one. We can use the converters parameter to cast
+the rating field value as a float. We can also convert the year to a datetime via
+the parse_dates parameter.
from river import stream
+
+params = {
+ 'converters': {'rating': float},
+ 'parse_dates': {'year': '%Y'}
+}
+for x, y in stream.iter_csv('tv_shows.csv', **params):
+ print(x, y)
+{'name': 'Planet Earth II', 'year': datetime.datetime(2016, 1, 1, 0, 0), 'rating': 9.5} None
+{'name': 'Planet Earth', 'year': datetime.datetime(2006, 1, 1, 0, 0), 'rating': 9.4} None
+{'name': 'Band of Brothers', 'year': datetime.datetime(2001, 1, 1, 0, 0), 'rating': 9.4} None
+{'name': 'Breaking Bad', 'year': datetime.datetime(2008, 1, 1, 0, 0), 'rating': 9.4} None
+{'name': 'Chernobyl', 'year': datetime.datetime(2019, 1, 1, 0, 0), 'rating': 9.4} None
+The value of y is always None because we haven't provided a value for the target
+parameter. Here is an example where a target is provided:
dataset = stream.iter_csv('tv_shows.csv', target='rating', **params)
+for x, y in dataset:
+ print(x, y)
+{'name': 'Planet Earth II', 'year': datetime.datetime(2016, 1, 1, 0, 0)} 9.5
+{'name': 'Planet Earth', 'year': datetime.datetime(2006, 1, 1, 0, 0)} 9.4
+{'name': 'Band of Brothers', 'year': datetime.datetime(2001, 1, 1, 0, 0)} 9.4
+{'name': 'Breaking Bad', 'year': datetime.datetime(2008, 1, 1, 0, 0)} 9.4
+{'name': 'Chernobyl', 'year': datetime.datetime(2019, 1, 1, 0, 0)} 9.4
+Finally, let's delete the example file.
+import os; os.remove('tv_shows.csv')
+Iterates over a dataset in LIBSVM format.
+The LIBSVM format is a popular way in the machine learning community to store sparse datasets. Only numerical feature values are supported. The feature names will be considered as strings.
+filepath_or_buffer
+Type → str
+Either a string indicating the location of a file, or a buffer object that has a read method.
target_type
+Default → <class 'float'>
The type of the target value.
+compression
+Default → infer
For on-the-fly decompression of on-disk data. If this is set to 'infer' and filepath_or_buffer is a path, then the decompression method is inferred for the following extensions: '.gz', '.zip'.
import io
+from river import stream
+
+data = io.StringIO('''+1 x:-134.26 y:0.2563
+1 x:-12 z:0.3
+-1 y:.25
+''')
+
+for x, y in stream.iter_libsvm(data, target_type=int):
+ print(y, x)
+1 {'x': -134.26, 'y': 0.2563}
+1 {'x': -12.0, 'z': 0.3}
+-1 {'y': 0.25}
+Iterates over the rows of a pandas.DataFrame.
X
+Type → pd.DataFrame
+A dataframe of features.
+y
+Type → pd.Series | pd.DataFrame | None
+Default → None
A series or a dataframe with one column per target.
+kwargs
+Extra keyword arguments are passed to the underlying call to stream.iter_array.
import pandas as pd
+from river import stream
+
+X = pd.DataFrame({
+ 'x1': [1, 2, 3, 4],
+ 'x2': ['blue', 'yellow', 'yellow', 'blue'],
+ 'y': [True, False, False, True]
+})
+y = X.pop('y')
+
+for xi, yi in stream.iter_pandas(X, y):
+ print(xi, yi)
+{'x1': 1, 'x2': 'blue'} True
+{'x1': 2, 'x2': 'yellow'} False
+{'x1': 3, 'x2': 'yellow'} False
+{'x1': 4, 'x2': 'blue'} True
+Iterates rows from one of the datasets provided by scikit-learn.
+This allows you to use any dataset from scikit-learn's datasets module. For instance, you can use the fetch_openml function to get access to all of the datasets from the OpenML website.
dataset
+Type → sklearn.utils.Bunch
+A scikit-learn dataset.
+kwargs
+Extra keyword arguments are passed to the underlying call to stream.iter_array.
import pprint
+from sklearn import datasets
+from river import stream
+
+dataset = datasets.load_diabetes()
+
+for xi, yi in stream.iter_sklearn_dataset(dataset):
+ pprint.pprint(xi)
+ print(yi)
+ break
+{'age': 0.038075906433423026,
+ 'bmi': 0.061696206518683294,
+ 'bp': 0.0218723855140367,
+ 's1': -0.04422349842444599,
+ 's2': -0.03482076283769895,
+ 's3': -0.04340084565202491,
+ 's4': -0.002592261998183278,
+ 's5': 0.019907486170462722,
+ 's6': -0.01764612515980379,
+ 'sex': 0.05068011873981862}
+151.0
+Iterates over the results from an SQL query.
+By default, SQLAlchemy prefetches results. Therefore, even though you can iterate over the resulting rows one by one, the results are in fact loaded in batch. You can modify this behavior by configuring the connection you pass to iter_sql. For instance, you can set the stream_results parameter to True, as explained in SQLAlchemy's documentation. Note, however, that this isn't available for all database engines.
query
+Type → str | sqlalchemy.TextClause | sqlalchemy.Select
+SQL query to be executed.
+conn
+Type → sqlalchemy.Connection
+An SQLAlchemy construct which has an execute method. In other words you can pass an engine, a connection, or a session.
target_name
+Type → str | None
+Default → None
The name of the target field. If this is None, then y will also be None.
As an example we'll create an in-memory database with SQLAlchemy.
+import datetime as dt
+import sqlalchemy
+
+engine = sqlalchemy.create_engine('sqlite://')
+
+metadata = sqlalchemy.MetaData()
+
+t_sales = sqlalchemy.Table('sales', metadata,
+ sqlalchemy.Column('shop', sqlalchemy.String, primary_key=True),
+ sqlalchemy.Column('date', sqlalchemy.Date, primary_key=True),
+ sqlalchemy.Column('amount', sqlalchemy.Integer)
+)
+
+metadata.create_all(engine)
+
+sales = [
+ {'shop': 'Hema', 'date': dt.date(2016, 8, 2), 'amount': 20},
+ {'shop': 'Ikea', 'date': dt.date(2016, 8, 2), 'amount': 18},
+ {'shop': 'Hema', 'date': dt.date(2016, 8, 3), 'amount': 22},
+ {'shop': 'Ikea', 'date': dt.date(2016, 8, 3), 'amount': 14},
+ {'shop': 'Hema', 'date': dt.date(2016, 8, 4), 'amount': 12},
+ {'shop': 'Ikea', 'date': dt.date(2016, 8, 4), 'amount': 16}
+]
+
+with engine.connect() as conn:
+ _ = conn.execute(t_sales.insert(), sales)
+ conn.commit()
+We can now query the database. We will set amount to be the target field.
from river import stream
+
+with engine.connect() as conn:
+ query = sqlalchemy.sql.select(t_sales)
+ dataset = stream.iter_sql(query, conn, target_name='amount')
+ for x, y in dataset:
+ print(x, y)
+{'shop': 'Hema', 'date': datetime.date(2016, 8, 2)} 20
+{'shop': 'Ikea', 'date': datetime.date(2016, 8, 2)} 18
+{'shop': 'Hema', 'date': datetime.date(2016, 8, 3)} 22
+{'shop': 'Ikea', 'date': datetime.date(2016, 8, 3)} 14
+{'shop': 'Hema', 'date': datetime.date(2016, 8, 4)} 12
+{'shop': 'Ikea', 'date': datetime.date(2016, 8, 4)} 16
+This also with raw SQL queries.
+with engine.connect() as conn:
+ query = "SELECT * FROM sales WHERE shop = 'Hema'"
+ dataset = stream.iter_sql(query, conn, target_name='amount')
+ for x, y in dataset:
+ print(x, y)
+{'shop': 'Hema', 'date': '2016-08-02'} 20
+{'shop': 'Hema', 'date': '2016-08-03'} 22
+{'shop': 'Hema', 'date': '2016-08-04'} 12
+Yields rows from a vaex.DataFrame.
X
+Type → vaex.dataframe.DataFrame
+A vaex DataFrame housing the training featuers.
+y
+Type → str | vaex.expression.Expression | None
+Default → None
The column or expression containing the target variable.
+features
+Type → list[str] | vaex.expression.Expression | None
+Default → None
A list of features used for training. If None, all columns in X will be used. Features specifying in y are ignored.
Shuffles a stream of data.
+This works by maintaining a buffer of elements. The first buffer_size elements are stored in memory. Once the buffer is full, a random element inside the buffer is yielded. Every time an element is yielded, the next element in the stream replaces it and the buffer is sampled again. Increasing buffer_size will improve the quality of the shuffling.
If you really want to stream over your dataset in a "good" random order, the best way is to split your dataset into smaller datasets and loop over them in a round-robin fashion. You may do this by using the roundrobin recipe from the itertools module.
stream
+Type → typing.Iterator
+The stream to shuffle.
+buffer_size
+Type → int
+The size of the buffer which contains the elements help in memory. Increasing this will increase randomness but will incur more memory usage.
+seed
+Type → int | None
+Default → None
Random seed used for sampling.
+from river import stream
+
+for i in stream.shuffle(range(15), buffer_size=5, seed=42):
+ print(i)
+0
+5
+2
+1
+8
+9
+6
+4
+11
+12
+10
+7
+14
+13
+3
+Simulate a time-ordered question and answer session.
+This method allows looping through a dataset in the order in which it arrived. Indeed, it usually is the case that labels arrive after features. Being able to go through a dataset in arrival order enables assessing a model's performance in a reliable manner. For instance, the evaluate.progressive_val_score is a high-level method that can be used to score a model on a dataset. Under the hood it uses this method to determine the correct arrival order.
dataset
+Type → base.typing.Dataset
+A stream of (features, target) tuples.
+moment
+Type → str | typing.Callable[[dict], dt.datetime] | None
+The attribute used for measuring time. If a callable is passed, then it is expected to take as input a dict of features. If None, then the observations are implicitly timestamped in the order in which they arrive. If a str is passed, then it will be used to obtain the time from the input features.
delay
+Type → str | int | dt.timedelta | typing.Callable | None
+The amount of time to wait before revealing the target associated with each observation to the model. This value is expected to be able to sum with the moment value. For instance, if moment is a datetime.date, then delay is expected to be a datetime.timedelta. If a callable is passed, then it is expected to take as input a dict of features and the target. If a str is passed, then it will be used to access the relevant field from the features. If None is passed, then no delay will be used, which leads to doing standard online validation. If a scalar is passed, such an int or a datetime.timedelta, then the delay is constant.
copy
+Type → bool
+Default → True
If True, then a separate copy of the features are yielded the second time around. This ensures that inadvertent modifications in downstream code don't have any effect.
The arrival delay isn't usually indicated in a dataset, but it might be able to be inferred +from the features. As an example, we'll simulate the departure and arrival time of taxi +trips. Let's first create a time table which records the departure time and the duration of +seconds of several taxi trips.
+import datetime as dt
+time_table = [
+ (dt.datetime(2020, 1, 1, 20, 0, 0), 900),
+ (dt.datetime(2020, 1, 1, 20, 10, 0), 1800),
+ (dt.datetime(2020, 1, 1, 20, 20, 0), 300),
+ (dt.datetime(2020, 1, 1, 20, 45, 0), 400),
+ (dt.datetime(2020, 1, 1, 20, 50, 0), 240),
+ (dt.datetime(2020, 1, 1, 20, 55, 0), 450)
+]
+We can now create a streaming dataset where the features are the departure dates and the +targets are the durations.
+dataset = (
+ ({'date': date}, duration)
+ for date, duration in time_table
+)
+Now, we can use simulate_qa to iterate over the events in the order in which they are
+meant to occur.
delay = lambda _, y: dt.timedelta(seconds=y)
+
+for i, x, y in simulate_qa(dataset, moment='date', delay=delay):
+ if y is None:
+ print(f'{x["date"]} - trip #{i} departs')
+ else:
+ arrival_date = x['date'] + dt.timedelta(seconds=y)
+ print(f'{arrival_date} - trip #{i} arrives after {y} seconds')
+2020-01-01 20:00:00 - trip #0 departs
+2020-01-01 20:10:00 - trip #1 departs
+2020-01-01 20:15:00 - trip #0 arrives after 900 seconds
+2020-01-01 20:20:00 - trip #2 departs
+2020-01-01 20:25:00 - trip #2 arrives after 300 seconds
+2020-01-01 20:40:00 - trip #1 arrives after 1800 seconds
+2020-01-01 20:45:00 - trip #3 departs
+2020-01-01 20:50:00 - trip #4 departs
+2020-01-01 20:51:40 - trip #3 arrives after 400 seconds
+2020-01-01 20:54:00 - trip #4 arrives after 240 seconds
+2020-01-01 20:55:00 - trip #5 departs
+2020-01-01 21:02:30 - trip #5 arrives after 450 seconds
+This function is extremely practical because it provides a reliable way to evaluate the
+performance of a model in a real scenario. Indeed, it allows to make predictions and
+perform model updates in exactly the same manner that would happen live. For instance, it
+is used in evaluate.progressive_val_score, which is a higher level function for
+evaluating models in an online manner.
Return the current performance along the horizon.
+Returns
+list[float]: The current performance.
++
Update the metric at each step along the horizon.
+Parameters
+Returns
+ForecastingMetric: self
++ + + + + + + + +
Holt-Winters forecaster.
+This is a standard implementation of the Holt-Winters forecasting method. Certain parametrisations result in special cases, such as simple exponential smoothing.
+Optimal parameters and initialisation values can be determined in a batch setting. However, in an online setting, it is necessary to wait and observe enough values. The first k = max(2, seasonality) values are indeed used to initialize the components.
Level initialization
+Trend initialization
+Trend initialization
+alpha
+Smoothing parameter for the level.
+beta
+Default → None
Smoothing parameter for the trend.
+gamma
+Default → None
Smoothing parameter for the seasonality.
+seasonality
+Default → 0
The number of periods in a season. For instance, this should be 4 for quarterly data, and 12 for yearly data.
+multiplicative
+Default → False
Whether or not to use a multiplicative formulation.
+from river import datasets
+from river import metrics
+from river import time_series
+
+dataset = datasets.AirlinePassengers()
+
+model = time_series.HoltWinters(
+ alpha=0.3,
+ beta=0.1,
+ gamma=0.6,
+ seasonality=12,
+ multiplicative=True
+)
+
+metric = metrics.MAE()
+
+time_series.evaluate(
+ dataset,
+ model,
+ metric,
+ horizon=12
+)
++1 MAE: 25.899087
++2 MAE: 26.26131
++3 MAE: 25.735903
++4 MAE: 25.625678
++5 MAE: 26.093842
++6 MAE: 26.90249
++7 MAE: 28.634398
++8 MAE: 29.284769
++9 MAE: 31.018351
++10 MAE: 32.252349
++11 MAE: 33.518946
++12 MAE: 33.975057
+Makes forecast at each step of the given horizon.
+Parameters
+None +
Updates the model.
+Parameters
+None + + + + + + + + + +
Same as HorizonMetric, but aggregates the result based on an provided function.
This allows, for instance, to measure the average performance of a forecasting model along the horizon.
+metric
+Type → metrics.base.RegressionMetric
+A regression metric.
+agg_func
+Type → typing.Callable[[list[float]], float]
+A function that takes as input a list of floats and outputs a single float. You may want to min, max, as well as statistics.mean and statistics.median.
This is used internally by the time_series.evaluate function when you pass an agg_func.
import statistics
+from river import datasets
+from river import metrics
+from river import time_series
+
+metric = time_series.evaluate(
+ dataset=datasets.AirlinePassengers(),
+ model=time_series.HoltWinters(alpha=0.1),
+ metric=metrics.MAE(),
+ agg_func=statistics.mean,
+ horizon=4
+)
+
+metric
+mean(MAE): 42.901748
+Return the current performance along the horizon.
+Returns
+list[float]: The current performance.
++
Update the metric at each step along the horizon.
+Parameters
+Returns
+ForecastingMetric: self
++ + + + + + + + +
Measures performance at each time step ahead.
+This allows to measure the performance of a model at each time step along the horizon. A copy of the provided regression metric is made for each time step. At each time step ahead, the metric is thus evaluated on each prediction for said time step, and not for the time steps before or after that.
+metric
+Type → metrics.base.RegressionMetric
+A regression metric.
+This is used internally by the time_series.evaluate function.
from river import datasets
+from river import metrics
+from river import time_series
+
+metric = time_series.evaluate(
+ dataset=datasets.AirlinePassengers(),
+ model=time_series.HoltWinters(alpha=0.1),
+ metric=metrics.MAE(),
+ horizon=4
+)
+
+metric
++1 MAE: 40.931286
++2 MAE: 42.667998
++3 MAE: 44.158092
++4 MAE: 43.849617
+Return the current performance along the horizon.
+Returns
+list[float]: The current performance.
++
Update the metric at each step along the horizon.
+Parameters
+Returns
+ForecastingMetric: self
++ + + + + + + + +
SNARIMAX model.
+SNARIMAX stands for (S)easonal (N)on-linear (A)uto(R)egressive (I)ntegrated (M)oving-(A)verage with e(X)ogenous inputs model.
+This model generalizes many established time series models in a single interface that can be trained online. It assumes that the provided training data is ordered in time and is uniformly spaced. It is made up of the following components:
+S (Seasonal)
+N (Non-linear): Any online regression model can be used, not necessarily a linear regression
+as is done in textbooks. - AR (Autoregressive): Lags of the target variable are used as features.
+I (Integrated): The model can be fitted on a differenced version of a time series. In this
+context, integration is the reverse of differencing. - MA (Moving average): Lags of the errors are used as features.
+X (Exogenous): Users can provide additional features. Care has to be taken to include
+features that will be available both at training and prediction time.
+Each of these components can be switched on and off by specifying the appropriate parameters. Classical time series models such as AR, MA, ARMA, and ARIMA can thus be seen as special parametrizations of the SNARIMAX model.
+This model is tailored for time series that are homoskedastic. In other words, it might not work well if the variance of the time series varies widely along time.
+p
+Type → int
+Order of the autoregressive part. This is the number of past target values that will be included as features.
+d
+Type → int
+Differencing order.
+q
+Type → int
+Order of the moving average part. This is the number of past error terms that will be included as features.
+m
+Type → int
+Default → 1
Season length used for extracting seasonal features. If you believe your data has a seasonal pattern, then set this accordingly. For instance, if the data seems to exhibit a yearly seasonality, and that your data is spaced by month, then you should set this to 12. Note that for this parameter to have any impact you should also set at least one of the p, d, and q parameters.
sp
+Type → int
+Default → 0
Seasonal order of the autoregressive part. This is the number of past target values that will be included as features.
+sd
+Type → int
+Default → 0
Seasonal differencing order.
+sq
+Type → int
+Default → 0
Seasonal order of the moving average part. This is the number of past error terms that will be included as features.
+regressor
+Type → base.Regressor | None
+Default → None
The online regression model to use. By default, a preprocessing.StandardScaler piped with a linear_model.LinearRegression will be used.
differencer (Differencer)
+y_trues (collections.deque)
+The p past target values.
errors (collections.deque)
+The q past error values.
import datetime as dt
+from river import datasets
+from river import time_series
+from river import utils
+
+period = 12
+model = time_series.SNARIMAX(
+ p=period,
+ d=1,
+ q=period,
+ m=period,
+ sd=1
+)
+
+for t, (x, y) in enumerate(datasets.AirlinePassengers()):
+ model = model.learn_one(y)
+
+horizon = 12
+future = [
+ {'month': dt.date(year=1961, month=m, day=1)}
+ for m in range(1, horizon + 1)
+]
+forecast = model.forecast(horizon=horizon)
+for x, y_pred in zip(future, forecast):
+ print(x['month'], f'{y_pred:.3f}')
+1961-01-01 494.542
+1961-02-01 450.825
+1961-03-01 484.972
+1961-04-01 576.401
+1961-05-01 559.489
+1961-06-01 612.251
+1961-07-01 722.410
+1961-08-01 674.604
+1961-09-01 575.716
+1961-10-01 562.808
+1961-11-01 477.049
+1961-12-01 515.191
+Classic ARIMA models learn solely on the time series values. You can also include features +built at each step.
+import calendar
+import math
+from river import compose
+from river import linear_model
+from river import optim
+from river import preprocessing
+
+def get_month_distances(x):
+ return {
+ calendar.month_name[month]: math.exp(-(x['month'].month - month) ** 2)
+ for month in range(1, 13)
+ }
+
+def get_ordinal_date(x):
+ return {'ordinal_date': x['month'].toordinal()}
+
+extract_features = compose.TransformerUnion(
+ get_ordinal_date,
+ get_month_distances
+)
+
+model = (
+ extract_features |
+ time_series.SNARIMAX(
+ p=1,
+ d=0,
+ q=0,
+ m=12,
+ sp=3,
+ sq=6,
+ regressor=(
+ preprocessing.StandardScaler() |
+ linear_model.LinearRegression(
+ intercept_init=110,
+ optimizer=optim.SGD(0.01),
+ intercept_lr=0.3
+ )
+ )
+ )
+)
+
+for x, y in datasets.AirlinePassengers():
+ model = model.learn_one(x, y)
+
+forecast = model.forecast(horizon=horizon)
+for x, y_pred in zip(future, forecast):
+ print(x['month'], f'{y_pred:.3f}')
+1961-01-01 444.821
+1961-02-01 432.612
+1961-03-01 457.739
+1961-04-01 465.544
+1961-05-01 476.575
+1961-06-01 516.255
+1961-07-01 565.405
+1961-08-01 572.470
+1961-09-01 512.645
+1961-10-01 475.919
+1961-11-01 438.033
+1961-12-01 456.892
+Makes forecast at each step of the given horizon.
+Parameters
+None +
Updates the model.
+Parameters
+None + + + + + + + + + +
Makes forecast at each step of the given horizon.
+Parameters
+None +
Updates the model.
+Parameters
+None + + + + + + + + +
Evaluates the performance of a forecaster on a time series dataset.
+To understand why this method is useful, it's important to understand the difference between nowcasting and forecasting. Nowcasting is about predicting a value at the next time step. This can be seen as a special case of regression, where the value to predict is the value at the next time step. In this case, the evaluate.progressive_val_score function may be used to evaluate a model via progressive validation.
Forecasting models can also be evaluated via progressive validation. This is the purpose of this function. At each time step t, the forecaster is asked to predict the values at t + 1, t + 2, ..., t + horizon. The performance at each time step is measured and returned.
dataset
+Type → base.typing.Dataset
+A sequential time series.
+model
+Type → time_series.base.Forecaster
+A forecaster.
+metric
+Type → metrics.base.RegressionMetric
+A regression metric.
+horizon
+Type → int
+agg_func
+Type → typing.Callable[[list[float]], float] | None
+Default → None
grace_period
+Type → int | None
+Default → None
Initial period during which the metric is not updated. This is to fairly evaluate models which need a warming up period to start producing meaningful forecasts. The value of this parameter is equal to the horizon by default.
+Evaluates the performance of a forecaster on a time series dataset and yields results.
+This does exactly the same as evaluate.progressive_val_score. The only difference is that this function returns an iterator, yielding results at every step. This can be useful if you want to have control over what you do with the results. For instance, you might want to plot the results.
dataset
+Type → base.typing.Dataset
+A sequential time series.
+model
+Type → time_series.base.Forecaster
+A forecaster.
+metric
+Type → metrics.base.RegressionMetric
+A regression metric.
+horizon
+Type → int
+agg_func
+Type → typing.Callable[[list[float]], float] | None
+Default → None
grace_period
+Type → int | None
+Default → None
Initial period during which the metric is not updated. This is to fairly evaluate models which need a warming up period to start producing meaningful forecasts. The value of this parameter is equal to the horizon by default.
+Extremely Fast Decision Tree classifier.
+Also referred to as Hoeffding AnyTime Tree (HATT) classifier.
+grace_period
+Type → int
+Default → 200
Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
The maximum depth a tree can reach. If None, the tree will grow indefinitely.
min_samples_reevaluate
+Type → int
+Default → 20
Number of instances a node should observe before reevaluating the best split.
+split_criterion
+Type → str
+Default → info_gain
Split criterion to use. - 'gini' - Gini - 'info_gain' - Information Gain - 'hellinger' - Helinger Distance
+delta
+Type → float
+Default → 1e-07
Significance level to calculate the Hoeffding bound. The significance level is given by 1 - delta. Values closer to zero imply longer split decision delays.
tau
+Type → float
+Default → 0.05
Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → nba
Prediction mechanism used at leafs. - 'mc' - Majority Class - 'nb' - Naive Bayes - 'nba' - Naive Bayes Adaptive
+nb_threshold
+Type → int
+Default → 0
Number of instances a leaf should observe before allowing Naive Bayes.
+nominal_attributes
+Type → list | None
+Default → None
List of Nominal attributes identifiers. If empty, then assume that all numeric attributes should be treated as continuous.
+splitter
+Type → Splitter | None
+Default → None
The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.GaussianSplitter is used if splitter is None.
binary_split
+Type → bool
+Default → False
If True, only allow binary splits.
+min_branch_fraction
+Type → float
+Default → 0.01
The minimum percentage of observed data required for branches resulting from split candidates. To validate a split candidate, at least two resulting branches must have a percentage of samples greater than min_branch_fraction. This criterion prevents unnecessary splits when the majority of instances are concentrated in a single branch.
max_share_to_split
+Type → float
+Default → 0.99
Only perform a split in a leaf if the proportion of elements in the majority class is smaller than this parameter value. This parameter avoids performing splits when most of the data belongs to a single class.
+max_size
+Type → float
+Default → 100.0
The max size of the tree, in Megabytes (MB).
+memory_estimate_period
+Type → int
+Default → 1000000
Interval (number of processed instances) between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
If True, enable merit-based tree pre-pruning.
+height
+leaf_prediction
+Return the prediction strategy used by the tree at its leaves.
+max_size
+Max allowed size tree can reach (in MB).
+n_active_leaves
+n_branches
+n_inactive_leaves
+n_leaves
+n_nodes
+split_criterion
+Return a string with the name of the split criterion being used by the tree.
+summary
+Collect metrics corresponding to the current status of the tree in a string buffer.
+from river.datasets import synth
+from river import evaluate
+from river import metrics
+from river import tree
+
+gen = synth.Agrawal(classification_function=0, seed=42)
+dataset = iter(gen.take(1000))
+
+model = tree.ExtremelyFastDecisionTreeClassifier(
+ grace_period=100,
+ delta=1e-5,
+ nominal_attributes=['elevel', 'car', 'zipcode'],
+ min_samples_reevaluate=100
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 87.29%
+Print an explanation of how x is predicted.
Parameters
+Returns
+str | None: A representation of the path followed by the tree to predict x; None if
+
Draw the tree using the graphviz library.
Since the tree is drawn without passing incoming samples, classification trees will show the majority class in their leaves, whereas regression trees will use the target mean.
+Parameters
+None None, the tree will grow indefinitely.+
Incrementally train the model
+Parameters
+1.0 Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Return a representation of the current tree structure organized in a pandas.DataFrame object.
In case the tree is empty or it only contains a single node (a leaf), None is returned.
Returns
+df
++
The Extremely Fast Decision Tree (EFDT) 1 constructs a tree incrementally. The EFDT seeks to +select and deploy a split as soon as it is confident the split is useful, and then revisits +that decision, replacing the split if it subsequently becomes evident that a better split is +available. The EFDT learns rapidly from a stationary distribution and eventually it learns the +asymptotic batch tree if the distribution from which the data are drawn is stationary.
+C. Manapragada, G. Webb, and M. Salehi. Extremely Fast Decision Tree. +In Proceedings of the 24th ACM SIGKDD International Conference on Knowledge Discovery & Data +Mining (KDD '18). ACM, New York, NY, USA, 1953-1962. +DOI: https://doi.org/10.1145/3219819.3220005 ↩
+Hoeffding Adaptive Tree classifier.
+grace_period
+Type → int
+Default → 200
Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
The maximum depth a tree can reach. If None, the tree will grow indefinitely.
split_criterion
+Type → str
+Default → info_gain
Split criterion to use. - 'gini' - Gini - 'info_gain' - Information Gain - 'hellinger' - Helinger Distance
+delta
+Type → float
+Default → 1e-07
Significance level to calculate the Hoeffding bound. The significance level is given by 1 - delta. Values closer to zero imply longer split decision delays.
tau
+Type → float
+Default → 0.05
Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → nba
Prediction mechanism used at leafs. - 'mc' - Majority Class - 'nb' - Naive Bayes - 'nba' - Naive Bayes Adaptive
+nb_threshold
+Type → int
+Default → 0
Number of instances a leaf should observe before allowing Naive Bayes.
+nominal_attributes
+Type → list | None
+Default → None
List of Nominal attributes. If empty, then assume that all numeric attributes should be treated as continuous.
+splitter
+Type → Splitter | None
+Default → None
The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.GaussianSplitter is used if splitter is None.
bootstrap_sampling
+Type → bool
+Default → True
If True, perform bootstrap sampling in the leaf nodes.
+drift_window_threshold
+Type → int
+Default → 300
Minimum number of examples an alternate tree must observe before being considered as a potential replacement to the current one.
+drift_detector
+Type → base.DriftDetector | None
+Default → None
The drift detector used to build the tree. If None then drift.ADWIN is used.
switch_significance
+Type → float
+Default → 0.05
The significance level to assess whether alternate subtrees are significantly better than their main subtree counterparts.
+binary_split
+Type → bool
+Default → False
If True, only allow binary splits.
+min_branch_fraction
+Type → float
+Default → 0.01
The minimum percentage of observed data required for branches resulting from split candidates. To validate a split candidate, at least two resulting branches must have a percentage of samples greater than min_branch_fraction. This criterion prevents unnecessary splits when the majority of instances are concentrated in a single branch.
max_share_to_split
+Type → float
+Default → 0.99
Only perform a split in a leaf if the proportion of elements in the majority class is smaller than this parameter value. This parameter avoids performing splits when most of the data belongs to a single class.
+max_size
+Type → float
+Default → 100.0
The max size of the tree, in Megabytes (MB).
+memory_estimate_period
+Type → int
+Default → 1000000
Interval (number of processed instances) between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
If True, enable merit-based tree pre-pruning.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+height
+leaf_prediction
+Return the prediction strategy used by the tree at its leaves.
+max_size
+Max allowed size tree can reach (in MB).
+n_active_leaves
+n_alternate_trees
+n_branches
+n_inactive_leaves
+n_leaves
+n_nodes
+n_pruned_alternate_trees
+n_switch_alternate_trees
+split_criterion
+Return a string with the name of the split criterion being used by the tree.
+summary
+Collect metrics corresponding to the current status of the tree in a string buffer.
+from river.datasets import synth
+from river import evaluate
+from river import metrics
+from river import tree
+
+gen = synth.ConceptDriftStream(stream=synth.SEA(seed=42, variant=0),
+ drift_stream=synth.SEA(seed=42, variant=1),
+ seed=1, position=500, width=50)
+dataset = iter(gen.take(1000))
+
+model = tree.HoeffdingAdaptiveTreeClassifier(
+ grace_period=100,
+ delta=1e-5,
+ leaf_prediction='nb',
+ nb_threshold=10,
+ seed=0
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 91.49%
+Print an explanation of how x is predicted.
Parameters
+Returns
+str | None: A representation of the path followed by the tree to predict x; None if
+
Draw the tree using the graphviz library.
Since the tree is drawn without passing incoming samples, classification trees will show the majority class in their leaves, whereas regression trees will use the target mean.
+Parameters
+None None, the tree will grow indefinitely.+
Train the model on instance x and corresponding target y.
+Parameters
+1.0 Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Return a representation of the current tree structure organized in a pandas.DataFrame object.
In case the tree is empty or it only contains a single node (a leaf), None is returned.
Returns
+df
++
The Hoeffding Adaptive Tree 1 uses a drift detector to monitor performance of branches in +the tree and to replace them with new branches when their accuracy decreases.
+The bootstrap sampling strategy is an improvement over the original Hoeffding Adaptive Tree +algorithm. It is enabled by default since, in general, it results in better performance.
+Bifet, Albert, and Ricard Gavaldà. "Adaptive learning from evolving data streams." + In International Symposium on Intelligent Data Analysis, pp. 249-260. Springer, Berlin, + Heidelberg, 2009. ↩
+Hoeffding Adaptive Tree regressor (HATR).
+This class implements a regression version of the Hoeffding Adaptive Tree Classifier. Hence, it also uses an ADWIN concept-drift detector instance at each decision node to monitor possible changes in the data distribution. If a drift is detected in a node, an alternate tree begins to be induced in the background. When enough information is gathered, HATR swaps the node where the change was detected by its alternate tree.
+grace_period
+Type → int
+Default → 200
Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
The maximum depth a tree can reach. If None, the tree will grow indefinitely.
delta
+Type → float
+Default → 1e-07
Significance level to calculate the Hoeffding bound. The significance level is given by 1 - delta. Values closer to zero imply longer split decision delays.
tau
+Type → float
+Default → 0.05
Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → adaptive
Prediction mechanism used at leafs. - 'mean' - Target mean - 'model' - Uses the model defined in leaf_model - 'adaptive' - Chooses between 'mean' and 'model' dynamically
leaf_model
+Type → base.Regressor | None
+Default → None
The regression model used to provide responses if leaf_prediction='model'. If not provided an instance of linear_model.LinearRegression with the default hyperparameters is used.
model_selector_decay
+Type → float
+Default → 0.95
The exponential decaying factor applied to the learning models' squared errors, that are monitored if leaf_prediction='adaptive'. Must be between 0 and 1. The closer to 1, the more importance is going to be given to past observations. On the other hand, if its value approaches 0, the recent observed errors are going to have more influence on the final decision.
nominal_attributes
+Type → list | None
+Default → None
List of Nominal attributes. If empty, then assume that all numeric attributes should be treated as continuous.
+splitter
+Type → Splitter | None
+Default → None
The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.TEBSTSplitter is used if splitter is None.
min_samples_split
+Type → int
+Default → 5
The minimum number of samples every branch resulting from a split candidate must have to be considered valid.
+bootstrap_sampling
+Type → bool
+Default → True
If True, perform bootstrap sampling in the leaf nodes.
+drift_window_threshold
+Type → int
+Default → 300
Minimum number of examples an alternate tree must observe before being considered as a potential replacement to the current one.
+drift_detector
+Type → base.DriftDetector | None
+Default → None
The drift detector used to build the tree. If None then drift.ADWIN is used. Only detectors that support arbitrarily valued continuous data can be used for regression.
switch_significance
+Type → float
+Default → 0.05
The significance level to assess whether alternate subtrees are significantly better than their main subtree counterparts.
+binary_split
+Type → bool
+Default → False
If True, only allow binary splits.
+max_size
+Type → float
+Default → 500.0
The max size of the tree, in Megabytes (MB).
+memory_estimate_period
+Type → int
+Default → 1000000
Interval (number of processed instances) between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
If True, enable merit-based tree pre-pruning.
+seed
+Type → int | None
+Default → None
Random seed for reproducibility.
+height
+leaf_prediction
+Return the prediction strategy used by the tree at its leaves.
+max_size
+Max allowed size tree can reach (in MB).
+n_active_leaves
+n_alternate_trees
+n_branches
+n_inactive_leaves
+n_leaves
+n_nodes
+n_pruned_alternate_trees
+n_switch_alternate_trees
+split_criterion
+Return a string with the name of the split criterion being used by the tree.
+summary
+Collect metrics corresponding to the current status of the tree in a string buffer.
+from river import datasets
+from river import evaluate
+from river import metrics
+from river import tree
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+
+model = (
+ preprocessing.StandardScaler() |
+ tree.HoeffdingAdaptiveTreeRegressor(
+ grace_period=50,
+ model_selector_decay=0.3,
+ seed=0
+ )
+)
+
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.823026
+Print an explanation of how x is predicted.
Parameters
+Returns
+str | None: A representation of the path followed by the tree to predict x; None if
+
Draw the tree using the graphviz library.
Since the tree is drawn without passing incoming samples, classification trees will show the majority class in their leaves, whereas regression trees will use the target mean.
+Parameters
+None None, the tree will grow indefinitely.+
Train the tree model on sample x and corresponding target y.
+Parameters
+1.0 Returns
+self
++
Predict the target value using one of the leaf prediction strategies.
+Parameters
+Returns
+Predicted target value.
++
Return a representation of the current tree structure organized in a pandas.DataFrame object.
In case the tree is empty or it only contains a single node (a leaf), None is returned.
Returns
+df
++
The Hoeffding Adaptive Tree 1 uses drift detectors to monitor performance of branches +in the tree and to replace them with new branches when their accuracy decreases.
+The bootstrap sampling strategy is an improvement over the original Hoeffding Adaptive Tree +algorithm. It is enabled by default since, in general, it results in better performance.
+To cope with ADWIN's requirements of bounded input data, HATR uses a novel error normalization +strategy based on the empiral rule of Gaussian distributions. We assume the deviations +of the predictions from the expected values follow a normal distribution. Hence, we subject +these errors to a min-max normalization assuming that most of the data lies in the +\(\left[-3\sigma, 3\sigma\right]\) range. These normalized errors are passed to the ADWIN +instances. This is the same strategy used by Adaptive Random Forest Regressor.
+Bifet, Albert, and Ricard Gavaldà. "Adaptive learning from evolving data streams." +In International Symposium on Intelligent Data Analysis, pp. 249-260. Springer, Berlin, +Heidelberg, 2009. ↩
+Hoeffding Tree or Very Fast Decision Tree classifier.
+grace_period
+Type → int
+Default → 200
Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
The maximum depth a tree can reach. If None, the tree will grow indefinitely.
split_criterion
+Type → str
+Default → info_gain
Split criterion to use. - 'gini' - Gini - 'info_gain' - Information Gain - 'hellinger' - Helinger Distance
+delta
+Type → float
+Default → 1e-07
Significance level to calculate the Hoeffding bound. The significance level is given by 1 - delta. Values closer to zero imply longer split decision delays.
tau
+Type → float
+Default → 0.05
Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → nba
Prediction mechanism used at leafs. - 'mc' - Majority Class - 'nb' - Naive Bayes - 'nba' - Naive Bayes Adaptive
+nb_threshold
+Type → int
+Default → 0
Number of instances a leaf should observe before allowing Naive Bayes.
+nominal_attributes
+Type → list | None
+Default → None
List of Nominal attributes identifiers. If empty, then assume that all numeric attributes should be treated as continuous.
+splitter
+Type → Splitter | None
+Default → None
The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.GaussianSplitter is used if splitter is None.
binary_split
+Type → bool
+Default → False
If True, only allow binary splits.
+min_branch_fraction
+Type → float
+Default → 0.01
The minimum percentage of observed data required for branches resulting from split candidates. To validate a split candidate, at least two resulting branches must have a percentage of samples greater than min_branch_fraction. This criterion prevents unnecessary splits when the majority of instances are concentrated in a single branch.
max_share_to_split
+Type → float
+Default → 0.99
Only perform a split in a leaf if the proportion of elements in the majority class is smaller than this parameter value. This parameter avoids performing splits when most of the data belongs to a single class.
+max_size
+Type → float
+Default → 100.0
The max size of the tree, in Megabytes (MB).
+memory_estimate_period
+Type → int
+Default → 1000000
Interval (number of processed instances) between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
If True, enable merit-based tree pre-pruning.
+height
+leaf_prediction
+Return the prediction strategy used by the tree at its leaves.
+max_size
+Max allowed size tree can reach (in MB).
+n_active_leaves
+n_branches
+n_inactive_leaves
+n_leaves
+n_nodes
+split_criterion
+Return a string with the name of the split criterion being used by the tree.
+summary
+Collect metrics corresponding to the current status of the tree in a string buffer.
+from river.datasets import synth
+from river import evaluate
+from river import metrics
+from river import tree
+
+gen = synth.Agrawal(classification_function=0, seed=42)
+dataset = iter(gen.take(1000))
+
+model = tree.HoeffdingTreeClassifier(
+ grace_period=100,
+ delta=1e-5,
+ nominal_attributes=['elevel', 'car', 'zipcode']
+)
+
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 84.58%
+Print an explanation of how x is predicted.
Parameters
+Returns
+str | None: A representation of the path followed by the tree to predict x; None if
+
Draw the tree using the graphviz library.
Since the tree is drawn without passing incoming samples, classification trees will show the majority class in their leaves, whereas regression trees will use the target mean.
+Parameters
+None None, the tree will grow indefinitely.+
Train the model on instance x and corresponding target y.
+Parameters
+1.0 Returns
+self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+A dictionary that associates a probability which each label.
++
Return a representation of the current tree structure organized in a pandas.DataFrame object.
In case the tree is empty or it only contains a single node (a leaf), None is returned.
Returns
+df
++
A Hoeffding Tree 1 is an incremental, anytime decision tree induction algorithm that is +capable of learning from massive data streams, assuming that the distribution generating +examples does not change over time. Hoeffding trees exploit the fact that a small sample can +often be enough to choose an optimal splitting attribute. This idea is supported mathematically +by the Hoeffding bound, which quantifies the number of observations (in our case, examples) +needed to estimate some statistics within a prescribed precision (in our case, the goodness of +an attribute).
+A theoretically appealing feature of Hoeffding Trees not shared by other incremental decision +tree learners is that it has sound guarantees of performance. Using the Hoeffding bound one +can show that its output is asymptotically nearly identical to that of a non-incremental +learner using infinitely many examples. Implementation based on MOA 2.
+G. Hulten, L. Spencer, and P. Domingos. Mining time-changing data streams. + In KDD’01, pages 97–106, San Francisco, CA, 2001. ACM Press. ↩
+Albert Bifet, Geoff Holmes, Richard Kirkby, Bernhard Pfahringer. + MOA: Massive Online Analysis; Journal of Machine Learning Research 11: 1601-1604, 2010. ↩
+Hoeffding Tree regressor.
+grace_period
+Type → int
+Default → 200
Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
The maximum depth a tree can reach. If None, the tree will grow indefinitely.
delta
+Type → float
+Default → 1e-07
Significance level to calculate the Hoeffding bound. The significance level is given by 1 - delta. Values closer to zero imply longer split decision delays.
tau
+Type → float
+Default → 0.05
Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → adaptive
Prediction mechanism used at leafs. - 'mean' - Target mean - 'model' - Uses the model defined in leaf_model - 'adaptive' - Chooses between 'mean' and 'model' dynamically
leaf_model
+Type → base.Regressor | None
+Default → None
The regression model used to provide responses if leaf_prediction='model'. If not provided an instance of linear_model.LinearRegression with the default hyperparameters is used.
model_selector_decay
+Type → float
+Default → 0.95
The exponential decaying factor applied to the learning models' squared errors, that are monitored if leaf_prediction='adaptive'. Must be between 0 and 1. The closer to 1, the more importance is going to be given to past observations. On the other hand, if its value approaches 0, the recent observed errors are going to have more influence on the final decision.
nominal_attributes
+Type → list | None
+Default → None
List of Nominal attributes identifiers. If empty, then assume that all numeric attributes should be treated as continuous.
+splitter
+Type → Splitter | None
+Default → None
The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.TEBSTSplitter is used if splitter is None.
min_samples_split
+Type → int
+Default → 5
The minimum number of samples every branch resulting from a split candidate must have to be considered valid.
+binary_split
+Type → bool
+Default → False
If True, only allow binary splits.
+max_size
+Type → float
+Default → 500.0
The max size of the tree, in Megabytes (MB).
+memory_estimate_period
+Type → int
+Default → 1000000
Interval (number of processed instances) between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
If True, enable merit-based tree pre-pruning.
+height
+leaf_prediction
+Return the prediction strategy used by the tree at its leaves.
+max_size
+Max allowed size tree can reach (in MB).
+n_active_leaves
+n_branches
+n_inactive_leaves
+n_leaves
+n_nodes
+split_criterion
+Return a string with the name of the split criterion being used by the tree.
+summary
+Collect metrics corresponding to the current status of the tree in a string buffer.
+from river import datasets
+from river import evaluate
+from river import metrics
+from river import tree
+from river import preprocessing
+
+dataset = datasets.TrumpApproval()
+
+model = (
+ preprocessing.StandardScaler() |
+ tree.HoeffdingTreeRegressor(
+ grace_period=100,
+ model_selector_decay=0.9
+ )
+)
+
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 0.793345
+Print an explanation of how x is predicted.
Parameters
+Returns
+str | None: A representation of the path followed by the tree to predict x; None if
+
Draw the tree using the graphviz library.
Since the tree is drawn without passing incoming samples, classification trees will show the majority class in their leaves, whereas regression trees will use the target mean.
+Parameters
+None None, the tree will grow indefinitely.+
Train the tree model on sample x and corresponding target y.
+Parameters
+1.0 Returns
+self
++
Predict the target value using one of the leaf prediction strategies.
+Parameters
+Returns
+Predicted target value.
++
Return a representation of the current tree structure organized in a pandas.DataFrame object.
In case the tree is empty or it only contains a single node (a leaf), None is returned.
Returns
+df
++
The Hoeffding Tree Regressor (HTR) is an adaptation of the incremental tree algorithm of the +same name for classification. Similarly to its classification counterpart, HTR uses the +Hoeffding bound to control its split decisions. Differently from the classification algorithm, +HTR relies on calculating the reduction of variance in the target space to decide among the +split candidates. The smallest the variance at its leaf nodes, the more homogeneous the +partitions are. At its leaf nodes, HTR fits either linear models or uses the target +average as the predictor.
+ + + + + + + + +Stochastic Gradient Tree1 for binary classification.
+Binary decision tree classifier that minimizes the binary cross-entropy to guide its growth.
+Stochastic Gradient Trees (SGT) directly minimize a loss function to guide tree growth and update their predictions. Thus, they differ from other incrementally tree learners that do not directly optimize the loss, but data impurity-related heuristics.
+delta
+Type → float
+Default → 1e-07
Define the significance level of the F-tests performed to decide upon creating splits or updating predictions.
+grace_period
+Type → int
+Default → 200
Interval between split attempts or prediction updates.
+init_pred
+Type → float
+Default → 0.0
Initial value predicted by the tree.
+max_depth
+Type → int | None
+Default → None
The maximum depth the tree might reach. If set to None, the trees will grow indefinitely.
lambda_value
+Type → float
+Default → 0.1
Positive float value used to impose a penalty over the tree's predictions and force them to become smaller. The greater the lambda value, the more constrained are the predictions.
+gamma
+Type → float
+Default → 1.0
Positive float value used to impose a penalty over the tree's splits and force them to be avoided when possible. The greater the gamma value, the smaller the chance of a split occurring.
+nominal_attributes
+Type → list | None
+Default → None
List with identifiers of the nominal attributes. If None, all features containing numbers are assumed to be numeric.
+feature_quantizer
+Type → tree.splitter.Quantizer | None
+Default → None
The algorithm used to quantize numeric features. Either a static quantizer (as in the original implementation) or a dynamic quantizer can be used. The correct choice and setup of the feature quantizer is a crucial step to determine the performance of SGTs. Feature quantizers are akin to the attribute observers used in Hoeffding Trees. By default, an instance of tree.splitter.StaticQuantizer (with default parameters) is used if this parameter is not set.
height
+n_branches
+n_leaves
+n_node_updates
+n_nodes
+n_observations
+n_splits
+from river import datasets
+from river import evaluate
+from river import metrics
+from river import tree
+
+dataset = datasets.Phishing()
+model = tree.SGTClassifier(
+ feature_quantizer=tree.splitter.StaticQuantizer(
+ n_bins=32, warm_start=10
+ )
+)
+metric = metrics.Accuracy()
+
+evaluate.progressive_val_score(dataset, model, metric)
+Accuracy: 82.24%
+Update the model with a set of features x and a label y.
Parameters
+1.0 Returns
+Classifier: self
++
Predict the label of a set of features x.
Parameters
+Returns
+base.typing.ClfTarget | None: The predicted label.
++
Predict the probability of each label for a dictionary of features x.
Parameters
+Returns
+dict[base.typing.ClfTarget, float]: A dictionary that associates a probability which each label.
++
Gouk, H., Pfahringer, B., & Frank, E. (2019, October). Stochastic Gradient Trees. +In Asian Conference on Machine Learning (pp. 1094-1109). ↩
+Stochastic Gradient Tree for regression.
+Incremental decision tree regressor that minimizes the mean square error to guide its growth.
+Stochastic Gradient Trees (SGT) directly minimize a loss function to guide tree growth and update their predictions. Thus, they differ from other incrementally tree learners that do not directly optimize the loss, but a data impurity-related heuristic.
+delta
+Type → float
+Default → 1e-07
Define the significance level of the F-tests performed to decide upon creating splits or updating predictions.
+grace_period
+Type → int
+Default → 200
Interval between split attempts or prediction updates.
+init_pred
+Type → float
+Default → 0.0
Initial value predicted by the tree.
+max_depth
+Type → int | None
+Default → None
The maximum depth the tree might reach. If set to None, the trees will grow indefinitely.
lambda_value
+Type → float
+Default → 0.1
Positive float value used to impose a penalty over the tree's predictions and force them to become smaller. The greater the lambda value, the more constrained are the predictions.
+gamma
+Type → float
+Default → 1.0
Positive float value used to impose a penalty over the tree's splits and force them to be avoided when possible. The greater the gamma value, the smaller the chance of a split occurring.
+nominal_attributes
+Type → list | None
+Default → None
List with identifiers of the nominal attributes. If None, all features containing numbers are assumed to be numeric.
+feature_quantizer
+Type → tree.splitter.Quantizer | None
+Default → None
The algorithm used to quantize numeric features. Either a static quantizer (as in the original implementation) or a dynamic quantizer can be used. The correct choice and setup of the feature quantizer is a crucial step to determine the performance of SGTs. Feature quantizers are akin to the attribute observers used in Hoeffding Trees. By default, an instance of tree.splitter.StaticQuantizer (with default parameters) is used if this parameter is not set.
height
+n_branches
+n_leaves
+n_node_updates
+n_nodes
+n_observations
+n_splits
+from river import datasets
+from river import evaluate
+from river import metrics
+from river import tree
+
+dataset = datasets.TrumpApproval()
+model = tree.SGTRegressor(
+ delta=0.01,
+ lambda_value=0.01,
+ grace_period=20,
+ feature_quantizer=tree.splitter.DynamicQuantizer(std_prop=0.1)
+)
+metric = metrics.MAE()
+
+evaluate.progressive_val_score(dataset, model, metric)
+MAE: 1.721818
+Fits to a set of features x and a real-valued target y.
Parameters
+1.0 Returns
+Regressor: self
++
Predict the output of features x.
Parameters
+Returns
+base.typing.RegTarget: The prediction.
++
This implementation enhances the original proposal 1 by using an incremental strategy to +discretize numerical features dynamically, rather than relying on a calibration set and +parameterized number of bins. The strategy used is an adaptation of the Quantization Observer +(QO) 2. Different bin size setting policies are available for selection. +They directly related to number of split candidates the tree is going to explore, and thus, +how accurate its split decisions are going to be. Besides, the number of stored bins per +feature is directly related to the tree's memory usage and runtime.
+Gouk, H., Pfahringer, B., & Frank, E. (2019, October). Stochastic Gradient Trees. +In Asian Conference on Machine Learning (pp. 1094-1109). ↩
+Mastelini, S.M. and de Leon Ferreira, A.C.P., 2021. Using dynamical quantization +to perform split attempts in online tree regressors. Pattern Recognition Letters. ↩
+A generic tree branch.
+children
+Child branches and/or leaves.
+height
+Distance to the deepest descendant.
+n_branches
+Number of branches, including thyself.
+n_leaves
+Number of leaves.
+n_nodes
+Number of descendants, including thyself.
+repr_split
+String representation of the split.
+Iterate over nodes in breadth-first order.
++
Iterate over branches in depth-first order.
++
Iterate over nodes in depth-first order.
++
Iterate over edges in depth-first order.
++
Iterate over leaves from the left-most one to the right-most one.
++
Return a tuple with the branch index and the child node related to the most traversed path.
+Used in case the split feature is missing from an instance.
++
Move to the next node down the tree.
+Parameters
++
Build a DataFrame containing one record for each node.
++
Return the leaf corresponding to the given input.
+Parameters
+True +
Iterate over the nodes of the path induced by x.
+Parameters
+True + + + + + + + + +
A generic tree node.
+kwargs
+Each provided keyword argument is stored in the leaf as an attribute.
+height
+n_branches
+n_leaves
+n_nodes
+Incremental Structured Output Prediction Tree (iSOUP-Tree) for multi-target regression.
+This is an implementation of the iSOUP-Tree proposed by A. Osojnik, P. Panov, and S. Džeroski 1.
+grace_period
+Type → int
+Default → 200
Number of instances a leaf should observe between split attempts.
+max_depth
+Type → int | None
+Default → None
The maximum depth a tree can reach. If None, the tree will grow indefinitely.
delta
+Type → float
+Default → 1e-07
Allowed error in split decision, a value closer to 0 takes longer to decide.
+tau
+Type → float
+Default → 0.05
Threshold below which a split will be forced to break ties.
+leaf_prediction
+Type → str
+Default → adaptive
Prediction mechanism used at leafs. - 'mean' - Target mean - 'model' - Uses the model defined in leaf_model - 'adaptive' - Chooses between 'mean' and 'model' dynamically
leaf_model
+Type → base.Regressor | dict | None
+Default → None
The regression model(s) used to provide responses if leaf_prediction='model'. It can be either a regressor (in which case it is going to be replicated to all the targets) or a dictionary whose keys are target identifiers, and the values are instances of base.Regressor.If not provided, instances of [linear_model.LinearRegression`](../../linear-model/LinearRegression) with the default hyperparameters are used for all the targets. If a dictionary is passed and not all target models are specified, copies from the first model match in the dictionary will be used to the remaining targets.
model_selector_decay
+Type → float
+Default → 0.95
The exponential decaying factor applied to the learning models' squared errors, that are monitored if leaf_prediction='adaptive'. Must be between 0 and 1. The closer to 1, the more importance is going to be given to past observations. On the other hand, if its value approaches 0, the recent observed errors are going to have more influence on the final decision.
nominal_attributes
+Type → list | None
+Default → None
List of Nominal attributes identifiers. If empty, then assume that all numeric attributes should be treated as continuous.
+splitter
+Type → Splitter | None
+Default → None
The Splitter or Attribute Observer (AO) used to monitor the class statistics of numeric features and perform splits. Splitters are available in the tree.splitter module. Different splitters are available for classification and regression tasks. Classification and regression splitters can be distinguished by their property is_target_class. This is an advanced option. Special care must be taken when choosing different splitters. By default, tree.splitter.TEBSTSplitter is used if splitter is None.
min_samples_split
+Type → int
+Default → 5
The minimum number of samples every branch resulting from a split candidate must have to be considered valid.
+binary_split
+Type → bool
+Default → False
If True, only allow binary splits.
+max_size
+Type → float
+Default → 500.0
The max size of the tree, in Megabytes (MB).
+memory_estimate_period
+Type → int
+Default → 1000000
Interval (number of processed instances) between memory consumption checks.
+stop_mem_management
+Type → bool
+Default → False
If True, stop growing as soon as memory limit is hit.
+remove_poor_attrs
+Type → bool
+Default → False
If True, disable poor attributes to reduce memory usage.
+merit_preprune
+Type → bool
+Default → True
If True, enable merit-based tree pre-pruning.
+height
+leaf_prediction
+Return the prediction strategy used by the tree at its leaves.
+max_size
+Max allowed size tree can reach (in MB).
+n_active_leaves
+n_branches
+n_inactive_leaves
+n_leaves
+n_nodes
+split_criterion
+Return a string with the name of the split criterion being used by the tree.
+summary
+Collect metrics corresponding to the current status of the tree in a string buffer.
+import numbers
+from river import compose
+from river import datasets
+from river import evaluate
+from river import linear_model
+from river import metrics
+from river import preprocessing
+from river import tree
+
+dataset = datasets.SolarFlare()
+
+num = compose.SelectType(numbers.Number) | preprocessing.MinMaxScaler()
+cat = compose.SelectType(str) | preprocessing.OneHotEncoder()
+
+model = tree.iSOUPTreeRegressor(
+ grace_period=100,
+ leaf_prediction='model',
+ leaf_model={
+ 'c-class-flares': linear_model.LinearRegression(l2=0.02),
+ 'm-class-flares': linear_model.PARegressor(),
+ 'x-class-flares': linear_model.LinearRegression(l2=0.1)
+ }
+)
+
+pipeline = (num + cat) | model
+metric = metrics.multioutput.MicroAverage(metrics.MAE())
+
+evaluate.progressive_val_score(dataset, pipeline, metric)
+MicroAverage(MAE): 0.426177
+Print an explanation of how x is predicted.
Parameters
+Returns
+str | None: A representation of the path followed by the tree to predict x; None if
+
Draw the tree using the graphviz library.
Since the tree is drawn without passing incoming samples, classification trees will show the majority class in their leaves, whereas regression trees will use the target mean.
+Parameters
+None None, the tree will grow indefinitely.+
Incrementally train the model with one sample.
+Training tasks: * If the tree is empty, create a leaf node as the root. * If the tree is already initialized, find the corresponding leaf for the instance and update the leaf node statistics. * If growth is allowed and the number of instances that the leaf has observed between split attempts exceed the grace period then attempt to split.
+Parameters
+1.0 +
Predict the target value using one of the leaf prediction strategies.
+Parameters
+Returns
+Predicted target value.
++
Return a representation of the current tree structure organized in a pandas.DataFrame object.
In case the tree is empty or it only contains a single node (a leaf), None is returned.
Returns
+df
++
Aljaž Osojnik, Panče Panov, and Sašo Džeroski. "Tree-based methods for online +multi-target regression." Journal of Intelligent Information Systems 50.2 (2018): 315-339. ↩
+Adapted version of the Quantizer Observer (QO)1 that is applied to Stochastic Gradient Trees (SGT).
+This feature quantizer starts by partitioning the inputs using the passed radius value. As more splits are created in the SGTs, new feature quantizers will use std * std_prop as the quantization radius. In the expression, std represents the standard deviation of the input data, which is calculated incrementally.
radius
+Type → float
+Default → 0.5
The initial quantization radius.
+std_prop
+Type → float
+Default → 0.25
The proportion of the standard deviation that is going to be used to define the radius value for new quantizer instances following the initial one.
+Mastelini, S.M. and de Leon Ferreira, A.C.P., 2021. Using dynamical quantization +to perform split attempts in online tree regressors. Pattern Recognition Letters. ↩
+iSOUP-Tree's Extended Binary Search Tree (E-BST).
+This class implements the Extended Binary Search Tree1 (E-BST) structure, using the variant employed by Osojnik et al.2 in the iSOUP-Tree algorithm. This structure is employed to observe the target space distribution.
+Proposed along with Fast Incremental Model Tree with Drift Detection1 (FIMT-DD), E-BST was the first attribute observer (AO) proposed for incremental Hoeffding Tree regressors. This AO works by storing all observations between splits in an extended binary search tree structure. E-BST stores the input feature realizations and statistics of the target(s) that enable calculating the split heuristic at any time. To alleviate time and memory costs, E-BST implements a memory management routine, where the worst split candidates are pruned from the binary tree.
+In this variant, only the left branch statistics are stored and the complete split-enabling statistics are calculated with an in-order traversal of the binary search tree.
+is_numeric
+Determine whether or not the splitter works with numerical features.
+is_target_class
+Check on which kind of learning task the splitter is designed to work. If True, the splitter works with classification trees, otherwise it is designed for regression trees.
Get the best split suggestion given a criterion and the target's statistics.
+Parameters
+True Returns
+BranchFactory: Suggestion of the best attribute split.
++
Not implemented in regression splitters.
+Parameters
++
Remove bad splits.
+Based on FIMT-DD's 1 procedure to remove bad split candidates from the E-BST. This mechanism is triggered every time a split attempt fails. The rationale is to remove points whose split merit is much worse than the best candidate overall (for which the growth decision already failed). Let \(m_1\) be the merit of the best split point and \(m_2\) be the merit of the second best split candidate. The ratio \(r = m_2/m_1\) along with the Hoeffding bound (\(\epsilon\)) are used to decide upon creating a split. A split occurs when \(r < 1 - \epsilon\). A split candidate, with merit \(m_i\), is considered badr if \(m_i / m_1 < r - 2\epsilon\). The rationale is the following: if the merit ratio for this point is smaller than the lower bound of \(r\), then the true merit of that split relative to the best one is small. Hence, this candidate can be safely removed. To avoid excessive and costly manipulations of the E-BST to update the stored statistics, only the nodes whose children are all bad split points are pruned, as defined in 1.
+Parameters
++
Update statistics of this observer given an attribute value, its target value and the weight of the instance observed.
+Parameters
++ + + + + + + + + +
Numeric attribute observer for classification tasks that is based on a Binary Search Tree.
+This algorithm1 is also referred to as exhaustive attribute observer, since it ends up storing all the observations between split attempts2.
+This splitter cannot perform probability density estimations, so it does not work well when coupled with tree leaves using naive bayes models.
+is_numeric
+Determine whether or not the splitter works with numerical features.
+is_target_class
+Check on which kind of learning task the splitter is designed to work. If True, the splitter works with classification trees, otherwise it is designed for regression trees.
Get the best split suggestion given a criterion and the target's statistics.
+Parameters
+Returns
+BranchFactory: Suggestion of the best attribute split.
++
The underlying data structure used to monitor the input does not allow probability density estimations. Hence, it always returns zero for any given input.
+Parameters
++
Update statistics of this observer given an attribute value, its target value and the weight of the instance observed.
+Parameters
++
Domingos, P. and Hulten, G., 2000, August. Mining high-speed data streams. +In Proceedings of the sixth ACM SIGKDD international conference on Knowledge discovery +and data mining (pp. 71-80). ↩
+Pfahringer, B., Holmes, G. and Kirkby, R., 2008, May. Handling numeric attributes in +hoeffding trees. In Pacific-Asia Conference on Knowledge Discovery and Data Mining +(pp. 296-307). Springer, Berlin, Heidelberg. ↩
+Numeric attribute observer for classification tasks that is based on Gaussian estimators.
+The distribution of each class is approximated using a Gaussian distribution. Hence, the probability density function can be easily calculated.
+n_splits
+Type → int
+Default → 10
The number of partitions to consider when querying for split candidates.
+is_numeric
+Determine whether or not the splitter works with numerical features.
+is_target_class
+Check on which kind of learning task the splitter is designed to work. If True, the splitter works with classification trees, otherwise it is designed for regression trees.
Get the best split suggestion given a criterion and the target's statistics.
+Parameters
+Returns
+BranchFactory: Suggestion of the best attribute split.
++
Get the probability for an attribute value given a class.
+Parameters
+Returns
+float: Probability for an attribute value given a class.
++
Update statistics of this observer given an attribute value, its target value and the weight of the instance observed.
+Parameters
++ + + + + + + + +
Numeric attribute observer for classification tasks that discretizes features using histograms.
+n_bins
+Type → int
+Default → 256
The maximum number of bins in the histogram.
+n_splits
+Type → int
+Default → 32
The number of split points to evaluate when querying for the best split candidate.
+is_numeric
+Determine whether or not the splitter works with numerical features.
+is_target_class
+Check on which kind of learning task the splitter is designed to work. If True, the splitter works with classification trees, otherwise it is designed for regression trees.
Get the best split suggestion given a criterion and the target's statistics.
+Parameters
+Returns
+BranchFactory: Suggestion of the best attribute split.
++
Get the probability for an attribute value given a class.
+Parameters
+Returns
+float: Probability for an attribute value given a class.
++
Update statistics of this observer given an attribute value, its target value and the weight of the instance observed.
+Parameters
++ + + + + + + + +
Quantization observer (QO).
+This splitter utilizes a hash-based quantization algorithm to keep track of the target statistics and evaluate split candidates. QO, relies on the radius parameter to define discretization intervals for each incoming feature. Split candidates are defined as the midpoints between two consecutive hash slots. Both binary splits and multi-way splits can be created by this attribute observer. This class implements the algorithm described in 1.
+The smaller the quantization radius, the more hash slots will be created to accommodate the discretized data. Hence, both the running time and memory consumption increase, but the resulting splits ought to be closer to the ones obtained by a batch exhaustive approach. On the other hand, if the radius is too large, fewer slots will be created, less memory and running time will be required, but at the cost of coarse split suggestions.
+QO assumes that all features have the same range. It is always advised to scale the features to apply this splitter. That can be done using the preprocessing module. A good "rule of thumb" is to scale data using preprocessing.StandardScaler and define the radius as a proportion of the features' standard deviation. For instance, the default radius value would correspond to one quarter of the normalized features' standard deviation (since the scaled data has zero mean and unit variance). If the features come from normal distributions, by following the empirical rule, roughly 32 hash slots will be created.
radius
+Type → float
+Default → 0.25
The quantization radius. QO discretizes the incoming feature in intervals of equal length that are defined by this parameter.
+allow_multiway_splits
+Default → False
Whether or not allow that multiway splits are evaluated. Numeric multi-way splits use the same quantization strategy of QO to create multiple tree branches. The same quantization radius is used, and each stored slot represents the split enabling statistics of one branch.
+is_numeric
+Determine whether or not the splitter works with numerical features.
+is_target_class
+Check on which kind of learning task the splitter is designed to work. If True, the splitter works with classification trees, otherwise it is designed for regression trees.
Get the best split suggestion given a criterion and the target's statistics.
+Parameters
+True Returns
+BranchFactory: Suggestion of the best attribute split.
++
Get the probability for an attribute value given a class.
+Parameters
+Returns
+float: Probability for an attribute value given a class.
++
Update statistics of this observer given an attribute value, its target value and the weight of the instance observed.
+Parameters
++
Mastelini, S.M. and de Leon Ferreira, A.C.P., 2021. Using dynamical quantization to +perform split attempts in online tree regressors. Pattern Recognition Letters. ↩
+Base class for the tree splitters.
+Each Attribute Observer (AO) or Splitter monitors one input feature and finds the best split point for this attribute. AOs can also perform other tasks related to the monitored feature, such as estimating its probability density function (classification case).
+This class should not be instantiated, as none of its methods are implemented.
+is_numeric
+Determine whether or not the splitter works with numerical features.
+is_target_class
+Check on which kind of learning task the splitter is designed to work. If True, the splitter works with classification trees, otherwise it is designed for regression trees.
Get the best split suggestion given a criterion and the target's statistics.
+Parameters
+Returns
+BranchFactory: Suggestion of the best attribute split.
++
Get the probability for an attribute value given a class.
+Parameters
+Returns
+float: Probability for an attribute value given a class.
++
Update statistics of this observer given an attribute value, its target value and the weight of the instance observed.
+Parameters
++ + + + + + + + +
Quantization strategy originally used in Stochastic Gradient Trees (SGT)1.
+Firstly, a buffer of size warm_start is stored. The data stored in the buffer is then used to quantize the input feature into n_bins intervals. These intervals will be replicated to every new quantizer. Feature values lying outside of the limits defined by the initial buffer will be mapped to the head or tail of the list of intervals.
n_bins
+Type → int
+Default → 64
The number of bins (intervals) to divide the input feature.
+warm_start
+Type → int
+Default → 100
The number of observations used to initialize the quantization intervals.
+buckets
+Type → list | None
+Default → None
This parameter is only used internally by the quantizer, so it must not be set. Once the intervals are defined, new instances of this quantizer will receive the quantization information via this parameter.
+Gouk, H., Pfahringer, B., & Frank, E. (2019, October). Stochastic Gradient Trees. +In Asian Conference on Machine Learning (pp. 1094-1109). ↩
+Truncated E-BST.
+Variation of E-BST that rounds the incoming feature values before passing them to the binary search tree (BST). By doing so, the attribute observer might reduce its processing time and memory usage since small variations in the input values will end up being mapped to the same BST node.
+digits
+Type → int
+Default → 1
The number of decimal places used to round the input feature values.
+is_numeric
+Determine whether or not the splitter works with numerical features.
+is_target_class
+Check on which kind of learning task the splitter is designed to work. If True, the splitter works with classification trees, otherwise it is designed for regression trees.
Get the best split suggestion given a criterion and the target's statistics.
+Parameters
+True Returns
+BranchFactory: Suggestion of the best attribute split.
++
Not implemented in regression splitters.
+Parameters
++
Remove bad splits.
+Based on FIMT-DD's [^1] procedure to remove bad split candidates from the E-BST. This mechanism is triggered every time a split attempt fails. The rationale is to remove points whose split merit is much worse than the best candidate overall (for which the growth decision already failed). Let \(m_1\) be the merit of the best split point and \(m_2\) be the merit of the second best split candidate. The ratio \(r = m_2/m_1\) along with the Hoeffding bound (\(\epsilon\)) are used to decide upon creating a split. A split occurs when \(r < 1 - \epsilon\). A split candidate, with merit \(m_i\), is considered badr if \(m_i / m_1 < r - 2\epsilon\). The rationale is the following: if the merit ratio for this point is smaller than the lower bound of \(r\), then the true merit of that split relative to the best one is small. Hence, this candidate can be safely removed. To avoid excessive and costly manipulations of the E-BST to update the stored statistics, only the nodes whose children are all bad split points are pruned, as defined in [^1].
+Parameters
++
Update statistics of this observer given an attribute value, its target value and the weight of the instance observed.
+Parameters
++ + + + + + + + +
A generic wrapper for performing rolling computations.
+This can be wrapped around any object which implements both an update and a revert method. Inputs to update are stored in a queue. Elements of the queue are popped when the window is full.
obj
+Type → Rollable
+An object that implements both an update method and a rollingmethod.
window_size
+Type → int
+Size of the window.
+For instance, here is how you can compute a rolling average over a window of size 3:
+from river import stats, utils
+
+X = [1, 3, 5, 7]
+rmean = utils.Rolling(stats.Mean(), window_size=3)
+
+for x in X:
+ print(rmean.update(x).get())
+1.0
+2.0
+3.0
+5.0
+Sorted running window data structure.
+size
+Type → int
+Size of the window to compute the rolling quantile.
+from river import utils
+
+window = utils.SortedWindow(size=3)
+
+for i in reversed(range(9)):
+ print(window.append(i))
+[8]
+[7, 8]
+[6, 7, 8]
+[5, 6, 7]
+[4, 5, 6]
+[3, 4, 5]
+[2, 3, 4]
+[1, 2, 3]
+[0, 1, 2]
+A generic wrapper for performing time rolling computations.
+This can be wrapped around any object which implements both an update and a revert method. Inputs to update are stored in a queue. Elements of the queue are popped when they are too old.
obj
+Type → Rollable
+An object that implements both an update method and a rollingmethod.
period
+Type → dt.timedelta
+A duration of time, expressed as a datetime.timedelta.
For instance, here is how you can compute a rolling average over a period of 3 days:
+from river import stats, utils
+
+X = {
+ dt.datetime(2019, 1, 1): 1,
+ dt.datetime(2019, 1, 2): 5,
+ dt.datetime(2019, 1, 3): 9,
+ dt.datetime(2019, 1, 4): 13
+}
+
+rmean = utils.TimeRolling(stats.Mean(), period=dt.timedelta(days=3))
+for t, x in X.items():
+ print(rmean.update(x, t=t).get())
+1.0
+3.0
+5.0
+9.0
++
+
Parameters
++
+
+
+
Parameters
++
+
Parameters
++
Parameters
++
+
Parameters
++
+
Parameters
++
Parameters
++
+
Parameters
+False + + + + + + + + +
Convert a dictionary containing data to a numpy array.
+There is not restriction to the type of keys in data, but values must be strictly numeric. To make sure random permutations of the features do not impact on the learning algorithms, keys are first converted to strings and then sorted prior to the conversion.
data
+A dictionary whose keys represent input attributes and the values represent their observed contents.
+from river.utils import dict2numpy
+dict2numpy({'a': 1, 'b': 2, 3: 3})
+array([3, 1, 2])
+Expands a grid of parameters.
+This method can be used to generate a list of model parametrizations from a dictionary where each parameter is associated with a list of possible parameters. In other words, it expands a grid of parameters.
+Typically, this method can be used to create copies of a given model with different parameter choices. The models can then be used as part of a model selection process, such as a selection.SuccessiveHalvingClassifier or a selection.EWARegressor.
The syntax for the parameter grid is quite flexible. It allows nesting parameters and can therefore be used to generate parameters for a pipeline.
+model
+Type → base.Estimator
+grid
+Type → dict
+The grid of parameters to expand. The provided dictionary can be nested. The only requirement is that the values at the leaves need to be lists.
+As an initial example, we can expand a grid of parameters for a single model.
+from river import linear_model
+from river import optim
+from river import utils
+
+model = linear_model.LinearRegression()
+
+grid = {'optimizer': [optim.SGD(.1), optim.SGD(.01), optim.SGD(.001)]}
+models = utils.expand_param_grid(model, grid)
+len(models)
+3
+models[0]
+LinearRegression (
+ optimizer=SGD (
+ lr=Constant (
+ learning_rate=0.1
+ )
+ )
+ loss=Squared ()
+ l2=0.
+ l1=0.
+ intercept_init=0.
+ intercept_lr=Constant (
+ learning_rate=0.01
+ )
+ clip_gradient=1e+12
+ initializer=Zeros ()
+)
+You can expand parameters for multiple choices like so:
+grid = {
+ 'optimizer': [
+ (optim.SGD, {'lr': [.1, .01, .001]}),
+ (optim.Adam, {'lr': [.1, .01, .01]})
+ ]
+}
+models = utils.expand_param_grid(model, grid)
+len(models)
+6
+You may specify a grid of parameters for a pipeline via nesting:
+from river import feature_extraction
+
+model = (
+ feature_extraction.BagOfWords() |
+ linear_model.LinearRegression()
+)
+
+grid = {
+ 'BagOfWords': {
+ 'strip_accents': [False, True]
+ },
+ 'LinearRegression': {
+ 'optimizer': [
+ (optim.SGD, {'lr': [.1, .01]}),
+ (optim.Adam, {'lr': [.1, .01]})
+ ]
+ }
+}
+
+models = utils.expand_param_grid(model, grid)
+len(models)
+8
+A context manager to log method calls.
+All method calls will be logged by default. This behavior can be overriden by passing filtering functions.
+class_condition
+Type → typing.Callable[[typing.Any], bool] | None
+Default → None
A function which determines if a class should be logged or not.
+method_condition
+Type → typing.Callable[[typing.Any], bool] | None
+Default → None
A function which determines if a method should be logged or not.
+import io
+import logging
+from river import anomaly
+from river import compose
+from river import datasets
+from river import preprocessing
+from river import utils
+
+model = compose.Pipeline(
+ preprocessing.MinMaxScaler(),
+ anomaly.HalfSpaceTrees(seed=42)
+)
+
+class_condition = lambda x: x.__class__.__name__ in ('MinMaxScaler', 'HalfSpaceTrees')
+
+logger = logging.getLogger()
+logger.setLevel(logging.DEBUG)
+
+logs = io.StringIO()
+sh = logging.StreamHandler(logs)
+sh.setLevel(logging.DEBUG)
+logger.addHandler(sh)
+
+with utils.log_method_calls(class_condition):
+ for x, y in datasets.CreditCard().take(1):
+ score = model.score_one(x)
+ model = model.learn_one(x)
+
+print(logs.getvalue())
+MinMaxScaler.transform_one
+HalfSpaceTrees.score_one
+MinMaxScaler.learn_one
+MinMaxScaler.transform_one
+HalfSpaceTrees.learn_one
+logs.close()
+Vector times matrix from left side, i.e. transpose(x)A.
+x
+A
+from river import utils
+
+x = {0: 4, 1: 5}
+
+A = {
+ (0, 0): 0, (0, 1): 1,
+ (1, 0): 2, (1, 1): 3
+}
+
+C = utils.math.dotvecmat(x, A)
+print(C)
+{0: 10.0, 1: 19.0}
+Multiplication for 2D matrices.
+A
+B
+import pprint
+from river import utils
+
+A = {
+ (0, 0): 2, (0, 1): 0, (0, 2): 4,
+ (1, 0): 5, (1, 1): 6, (1, 2): 0
+}
+
+B = {
+ (0, 0): 1, (0, 1): 1, (0, 2): 0, (0, 3): 0,
+ (1, 0): 2, (1, 1): 0, (1, 2): 1, (1, 3): 3,
+ (2, 0): 4, (2, 1): 0, (2, 2): 0, (2, 3): 0
+}
+
+C = utils.math.matmul2d(A, B)
+pprint.pprint(C)
+{(0, 0): 18.0,
+ (0, 1): 2.0,
+ (0, 2): 0.0,
+ (0, 3): 0.0,
+ (1, 0): 17.0,
+ (1, 1): 5.0,
+ (1, 2): 6.0,
+ (1, 3): 18.0}
+Minkowski distance.
+a
+Type → dict
+b
+Type → dict
+p
+Type → int
+Parameter for the Minkowski distance. When p=1, this is equivalent to using the Manhattan distance. When p=2, this is equivalent to using the Euclidean distance.
Outer-product between two vectors.
+u
+Type → dict
+v
+Type → dict
+import pprint
+from river import utils
+
+u = dict(enumerate((1, 2, 3)))
+v = dict(enumerate((2, 4, 8)))
+
+uTv = utils.math.outer(u, v)
+pprint.pprint(uTv)
+{(0, 0): 2,
+ (0, 1): 4,
+ (0, 2): 8,
+ (1, 0): 4,
+ (1, 1): 8,
+ (1, 2): 16,
+ (2, 0): 6,
+ (2, 1): 12,
+ (2, 2): 24}
+Normalize the values in a dictionary using the given factor.
+For each element in the dictionary, applies value/factor.
dictionary
+Dictionary to normalize.
+factor
+Default → None
Normalization factor value. If not set, use the sum of values.
+inplace
+Default → True
If True, perform operation in-place
+raise_error
+Default → False
In case the normalization factor is either 0 or None: - True: raise an error. - False: return gracefully (if inplace=False, a copy of) dictionary.
Scale the values in a dictionary.
+For each element in the dictionary, applies value * multiplier.
dictionary
+Dictionary to scale.
+multiplier
+Scaling value.
+inplace
+Default → True
If True, perform operation in-place
+Pretty-prints a table.
+headers
+Type → list[str]
+The column names.
+columns
+Type → list[list[str]]
+The column values.
+order
+Type → list[int] | None
+Default → None
Order in which to print the column the values. Defaults to the order in which the values are given.
+Sample a random value from a Poisson distribution.
+rate
+Type → float
+rng
+Default → <module 'random' from '/opt/hostedtoolcache/Python/3.9.17/x64/lib/python3.9/random.py'>
[^1] Wikipedia article
+ + + + + + + + +