use crate::api::{Capabilities, Estimator, HasCapabilities, HasParams, ModelError, Transformer};
use crate::data::MatrixView;
use super::scaling::{inverse_transform_allocating, validate_transform_request};
pub type ElementwiseFn = fn(f32) -> f32;
#[derive(Clone, Copy, Debug)]
pub struct FunctionTransformerParams {
func: ElementwiseFn,
inverse_func: Option<ElementwiseFn>,
}
fn identity(value: f32) -> f32 {
value
}
impl Default for FunctionTransformerParams {
fn default() -> Self {
Self {
func: identity,
inverse_func: Some(identity),
}
}
}
impl FunctionTransformerParams {
#[must_use]
pub const fn with_func(mut self, func: ElementwiseFn) -> Self {
self.func = func;
self.inverse_func = None;
self
}
#[must_use]
pub const fn with_inverse_func(mut self, inverse_func: ElementwiseFn) -> Self {
self.inverse_func = Some(inverse_func);
self
}
#[must_use]
pub const fn func(&self) -> ElementwiseFn {
self.func
}
#[must_use]
pub const fn inverse_func(&self) -> Option<ElementwiseFn> {
self.inverse_func
}
}
#[derive(Clone, Copy, Debug)]
pub struct FunctionTransformer {
n_features_in: usize,
params: FunctionTransformerParams,
}
impl FunctionTransformer {
pub fn fit(
data: &MatrixView<'_>,
params: FunctionTransformerParams,
) -> Result<Self, ModelError> {
Ok(Self {
n_features_in: data.columns(),
params,
})
}
#[must_use]
pub const fn n_features_in(&self) -> usize {
self.n_features_in
}
#[must_use]
pub const fn n_features_out(&self) -> usize {
self.n_features_in
}
#[must_use]
pub const fn get_params(&self) -> &FunctionTransformerParams {
&self.params
}
pub fn transform_into<'output>(
&self,
data: &MatrixView<'_>,
output: &'output mut [f32],
) -> Result<MatrixView<'output>, ModelError> {
<Self as Transformer>::transform_into(self, data, output)
}
pub fn transform(&self, data: &MatrixView<'_>) -> Result<crate::data::DenseMatrix, ModelError> {
<Self as Transformer>::transform(self, data)
}
pub fn inverse_transform_into<'output>(
&self,
data: &MatrixView<'_>,
output: &'output mut [f32],
) -> Result<MatrixView<'output>, ModelError> {
let inverse = self
.params
.inverse_func
.ok_or(ModelError::NoInverseFunction)?;
validate_transform_request(self.n_features_in, data, output)?;
self.apply(inverse, data, output)
}
pub fn inverse_transform(
&self,
data: &MatrixView<'_>,
) -> Result<crate::data::DenseMatrix, ModelError> {
if self.params.inverse_func.is_none() {
return Err(ModelError::NoInverseFunction);
}
inverse_transform_allocating(self.n_features_in, data, |batch, output| {
self.inverse_transform_into(batch, output).map(|_| ())
})
}
fn apply<'output>(
&self,
map: ElementwiseFn,
data: &MatrixView<'_>,
output: &'output mut [f32],
) -> Result<MatrixView<'output>, ModelError> {
for (row_index, row) in data.iter_rows().enumerate() {
for (column, value) in row.iter().enumerate() {
if !map(*value).is_finite() {
return Err(ModelError::NonFiniteTransform {
row: row_index,
column,
});
}
}
}
for (row, output_row) in data
.iter_rows()
.zip(output.chunks_exact_mut(self.n_features_in))
{
for (value, slot) in row.iter().zip(output_row) {
*slot = map(*value);
}
}
Ok(MatrixView::from_validated_parts(
output,
data.rows(),
self.n_features_in,
))
}
}
impl Estimator for FunctionTransformer {
fn n_features_in(&self) -> usize {
self.n_features_in
}
}
impl HasCapabilities for FunctionTransformer {
const CAPABILITIES: Capabilities = Capabilities::NONE;
}
impl HasParams for FunctionTransformer {
type Params = FunctionTransformerParams;
fn get_params(&self) -> &Self::Params {
&self.params
}
}
impl Transformer for FunctionTransformer {
fn n_features_out(&self) -> usize {
self.n_features_in
}
fn transform_into<'output>(
&self,
data: &MatrixView<'_>,
output: &'output mut [f32],
) -> Result<MatrixView<'output>, ModelError> {
validate_transform_request(self.n_features_in, data, output)?;
self.apply(self.params.func, data, output)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::data::DenseMatrix;
fn matrix(values: &[f32], rows: usize, columns: usize) -> DenseMatrix {
DenseMatrix::new(values.to_vec(), rows, columns).unwrap()
}
fn double(value: f32) -> f32 {
value * 2.0
}
fn halve(value: f32) -> f32 {
value / 2.0
}
fn reciprocal(value: f32) -> f32 {
1.0 / value
}
fn fitted(params: FunctionTransformerParams) -> FunctionTransformer {
let data = matrix(&[1.0, 2.0, 3.0, 4.0], 2, 2);
FunctionTransformer::fit(&data.as_view(), params).unwrap()
}
#[test]
fn the_supplied_function_is_applied_to_every_value() {
let data = matrix(&[1.0, 2.0, 3.0, 4.0], 2, 2);
let transformer = fitted(FunctionTransformerParams::default().with_func(double));
assert_eq!(
transformer.transform(&data.as_view()).unwrap().as_slice(),
&[2.0, 4.0, 6.0, 8.0]
);
}
#[test]
fn the_default_is_the_identity_in_both_directions() {
let data = matrix(&[1.0, -2.5, 0.0, 4.0], 2, 2);
let transformer = fitted(FunctionTransformerParams::default());
assert_eq!(
transformer.transform(&data.as_view()).unwrap().as_slice(),
data.as_slice()
);
assert!(transformer.get_params().inverse_func().is_some());
}
#[test]
fn supplying_a_forward_map_clears_an_inverse_belonging_to_another_map() {
let params = FunctionTransformerParams::default()
.with_inverse_func(halve)
.with_func(double);
assert!(params.inverse_func().is_none());
let params = params.with_inverse_func(halve);
assert!(params.inverse_func().is_some());
}
#[test]
fn a_non_finite_result_is_reported_at_its_first_row_major_cell() {
let data = matrix(&[1.0, 2.0, 0.0, 4.0], 2, 2);
let transformer = fitted(FunctionTransformerParams::default().with_func(reciprocal));
let mut output = [91.0; 4];
assert_eq!(
transformer
.transform_into(&data.as_view(), &mut output)
.unwrap_err(),
ModelError::NonFiniteTransform { row: 1, column: 0 }
);
assert_eq!(output, [91.0; 4], "nothing is written when anything fails");
}
#[test]
fn a_non_monotone_map_is_still_checked_at_every_value() {
fn spike(value: f32) -> f32 {
if value == 2.0 { f32::INFINITY } else { value }
}
let data = matrix(&[1.0, 2.0, 3.0], 3, 1);
let transformer = fitted(FunctionTransformerParams::default().with_func(spike));
let narrow = matrix(&[1.0, 2.0, 3.0], 3, 1);
let transformer =
FunctionTransformer::fit(&narrow.as_view(), *transformer.get_params()).unwrap();
let mut output = [7.0; 3];
assert_eq!(
transformer
.transform_into(&data.as_view(), &mut output)
.unwrap_err(),
ModelError::NonFiniteTransform { row: 1, column: 0 }
);
assert_eq!(output, [7.0; 3]);
}
#[test]
fn refitting_the_same_batch_is_deterministic() {
let data = matrix(&[1.0, 2.0, 3.0, 4.0], 2, 2);
let params = FunctionTransformerParams::default().with_func(double);
let first = fitted(params).transform(&data.as_view()).unwrap();
let second = fitted(params).transform(&data.as_view()).unwrap();
assert_eq!(first.as_slice(), second.as_slice());
assert_eq!(fitted(params).n_features_in(), 2);
}
#[test]
fn the_inverse_applies_exactly_the_supplied_function() {
let data = matrix(&[1.0, 2.0, 3.0, 4.0], 2, 2);
let transformer = fitted(
FunctionTransformerParams::default()
.with_func(double)
.with_inverse_func(halve),
);
let transformed = transformer.transform(&data.as_view()).unwrap();
let recovered = transformer
.inverse_transform(&transformed.as_view())
.unwrap();
assert_eq!(recovered.as_slice(), data.as_slice());
}
#[test]
fn a_missing_inverse_is_refused_rather_than_treated_as_the_identity() {
let data = matrix(&[1.0, 2.0, 3.0, 4.0], 2, 2);
let transformer = fitted(FunctionTransformerParams::default().with_func(double));
assert_eq!(
transformer.inverse_transform(&data.as_view()).unwrap_err(),
ModelError::NoInverseFunction
);
let mut output = [91.0; 4];
assert_eq!(
transformer
.inverse_transform_into(&data.as_view(), &mut output)
.unwrap_err(),
ModelError::NoInverseFunction
);
assert_eq!(output, [91.0; 4]);
}
#[test]
fn a_wrong_inverse_is_applied_as_given_rather_than_checked() {
let data = matrix(&[1.0, 2.0, 3.0, 4.0], 2, 2);
let transformer = fitted(
FunctionTransformerParams::default()
.with_func(double)
.with_inverse_func(double),
);
assert_eq!(
transformer
.inverse_transform(&data.as_view())
.unwrap()
.as_slice(),
&[2.0, 4.0, 6.0, 8.0]
);
}
#[test]
fn validates_width_and_workspace_before_writing() {
let data = matrix(&[1.0, 2.0, 3.0, 4.0], 2, 2);
let transformer = fitted(FunctionTransformerParams::default().with_func(double));
let mut short = [91.0; 3];
assert_eq!(
transformer
.transform_into(&data.as_view(), &mut short)
.unwrap_err(),
ModelError::OutputLength {
expected: 4,
actual: 3
}
);
assert_eq!(short, [91.0; 3]);
let narrow = matrix(&[1.0, 2.0, 3.0], 1, 3);
let mut narrow_output = [91.0; 3];
assert_eq!(
transformer
.transform_into(&narrow.as_view(), &mut narrow_output)
.unwrap_err(),
ModelError::FeatureDimension {
expected: 2,
actual: 3
}
);
assert_eq!(narrow_output, [91.0; 3]);
}
}