.\" Text automatically generated by txt2man
.TH mlpack_sparse_coding 1 "11 January 2024" "mlpack-4.3.0" "User Commands"
.SH NAME
\fBmlpack_sparse_coding \fP- sparse coding
.SH SYNOPSIS
.nf
.fam C
 \fBmlpack_sparse_coding\fP [\fB-k\fP \fIint\fP] [\fB-i\fP \fIunknown\fP] [\fB-m\fP \fIunknown\fP] [\fB-l\fP \fIdouble\fP] [\fB-L\fP \fIdouble\fP] [\fB-n\fP \fIint\fP] [\fB-w\fP \fIdouble\fP] [\fB-N\fP \fIbool\fP] [\fB-o\fP \fIdouble\fP] [\fB-s\fP \fIint\fP] [\fB-T\fP \fIunknown\fP] [\fB-t\fP \fIunknown\fP] [\fB-V\fP \fIbool\fP] [\fB-c\fP \fIunknown\fP] [\fB-d\fP \fIunknown\fP] [\fB-M\fP \fIunknown\fP] [\fB-h\fP \fB-v\fP] 
.fam T
.fi
.fam T
.fi
.SH DESCRIPTION


An implementation of Sparse Coding with Dictionary Learning, which achieves
sparsity via an l1-norm regularizer on the codes (LASSO) or an (l1+l2)\fB-norm\fP
regularizer on the codes (the Elastic Net). Given a dense data matrix X with
d dimensions and n points, sparse coding seeks to find a dense dictionary
matrix D with k atoms in d dimensions, and a sparse coding matrix Z with n
points in k dimensions.
.PP
The original data matrix X can then be reconstructed as Z * D. Therefore,
this program finds a representation of each point in X as a sparse linear
combination of atoms in the dictionary D.
.PP
The sparse coding is found with an algorithm which alternates between a
dictionary step, which updates the dictionary D, and a sparse coding step,
which updates the sparse coding matrix.
.PP
Once a dictionary D is found, the sparse coding model may be used to encode
other matrices, and saved for future usage.
.PP
To run this program, either an input matrix or an already-saved sparse coding
model must be specified. An input matrix may be specified with the
\(cq\fB--training_file\fP (\fB-t\fP)' option, along with the number of atoms in the
dictionary (specified with the '\fB--atoms\fP (\fB-k\fP)' parameter). It is also possible
to specify an initial dictionary for the optimization, with the
\(cq\fB--initial_dictionary_file\fP (\fB-i\fP)' parameter. An input model may be specified
with the '\fB--input_model_file\fP (\fB-m\fP)' parameter.
.PP
As an example, to build a sparse coding model on the dataset 'data.csv' using
200 atoms and an l1-regularization parameter of 0.1, saving the model into
\(cqmodel.bin', use 
.PP
$ \fBmlpack_sparse_coding\fP \fB--training_file\fP data.csv \fB--atoms\fP 200 \fB--lambda1\fP 0.1
\fB--output_model_file\fP model.bin
.PP
Then, this model could be used to encode a new matrix, 'otherdata.csv', and
save the output codes to 'codes.csv': 
.PP
$ \fBmlpack_sparse_coding\fP \fB--input_model_file\fP model.bin \fB--test_file\fP otherdata.csv
\fB--codes_file\fP codes.csv
.RE
.PP

.SH OPTIONAL INPUT OPTIONS 

.TP
.B
\fB--atoms\fP (\fB-k\fP) [\fIint\fP]
Number of atoms in the dictionary. Default value 15. 
.TP
.B
\fB--help\fP (\fB-h\fP) [\fIbool\fP]
Default help info. 
.TP
.B
\fB--info\fP [string]
Print help on a specific option. Default value ''. 
.TP
.B
\fB--initial_dictionary_file\fP (\fB-i\fP) [\fIunknown\fP]
Optional initial dictionary matrix. 
.TP
.B
\fB--input_model_file\fP (\fB-m\fP) [\fIunknown\fP]
File containing input sparse coding model. 
.TP
.B
\fB--lambda1\fP (\fB-l\fP) [\fIdouble\fP]
Sparse coding l1-norm regularization parameter.  Default value 0. 
.TP
.B
\fB--lambda2\fP (\fB-L\fP) [\fIdouble\fP]
Sparse coding l2-norm regularization parameter.  Default value 0. 
.TP
.B
\fB--max_iterations\fP (\fB-n\fP) [\fIint\fP]
Maximum number of iterations for sparse coding (0 indicates no limit). Default value 0. 
.TP
.B
\fB--newton_tolerance\fP (\fB-w\fP) [\fIdouble\fP]
Tolerance for convergence of Newton method.  Default value 1e-06. 
.TP
.B
\fB--normalize\fP (\fB-N\fP) [\fIbool\fP]
If set, the input data matrix will be normalized before coding. 
.TP
.B
\fB--objective_tolerance\fP (\fB-o\fP) [\fIdouble\fP]
Tolerance for convergence of the objective function. Default value 0.01. 
.TP
.B
\fB--seed\fP (\fB-s\fP) [\fIint\fP]
Random seed. If 0, 'std::time(NULL)' is used.  Default value 0. 
.TP
.B
\fB--test_file\fP (\fB-T\fP) [\fIunknown\fP]
Optional matrix to be encoded by trained model. 
.TP
.B
\fB--training_file\fP (\fB-t\fP) [\fIunknown\fP]
Matrix of training data (X). 
.TP
.B
\fB--verbose\fP (\fB-v\fP) [\fIbool\fP]
Display informational messages and the full list of parameters and timers at the end of execution. 
.TP
.B
\fB--version\fP (\fB-V\fP) [\fIbool\fP]
Display the version of mlpack.  
.SH OPTIONAL OUTPUT OPTIONS 

.TP
.B
\fB--codes_file\fP (\fB-c\fP) [\fIunknown\fP]
Matrix to save the output sparse codes of the test matrix (\fB--test_file\fP) to. 
.TP
.B
\fB--dictionary_file\fP (\fB-d\fP) [\fIunknown\fP]
Matrix to save the output dictionary to. 
.TP
.B
\fB--output_model_file\fP (\fB-M\fP) [\fIunknown\fP]
File to save trained sparse coding model to.
.SH ADDITIONAL INFORMATION

For further information, including relevant papers, citations, and theory,
consult the documentation found at http://www.mlpack.org or included with your
distribution of mlpack.