C API Reference

Double Vector Functions

struct dvector

A dynamic array of doubles. The dvector struct is a dynamic array of double represented by a pointer to a double and its size (size_t size).

• data A pointer to a double type.

• size The size of the array of strings.

void NewDVector(dvector **d, size_t size)

Allocate a dvector with a specific size

void DelDVector(dvector **d)

Delete a dvector

void initDVector(dvector **d)

initialize an empty dvector

void DVectorAppend(dvector *d, double val)

Append a value to a dvector

void DVectorRemoveAt(dvector *d, size_t indx)

Remove a value to a dvector

void PrintDVector(dvector *v)

Print a dvector to video

Unsigned int Vector Functions

struct uivector

A dynamic array of unsigned integers. The dvector struct is a dynamic array of unsigned integers represented by a pointer to a unsigned integers and its size (size_t size).

• data A pointer to unsigned integer type.

• size The size of the array of strings.

void NewUIVector(uivector **d, size_t size)

Allocate a uivector with a specific size

void DelUIVector(uivector **d)

Delete a uivector

void initUIVector(uivector **d)

Initialize an empty uivector

void UIVectorAppend(uivector *d, size_t val)

Append a value to an uivector

void UIVectorRemoveAt(uivector *d, size_t indx)

Remove a value to an uivector

void PrintUIVector(uivector *v)

Print an uivector

Int Vector Functions

struct ivector

A dynamic array of integers. The dvector struct is a dynamic array of integers represented by a pointer to a integers and its size (size_t size).

• data A pointer to a double type.

• size The size of the array of strings.

void NewIVector(ivector **d, size_t size)

Allocate a ivector with a specific size

void DelIVector(ivector **d)

Delete a ivector

void initIVector(ivector **d)

Initialize an ivector

void IVectorAppend(ivector *d, int val)

Append a value to an ivector

void IVectorRemoveAt(ivector *d, size_t indx)

Remove a value to a ivector

void PrintIVector(ivector *v)

Print to video an ivector

String Vector Functions

struct strvector

A dynamic array of strings. The strvector struct is a dynamic array of strings represented by a pointer to a character pointer (char data) and its size (size_t size).

• data A pointer to a character pointer representing the array of strings.

• size The size of the array of strings.

void NewStrVector(strvector **s, size_t size)

Allocate a strvector with a specific size

void DelStrVector(strvector **s)

Delete a strvector

void initStrVector(strvector **s)

initialize an empty strvector

void StrVectorAppend(strvector *s, char *str)

Append a string value to a strvector

void PrintStrVector(strvector *s)

Print to video a strvector

Matrix Functions

struct matrix

Matrix data structure

• data two dimensional array of double

• row number of rows

• col number of columns

void NewMatrix(matrix **m, size_t row_, size_t col_)

Allocate a matrix in memory with dimension “row” and “col”

Parameters

• m – matrix data structure

• row – number of rows

• col – number of columns

void DelMatrix(matrix**)

Destroy a matrix allocation

void initMatrix(matrix **m)

Description: Allocate a matrix in memory without a dimension.

void MatrixAppendRow(matrix *m, dvector *row)

Append double vector uivector as row.

void MatrixAppendCol(matrix *m, dvector *col)

Append double vector uivector as column.

void MatrixDeleteRowAt(matrix *m, size_t row)

Delete a specific row in a matrix

void MatrixDeleteColAt(matrix *m, size_t col)

Delete a specific column in a matrix

void PrintMatrix(matrix *m)

Print a matrix to cmdout

Tensor Functions

struct tensor

Tensor data structure

• m list of matrix

• order number of matrix layers

void NewTensor(tensor **t, size_t order_)

Create a new empty tensor with a predefined order.

void NewTensorMatrix(tensor *t, size_t order, size_t row, size_t col)

Create into an empty tensor a matrix of “row x col” at position “order”

Parameters

• t – input tensor

• order – point where to add the matrix

• row – number of rows of the matrix

• col – number of columns of the matrix

void AddTensorMatrix(tensor *t, size_t row, size_t col)

Append to a tensor a matrix at the end of it.

Parameters

• t – input tensor

• row – number of rows of the matrix

• col – number of columns of the matrix

void DelTensor(tensor **t)

Delete a tensor and free up the memory.

void initTensor(tensor **t)

Initialize an empty tensor

void PrintTensor(tensor *t)

Print to video the tensor.

PCA Functions

struct PCAMODEL

PCA model data structure.

• scores matrix of scores

• loadings matrix of loadings

• varexp vector of explained variance by every component

• colaverage input matrix column average

• colscaling input matrix column scaling

void NewPCAModel(PCAMODEL **m)

Initialize an empty PCAMODEL

void DelPCAModel(PCAMODEL **m)

Delete a PCAMODEL

void PCA(matrix *mx, int scaling, size_t npc, PCAMODEL *model, ssignal *s)

Calculate a principal component analysis using the NIPALS algorithm.

Available scalings:

• 0: No scaling. Only mean centering

• 1: Mean centering and STDEV scaling

• 2: Mean centering and Root-Mean-Square column scaling

• 3: Mean centering and Pareto scaling

• 4: Mean centering and min-max range scaling

• 5: Mean centering and level scaling

Returns Nothing.

Parameters

• mx – libscientific matrix data input

• scaling – scaling type expressed as unsigned int type

• npc – number of desired principal components

• PCAMODEL – initialized model using NewPCAModel(…). The datastructure will be populated with results

• ssignal – libscientific signal. Default value is NULL

void PCAScorePredictor(matrix *mx, PCAMODEL *model, size_t npc, matrix *pscores)

Predict scores given a principal component analysis and a matrix as input.

Returns Nothing.

Parameters

• mx – libscientific matrix data input

• npc – number of desired principal components

• pscores – predicted scores

• PCAMODEL – pca model input

void PCAIndVarPredictor(matrix *t, matrix *p, dvector *colaverage, dvector *colscaling, size_t npc, matrix *mx)

Reconstruct the original input matrix from PCA model using scores and loadings.

Returns Nothing.

Parameters

• t – pca scores with size #objects x npc

• p – pca loadings with size npc x #features

• colaverage – input column average with size #features

• colscaling – input column scaling with size #features

• npc – desired principal components to use for the matrix reconstruction

• mx – ouptut reconstructed matrix

void GetResidualMatrix(matrix *mx, PCAMODEL *model, size_t pc, matrix *rmx)

Compute the residual matrix for a specific number of component.

Returns Nothing.

Parameters

• mx – original input matrix

• model – computed pca model

• pc – max component to extract the residual matrix

• rmx – residual matrix of output

void PrintPCA(PCAMODEL *m)

Print PCAMODEL to video.

Parameters

• m – computed pca model

CPCA Functions

struct CPCAMODEL

CPCA model data structure.

• block_scores matrix of scores

• block_loadings matrix of loadings

• super_scores matrix of super scores

• super_weights matrix of super weigths

• scaling_factor dvector of scaling factors

• total_expvar dvector of total explained variance

• block_expvar dvector list of block explained variance

• colaverage dvector list of column average

• colscaling dvector list of column scaling

void NewCPCAModel(CPCAMODEL **m)

Inizialize a new CPCA Model

void DelCPCAModel(CPCAMODEL **m)

Delete a new CPCA Model

void CPCA(tensor *x, int scaling, size_t npc, CPCAMODEL *model)

Consensus Principal Component Analysis

Available scalings:

• 0: No scaling. Only mean centering

• 1: Mean centering and STDEV scaling

• 2: Mean centering and Root-Mean-Square column scaling

• 3: Mean centering and Pareto scaling

• 4: Mean centering and min-max range scaling

• 5: Mean centering and level scaling

Parameters

• x – libscientific tensor data input

• scaling – scaling type expressed as unsigned int type

• npc – number of desired principal components

• model – initialized model using NewCPCAModel(…). The datastructure will be populated with results

void CPCAScorePredictor(tensor *x, CPCAMODEL *model, size_t npc, matrix *p_super_scores, tensor *p_block_scores)

Project objects in a CPCA model.

Parameters

• x – libscientific tensor data input

• model – CPCA model

• npc – number of desired principal components

• p_super_scores – predicted super scores

• p_block_scores – predicted block of scores

void PrintCPCA(CPCAMODEL *m)

Print CPCAMODEL to video.

Returns Nothing.

Parameters

• m – computed cpca model

PLS Functions

struct PLSMODEL

PLS model data structure

• xscores x space scores

• xloadings x space loadings

• xweights x space weights

• yscores y space scores

• yloadings y space loadings

• b pls regression coefficients

• xvarexp variance explained in the x space

• xcolaverage x independent variable column average

• xcolscaling x independent variable column scaling

• ycolaverage y independent variable column average

• ycolscaling y independent variable column scaling

• recalculated_y y recalculated

• recalc_residuals y recalculated residuals

• predicted_y y predicted

• pred_residuals y predicted residuals

• r2y_recalculated r squared using y recalculated values

• r2y_validation

• q2y q squared using y predicted values

• sdep standard deviation over prediction using y predictions

• sdec standard deviation over recalculation using y recalculated

• bias bias

• roc_recalculated receiver operating characteristic using y recalculated

• roc_validation receiver operating characteristic using y predicted

• roc_auc_recalculated receiver operating characteristic area under the curve using y recalculated

• roc_auc_validation eceiver operating characteristic area under the curve using y predicted

• precision_recall_recalculated precision-recall curve using y recalculated

• precision_recall_validation precision-recall curve using y predicted

• precision_recall_ap_recalculated precision-recall aread under the curve using y recalculated

• precision_recall_ap_validation precision-recall aread under the curve using y predicted

• yscrambling y-scrambling r-squared and q-squared

void NewPLSModel(PLSMODEL **m)

Create a new PLSMODEL

void DelPLSModel(PLSMODEL **m)

Delete a PLSMODEL

void PLS(matrix *mx, matrix *my, size_t nlv, int xautoscaling, int yautoscaling, PLSMODEL *model, ssignal *s)

Calculate a partial least squares model using the NIPALS algorithm.

Available scalings:

• 0: No scaling. Only mean centering

• 1: Mean centering and STDEV scaling

• 2: Mean centering and Root-Mean-Square column scaling

• 3: Mean centering and Pareto scaling

• 4: Mean centering and min-max range scaling

• 5: Mean centering and level scaling

Returns Nothing.

Parameters

• mx – libscientific matrix data input: x independent variables

• my – libscientific matrix data input: y dependent variables

• nlv – number of desired latent variables

• xautoscaling – scaling typeon the x independent variables expressed as unsigned int type

• yautoscaling – scaling typeon the y dependent variables expressed as unsigned int type

• PLSMODEL – output -initialized model using NewPLSAModel(…). The datastructure will be populated with results

• ssignal – libscientific signal. Default value is NULL.

void PLSBetasCoeff(PLSMODEL *model, size_t nlv, dvector *betas)

Calculate betas coefficients from a pls model at specific nlv latent variables

Parameters

• model – libscientific matrix data input: x independent variables

• nlv – number of desired latent variables

• betas – output - initialized libscientific dvector

void PLSScorePredictor(matrix *mx, PLSMODEL *model, size_t nlv, matrix *xscores)

Project a matrix and predict the scores into the new space. This function is used before predict the Y values

Parameters

• mx – libscientific matrix data input: x independent variables

• model – PLSMODEL

• nlv – number of desired latent variables

• xscores – output - initialized libscientific matrix

void PLSYPredictor(matrix *tscore, PLSMODEL *model, size_t nlv, matrix *y)

Calculate the Y values at a specific lv number (nlv).

N.B.: The output of y will be: [y->row][y-col]

Parameters

• tscore – input matrix of scores calculated using PLSScorePredictor

• model – PLSMODEL

• nlv – number of desired latent variables

• y – output - initialized libscientific matrix

void PLSYPredictorAllLV(matrix *mx, PLSMODEL *model, matrix *tscores, matrix *y)

Calculate the Y values at all the lv.

N.B.: The output of y will be: [y->row][y->col*nlv]

Parameters

• mx – input matrix of scores calculated using PLSScorePredictor

• model – PLSMODEL

• tscores – output - predicted scores

• y – output - y predicted

void PLSRegressionStatistics(matrix *my_true, matrix *my_pred, matrix *ccoeff, matrix *rmse, matrix *bias)

Calculate the correlation coefficient (ccoeff), the root mean square error of the prediction (rmse), the bias of the prediction (bias) in a regression model. mx and my could be the training or the test datasets.

Parameters

• my_true – input matrix of y true values

• my_pred – input matrix of y predicted or recalculated values

• ccoeff – output - correlation coefficients q-squared or r-squared if my_pred is respectivelly predicted or recalculated

• rmse – output - root mean square error

• bias – output - bias defined as how distant are we from the diagonal

void PLSDiscriminantAnalysisStatistics(matrix *my_true, matrix *my_score, tensor *roc, matrix *roc_auc, tensor *precision_recall, matrix *precision_recall_ap)

Calculate the roc curve, the auc, the precision recall curve, the precision_recall_auc of a classification model. mx and my could be the training or the test datasets.

Parameters

• my_true – input matrix of y true values

• roc – output - roc curves

• roc_auc – output - roc AUCs

• precision_recall – output - precision-recall curves

• precision_recall_ap – output - precision-recall AUCs

• my_scores – input matrix of y predicted or recalculated class scores/probabilities

int GetLVCCutoff(matrix *coeff)

Get the Cutoff based on the grow of r2, q2 in case of regression or auc in case of classification.

void PrintPLSModel(PLSMODEL *model)

Print to video a PLSMODEL

MLR Functions

struct MLRMODEL

Multiple Linear Regression data structure

• b beta coefficients

• recalculated_y y recalculated

• predicted_y y predicted

• recalc_residuals residuals using recalculated values

• pred_residuals residuals using predicted values

• ymean y averages

• r2y_model model r-squared using y recalculated

• q2y model q-squared using y predicted

• sdep standard deviation over prediction

• sdec standard deviation over recalculation

• bias model bias

• r2q2scrambling y scrambling results

void NewMLRModel(MLRMODEL **m)

Initialize an MLR model

void DelMLRModel(MLRMODEL **m)

Delete a MLR model

void MLR(matrix *mx, matrix *my, MLRMODEL *model, ssignal *s)

Calculate a MLR model using OLS algorithm

Parameters

• mx – x independent variables input

• my – y dependent variables input

• model – initialized model using NewMLRModel(…). The datastructure will be populated with results

void MLRPredictY(matrix *mx, matrix *my, MLRMODEL *model, matrix *predicted_y, matrix *predicted_residuals, dvector *r2y, dvector *sdep)

Predict Y targets using a MLR model

Parameters

• mx – x independent variables input

• my – y dependent variables input (if known)

• model – computed MLRMODEL

• predicted_y – y predicted

• predicted_residuals – residuals using y predicted

• r2y – r-squared of the prediction if my known

• sdep – standard deviation over prediction if my known

void MLRRegressionStatistics(matrix *my_true, matrix *my_pred, dvector *ccoeff, dvector *rmse, dvector *bias)

Calculate the correlation coefficient (ccoeff), the standard deviation of the prediction (stdev), the bias of the prediction (bias) in a regression model. mx and my could be the training or the test datasets.

Parameters

• my_true – input matrix of y true values

• my_pred – input matrix of y predicted or recalculated values

• ccoeff – output - correlation coefficients q-squared or r-squared if my_pred is respectivelly predicted or recalculated

• rmse – output - root mean square error

• bias – output - bias defined as how distant are we from the diagonal

void PrintMLR(MLRMODEL *m)

Print MRLMODEL to video.

Returns Nothing.

Parameters

• m – computed mlr model

LDA Functions

struct LDAMODEL

void NewLDAModel(LDAMODEL **m)

Initialize and LDAMODEL

void DelLDAModel(LDAMODEL **m)

Delete and LDAMODEL

void LDA(matrix *mx, matrix *my, LDAMODEL *lda)

Calculate and LDA Fisher discriminant analyisis model

Parameters

• mx – input matrix of independent variables

• my – input matrix of classes

• lda – initialized model using NewLDAModel(…). The datastructure will be populated with results

void LDAPrediction(matrix *mx, LDAMODEL *lda, matrix *pfeatures, matrix *probability, matrix *mnpdf, matrix *prediction)

Predict classes using an LDA fisher discriminant analysis model

Parameters

• mx – input matrix of independent variables

• lda – computed LDAMODEL

• pfeatures – predicted features

• probabilities –

• multivariate – normal probability distribution of features

• predicted – classes

void LDAStatistics(dvector *y_true, dvector *y_pred, matrix *roc, double *roc_auc, matrix *precision_recal, double *pr_auc)

Binary statistics

void LDAMulticlassStatistics(matrix *y_true, matrix *y_pred, tensor *roc, dvector *roc_aucs, tensor *precision_recals, dvector *pr_aucs)

Multiclass statistics

void PrintLDAModel(LDAMODEL *m)

Print LDAMODEL to video.

Returns Nothing.

Parameters

• m – computed lda model

UPCA Functions

struct UPCAMODEL

UPCA model data structure.

• scores matrix of scores

• loadings tesnor of loadings

• varexp vector of explained variance by every component

• colaverage vector list of column average

• colaverage vector list of column scaling

void NewUPCAModel(UPCAMODEL **m)

Initialize an empty UPCAMODEL

void DelUPCAModel(UPCAMODEL **m)

Delete an UPCAMODEL

void UPCA(tensor *X, size_t npc, size_t autoscaling, UPCAMODEL *m, ssignal *s)

Unfolded Principal Component Analysis

Available scalings:

• 0: No scaling. Only mean centering

• 1: Mean centering and STDEV scaling

• 2: Mean centering and Root-Mean-Square column scaling

• 3: Mean centering and Pareto scaling

• 4: Mean centering and min-max range scaling

• 5: Mean centering and level scaling

Parameters

• X – input tensor

• npc – number of desired principal components

• autoscaling –

• m – initialized model using NewUPCAModel(…). The datastructure will be populated with results

• ssignal – libscientific signal. Default value is NULL

void UPCAScorePredictor(tensor *X, UPCAMODEL *model, size_t npc, matrix *pscores)

Predict scores given an unfolded principal component analysis and a tensor as input.

Parameters

• X – input tensor

• model – computed UPCAMODEL

• npc – number of desired principal components

• pscores – predicted scores

void UPCAIndVarPredictor(matrix *T, tensor *P, dvectorlist *colaverage, dvectorlist *colscaling, size_t npc, tensor *X)

Reconstruct the original input tensor from UPCA model using scores and loadings.

Returns Nothing.

Parameters

• colaverage – input list of column average with size #features

• colscaling – input list of column scaling with size #features

• npc – desired principal components to use for the tensor reconstruction

• X – ouptut reconstructed tensor

• t – upca scores with size #objects x npc

• p – upca loadings with size order x npc x #features

void PrintUPCAModel(UPCAMODEL *m)

Print UPCAMODEL to video.

Parameters

• m – computed upca model

Object Selection Functions