/
DVFA.jl
370 lines (311 loc) · 10.1 KB
/
DVFA.jl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
"""
DVFA.jl
# Description
Includes all of the structures and logic for running a Dual-Vigilance Fuzzy ART (DVFA) module.
# Authors
- MATLAB implementation: Leonardo Enzo Brito da Silva
- Julia port: Sasha Petrenko <sap625@mst.edu>
# References
1. L. E. Brito da Silva, I. Elnabarawy and D. C. Wunsch II, 'Dual Vigilance Fuzzy ART,' Neural Networks Letters. To appear.
2. G. Carpenter, S. Grossberg, and D. Rosen, 'Fuzzy ART: Fast stable learning and categorization of analog patterns by an adaptive resonance system,' Neural Networks, vol. 4, no. 6, pp. 759-771, 1991.
"""
# -----------------------------------------------------------------------------
# TYPES
# -----------------------------------------------------------------------------
"""
Dual Vigilance Fuzzy ART options struct.
$(_OPTS_DOCSTRING)
"""
@with_kw mutable struct opts_DVFA <: ARTOpts @deftype Float
"""
Lower-bound vigilance parameter: rho_lb ∈ [0, 1].
"""
rho_lb = 0.55; @assert rho_lb >= 0.0 && rho_lb <= 1.0
"""
Upper bound vigilance parameter: rho_ub ∈ [0, 1].
"""
rho_ub = 0.75; @assert rho_ub >= 0.0 && rho_ub <= 1.0
"""
Choice parameter: alpha > 0.
"""
alpha = 1e-3; @assert alpha > 0.0
"""
Learning parameter: beta ∈ (0, 1].
"""
beta = 1.0; @assert beta > 0.0 && beta <= 1.0
"""
Maximum number of epochs during training.
"""
max_epoch::Int = 1
"""
Display flag for progress bars.
"""
display::Bool = false
"""
Flag to use an uncommitted node when learning.
If true, new weights are created with ones(dim) and learn on the complement-coded sample.
If false, fast-committing is used where the new weight is simply the complement-coded sample.
"""
uncommitted::Bool = false
"""
Selected activation function.
"""
activation::Symbol = :basic_activation
"""
Selected match function.
"""
match::Symbol = :unnormalized_match
"""
Selected weight update function.
"""
update::Symbol = :basic_update
end
"""
Dual Vigilance Fuzzy ARTMAP module struct.
For module options, see [`AdaptiveResonance.opts_DVFA`](@ref).
# References:
1. L. E. Brito da Silva, I. Elnabarawy and D. C. Wunsch II, 'Dual Vigilance Fuzzy ART,' Neural Networks Letters. To appear.
2. G. Carpenter, S. Grossberg, and D. Rosen, 'Fuzzy ART: Fast stable learning and categorization of analog patterns by an adaptive resonance system,' Neural Networks, vol. 4, no. 6, pp. 759-771, 1991.
"""
mutable struct DVFA <: AbstractFuzzyART
# Get parameters
"""
DVFA options struct.
"""
opts::opts_DVFA
"""
Data configuration struct.
"""
config::DataConfig
# Working variables
"""
Operating upper bound module threshold value, a function of the upper bound vigilance parameter.
"""
threshold_ub::Float
"""
Operating lower bound module threshold value, a function of the lower bound vigilance parameter.
"""
threshold_lb::Float
"""
Incremental list of labels corresponding to each F2 node, self-prescribed or supervised.
"""
labels::ARTVector{Int}
"""
Category weight matrix.
"""
W::ARTMatrix{Float}
"""
Activation values for every weight for a given sample.
"""
T::ARTVector{Float}
"""
Match values for every weight for a given sample.
"""
M::ARTVector{Float}
"""
Number of category weights (F2 nodes).
"""
n_categories::Int
"""
Number of labeled clusters, may be lower than `n_categories`
"""
n_clusters::Int
"""
Current training epoch.
"""
epoch::Int
"""
Runtime statistics for the module, implemented as a dictionary containing entries at the end of each training iteration.
These entries include the best-matching unit index and the activation and match values of the winning node.
"""
stats::ARTStats
end
# -----------------------------------------------------------------------------
# CONSTRUCTORS
# -----------------------------------------------------------------------------
"""
Implements a DVFA learner with optional keyword arguments.
# Arguments
- `kwargs`: keyword arguments to pass to the DVFA options struct (see [`AdaptiveResonance.opts_DVFA`](@ref).)
# Examples
By default:
```julia-repl
julia> DVFA()
DVFA
opts: opts_DVFA
...
```
or with keyword arguments:
```julia-repl
julia> DVFA(rho=0.7)
DVFA
opts: opts_DVFA
...
```
"""
function DVFA(;kwargs...)
opts = opts_DVFA(;kwargs...)
DVFA(opts)
end
"""
Implements a DVFA learner with specified options.
# Arguments
- `opts::opts_DVFA`: the DVFA options (see [`AdaptiveResonance.opts_DVFA`](@ref)).
# Examples
```julia-repl
julia> my_opts = opts_DVFA()
julia> DVFA(my_opts)
DVFA
opts: opts_DVFA
...
```
"""
function DVFA(opts::opts_DVFA)
DVFA(
opts, # opts
DataConfig(), # config
0.0, # threshold_ub
0.0, # threshold_lb
ARTVector{Int}(undef, 0), # labels
ARTMatrix{Float}(undef, 0, 0), # W
ARTVector{Float}(undef, 0), # M
ARTVector{Float}(undef, 0), # T
0, # n_categories
0, # n_clusters
0, # epoch
build_art_stats(), # stats
)
end
# -----------------------------------------------------------------------------
# FUNCTIONS
# -----------------------------------------------------------------------------
# COMMON DOC: Set threshold function
function set_threshold!(art::DVFA)
# DVFA thresholds
art.threshold_ub = art.opts.rho_ub * art.config.dim
art.threshold_lb = art.opts.rho_lb * art.config.dim
end
"""
Creates a new category for the DVFA modules.
# Arguments
- `art::DVFA`: the DVFA module to add a category to.
- `x::RealVector`: the sample to use for adding a category.
- `y::Integer`: the new label for the new category.
"""
function create_category!(art::DVFA, x::RealVector, y::Integer ; new_cluster::Bool=true)
# Increment the number of categories
art.n_categories += 1
# If we are creating a new cluster altogether, increment that
new_cluster && (art.n_clusters += 1)
# If we use an uncommitted node
if art.opts.uncommitted
# Add a new weight of ones
append!(art.W, ones(art.config.dim_comp, 1))
# Learn the uncommitted node on the sample
learn!(art, x, art.n_categories)
else
# Fast commit the sample
append!(art.W, x)
end
# Update sample labels
push!(art.labels, y)
end
# COMMON DOC: Incremental DVFA training method
function train!(art::DVFA, x::RealVector ; y::Integer=0, preprocessed::Bool=false)
# Flag for if training in supervised mode
supervised = !iszero(y)
# Run the sequential initialization procedure
sample = init_train!(x, art, preprocessed)
# Initialization
if isempty(art.W)
# Set the first label as either 1 or the first provided label
y_hat = supervised ? y : 1
# Initialize the module with the first sample and label
initialize!(art, sample, y=y_hat)
# Return the selected label
return y_hat
end
# If label is new, break to make new category
if supervised && !(y in art.labels)
create_category!(art, sample, y)
return y
end
# Compute the activation and match for all categories
activation_match!(art, sample)
# Sort activation function values in descending order
index = sortperm(art.T, rev=true)
# Default to mismatch
mismatch_flag = true
# Loop over all categories
for j = 1:art.n_categories
# Best matching unit
bmu = index[j]
# If supervised and the label differs, trigger mismatch
if supervised && (art.labels[bmu] != y)
break
end
# Vigilance test upper bound
if art.M[bmu] >= art.threshold_ub
# Learn the sample
learn!(art, sample, bmu)
# Update sample label for output
# y_hat = supervised ? y : art.labels[bmu]
y_hat = art.labels[bmu]
# No mismatch
mismatch_flag = false
break
# Vigilance test lower bound
elseif art.M[bmu] >= art.threshold_lb
# Update sample labels
y_hat = supervised ? y : art.labels[bmu]
# Create a new category in the same cluster
create_category!(art, sample, y_hat, new_cluster=false)
# No mismatch
mismatch_flag = false
break
end
end
# If there was no resonant category, make a new one
if mismatch_flag
# Keep the bmu as the top activation despite creating a new category
bmu = index[1]
# Create a new category-to-cluster label
y_hat = supervised ? y : art.n_clusters + 1
# Create a new category
create_category!(art, sample, y_hat)
end
# Update the stored match and activation values
log_art_stats!(art, bmu, mismatch_flag)
return y_hat
end
# COMMON DOC: Incremental DVFA classify method
function classify(art::DVFA, x::RealVector ; preprocessed::Bool=false, get_bmu::Bool=false)
# Preprocess the data
sample = init_classify!(x, art, preprocessed)
# Compute activation and match functions
activation_match!(art, sample)
# Sort activation function values in descending order
index = sortperm(art.T, rev=true)
mismatch_flag = true
for jx in 1:art.n_categories
bmu = index[jx]
# Vigilance check - pass
if art.M[bmu] >= art.threshold_ub
# Current winner
y_hat = art.labels[bmu]
mismatch_flag = false
break
end
end
# If we did not find a resonant category
if mismatch_flag
# Create new weight vector
bmu = index[1]
# Report either the best matching unit or the mismatch label -1
y_hat = get_bmu ? art.labels[bmu] : -1
end
# Update the stored match and activation values
log_art_stats!(art, bmu, mismatch_flag)
# Return the inferred label
return y_hat
end