0
# Statistics Monitoring
1

2
The statistics monitoring system collects comprehensive training metrics from DeepLearning4J models and provides them to the UI for visualization. It's the modern replacement for deprecated iteration listeners.
3

4
## Core Statistics API
5

6
### StatsListener
7

8
The primary iteration listener for collecting model statistics during training.
9

10
```java { .api }
11
public class StatsListener extends BaseStatsListener {
12
    // Basic constructor with default frequency (every iteration)
13
    public StatsListener(StatsStorageRouter router);
14
    
15
    // Constructor with custom reporting frequency
16
    public StatsListener(StatsStorageRouter router, int listenerFrequency);
17
    
18
    // Full configuration constructor
19
    public StatsListener(StatsStorageRouter router, 
20
                        StatsInitializationConfiguration initConfig,
21
                        StatsUpdateConfiguration updateConfig, 
22
                        String sessionID, String workerID);
23
    
24
    // Create a copy of the listener
25
    public StatsListener clone();
26
    
27
    // Factory methods for reports
28
    public StatsInitializationReport getNewInitializationReport();
29
    public StatsReport getNewStatsReport();
30
    public StorageMetaData getNewStorageMetaData(long initTime, String sessionID, String workerID);
31
}
32
```
33

34
### BaseStatsListener
35

36
Abstract base class providing common functionality for statistics listeners.
37

38
```java { .api }
39
public abstract class BaseStatsListener implements IterationListener {
40
    protected StatsStorageRouter storageRouter;
41
    protected StatsInitializationConfiguration initConfig;
42
    protected StatsUpdateConfiguration updateConfig;
43
    protected String sessionID;
44
    protected String workerID;
45
    
46
    public BaseStatsListener(StatsStorageRouter router, 
47
                           StatsInitializationConfiguration initConfig,
48
                           StatsUpdateConfiguration updateConfig, 
49
                           String sessionID, String workerID);
50
}
51
```
52

53
### J7StatsListener
54

55
Java 7 compatible version of the statistics listener.
56

57
```java { .api }
58
public class J7StatsListener extends BaseStatsListener {
59
    public J7StatsListener(StatsStorageRouter router);
60
    public J7StatsListener(StatsStorageRouter router, int listenerFrequency);
61
}
62
```
63

64
## Configuration API
65

66
### StatsUpdateConfiguration
67

68
Configuration interface for controlling statistics collection frequency and types.
69

70
```java { .api }
71
public interface StatsUpdateConfiguration extends Serializable {
72
    // Reporting frequency in terms of listener calls
73
    int reportingFrequency();
74
    
75
    // Performance and System Stats
76
    boolean collectPerformanceStats();
77
    boolean collectMemoryStats();
78
    boolean collectGarbageCollectionStats();
79
    
80
    // General Stats
81
    boolean collectLearningRates();
82
    
83
    // Histogram Configuration
84
    boolean collectHistograms(StatsType type);
85
    int numHistogramBins(StatsType type);
86
    
87
    // Summary Statistics
88
    boolean collectMean(StatsType type);
89
    boolean collectStdev(StatsType type);
90
    boolean collectMeanMagnitudes(StatsType type);
91
}
92
```
93

94
### DefaultStatsUpdateConfiguration
95

96
Default implementation with builder pattern for easy configuration.
97

98
```java { .api }
99
public class DefaultStatsUpdateConfiguration implements StatsUpdateConfiguration {
100
    public static final int DEFAULT_REPORTING_FREQUENCY = 10;
101
    
102
    public static class Builder {
103
        public Builder reportingFrequency(int frequency);
104
        public Builder collectPerformanceStats(boolean collect);
105
        public Builder collectMemoryStats(boolean collect);
106
        public Builder collectGarbageCollectionStats(boolean collect);
107
        public Builder collectLearningRates(boolean collect);
108
        
109
        // Histogram collection by type
110
        public Builder collectHistogramsParameters(boolean collect);
111
        public Builder collectHistogramsGradients(boolean collect);
112
        public Builder collectHistogramsUpdates(boolean collect);
113
        public Builder collectHistogramsActivations(boolean collect);
114
        public Builder numHistogramBins(int bins);
115
        
116
        // Mean collection by type
117
        public Builder collectMeanParameters(boolean collect);
118
        public Builder collectMeanGradients(boolean collect);
119
        public Builder collectMeanUpdates(boolean collect);
120
        public Builder collectMeanActivations(boolean collect);
121
        
122
        // Standard deviation collection by type
123
        public Builder collectStdevParameters(boolean collect);
124
        public Builder collectStdevGradients(boolean collect);
125
        public Builder collectStdevUpdates(boolean collect);
126
        public Builder collectStdevActivations(boolean collect);
127
        
128
        // Mean magnitude collection by type
129
        public Builder collectMeanMagnitudesParameters(boolean collect);
130
        public Builder collectMeanMagnitudesGradients(boolean collect);
131
        public Builder collectMeanMagnitudesUpdates(boolean collect);
132
        public Builder collectMeanMagnitudesActivations(boolean collect);
133
        
134
        public DefaultStatsUpdateConfiguration build();
135
    }
136
}
137
```
138

139
### StatsInitializationConfiguration
140

141
Configuration interface for statistics initialization.
142

143
```java { .api }
144
public interface StatsInitializationConfiguration {
145
    boolean collectSoftwareInfo();
146
    boolean collectHardwareInfo();
147
    boolean collectModelInfo();
148
}
149
```
150

151
### DefaultStatsInitializationConfiguration
152

153
Default implementation for initialization configuration.
154

155
```java { .api }
156
public class DefaultStatsInitializationConfiguration implements StatsInitializationConfiguration {
157
    public DefaultStatsInitializationConfiguration();
158
    public DefaultStatsInitializationConfiguration(boolean collectSoftwareInfo, 
159
                                                  boolean collectHardwareInfo,
160
                                                  boolean collectModelInfo);
161
}
162
```
163

164
## Statistics Reports
165

166
### StatsReport Interface
167

168
Interface for statistics reports generated during training.
169

170
```java { .api }
171
public interface StatsReport extends Persistable {
172
    void reportIterationCount(int iterationCount);
173
    void reportIDs(String sessionID, String typeID, String workerID, long timeStamp);
174
    void reportScore(double score);
175
    void reportLearningRates(Map<String, Double> learningRatesByParam);
176
    void reportHistograms(Map<StatsType, Map<String, Histogram>> histograms);
177
    void reportMean(StatsType statsType, String paramName, double mean);
178
    void reportStdev(StatsType statsType, String paramName, double stdev);
179
    void reportMeanMagnitudes(StatsType statsType, String paramName, double meanMag);
180
}
181
```
182

183
### StatsInitializationReport Interface
184

185
Interface for initialization reports containing model setup information.
186

187
```java { .api }
188
public interface StatsInitializationReport extends Persistable {
189
    void reportIDs(String sessionID, String typeID, String workerID, long timeStamp);
190
    void reportSoftwareInfo(Map<String, String> softwareInfo);
191
    void reportHardwareInfo(Map<String, String> hardwareInfo);
192
    void reportModelInfo(String modelClassName, String modelConfigJson, String[] paramNames);
193
}
194
```
195

196
### Report Implementations
197

198
```java { .api }
199
// SBE (Simple Binary Encoding) implementations for efficiency
200
public class SbeStatsReport implements StatsReport {
201
    public SbeStatsReport();
202
}
203

204
public class SbeStatsInitializationReport implements StatsInitializationReport {
205
    public SbeStatsInitializationReport();
206
}
207

208
// Java-based implementations for compatibility
209
public class JavaStatsReport implements StatsReport {
210
    public JavaStatsReport();
211
}
212

213
public class JavaStatsInitializationReport implements StatsInitializationReport {
214
    public JavaStatsInitializationReport();
215
}
216
```
217

218
## Statistics Types and Enums
219

220
### StatsType Enumeration
221

222
```java { .api }
223
public enum StatsType {
224
    Parameters,    // Model parameters (weights, biases)
225
    Gradients,     // Parameter gradients (pre-update)
226
    Updates,       // Parameter updates (post-update/processed gradients)
227
    Activations    // Layer activations
228
}
229
```
230

231
### SummaryType Enumeration
232

233
```java { .api }
234
public enum SummaryType {
235
    Mean,           // Mean values
236
    Stdev,          // Standard deviation
237
    MeanMagnitudes  // Mean magnitudes
238
}
239
```
240

241
### Histogram Interface
242

243
```java { .api }
244
public interface Histogram {
245
    double[] getBinRanges();
246
    long[] getCounts();  
247
    String getLabel();
248
}
249
```
250

251
## Usage Examples
252

253
### Basic Statistics Collection
254

255
```java
256
import org.deeplearning4j.ui.stats.StatsListener;
257
import org.deeplearning4j.ui.storage.InMemoryStatsStorage;
258
import org.deeplearning4j.ui.api.UIServer;
259

260
// Create storage and UI server
261
InMemoryStatsStorage statsStorage = new InMemoryStatsStorage();
262
UIServer uiServer = UIServer.getInstance();
263
uiServer.attach(statsStorage);
264

265
// Create listener with default settings
266
StatsListener statsListener = new StatsListener(statsStorage);
267

268
// Attach to your model
269
MultiLayerNetwork model = new MultiLayerNetwork(config);
270
model.init();
271
model.setListeners(statsListener);
272

273
// Train - statistics will be collected automatically
274
model.fit(trainingData);
275
```
276

277
### Custom Statistics Configuration
278

279
```java
280
import org.deeplearning4j.ui.stats.StatsListener;
281
import org.deeplearning4j.ui.stats.impl.DefaultStatsUpdateConfiguration;
282

283
// Create custom configuration
284
DefaultStatsUpdateConfiguration config = new DefaultStatsUpdateConfiguration.Builder()
285
    .reportingFrequency(10)           // Collect every 10 iterations
286
    .collectParameterStats(true)       // Collect parameter statistics
287
    .collectActivationStats(false)     // Skip activation statistics
288
    .collectGradientStats(true)        // Collect gradient statistics
289
    .collectHistograms(true)           // Collect histogram data
290
    .build();
291

292
// Create listener with custom configuration
293
StatsListener statsListener = new StatsListener(statsStorage, null, config, null, null);
294

295
model.setListeners(statsListener);
296
```
297

298
### Multiple Listeners for Different Purposes
299

300
```java
301
// Listener for detailed statistics (every iteration)
302
StatsListener detailedListener = new StatsListener(detailedStorage, 1);
303

304
// Listener for summary statistics (every 100 iterations)  
305
StatsListener summaryListener = new StatsListener(summaryStorage, 100);
306

307
// Attach both listeners
308
model.setListeners(detailedListener, summaryListener);
309
```
310

311
### Cloning Listeners for Multiple Models
312

313
```java
314
// Create base listener configuration
315
StatsListener baseListener = new StatsListener(statsStorage, customConfig, null, null);
316

317
// Clone for multiple models
318
StatsListener model1Listener = baseListener.clone();
319
StatsListener model2Listener = baseListener.clone();
320

321
model1.setListeners(model1Listener);
322
model2.setListeners(model2Listener);
323
```
324

325
## Legacy Listeners (Deprecated)
326

327
The following listeners are deprecated but still part of the API for compatibility:
328

329
### HistogramIterationListener (Deprecated)
330

331
```java { .api }
332
@Deprecated
333
public class HistogramIterationListener extends StatsListener {
334
    public HistogramIterationListener(int iterations);
335
    public HistogramIterationListener(int iterations, boolean openBrowser);
336
    public HistogramIterationListener(StatsStorage ssr, int iterations, boolean openBrowser);
337
}
338
```
339

340
### FlowIterationListener (Deprecated)
341

342
```java { .api }
343
@Deprecated  
344
public class FlowIterationListener implements IterationListener {
345
    public FlowIterationListener();
346
    public FlowIterationListener(int iterations);
347
    public FlowIterationListener(StatsStorage statsStorage, int iterations);
348
}
349
```
350

351
### ConvolutionalIterationListener (Deprecated)
352

353
```java { .api }
354
@Deprecated
355
public class ConvolutionalIterationListener extends StatsListener {
356
    public ConvolutionalIterationListener(int iterations);
357
    public ConvolutionalIterationListener(int iterations, boolean openBrowser);
358
}
359
```
360

361
**Migration Note**: Use `StatsListener` instead of these deprecated classes. The new `StatsListener` provides all functionality with better performance and more configuration options.