SHOGUN  3.2.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
general_altra.h
Go to the documentation of this file.
1 /* This program is free software: you can redistribute it and/or modify
2  * it under the terms of the GNU General Public License as published by
3  * the Free Software Foundation, either version 3 of the License, or
4  * (at your option) any later version.
5  *
6  * This program is distributed in the hope that it will be useful,
7  * but WITHOUT ANY WARRANTY; without even the implied warranty of
8  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
9  * GNU General Public License for more details.
10  *
11  * You should have received a copy of the GNU General Public License
12  * along with this program. If not, see <http://www.gnu.org/licenses/>.
13  *
14  * Copyright (C) 2009 - 2012 Jun Liu and Jieping Ye
15  */
16 
17 #ifndef GENERAL_ALTRA_SLEP
18 #define GENERAL_ALTRA_SLEP
19 
20 #include <shogun/lib/config.h>
21 
22 #include <stdio.h>
23 #include <stdlib.h>
24 #include <math.h>
25 #include <string.h>
26 
27 /*
28  * Important Notice: September 20, 2010
29  *
30  * In this head file, we deal with the case that the features might not be well ordered.
31  *
32  * If the features in the tree strucutre are well ordered, i.e., the indices of the left nodes is always less
33  * than the right nodes, please refer to "altra.h".
34  *
35  * The advantage of "altra.h" is that, we donot need to use an explicit
36  * variable for recording the indices.
37  *
38  *
39  */
40 
41 /*
42  * -------------------------------------------------------------------
43  * Functions and parameter
44  * -------------------------------------------------------------------
45  *
46  * general_altra solves the following problem
47  *
48  * 1/2 \|x-v\|^2 + \sum \lambda_i \|x_{G_i}\|,
49  *
50  * where x and v are of dimension n,
51  * \lambda_i >=0, and G_i's follow the tree structure
52  *
53  * It is implemented in Matlab as follows:
54  *
55  * x=general_altra(v, n, G, ind, nodes);
56  *
57  * G contains the indices of the groups.
58  * It is a row vector. Its length equals to \sum_i \|G_i\|.
59  * If all the entries are penalized with L1 norm,
60  * its length is \sum_i \|G_i\| - n.
61  *
62  * ind is a 3 x nodes matrix.
63  * Each column corresponds to a node.
64  *
65  * The first element of each column is the starting index,
66  * the second element of each column is the ending index
67  * the third element of each column corrreponds to \lambbda_i.
68  *
69  *
70  *
71  * The following example shows how G and ind works:
72  *
73  * G={ {1, 2}, {4, 5}, {3, 6}, {7, 8},
74  * {1, 2, 3, 6}, {4, 5, 7, 8},
75  * {1, 2, 3, 4, 5, 6, 7, 8} }.
76  *
77  * ind={ [1, 2, 100]', [3, 4, 100]', [5, 6, 100]', [7, 8, 100]',
78  * [9, 12, 100]', [13, 16, 100]', [17, 24, 100]' }
79  *
80  * where "100" denotes the weight for the nodes.
81  *
82  *
83  *
84  * -------------------------------------------------------------------
85  * Notices:
86  * -------------------------------------------------------------------
87  *
88  * 1. The features in the tree might not be well ordered. Otherwise, you are
89  * suggested to use "altra.h".
90  *
91  * 2. When each elements of x are penalized via the same L1
92  * (equivalent to the L2 norm) parameter, one can simplify the input
93  * by specifying
94  * the "first" column of ind as (-1, -1, lambda)
95  *
96  * In this case, we treat it as a single "super" node. Thus in the value
97  * nodes, we only count it once.
98  *
99  * 3. The values in "ind" are in [1,length(G)].
100  *
101  * 4. The third element of each column should be positive. The program does
102  * not check the validity of the parameter.
103  *
104  * 5. The values in G should be within [1, n].
105  *
106  * It is still valid to use the zero regularization parameter.
107  * In this case, the program does not change the values of
108  * correponding indices.
109  *
110  *
111  * -------------------------------------------------------------------
112 * History:
113 * -------------------------------------------------------------------
114 *
115 * Composed by Jun Liu on April 20, 2010
116 *
117 * For any question or suggestion, please email j.liu@asu.edu.
118 *
119 */
120 void general_altra(double *x, double *v, int n, double *G, double *ind, int nodes, double mult=1.0);
121 
122 /*
123  * altra_mt is a generalization of altra to the
124  *
125  * multi-task learning scenario (or equivalently the multi-class case)
126  *
127  * altra_mt(X, V, n, k, G, ind, nodes);
128  *
129  * It applies altra for each row (1xk) of X and V
130  *
131  */
132 void general_altra_mt(double *X, double *V, int n, int k, double *G, double *ind, int nodes, double mult=1.0);
133 
134 /*
135  * compute
136  * lambda2_max=general_computeLambda2Max(x,n,G, ind,nodes);
137  *
138  * compute the 2 norm of each group, which is divided by the ind(3,:),
139  * then the maximum value is returned
140  */
141 /*
142  *This function does not consider the case ind={[-1, -1, 100]',...}
143  *
144  *This functions is not used currently.
145  */
146 void general_computeLambda2Max(double *lambda2_max, double *x, int n, double *G, double *ind, int nodes);
147 
148 /*
149  * -------------------------------------------------------------------
150  * Function and parameter
151  * -------------------------------------------------------------------
152  *
153  * treeNorm compute
154  *
155  * \sum \lambda_i \|x_{G_i}\|,
156  *
157  * where x is of dimension n,
158  * \lambda_i >=0, and G_i's follow the tree structure
159  *
160  * The file is implemented in the following in Matlab:
161  *
162  * tree_norm=general_treeNorm(x, n, G, ind,nodes);
163  */
164 double general_treeNorm(double *x, int ldx, int n, double *G, double *ind, int nodes);
165 
166 /*
167  * -------------------------------------------------------------------
168  * Function and parameter
169  * -------------------------------------------------------------------
170  *
171  * findLambdaMax compute
172  *
173  * the lambda_{max} that achieves a zero solution for
174  *
175  * min 1/2 \|x-v\|^2 + \lambda_{\max} * \sum w_i \|x_{G_i}\|,
176  *
177  * where x is of dimension n,
178  * w_i >=0, and G_i's follow the tree structure
179  *
180  * The file is implemented in the following in Matlab:
181  *
182  * lambdaMax=general_findLambdaMax(v, n, G, ind,nodes);
183  */
184 double general_findLambdaMax(double *v, int n, double *G, double *ind, int nodes);
185 
186 /*
187  * findLambdaMax_mt is a generalization of findLambdaMax to the
188  *
189  * multi-task learning scenario (or equivalently the multi-class case)
190  *
191  * lambdaMax=general_findLambdaMax_mt(X, V, n, k, G, ind, nodes);
192  *
193  * It applies findLambdaMax for each row (1xk) of X and V
194  *
195  */
196 double general_findLambdaMax_mt(double *V, int n, int k, double *G, double *ind, int nodes);
197 #endif /* ----- #ifndef GENERAL_ALTRA_SLEP ----- */
198 

SHOGUN Machine Learning Toolbox - Documentation