| Environments | PYTHON :: EASI :: MODELER |
| Quick links | Description :: Parameters :: Parameter descriptions :: Details :: Examples :: References :: Related |
| Back to top |
| Back to top |
nntrain(file, dbnns, momen, learn, maxterr, maxierr, maxit, ltyp)
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| FILE * | str | Input-file name | 1 - | |
| DBNNS * | List[int] | Input neural-network segment | 1 - 1 | |
| MOMEN | List[float] | Neural-network training momentum rate | 0 - 1 | 0 - 1.0 Default: 0.9 |
| LEARN | List[float] | Neural-network training learning rate | 0 - 1 | 0.0 - 1.0 Default: 0.1 |
| MAXTERR | List[float] | Maximum total error | 0 - 1 | 0.0 - Default: 0.01 |
| MAXIERR | List[float] | Maximum individual error | 0 - 1 | 0.0 - Default: 0.001 |
| MAXIT | List[int] | Maximum number of iterations | 0 - 1 | 1 - Default: 1000 |
| LTYP | str | List type | 0 - 5 | BRIEF | SHORT | FULL Default: SHORT |
| Back to top |
FILE
The name of the PCIDSK image file that contains the neural-network segment to train and the image data and bitmaps to use in sampling.
DBNNS
The neural-network segment (type 180) from which to read the input neural-network data and that will receive the trained neural network. The segment must be created by NNCREAT (which sets the DBNNS parameter).
MOMEN
The momentum rate (between 0.0 and 1.0) for neural-network training. If no value is specified, a rate of 0.9 is applied by default. A high momentum rate allows for the specification of a higher learning rate without the risk of oscillation or non-convergence. The specified momentum rate is saved in the neural-network segment for future report generation.
This parameter is optional.
LEARN
The learning rate (between 0.0 and 1.0) for neural-network training. If no value is specified, a learning rate of 0.1 is applied by default. A higher learning rate speeds up the training, but increases the risk of oscillation or non-convergence of the training result. The specified learning rate is saved in the neural-network segment for future report generation.
MAXTERR
The maximum normalized total error to allow. If no value is specified, a maximum total error of 0.01 is applied by default. If this error occurs below the value specified, the neural-network processing stops and the NNTRAIN run terminates.
This parameter is optional.
MAXIERR
The maximum individual error to allow for all samples. If no value is specified, a maximum individual error of 0.001 is applied by default. If this error occurs below the value specified for all samples, the neural-network processing stops and the NNTRAIN run terminates.
This parameter is optional.
MAXIT
The maximum number of iterations to run on the neural network. If no value is specified, a maximum number of iterations of 1000 is applied by default. If the number of iterations exceeds the value specified, the neural-network processing stops and the NNTRAIN run terminates.
This parameter is optional.
LTYP
The report listing type.
This parameter is optional.
| Back to top |
NNTRAIN trains an existing neural-network segment created with NNCREAT for back-propagation neural-network processing using sample data from training sites. When the neural-network training reaches a specified maximum acceptable error or the maximum number of iterations, training terminates. NNCLASS uses the trained neural network to classify imagery.
Dimensions of the neural network: number of layers and units per layer
Input sampling information: image channels to sample, bitmaps that define the training sites under which to sample, and number of samples to collect
The momentum rate (MOMEN) and learning rate (LEARN) for building the neural network can be specified. For more information, see Training later in this topic.
Typically, the neural network is trained when NNTRAIN completes when either of the first two conditions have been met. If NNTRAIN completes because it exceeds the maximum allowable number of iterations, NNTRAIN may need to be run again if the total normalized error is still too large.
LTYP (Listing Type) specifies whether to print a BRIEF report, where only the error plot is reported; a SHORT report, where the first 10 samples per class are reported; or a FULL report, where all samples are reported. A FULL report should be produced only if there are a few samples.
Training
Back-propagation neural networks need to be trained to learn the input patterns of interest. When the neural-network segment is first created by NNCREAT, the weights for the inter-unit connections are initialized to random values in the range of -0.5 to +0.5. If a classification is performed with NNCLASS before training the neural network, the classification results are completely random. (NNCLASS checks the number of training iterations and will not run if the neural network is untrained.)
Typically, back-propagation neural networks require a number of iterations (100 to 10000) before the interconnection weights stabilize enough to recognize the input patterns. If NNTRAIN terminates when the specified number of iterations (MAXIT) is reached and the specified individual error (MAXTERR or MAXIERR) has not been met, the network may need to be trained again with NNTRAIN. If it still does not converge, you may need to redefine the neural network (using different input channels, more accurate bitmaps, more input and hidden units, or more samples).
The learning and momentum rates affect how quickly the neural network stabilizes. A high learning rate (0.9) converges quickly, but may exit prematurely. A low learning rate (0.1) takes more iterations to train, but has less of a tendency to exit prematurely. The risk of using a high learning rate is that the modeling may oscillate and not stabilize. You can observe how different learning rates converge by examining the error plot in the output report.
The momentum rate can be used to speed up learning. A high momentum rate (0.9) trains with larger steps than a lower rate (0.1). Using a momentum term helps reduce oscillation between iterations and allows a higher learning rate to be specified without the risk of non-convergence.
Before running NNTRAIN, NNCREAT should be run to completion with the parameters defined as described in the corresponding NNCREAT Help topic.
| Back to top |
The following example uses the neural-network segment as created and initialized in the Example section of the NNCREAT Help topic.
from pci.nntrain import nntrain file = "irvine.pix" dbnns = [] # replace this with the dbnns returned by nncreat() momen = [] # default: 0.9 learn = [] # default: 0.1 maxterr = [] # default: 0.01 maxierr = [] # default: 0.001 maxit = [100] # up to 100 training iterations ltyp = "" # default: "SHORT" nntrain( file, dbnns, momen, learn, maxterr, maxierr, maxit, ltyp )
The report produced by NNTRAIN features the following sections.
Normalized Total Error
Iteration 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
count +----+----+----+----+----+----+----+----+----+----+
| * 0.4847691
| * 0.3315262
| * 0.2949889
| * 0.2761596
| * 0.2598612
| * 0.2316833
| * 0.2134420
| * 0.1958757
| * 0.1849854
10| * 0.1768456
: :
90| * 0.1062003
| * 0.1065159
| * 0.1078437
| * 0.1056879
| * 0.1063209
| * 0.1062619
| * 0.1079417
| * 0.1061828
| * 0.1064589
| * 0.1067913
100| * 0.1071009
Weights between unit 1 of hidden layer 1 and units of the input layer
-102.304550 -56.214401 12.993260 1.702257 34.554241
Threshold of unit 1 of hidden layer 1 is 5.448689
: : :
Weights between unit 8 of the output layer and units of hidden layer 1
5.953261 -0.189555 1.195738 0.200329 -0.901565 -0.810488 -0.446700 1.588004
Threshold of unit 8 of the output layer is -3.285881
Output Class 1, dbib(9), encode value: 10
================
Sample 1 output 1 = 0.914511 target 1 = 0.900000
output 2 = 0.069890 target 2 = 0.100000
output 3 = 0.080440 target 3 = 0.100000
output 4 = 0.047301 target 4 = 0.100000
output 5 = 0.090400 target 5 = 0.100000
output 6 = 0.108390 target 6 = 0.100000
output 7 = 0.109386 target 7 = 0.100000
output 8 = 0.092427 target 8 = 0.100000
: : :
Output Class 8, dbib(16), encode value: 80
================
Sample 10223 output 1 = 0.005718 target 1 = 0.100000
output 2 = 0.032834 target 2 = 0.100000
output 3 = 0.120167 target 3 = 0.100000
output 4 = 0.069566 target 4 = 0.100000
output 5 = 0.135080 target 5 = 0.100000
output 6 = 0.402099 target 6 = 0.100000
output 7 = 0.199519 target 7 = 0.100000
output 8 = 0.643339 target 8 = 0.900000
Sample 10224 output 1 = 0.000602 target 1 = 0.100000
output 2 = 0.070986 target 2 = 0.100000
output 3 = 0.121896 target 3 = 0.100000
output 4 = 0.004467 target 4 = 0.100000
output 5 = 0.120786 target 5 = 0.100000
output 6 = 0.614845 target 6 = 0.100000
output 7 = 0.297951 target 7 = 0.100000
output 8 = 0.944590 target 8 = 0.900000
: : :
Previous number of iterations: 0
Iterations in the active run: 100
Total number of iterations: 100
Target maximum individual error: 0.0010000
Actual maximum individual error: 2.4291029
Target maximum total error: 0.0100000
Actual maximum total error: 0.1071009
The error plot at the top of the report shows that the neural network converges and stabilizes by the 100th training iteration.
Next, the weights for the neural network are displayed followed by the output values produced by the neural network, and using the training samples as input to the neural network. Looking at Sample 1 (Class 1, type 1 water) and Sample 10224 (Class 8, forest areas), the neural network is well trained for these samples. The output from the neural network is close to the target value for which it was trained.
Sample 10223, however, has not stabilized. The output is not near the target values. Class 8 (forest areas) is the strongest class, but Class 6 (type 2 crop) has a high value and class 7 (type 3 crop) has a relevant activation. The other classes are close to the minimum training target of 0.1, so they are not relevant.
The last part of the report shows that NNTRAIN terminated when it reached the maximum number of iterations rather than reaching the maximum errors. Looking at the actual errors, it is likely NNTRAIN will not reach the default error thresholds.
If a classification was achieved at this point, the results would be deemed reasonable. However, due to unresolved output for some training samples, it is worthwhile to further train the neural network with a smaller momentum, learning rate, or both. Smaller rates train slower (with smaller-step increments), but are more stable. Because the network has already converged to a usable state, this is simply a fine-tuning of the network weights.
from pci.nntrain import nntrain file = "irvine.pix" # dbnns set by nncreat momen = [0.01] # use a smaller momentum rate learn = [0.01] # use a smaller learning rate maxterr = [] # default: 0.01 maxierr = [] # default: 0.001 maxit = [100] # up to 100 training iterations ltyp = "" # default: "SHORT" nntrain( file, dbnns, momen, learn, maxterr, maxierr, maxit, ltyp )
Normalized Total Error
Iteration 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
count +----+----+----+----+----+----+----+----+----+----+
| * 0.1067650
| * 0.1027549
| * 0.1033934
| * 0.1013899
| * 0.1019213
| * 0.1004492
| * 0.1019276
| * 0.1005660
| * 0.1017237
10| * 0.1003434
: :
90| * 0.1007395
| * 0.1004160
| * 0.1009435
| * 0.1000615
| * 0.1005859
| * 0.1010328
| * 0.1018717
| * 0.1009491
| * 0.1012988
| * 0.1004003
100| * 0.1014162
Weights between unit 1 of hidden layer 1 and units of the input layer
-102.715591 -56.253204 13.007506 1.583847 34.527946
Threshold of unit 1 of hidden layer 1 is 5.393408
: :
Weights between unit 8 of the output layer and units of hidden layer 1
5.783882 -0.271133 1.209756 0.217568 -0.704609 -0.564478 -0.288406 1.190175
Threshold of unit 8 of the output layer is -3.205058
Output Class 1, dbib(9), encode value: 10
================
Sample 1 output 1 = 0.877992 target 1 = 0.900000
output 2 = 0.086499 target 2 = 0.100000
output 3 = 0.085330 target 3 = 0.100000
output 4 = 0.096251 target 4 = 0.100000
output 5 = 0.110453 target 5 = 0.100000
output 6 = 0.102510 target 6 = 0.100000
output 7 = 0.095599 target 7 = 0.100000
output 8 = 0.089358 target 8 = 0.100000
: : :
Output Class 8, dbib(16), encode value: 80
================
Sample 10223 output 1 = 0.005024 target 1 = 0.100000
output 2 = 0.056945 target 2 = 0.100000
output 3 = 0.066530 target 3 = 0.100000
output 4 = 0.115694 target 4 = 0.100000
output 5 = 0.167494 target 5 = 0.100000
output 6 = 0.498106 target 6 = 0.100000
output 7 = 0.205996 target 7 = 0.100000
output 8 = 0.601192 target 8 = 0.900000
Sample 10224 output 1 = 0.000710 target 1 = 0.100000
output 2 = 0.102203 target 2 = 0.100000
output 3 = 0.072264 target 3 = 0.100000
output 4 = 0.007917 target 4 = 0.100000
output 5 = 0.136404 target 5 = 0.100000
output 6 = 0.706184 target 6 = 0.100000
output 7 = 0.306816 target 7 = 0.100000
output 8 = 0.933863 target 8 = 0.900000
: : :
Previous number of iterations: 100
Iterations in the active run: 100
Total number of iterations: 200
Target maximum individual error: 0.0010000
Actual maximum individual error: 2.2561827
Target maximum total error: 0.0100000
Actual maximum total error: 0.1014162
In the second report, the error plot is smoother. Sample 1 and 10224 are much the same as before. Sample 10223 is still Class 8 (forest areas), but has dropped in activation. The Class 6 (type 2 crop) output is higher. With additional training of the neural network at the same rates, Class 6 could pass Class 8 in activation for this sample.
While additional training of the neural network could be performed, it is stable enough to classify imagery with NNCLASS.
| Back to top |
The code for NNTRAIN was adapted from a program written by M. S. Klassen and Y. H. Pao (1989) and modified by A. Zhang (1993).
© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.