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.

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

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.

The Initial 6, Fit 6, Initial 11, and Fit 11 or Fit 11,4 buttons

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.

Getting data to and from the applet

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.

The Load, Reset, Clear All, Clear, and Zoom buttons

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.

The Buttons 1, 2, 3, 4, and 5 at the top of the plot

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.

Writing results to files

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.)

Running the applet on a demonstration data file

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.)

Documentation

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.

The nonlinear least squares code

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.

Installation of the application

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
• Format.java
• Format.class
• 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.

Differences between the applet and the application

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

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.

Rubberband.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.

Bugs

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.