Data scaling: API and documentation

[elcorto]

From mala/datahandling/data_scaler.py:

DataScaler.transform()

    def transform(self, unscaled):
        """
        Transform data from unscaled to scaled.

        Unscaled means real world data, scaled means data as is used in
        the network. Data is transformed in-place.

        Parameters
        ----------
        unscaled : torch.Tensor
            Real world data.

        Returns
        -------
        scaled : torch.Tensor
            Scaled data.
        """

That method in-place modifies the array unscaled (that is documented), but it returns nothing (so None), so the doc string needs to be adapted (remove Returns section).

The method DataScaler.inverse_transform() returns a new array and doesn't modify the scaled input array.

The naming of the methods suggests that DataScaler operates like e.g., sklearn.preprocessing.StandardScaler, but this API is different in the following ways:

• methods always return a transformed array
• methods have a copy arg that allows to select whether in-place mods are desired, see transform() and inverse_transform()
• the equivalent of DataScaler's start_incremental_fitting() + incremental_fit() + finish_incremental_fitting() is probably targeting the functionality of StandardScaler.partial_fit() but seems more complex?
• Scaling always operates on feature columns and $X$ is assumed to have shape (n_samples, n_features) (see also Data scaling: row vs. column and naming of methods #482)