FPL Statistics Group
DISCLAIMER OF WARRANTIES
THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
THE AUTHOR DOES NOT WARRANT, GUARANTEE OR MAKE ANY
REPRESENTATIONS REGARDING THE SOFTWARE OR DOCUMENTATION IN TERMS
OF THEIR CORRECTNESS, RELIABILITY, CURRENTNESS, OR OTHERWISE.
THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE
IS ASSUMED BY YOU. IN NO CASE WILL ANY PARTY INVOLVED WITH THE
CREATION OR DISTRIBUTION OF THE SOFTWARE BE LIABLE FOR ANY DAMAGE
THAT MAY RESULT FROM THE USE OF THIS SOFTWARE.
Sorry about that.
Warning
Frankly, this code is not of commercial quality. It is still
experimental in nature. The code appears to perform its tasks
correctly, but it does not represent high quality object oriented
programming. It is agglomerative in nature and includes both elements from
Java 1.02 and Java 2. At some point if we have the time we will clean
it up and improve it. For the moment it serves our purposes and we
expect that it should also be useful to others.
- Microfibril Angle Estimation From X-Ray
Diffraction Patterns
- The Initial 6, Fit 6, Initial 11, and Fit
11 or Fit 11,4 buttons
- Getting data to and from the applet
- The Load, Reset, Clear All, Clear, and Zoom buttons
- The Buttons 1, 2, 3, 4, and 5
at the top of the plot
- Writing results to files
- Running the applet on a demonstration data
file
- Documentation
- The nonlinear least squares code
- Installation of the application
- Differences between the applet and the
application
- Format.java
- Rubberband.java
- Support
- Bugs
This site provides a Web runnable Java applet
that performs a nonlinear regression fit to estimate
microfibril angle from X-ray diffraction patterns. It also provides a
means of downloading and installing a Java
application
version of this
applet.
Here are links
to a
2001 paper and a
2006 paper by Steve Verrill,
Dave Kretschmann, and Vicki Herian of the USDA Forest Products
Laboratory
that describe this work.
Ideally the fitting process could be entirely automated. However,
the fit involves a 11 parameter nonlinear regression and if initial
estimates of the parameters are off, human intervention is required.
For the most part the initial estimates that are automatically
generated work well, but occasionally they fail. Currently this leads
to a relatively fast but tedious (if you have hundreds of diffraction patterns)
process in which a user clicks the Initial 6, Fit 6,
Fit 11 or Fit 11,4, and
Next buttons in sequence.
Before fitting the full 11 parameter model, the simpler 6 parameter
model must be fit in order to obtain decent initial estimates for the
11 parameter model.
The Initial 6 button leads to an automatic calculation of initial
estimates of six parameters --- a, the baseline of the data, b1, the
height of the first major peak above the baseline, b2, the height of
the second major peak above the baseline, mu1, the
center of the first major peak, sigma1, which is the half width of
the first major peak at approximately 61% of its maximum height above
the baseline,
and sigma2, which is the half width of
the second major peak at approximately 61% of its maximum height above
the baseline.
(In LaTeX, the 6 parameter model is
"intensity = a + b_1 \times \exp(-(angle - \mu_1)^2/(2 \sigma_1^2)) +
b_2 \times \exp(-(angle - (\mu_1 + 180))^2/(2 \sigma_2^2))".)
The Initial 6 results are plotted as a blue overlay on the data.
This overlay can be quite far from a good fit and still represent
adequate starting values for the 6 parameter fit.
A user will quickly get an idea of how good
this initial 6 parameter fit needs to be to yield a decent final 6
parameter fit.
If, as occasionally happens, the initial automatic parameter estimates
are too poor to yield a good final fit, then the user must provide
improved initial estimates. This can be done in two ways. The user
can type initial estimates into the text fields next to the a, b1, b2,
mu1, and sigma1 buttons or
the user can use the mouse to identify good initial values:
- To use the mouse to identify an initial a value, click the a
button. A horizontal blue line will appear at the height
corresponding to the current a value. Now click the mouse on the
plot at a height
that is approximately even
with the plot's baseline. The first horizontal blue line will be
replaced with a new one that corresponds to the height selected by the
mouse click. This new a value will also appear in the text field
next to the a button. In addition, the old initial fit overlay will be
replaced by a new (cyan) overlay based on the new initial parameter values.
- To use the mouse to identify an initial b1 value, click the b1
button. A horizontal blue line will appear at the height
corresponding to the current a + b1 value. Now click the mouse on the
plot at a height
that is approximately even
with the leftmost main peak's maximum. The first horizontal blue line will be
replaced with a new one that corresponds to the height selected by the
mouse click. The new b1 value (calculated as click height minus the a
value) will also appear in the text field
next to the b1 button. In addition, the old initial fit overlay will be
replaced by a new (cyan) overlay based on the new initial parameter values.
- To use the mouse to identify an initial b2 value, click the b2
button. A horizontal blue line will appear at the height
corresponding to the current a + b2 value. Now click the mouse on the
plot at a height
that is approximately even
with the rightmost main peak's maximum. The first horizontal blue line will be
replaced with a new one that corresponds to the height selected by the
mouse click. The new b2 value (calculated as click height minus the a
value) will also appear in the text field
next to the b2 button. In addition, the old initial fit overlay will be
replaced by a new (cyan) overlay based on the new initial parameter values.
- To use the mouse to identify an initial mu1 value, click the mu1
button. A vertical blue line will appear at the x value
corresponding to the current mu1 value. Now click the mouse on the
plot at an x value
that is approximately at the midpoint
of the leftmost main peak. The first vertical blue line will be
replaced with a new one that corresponds to the x value selected by the
mouse click. The new mu1 value
will also appear in the text field
next to the mu1 button. In addition, the old initial fit overlay will be
replaced by a new (cyan) overlay based on the new initial parameter values.
- To use the mouse to identify an initial sigma1 value (which
is used for both sigma1 and sigma2), click the sigma1
button. A vertical blue line will appear at the x value
corresponding to the current mu1 value. A second vertical blue line
will appear at the x value corresponding to mu1 + sigma1.
Now click the mouse on the
plot at an x value
that is approximately equal to an improved mu1 + sigma1 estimate.
(Ideally this should be at a point at which the curve is at about 60%
of its maximum height. However the initial sigma1 value
does not have to be very close at all
to the correct
value in order for the subsequent nonlinear least squares to succeed.)
The second vertical blue line will be
replaced with a new one that corresponds to the x value selected by the
mouse click. The new sigma1 value (calculated as the click x value minus mu1)
will also appear in the text field
next to the sigma1 button. In addition, the old initial fit overlay will be
replaced by a new (cyan) overlay based on the new initial parameter values.
After a user is satisfied with a new initial fit overlay (one set of
button clicks should be sufficient), they can proceed with
with a fit of the 2 single peaks model by clicking the Fit 6 button.
The result of a nonlinear least squares fit of this model will appear
as a green overlay (replacing the blue or cyan initial conditions
overlay). Also this fit yields initial parameter estimates for a fit of the
full 11 parameter model. See the
2006 paper by
by Verrill, Kretschmann, and
Herian for details. The initial
parameter estimates are displayed in the text fields next
to the "MFA", "rot", "tilt", "sdFB_lp", "sdFB_rp", "sdRL_lp",
"sdRL_rp", "a", "bFB",
"bRL", and "bRdL"
labels in the lower half of the right panel. The plot of the fit
corresponding to these initial parameter values can be displayed by
clicking the Initial 11 button. The fit appears as a yellow
overlay.
Before proceeding with a 11 parameter fit we need to consider the
possibility that the initial estimate of the rotation (parameter
"rot") of the wood cells
should not be 0 degrees.
As noted in the 2005 paper,
if the front faces of the wood cells in a specimen are not perpendicular to the
X-ray beam, then the location of the 8 bright spots will change. As
illustrated in Figure 31 of the paper,
if the front faces are perpendicular to the beam, the
complete broadened profile should contain left and right profiles with
central peaks. As illustrated in Figure 32 of the paper,
if the front faces of the wood
cells are rotated 22.5 degrees in a counterclockwise direction (looking down
at the specimen from above), the complete profile should contain a left
profile with 2 noncentral peaks and a right profile with
a central peak. If a user sees this pattern, they could click
the nc,c (this stands for noncentral, central)
button on the right panel prior to performing the 11
parameter fit. As illustrated in Figure 33 of the paper,
if the front faces of the wood
cells are rotated 45 degrees in a counterclockwise direction,
the complete profile should contain left
and right profiles that each contain
2 noncentral peaks. If a user sees this pattern, they could click
the nc,nc button on the right panel prior to performing the 11
parameter fit. Finally, as illustrated in Figure 34 of the paper,
if the front faces of the wood
cells are rotated 67.5 degrees in a counterclockwise direction
(or -22.5 degrees in a clockwise
direction),
the complete profile should contain a left
profile with a central peak and a right profile with
2 noncentral peaks. If a user sees this pattern, they could click
the c,nc button on the right panel prior to performing the 11
parameter fit.
The program
permits a user to change the
initial 11 parameter estimates by changing the values displayed in the
text fields in the lower half of the right hand panel.
A user performs a 11 parameter fit by clicking on either the Fit
11 button or the Fit 11,4 button. If the Fit 11 button is
clicked, one nonlinear least squares fit is performed and the resulting
predicted intensity values are plotted as a red overlay. A smoothing
of the observed intensity data is plotted as a green overlay.
The final
parameter estimates are displayed in the "MFA", "rot",
"tilt", "sdFB_lp", "sdFB_rp", "sdRL_lp",
"sdRL_rp", "a", "bFB",
"bRL", and "bRdL"
text fields. The
MFA estimate also
appears in the panel at the top of the window. If the fit is the first 11 parameter
fit of the data set then the MFA estimate appears next to the 1
button. If the fit is the second 11 parameter
fit of the data set then the MFA estimate appears next to the 2
button. And so on. When more than one fit is performed, the ID of the
fit that corresponds to a minimum mean sum of squares is placed in the box
to the right of ``ID_min'' in the top panel. The corresponding
minimum mean sum of squares is placed in the box to the right of
``mss_min'' in the top panel. Currently, the program permits at most five 11
parameter fits of a particular data set. (Of course one can always
reload the data set in order to obtain additional fits. However this
should seldom be necessary.) See below for a description
of how results are saved to a file.
If the
Fit 11,4 button is clicked (this is our standard protocol),
four fits are performed. They differ
only in the initial estimate of the rotation. The four fits use
-22.5 degrees, 0 degrees, 22.5 degrees, and 45 degrees as the initial rotation
estimates. Of these four fits, the fit associated with the smallest
sum of squares is reported in the appropriate box on the top panel.
The applet expects data in the following form: The data
file should be an ASCII text file, not a proprietary word processing or
spreadsheet document. Text files can be produced by proprietary word
processing or spread sheet programs. On personal computers they tend
to have extensions such as ".txt" or ".prn".
The text file should begin with a data set's name. The
data set name can contain no spaces.
Next the text file should contain 2 columns of X-ray
diffraction pattern data. The
first column should contain angle values (for example, -180 to 180 or
0 to 360 or ...) and the second column should contain the
corresponding intensity values.
The angles in the first column must
be increasing but they do not have to be increasing in constant
increments.
At the end of this angle/intensity
data, a new data set can be placed. Again it must begin with a line
that contains only the data set name.
Here is an excerpt from the mfa_demo_input file that is the
default applet data file:
03ar1erX
-0.1364E+03 0.3084E+03
-0.1363E+03 0.3084E+03
-0.1362E+03 0.3125E+03
-0.1361E+03 0.3144E+03
-0.1360E+03 0.3144E+03
-0.1359E+03 0.3144E+03
.
.
.
0.2231E+03 0.3064E+03
0.2232E+03 0.3016E+03
0.2233E+03 0.3026E+03
0.2234E+03 0.3084E+03
0.2235E+03 0.3084E+03
0.2236E+03 0.3084E+03
12br1erX
-0.1364E+03 0.3259E+03
-0.1363E+03 0.3259E+03
-0.1362E+03 0.3275E+03
-0.1361E+03 0.3343E+03
-0.1360E+03 0.3343E+03
-0.1359E+03 0.3343E+03
.
.
.
Currently, the applet can handle at most 120 data sets in the
data file. Also each data set can contain at most 3700 observations
(for a possible total of 444,000 angle/intensity pairs in the data file).
If either of these restrictions presents a problem for you,
please
contact Steve
Verrill at
sverrill@fs.fed.us
or 608-231-9375.
We describe below how to obtain a Java application version of this applet
that can be run locally on your
machine with access to your file system. It can read the data file
directly from your file system and write the results files directly to
your file system. However, for quite good security reasons Java
applets cannot read from or write to your file system. Thus if you
do not want to bother downloading and installing the application
version of this applet, but do want to run it on your data, you must
anonymous ftp the data file to
www1.fpl.fs.fed.us
and put
it in the pub/data directory. Then, after you start the applet (see
below),
replace "mfa_demo_input" in the first applet window with the
name of your data file, and "mfa_demo_output" in the first applet
window with the prefix that you want for your output files. Note that
these names should be unique to you to avoid intermixing your results
with those of another user.
If a user never clicks the Load button the data sets are simply
presented in the order in which they appear in the data file.
The Load button permits a user to load a particular one of the data
sets in the data file. The user must type the data set name exactly as it
appears in the data file (upper and lower case matter)
into the text field next to the Load
button and then click the Load button. After a file
has been loaded via the Load button, the files are presented in the order in
which they appear in the data file but beginning with the file just
loaded.
The Reset, Clear All, Clear, and Zoom buttons can be used to
remove "glitches" in the data. In particular:
- A user excludes rectangular regions of data by pushing a mouse
button down at one corner of the rectangle, holding the button down
while moving the pointer to the opposite corner of the rectangle, and
then releasing the button. While a user is performing this movement,
an animated red rectangle appears that outlines the current exclusion
region. After the button is released the outline of the rectangle
turns black, and it can no longer be moved.
- If a user wants to look at only the data that has not been
excluded, the user should press the Zoom button. A sequence of
zooms can be performed.
- Currently, the program does not permit a user to unzoom a single
zoom.
However a user can reactivate all of the data by pressing the
Reset button at the bottom of the page. A user can see all of
the inactivated rectangles by performing a fit and then
clicking the appropriate recall button at the top of the page.
- The data in an inactivated
rectangle can be reactivated if the rectangle is "cleared." A user
clears a rectangle by clicking a mouse button in it (all rectangles
that contain this point will be cleared) and then clicking
on the Clear button at the bottom of the page. All rectangles
that are shown on the current page (in the current "zoom state")
will be cleared if the user clicks
the Clear All button at the bottom of the page.
As explained above, a user fits the active data by sequentially clicking the
Initial 6, Fit 6, and
Fit 11 or Fit 11,4
buttons in the right hand panel.
After a 11 parameter fit has been performed, an estimate of
the microfibril angle
appears in one of the boxes at the top of the page. Up to 5 fits can be
performed on any one data set (of course, additional fits can be
performed by reloading the data set). If
i < 5 fits have been performed, and the Fit 11 or Fit
11,4
button is
clicked, the MFA estimate from the fit will appear in text field i + 1
at the top of the page. (If there are four or five empty fields at
the top of the page, and the Fit 11,4 button is clicked, the
results from all four fits will appear at the top. If one to three
fields are available at the top of the page,
and the Fit 11,4 button is clicked, only the best of the four
fits will appear at the top.)
At any
time prior to a click of one of the Load, Back, Next, or Stop
buttons, a fit can be recalled by clicking the button (buttons 1 -- 5)
corresponding to the fit
at the top of the page.
The Back button loads the preceeding data set in the data file.
The Next button loads the next data set in the data file.
The Stop button ends the execution of the program.
If a 11 parameter fit has been performed, then when the next
Load, Back, Next, or Stop button is clicked, information
is written to two results files. To a file titled xxx.ests
(where xxx is the output prefix provided by the user in the startup box)
in the pub/data anonymous ftp space on www1.fpl.fs.fed.us,
the applet writes the
ID, the 11 parameter estimates (including the the microfibril angle estimate)
calculated from the most recently
displayed 11 parameter fit. Thus, if the user wants to save the
results from the fit that yielded the
lowest mean sum of squares, and it was not the most
recent fit, they will have to first
recall it by clicking on the button at the top of the page (from 1
to 5) that corresponds to the fit.
To a file titled xxx.inact
(where xxx is the output prefix provided by
the user in the startup box), the applet writes the ID, the number
of inactivated rectangles associated with the most recently displayed
fit,
and the pairs of x,y values that define them. These
files can be retrieved via anonymous ftp from the pub/data directory of
www1.fpl.fs.fed.us. (Warning: As of 7/1/05 we have
been having ongoing problems with our anonymous ftp connection. If
you cannot get anonymous ftp to work for your data, please e-mail
me (Steve Verrill) at
sverrill@fs.fed.us.
You can e-mail me your data and I can e-mail you the results files.)
Here is
the current applet. When you click the Go button in
the startup box, the entire data set (currently up to 444,000
observations) is downloaded from www1.fpl.fs.fed.us to your machine.
If your data set is large enough this can take tens of seconds, so
please be patient. Also the fits are not instantaneous. They can
take seconds to perform. (The application is faster.)
Currently the documentation consists of this web page, the
comments in the code, and the papers
(2001,
2006)
by Verrill, Kretschmann, and
Herian.
If, after a careful reading of this page,
you cannot understand how to run the applet or the application, please
contact Steve Verrill at
sverrill@fs.fed.us
or 608-231-9375.
If you are not particularly interested in microfibril angle
estimation, but are interested in Java code to perform nonlinear least
squares, here is a source.
If you would prefer to have a version of this code that resides on
your personal machine you can download a Java application version of
the applet.
The code is available in compressed tar or
Windows 98 and later zip
form.
Given the way that the code is currently written you will need to
place the following directories and associated files
under a directory in your CLASSPATH (see below).
The creation of the
subdirectories
is done automatically if
you are untarring the compressed tar file on a UNIX box. On a Windows
box, the creation
of the subdirectories under the directory in which you have unzipped
the program can be done by running the install.bat program.
- corejava
- optimization
- Lmder_fcn.java
- Lmder_fcn.class
- Lmdif_fcn.java
- Lmdif_fcn.class
- Minpack_f77.java
- Minpack_f77.class
- rubberband
- Rubberband.java
- Rubberband.class
- RubberbandRectangle.java
- RubberbandRectangle.class
- RubberbandRectangleX.java
- RubberbandRectangleX.class
- sorts
- Real_Sorts_f77.java
- Real_Sorts_f77.class
- SPV_graphics
- SPVGraph.java
- SPVGraph.class
- SPVGrint.java
- SPVGrint.class
- TicDraw.java
- TicDraw.class
- TicID.java
- TicID.class
You will then need to place the other classes (MFA_application.class,
MFA_application1.class, MFA_application_canvas.class,
Nlin6.class, Nlin11.class,
Spots8.class,
Pdown_application.class,
Pright_application.class, and Pup_application.class)
together in a directory
and type
java MFA_application
while you are in that directory to run the application. (You
would have to type this at a DOS command line under Windows.)
For a UNIX machine, your CLASSPATH will be set in your .cshrc file
if you are running under the C-shell.
For a WINDOWS machine, your
CLASSPATH will
probably already include the "current working directory." Thus if you
install MFA_application.class,
MFA_application1.class, MFA_application_canvas.class,
Nlin6.class, Nlin11.class,
Spots8.class,
Pdown_application.class,
Pright_application.class, and Pup_application.class
in a directory, and the corejava, optimization,
rubberband, sorts, and
SPV_graphics subdirectories under that directory, then if you type
java MFA_application in the directory, the program should run.
Of course for this to work,
you will need a Java runtime environment (JRE) on your machine.
If your machine does not currently include a JRE, you can obtain one
for free at
http://java.sun.com/j2se/desktopjava/index.jsp (Solaris, Linux, or Windows) or
http://devworld.apple.com/java/ (Apple). (There are free sites on the
Web for other machines such as IBM and HP UNIX boxes.) You will need
to follow the associated installation instructions to get the JRE set
up on your system.
The application permits you to choose input and output files with a
file chooser. To do so click on one of the Browse buttons in
the startup box. Also, if your printer can handle postscript,
the application permits you to print plots via the
Print button at the bottom of the page.
On our machines the
application runs faster than the applet.
Format.java is software described in Cornell
and Horstmann's Core Java (SunSoft Press/Prentice-Hall).
(We like this book.)
We use it to write to and read from the text fields.
Here is what Cornell and Horstmann
have to say about the use of code from their book:
NOTE: People have often asked what the licensing requirements for
using the sample code in a commercial situation are. You can freely
use any code from this book for non-commercial use. However, if you
do want to use the code as a basis for a commercial project, we simply
require that every person on the development team for that project own
a copy of Core Java.
The rubberband material is software described in Geary and McClellan's
Graphic Java (Sunsoft Press/Prentice-Hall). (We also like this
book.) We use this material to produce the rectangles that exclude
data points.
Here is what Geary and McClellan
have to say about the use of code from their book:
The CD that accompanies this book includes:
- All the source code for the Graphic Java Toolkit.
- Unit test applets for all GJT components, including HTML files for
unit test applets.
- HTML documentation for all GJT classes.
- Numerous image files in .gif format developed by Pixelsite
Virtually all these programs are discussed throughout the book. Feel
free to borrow, adapt, or extend these for your own purposes.
If you have questions about this software,
or suggestions for improvement,
please contact Steve Verrill at
sverrill@fs.fed.us
or 608-231-9375. Also see this link to the
FPL Statistics Group.
As of 9/23/05 no bugs have been reported. However, we assume that
they exist. Bugs will be corrected as they are reported and
descriptions of any bugs and bug fixes will be documented here.
We welcome suggestions for improving this program. Please send
suggestions and bug reports to the e-mail address given below.
For further information, please contact Steve Verrill at
sverrill@fs.fed.us
or 608-231-9375.
[Forest Service]
[Forest Products
Lab]
[FPL Statistics Group]
Last modified on 4/11/07.
As of last midnight, this page had been accessed




times.