# `pls_projection`

Partial Least Squares projection reducer for target-valued continuous datasets. The library implements the `dimension_reducer_protocol` defined in the `dimension_reduction_protocols` library and learns a deterministic PLS1 projection by centering the training data, optionally standardizing continuous attributes, centering the numeric target, extracting latent directions using repeated cross-covariance maximization with sequential deflation, and storing the resulting direct projection rotations for future transforms.

Requires a dataset implementing `target_supervised_dimension_reduction_dataset_protocol` and therefore uses a numeric target during training.

## API documentation

Open the ../../apis/library_index.html#pls_projection link in a web browser.

## Loading

To load this library, load the `loader.lgt` file:

    | ?- logtalk_load(pls_projection(loader)).

## Testing

To test this library predicates, load the `tester.lgt` file:

    | ?- logtalk_load(pls_projection(tester)).

## Features

- Continuous Datasets: Accepts datasets containing only continuous attributes and rejects datasets that also declare the target name as an input feature. Missing or nonnumeric values are also rejected.

- Target-Supervised Learning: Uses a numeric target attribute declared by datasets implementing `target_supervised_dimension_reduction_dataset_protocol`.

- Centering and Optional Scaling: Centers all attributes and optionally standardizes them before learning latent directions.

- Deterministic Components: Learns components deterministically from feature-target cross-covariance without stochastic initialization.

- Configurable Shortfall Handling: Lets callers choose whether an extraction shortfall raises an error or truncates the learned reducer with explicit diagnostics.

- Projection API: Transforms a new instance into a list of `component_N-Value` pairs using the learned direct PLS rotation vectors.

- Model Export: Learned reducers can be exported as predicate clauses or written to a file.

## Options

The `learn/3` predicate accepts the following options:

- `n_components/1`: Number of latent PLS components to extract. Requests that exceed `min(FeatureCount, SampleCount - 1)` raise `domain_error(component_count, Requested-Maximum)`. The default is `2`.

- `feature_scaling/1`: Whether to standardize continuous attributes before projection. Options: `true` (default) or `false`.

- `shortfall_policy/1`: Controls what happens when residual feature-target cross-covariance becomes negligible before all requested components are extracted. Options: `truncate` (default), which returns a reducer with fewer components and records a `shortfall(truncated(Requested, Learned, ScoreEnergy, Tolerance))` diagnostic, or `error`, which raises `domain_error(component_count, Requested-Learned)`.

- `tolerance/1`: Positive numerical tolerance used to stop extracting components when the residual feature-target cross-covariance becomes negligible. The default is `1.0e-8`.

## Usage

The following example uses the sample target-valued dataset shipped with the `dimension_reduction_protocols` library:

    | ?- logtalk_load(dimension_reduction_protocols('test_datasets/target_latent_measurements')).

### Learning a reducer

    | ?- pls_projection::learn(target_latent_measurements, DimensionReducer).

    | ?- pls_projection::learn(target_latent_measurements, DimensionReducer, [n_components(1), feature_scaling(false)]).

### Transforming new instances

    | ?- pls_projection::learn(target_latent_measurements, DimensionReducer, [n_components(2)]),
         pls_projection::transform(DimensionReducer, [f1-4.0, f2-8.0, f3-2.0, f4-(-2.0)], ReducedInstance).

### Exporting and reusing the reducer

    | ?- pls_projection::learn(target_latent_measurements, DimensionReducer, [n_components(2)]),
         pls_projection::export_to_file(target_latent_measurements, DimensionReducer, reducer, 'pls_projection_reducer.pl').

    | ?- logtalk_load('pls_projection_reducer.pl'),
         reducer(Reducer),
         pls_projection::transform(Reducer, [f1-4.0, f2-8.0, f3-2.0, f4-(-2.0)], ReducedInstance).

## Dimension reducer representation

The learned dimension reducer is represented by a compound term with the functor chosen by the implementation and arity 3. For example:

    pls_projection_reducer(Encoders, Rotations, Diagnostics)

Where:

- `Encoders`: List of continuous attribute encoders storing attribute name, mean, and scale.

- `Rotations`: List of direct PLS projection vectors derived from the learned latent weights and loadings.

- `Diagnostics`: Learned metadata including the effective training options, target information, target loadings, and optional truncate-mode shortfall details.

When exported using `export_to_clauses/4` or `export_to_file/4`, this reducer term is serialized directly as the single argument of the generated predicate clause so that the exported model can be loaded and reused as-is.

## References

1. Wold, H. (1975) - “Soft modelling by latent variables; the nonlinear iterative partial least squares (NIPALS) approach”.

2. Geladi, P. and Kowalski, B. R. (1986) - “Partial least-squares regression: a tutorial”.