REDUCE 3D 2.5.9

Program Notes: 31 July 2000

General

This program takes a merge file (text) representing the size and location of each crystal of a certain phase in a volume, and calculates various statistics on the set of crystals. A set of holes can optionally be included as well, and the statistics can be tuned and excluded by the user. The set of crystals can be interactively rendered in 3D, however this functionality has also been moved into Render3D (and is more current there), which has supplanted Reduce3D for rendering.

Memory Required: 4096K (really depends on file size and program settings)

Input File Type

TEXT

Input Limits

Dictated by available memory.

Input Format

Reads in files from Crystallize91, Crystallize95, or Integrate. Can read old style, in which fields have specific lengths, or new (better) style, in which fields are delimited by tab characters. The file must be consistent - using tabs in the header, but spaces in the body is not allowed. A persistent issue in which a blank line was required at the end of files should now be fixed.

Output File Types

TEXT

Output Format

The first line of each file is a file-type identifier, to be used by subsequent programs. The second line is the comment line present in the input file. In all cases, the labels are separated from the numeric fields by a tab character. The file names are produced automatically, first by stripping off the ".MERGE" extension (or, if that is not the extension, it strips off whatever the last extension is, if any) and then appending either [".Reduce3D", ".Reduce3DXl", ".MeanCSD", ".MaxCSD", ".LogCSD", ".RegCSD", ".NNCSD"] or [".RED3", ".R3ST", ".CSD1", ".CSD2", ".CSD3", ".CSD4", ".CSD5"], depending on the length of the root file name, and the file type.

The REDUCE3D file is the main data set, containing the results of the statistics and the settings used to produce those statistics. The settings are saved in the text, and as a resource readable by the same version of Reduce3D that produced it, as discussed below. The structure of the text file is as follows:

Line(s) Data
1 Filename of input file
2 Label of Reduce3D version used to make the file
3 Comment from input file
4-61 Processing parameters
62-132 Main single-value statistics, many with envelope values on the same line. All labels are separated from values by tab characters.
133-? Table of correlation function values and envelope values for same. These are best not read directly, but by GraphCFs, code written for displaying these graphs.
?-? The table can be followed by a table of crystals.

Note that the Reduce3D file is set up with the creator as GraphCFs, so it can be double-clicked to display the results immediately. All other saved files are set up with CodeWarrior as the creator.

The CSD1 file consists of: a one-line header; a line with the name of the MERGE file; a line citing the number of size classes used in generating the data that follow for the mean-normalized cumulative CSD plot; a title line giving the name of the plot and the number of means the values were normalized to; and finally one line per size class, containing the fractional distance along the inverse normalized radius axis at the low limit of the size class, followed by the cumulative percentage of the crystals that fall into that size class. These entries may be read simply as the abscissa and ordinate values for the cumulative CSD plot.

The CSD2 file consists of: a one-line header; a line with the name of the MERGE file; a line citing the number of size classes used in generating the data that follow for the maxn-normalized cumulative CSD plot; a title line giving the name of the plot; and finally one line per size class, containing the fractional distance along the inverse normalized radius axis at the low limit of the size class, followed by the cumulative percentage of the crystals that fall into that size class. These entries may be read simply as the abscissa and ordinate values for the cumulative CSD plot.

The CSD3 file consists of: a one-line header; a line with the name of the MERGE file; a line citing the number of size classes used in generating the data that follow for the maxn-normalized cumulative CSD plot; a title line giving the name of the plot; and finally one line per size class, containing the upper limit of the size class (in cm) followed by the natural log of the slope of the cumulative size distribution plot (ln [dN*/dL], in the notation of Cashman and Ferry, 1988) at that size class. These entries may be read simply as the abscissa and ordinate values for the logarithmic CSD plot.

ResTypes (not registered with Apple)

Application (Blob 1.0) = ‘qtRD’

Operator Notes

  1. Program can be run by launching the application, or by dragging the input files onto the application.
  2. Upon launch, a settings/preferences window with six tabs is posted. The settings in this window persist between runs, stored in a file in the Preferences folder of the System folder named "Reduce 3D Prefs". The default settings can be recalled with the button at the bottom of the window. Each of the tabs controls different aspects of the program’s operation:
    1. CSDs — This tab controls whether to output various types of crystal size distribution files, and how to calculate the bin sizes
      1. Mean Normalized Cumulative CSD - Histogram of crystal radii, normalized to the mean radius of the population
        1. Number of size classes - number of bins in histogram
        2. Max value on x-axis (#radii)
      2. Logarithmic CSD
        1. Number of size classes - number of bins in histogram
      3. Max Normalized Cumulative CSD
        1. Number of size classes - number of bins in histogram
      4. Regular and NN CSD - Regular CSD, and CSD of nearest neighbors
        1. Delta L (bin spacing) - size of histogram bins, in cm.
    2. Statistics - These settings control which statistics to calculate, and details of that calculation.
      1. Quadrat Test - Rarely used now, places a sphere in the volume and counts crystals inside it to measure ordering / clustering
        1. Number of placings - How many placings per test.
        2. Number of repetitions - How many tests are performed (and then averaged into a single measurement)
      2. Impingement Correction (if needed) - This operation adjusts crystal sizes to account for impingement in Crystallize simulations. In these simulations, crystal volume is based solely on domain volume, and if two crystals overlap, then the joint volume is less than the appropriate percentage of their joint domains. This operation increases the extended volume to account for the impingement. The process is iterative (over the whole set of crystals), and continues until both the maximum error is less than the value indicated, and the mean error is less than the value indicated.
        1. Mean error tolerance - See above.
        2. Max error tolerance - See above.
      3. Do other statistical tests - This selector chooses whether to perform a range of basic statistical measures. Note that some of these measures are required for other tests, and will be performed regardless. These tests include: Nearest neighbor tests, Avrami Tests, and crystal size distribution measures.
      4. Inflate bounding box - This operation takes the finished bounding box, and moves each vertex away from the center by the radius of the crystal it occupies, in order to include more crystals at the expense of accuracy in certain measures such as volume fraction and crystal number density.
      5. Discard boundary crystals - This causes any crystals that have a negative radius (a label used in Crystallize-saved Merge files for crystals with bad domains) to be discarded. If not checked, all crystals are kept, and those with negative radii are changed into their positive versions.
      6. Use Raeburn’s version - This uses the formulation of Raeburn and Daniel & Spear for the Correlation functions. See Hirsch, et al. (2000) for details.
      7. Use volume for mark - This uses volume in the calculation of the MCF
      8. Random Point Test - This test is described in Denison, et al. (97). A point is placed randomly, and if the nearest crystal center is nearer than the nearest hole surface and the nearest bounding box surface, then the distance to the crystal is noted. This distance is compared to the value expected in a random distribution, and comparison to envelope values can also be perfomed.
        1. Number of placings - How many placings per test.
        2. Number of repetitions - How many tests are performed (and then averaged into a single measurement)
      9. L function, PCF, MCF - See Hirsch, et al. (2000) for full details. These functions measure the isolation of crystals at a range of scales.
        1. Number of NN distances to measure - This setting dictates the maximum scale to measure the function, as a function of nearest-neighbor distance
        2. Overlap bandwiths by - This setting dictates the spacing of scales of measurement. Overlapping is needed because the outer edged of the bandwidth are weighted very lightly, so do not contribute greatly to the final value at the point.
        3. Number of offset volume points - When calculating the volume of overlap of the bounding box and its offset copy, depending on the shape of the box (see below), an analytical solution may be tractable or not. If not, then a monte carlo estimation is performed. This value controls the number of points in the monte carlo operation.
        4. "c" value for Epanecnikov bandwidth - Dictates the size of the bandwidth, together with the crystal number density. See Hirsch, et al. (2000) for more details.
        5. Sample shape - If this is set at "Sides", the behavior is the old style - uses all the crystals, but it’s slow. Other settings cause a geometric primitive to be fit inside the sides-based bounding box, optimized to enclose as many crystals as possible, and used as the new bounding box to dramatically speed up calculations.
    3. Envelopes - These settings control how the interface-control null hypothesis runs are calculated.
      1. Number of envelope runs - How many null-hypothesis simulations are produced for the null-hypothesis regions.
      2. Match volume fraction in envelope sims - Deprecated. Alters crystal radii in null hypothesis simulations to match the array of crystals being measured.
      3. Match nucleation PDF, if present. - Deprecated. Parses comment line in Crystallize datasets for nucleation probability distribution function, and uses this PDF in making envelope simulations.
      4. Observability Filter - See Hirsch, et al. for details. Filters out simulation crystals that would be unobservable based on the two parts of the criterion.
        1. Separation / Int. Plane Factor - Dictates how close together crystals may be and still be recognizable as separate.
        2. Pair len. / smaller radius factor - Dictates the minimum aspect ratio necessary for crystals to be separately recognizable.
    4. Output - These settings deal with other files that may be output.
      1. Output Reduce3D text file. - This is the main file. It will be marked as belonging to GraphCFs for easy graphing.
      2. Output individual crystal data - Whether the set of crystals should be included in the Reduce3D file.
      3. Output R3STT file - Deprecated. This format used to be the data without labels, for each use in spreadsheets. Modern Excel macros can strip out relevant data from files with ease now.
      4. Output 1,2,3 sigma - This is an option of saving, in the Reduce3D file, mean and sigma values as opposed to the bottom and top of the n-percent confidence regions.
      5. Confidence level - Regular confidence limits, i.e., 95% is 1-sigma. As the number of envelopes is small (typically ~100), you will not get exactly the confidence level you ask for, due to rounding.
    5. Miscellaneous - Various other settings, including algorithm parameters.
      1. CPU greediness - This sets the default greediness value for the progress dialogs, which dictates how much time is allotted to other processes running on the machine
      2. Random seed - This allows for deterministic, random behavior.
      3. Tidy up files - This subjects the incoming crystal array (the data we’re measuring) to the same observability tests as the envelope simulations.
      4. Verbose - Saves a file on the desktop with information about program operation.
      5. Holes File - This is an option to read in another set of crystals, in the same coordinates and with the same origin as the main data set, to be treated as holes. The surfaces of the holes are treated similarly to the edges of the bounding box.
      6. Deal with bad claude - Don’t use this! This was a kludge for addressing the inadequacies of Claude’s original processing.
      7. Discard Xls with radius less than - Don’t use this! This is part of the Claude kludge.
    6. Shave - Settings for "Shaving" volume off the input volume, and how to deal with the gradually reduced volumes.
      1. Do Shave analysis - turns on shaving
      2. Keep aspect ratio - shave in all dimensions, or only one?
      3. X Popup - Which dimension to shave, if not keeping aspect ratio
      4. Percent field - Thickness of shavings
      5. Outside Popup - Shave from low values, high values, or both ("outside"). This applies to 1-D or 3-D shaving
      6. Percent bound - Minimum percent of original left at end.
      7. Crystal bound - Minimum number of crystals left at end.
      8. Aspect Ratio bound - Maximum aspect ratio at end. Only applies to 1-D shaving.
      9. Larger popup - Really, "larger" means larger-larger-smaller for the three fields just above it. In other words, shaving will continue longer if this is set to "smaller", and it will stop sooner if this is set to "larger".
      10. Shave and output only - If this is checked, then each shaved data volume is saved to a file, instead of being measured for statistics each time. This is probably best, now that batch mode is so easy to do, by dragging and dropping in the finder.
  3. A GraphCFs file can be dragged onto the icon to start the program, and the settings used for that calculation will be used.

Program Notes

In version 1.0.2, all crystals in the data set are considered in making the nearest neighbor calculations. In later versions, it is planned to eliminate from consideration those crystals that are close enough to the boundaries of the analysis region to make it probable that their nearest neighbors lie outside the region.

To make 3d calculations which require knowing the exact spatial extent of the sample, a 3d bounding box calculation was included in the code in version 1.0.5. For details, see the documentation for program 3DBB.

The area correction for the Avrami test is the correction in VOLUME. Thus, it does not take into account areas where more than 2 crystals overlap. This should be a minor effect, as it shouldn't happen very often.

Starting in version 1.1.7, all of the CSD plots use extended radius, rather than actual. This is so they’ll be analogous to other CSD’s in the literature.

Since it is a lot faster to tell if a sphere is inside a volume than a cube (only check one point and a distance instead of 8 points...), we experimented with the idea of using a sphere for the quadrat test instead of a cube. After many tests they seemed to give about the same answer (as they really should), so as of version 1.1.3 we took out the cubic quadrat test and only calculate the spherical one. The old code is still intact, though, in case it's needed.

See Hirsch, et al. (2000) at http://gmr.minsocam.org/papers/v2/v2n3/v2n3abs.html for detailed notes on the current calculation methods.

Note that the inset primitive isn’t as elegant as would be desired, as it throws out all crystals outside its bounds after figuring out the best primitive. Ideally, it would use these crystals in measuring statistics, to alleviate the problem with crystals and random points near the sides of the box needing to be ignored in statistics calculations. Additionally, this region could be used as a kind of pre-existing guard region for the CF calculations, if one could figure out how to do it in a reasonable way.

There is a hash table of crystal locations that is constructed at various points to speed in locating crystals in an area, a frequent task for many statistics. Certain operations on the crystal array will make the hash table invalid and it will need to be reconstructed with "RebuildLists"

Known Bugs

None at this time.

Planned Improvements

None at this time.

Release History

This program was based on a version to analyze 2D data sets, called Reduce. That was renamed Reduce2D and this evolved into Reduce3D in 1992.

Reduce history

1.0.0 11 June 91

1.0.1 16 June 91

1.0.2 27 June 91

1.0.3 16 November 1991

1.0.3a 28 November 1991

1.0.4 6 December 1991

1.0.5 13 January 1992

Reduce3D history

1.1.0 1 December 1992

1.1.1 17 February 1993

1.1.2 23 February 1993

1.1.3 14 July 1993

1.1.4 10 June 1994

1.1.5 21 July 1994

1.1.6 29 July 1994

1.1.7 5 August 1994

1.1.8 14 March 1995

1.2.0 9 April 1995

2.0.0 18 July 1995

(Program Notes hiatus)

2.5.3 28 September, 1999

2.5.4 1 October, 1999

(Program Notes hiatus)

2.5.7 3 May 2000

2.5.9 1 August 2000

Authorship

REDUCE was written by William Carlson in early June 1991. Versions 1.0.3 and 1.0.4 written by Richard Ketcham in November and December 1991. Version 1.0.3a fix was done by Cambria Johnson. Version 1.0.5 done by Richard Ketcham in January 1992.

REDUCE3D was writted by Richard Ketcham at the end of July and November-December, 1992. Versions through 2.0.0 by Rich Ketcham, dates as listed. Rewritten in Code Warrior PowerPlant C++ by David Hirsch in late 1995, and all later versions are by David Hirsch, dates as listed.

References

Daniel, C.G., and Spear, F.S. (1999) The clustered nucleation and growth processes of garnet in regional metamorphic rocks from north-west Connecticut, USA. Journal of Metamorphic Geology, 17(5), 503-520.

Hirsch, D.M., Ketcham, R.A., and Carlson, W.D. (2000) An evaluation of spatial correlation functions in textural analysis of metamorphic rocks. Geological Materials Research, 2(3), 1-41.

Raeburn, S.P. (1996) New methods in quantitative metamorphic petrology. Unpub. Ph.D. Thesis, 281 p. Pennsylvania State University.