smartcore/
api.rs

1//! # Common Interfaces and API
2//!
3//! This module provides interfaces and uniform API with simple conventions
4//! that are used in other modules for supervised and unsupervised learning.
5
6use crate::error::Failed;
7
8/// An estimator for unsupervised learning, that provides method `fit` to learn from data
9pub trait UnsupervisedEstimator<X, P> {
10    /// Fit a model to a training dataset, estimate model's parameters.
11    /// * `x` - _NxM_ matrix with _N_ observations and _M_ features in each observation.
12    /// * `parameters` - hyperparameters of an algorithm
13    fn fit(x: &X, parameters: P) -> Result<Self, Failed>
14    where
15        Self: Sized,
16        P: Clone;
17}
18
19/// An estimator for supervised learning, that provides method `fit` to learn from data and training values
20pub trait SupervisedEstimator<X, Y, P>: Predictor<X, Y> {
21    /// Empty constructor, instantiate an empty estimator. Object is dropped as soon as `fit()` is called.
22    /// used to pass around the correct `fit()` implementation.
23    /// by calling `::fit()`. mostly used to be used with `model_selection::cross_validate(...)`
24    fn new() -> Self;
25    /// Fit a model to a training dataset, estimate model's parameters.
26    /// * `x` - _NxM_ matrix with _N_ observations and _M_ features in each observation.
27    /// * `y` - target training values of size _N_.
28    /// * `parameters` - hyperparameters of an algorithm
29    fn fit(x: &X, y: &Y, parameters: P) -> Result<Self, Failed>
30    where
31        Self: Sized,
32        P: Clone;
33}
34
35/// An estimator for supervised learning.
36/// In this one parameters are borrowed instead of moved, this is useful for parameters that carry
37/// references. Also to be used when there is no predictor attached to the estimator.
38pub trait SupervisedEstimatorBorrow<'a, X, Y, P> {
39    /// Empty constructor, instantiate an empty estimator. Object is dropped as soon as `fit()` is called.
40    /// used to pass around the correct `fit()` implementation.
41    /// by calling `::fit()`. mostly used to be used with `model_selection::cross_validate(...)`
42    fn new() -> Self;
43    /// Fit a model to a training dataset, estimate model's parameters.
44    /// * `x` - _NxM_ matrix with _N_ observations and _M_ features in each observation.
45    /// * `y` - target training values of size _N_.
46    /// * `&parameters` - hyperparameters of an algorithm
47    fn fit(x: &'a X, y: &'a Y, parameters: &'a P) -> Result<Self, Failed>
48    where
49        Self: Sized,
50        P: Clone;
51}
52
53/// Implements method predict that estimates target value from new data
54pub trait Predictor<X, Y> {
55    /// Estimate target values from new data.
56    /// * `x` - _NxM_ matrix with _N_ observations and _M_ features in each observation.
57    fn predict(&self, x: &X) -> Result<Y, Failed>;
58}
59
60/// Implements method predict that estimates target value from new data, with borrowing
61pub trait PredictorBorrow<'a, X, T> {
62    /// Estimate target values from new data.
63    /// * `x` - _NxM_ matrix with _N_ observations and _M_ features in each observation.
64    fn predict(&self, x: &'a X) -> Result<Vec<T>, Failed>;
65}
66
67/// Implements method transform that filters or modifies input data
68pub trait Transformer<X> {
69    /// Transform data by modifying or filtering it
70    /// * `x` - _NxM_ matrix with _N_ observations and _M_ features in each observation.
71    fn transform(&self, x: &X) -> Result<X, Failed>;
72}
73
74/// empty parameters for an estimator, see `BiasedEstimator`
75pub trait NoParameters {}
smartcore/api.rs

smartcore/
api.rs
