Matrix data scaling and normalization using double precision. More...

#include <dmlfw_matrix.h>

Include dependency graph for dmlfw_scale_double.h:

This graph shows which files directly or indirectly include this file:

dmlfw_mat_double *	dmlfw_scale_double (char dataset_file_name, dmlfw_row_vec_string columns_to_scale, char parameters_file_name, char algorithm, dmlfw_mat_double *matrix)
	Scales data from a dataset according to specified columns and algorithm.

dmlfw_mat_double *	dmlfw_scale_double_min_max (dmlfw_mat_double matrix, index_t start_row_index, index_t start_column_index, index_t end_row_index, index_t end_column_index, dmlfw_mat_double min_max_matrix, dmlfw_mat_double scaled_matrix)
	Performs min-max scaling on a submatrix slice and optionally returns min-max matrix.

dmlfw_mat_double *	dmlfw_scale_double_with_given_min_max (dmlfw_mat_double matrix, index_t start_row_index, index_t start_column_index, index_t end_row_index, index_t end_column_index, dmlfw_mat_double min_max_matrix, dmlfw_mat_double *scaled_matrix)
	Scales matrix using given min-max matrix for normalization.

dmlfw_mat_double *	dmlfw_scale_double_with_given_parameters (char dataset_file_name, char parameters_file_name, char algorithm, dmlfw_mat_double matrix)
	Scales data using pre-computed parameters according to algorithm.

dmlfw_mat_double *	dmlfw_scale_double_z_score (dmlfw_mat_double matrix, index_t start_row_index, index_t start_column_index, index_t end_row_index, index_t end_column_index, dmlfw_mat_double mean_standard_deviation_matrix, dmlfw_mat_double scaled_matrix)
	Performs z-score scaling on a submatrix slice, optionally returning mean/std matrix.

dmlfw_mat_double *	dmlfw_scale_double_z_score_with_given_mean_standard_deviation (dmlfw_mat_double matrix, index_t start_row_index, index_t start_column_index, index_t end_row_index, index_t end_column_index, dmlfw_mat_double mean_standard_deviation_matrix, dmlfw_mat_double *scaled_matrix)
	Scales matrix using given mean and standard deviation matrix.

#define	MLFW_MIN_MAX_SCALING_ALGORITHM "min-max"

#define	MLFW_Z_SCORE_SCALING_ALGORITHM "z-score"

Detailed Description

Matrix data scaling and normalization using double precision.

Version: 1.0

Date: 2025-09-25

This module provides scaling algorithms applied to double precision matrices, such as min-max normalization and z-score standardization.

Algorithms include:

Min-Max scaling (rescale to [0,1])
Z-Score scaling (mean 0, standard deviation 1)

Functions support loading scaling parameters from files and applying previously computed parameters to new data.

Error Handling:

All functions validate input parameters and interoperability. Errors are reported via the centralized error API, using dmlfw_error(), dmlfw_get_error_string(), and dmlfw_get_debug_string().

Ownership:

Caller owns all input matrices. Output matrices are allocated if NULL is passed, and ownership passes to the caller, who must free them.

Macro Definition Documentation

◆ MLFW_MIN_MAX_SCALING_ALGORITHM

#define MLFW_MIN_MAX_SCALING_ALGORITHM "min-max"

Min-Max scaling algorithm identifier string.

Examples: example_dmlfw_scale_double.c.

◆ MLFW_Z_SCORE_SCALING_ALGORITHM

#define MLFW_Z_SCORE_SCALING_ALGORITHM "z-score"

Z-Score scaling algorithm identifier string.

Function Documentation

◆ dmlfw_scale_double()

dmlfw_mat_double * dmlfw_scale_double	(	char *	dataset_file_name,
		dmlfw_row_vec_string *	columns_to_scale,
		char *	parameters_file_name,
		char *	algorithm,
		dmlfw_mat_double *	matrix
	)

Scales data from a dataset according to specified columns and algorithm.

Parameters

dataset_file_name	[in] File path of the dataset (CSV or supported format).
columns_to_scale	[in] Row vector of column names/labels to scale.
parameters_file_name	[in] Path to save or read scaling parameters.
algorithm	[in] Scaling algorithm identifier: "min-max" or "z-score".
matrix	[in,out] Optional pre-allocated matrix to store scaled data, or NULL to allocate a new one.

Returns: Pointer to the scaled matrix or NULL on error.

Usage example:

char err[512], dbg[512];
dmlfw_mat_double *scaled = dmlfw_scale_double("input.csv", cols_to_scale, "params.json", MLFW_MIN_MAX_SCALING_ALGORITHM, NULL);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Scaling error: %s\nDebug: %s\n", err, dbg);
    return NULL;
}
// use scaled...
dmlfw_mat_double_destroy(scaled);

Examples: example_dmlfw_scale_double.c.

◆ dmlfw_scale_double_min_max()

dmlfw_mat_double * dmlfw_scale_double_min_max	(	dmlfw_mat_double *	matrix,
		index_t	start_row_index,
		index_t	start_column_index,
		index_t	end_row_index,
		index_t	end_column_index,
		dmlfw_mat_double **	min_max_matrix,
		dmlfw_mat_double *	scaled_matrix
	)

Performs min-max scaling on a submatrix slice and optionally returns min-max matrix.

Parameters

matrix	[in] Input matrix.
start_row_index	[in] Start index for rows (inclusive).
start_column_index	[in] Start index for columns (inclusive).
end_row_index	[in] End index for rows (inclusive).
end_column_index	[in] End index for columns (inclusive).
min_max_matrix	[out] Optional pointer to store min and max values matrix, allocated if NULL.
scaled_matrix	[in,out] Optional matrix to store the scaled data, or NULL to allocate a new matrix.

Returns: Pointer to scaled matrix or NULL on error.

◆ dmlfw_scale_double_with_given_min_max()

dmlfw_mat_double * dmlfw_scale_double_with_given_min_max	(	dmlfw_mat_double *	matrix,
		index_t	start_row_index,
		index_t	start_column_index,
		index_t	end_row_index,
		index_t	end_column_index,
		dmlfw_mat_double *	min_max_matrix,
		dmlfw_mat_double *	scaled_matrix
	)

Scales matrix using given min-max matrix for normalization.

Parameters

matrix	[in] Input matrix to scale.
start_row_index	[in] Start row index for submatrix.
start_column_index	[in] Start column index for submatrix.
end_row_index	[in] End row index for submatrix.
end_column_index	[in] End column index for submatrix.
min_max_matrix	[in] Matrix containing min and max values per column.
scaled_matrix	[in,out] Optional matrix to hold scaled result, or NULL for allocation.

Returns: Pointer to scaled matrix or NULL on error.

◆ dmlfw_scale_double_with_given_parameters()

dmlfw_mat_double * dmlfw_scale_double_with_given_parameters	(	char *	dataset_file_name,
		char *	parameters_file_name,
		char *	algorithm,
		dmlfw_mat_double *	matrix
	)

Scales data using pre-computed parameters according to algorithm.

Parameters

dataset_file_name	[in] Dataset source file path.
parameters_file_name	[in] File for reading pre-computed scaling parameters.
algorithm	[in] Scaling algorithm identifier.
matrix	[in,out] Optional matrix to output scaled data, or NULL to allocate.

Returns: Pointer to scaled matrix or NULL on error.

◆ dmlfw_scale_double_z_score()

dmlfw_mat_double * dmlfw_scale_double_z_score	(	dmlfw_mat_double *	matrix,
		index_t	start_row_index,
		index_t	start_column_index,
		index_t	end_row_index,
		index_t	end_column_index,
		dmlfw_mat_double **	mean_standard_deviation_matrix,
		dmlfw_mat_double *	scaled_matrix
	)

Performs z-score scaling on a submatrix slice, optionally returning mean/std matrix.

Parameters

matrix	[in] Input matrix.
start_row_index	[in] Start row index (inclusive).
start_column_index	[in] Start column index (inclusive).
end_row_index	[in] End row index (inclusive).
end_column_index	[in] End column index (inclusive).
mean_standard_deviation_matrix	[out] Optional pointer for mean and std dev, allocated if NULL.
scaled_matrix	[in,out] Matrix to store scaled data or NULL to allocate.

Returns: Pointer to scaled matrix or NULL on error.

◆ dmlfw_scale_double_z_score_with_given_mean_standard_deviation()

dmlfw_mat_double * dmlfw_scale_double_z_score_with_given_mean_standard_deviation	(	dmlfw_mat_double *	matrix,
		index_t	start_row_index,
		index_t	start_column_index,
		index_t	end_row_index,
		index_t	end_column_index,
		dmlfw_mat_double *	mean_standard_deviation_matrix,
		dmlfw_mat_double *	scaled_matrix
	)

Scales matrix using given mean and standard deviation matrix.

Parameters

matrix	[in] Input matrix.
start_row_index	[in] Start row index for scaling.
start_column_index	[in] Start column index for scaling.
end_row_index	[in] End row index for scaling.
end_column_index	[in] End column index for scaling.
mean_standard_deviation_matrix	[in] Matrix with mean and std deviation.
scaled_matrix	[in,out] Matrix for scaled output or NULL to allocate.

Returns: Pointer to scaled matrix or NULL on error.