Notes on Operation

Reduce3D can be run by launching the application, by dragging the input files onto the application, or by double-clicking text (ascii / UTF8) files ending in ".Int". Note that you cannot drag a holes file onto the application – it must be set in the settings window. If launched by running the program directly (i.e., without dragging or clicking input files), then when the settings window is dismissed, the user will be prompted to choose one or more input files. Following this, a progress window will be posted to inform the user of the progress of the calculations. Output file(s) for a particular input file will be saved to the same directory.

Saving envelope datasets is possible. If the [Shift] and {Option] keys are both held down when an envelope simulation is created, then that dataset will be saved to a suitably-named file in the same directory as the input file. If the input file was located at: "/Users/bob/Desktop/data.Int", and the [Shift] and {Option] keys were held down when simulation 83 was created, then that simulation's data will be recorded in a file at: "/Users/bob/Desktop/data_Sim_83.Int". Note that this is an .Int file and can be used as input to Reduce3D.

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 "com.davehirsch.Reduce3D.plist”. The default settings are hard-coded, and can be recalled with the button at the bottom of the window. Each of the tabs controls different aspects of the program’s operation (note that each item has a help tag (aka "tool tip") that will pop up when the cursor hovers over it. The text of each is very similar to the following text).

CSDs – These items control whether to output various types of crystal size distribution (CSD) files, and how to calculate the bin sizes

Mean-Normalized CSD - Histogram of (extended) crystal radii, normalized to the mean radius of the population. This includes both cumulative and non-cumulative data.
Number of size classes - number of bins in histogram
Max x-value - the maximum number of radii for the top histogram bin.
Logarithmic CSD - A CSD designed to be comparable to that shown in Cashman & Ferry (1988). It plots the logarithm of the slope of the cumulate histogram of extended radius, normalized to maximum radius and unit volume.
Max-Normalized CSD - Histogram of (extended) crystal radii, normalized to the maximum radius of the population. This includes both cumulative and non-cumulative data.
Regular and NN CSD - Regular CSD (histogram of extended radius), and CSD of nearest neighbors' extended radius.
Delta L - size of histogram bins, in cm.

Statistics - These settings control which statistics to calculate, and details of that calculation. Note that some basic statistics are calculated regardless of these settings.

Quadrat Test - Rarely used now, places a sphere in the volume and counts crystals inside it to measure ordering / clustering
- Number of placings - How many placings per test.
- Number of repetitions - How many tests are performed (and then averaged into a single measurement)
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. More info on this here.
Do other statistical tests - This 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.
Inflate bounding box - This operation takes the finished bounding box, and moves each vertex away from the box's center by the radius of the crystal the vertex occupies, in order to include more crystals in the calculation (because crystals on or outside the bounding box are discarded). This advantage, however, comes at the expense of accuracy in certain measures such as volume fraction and crystal number density.
Discard boundary crystals - This causes any crystals that have a negative radius to be discarded. Negative radii are used by Crystallize to label those crystals that have illegal domains. This typically indicates that a crystal lies on the boundary of the volume. If not checked, all crystals are kept, and those with negative radii are changed into their positive versions.
Use Raeburn’s version - This uses the formulation of Raeburn (1996) and Daniel & Spear (1999) for the Correlation functions. See Hirsch, et al. (2000) for details.
Use volume for mark - This uses volume in the calculation of the MCF.
Random Point Test - This test is described in Denison, et al. (1997). 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.
L function, PCF, MCF - See Hirsch, et al. (2000) for full details. These functions measure the isolation of crystals at a range of scales.

Number of NN distances to measure - This setting dictates the maximum scale over which to measure the function, in terms of nearest-neighbor distance.
Overlap bandwiths by - This setting dictates the spacing of the 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.
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.
Specify test interval directly - This allows you to choose between two different ways of determining the test interval (the interval between adjacent test distances used in the correlation functions).

“c” value for Epanecnikov bandwidth - Dictates the size of the bandwidth, together with the crystal number density. Bandwidth and test interval scale directly with this value. See Hirsch, et al. (2000) for more details.
test distance interval - Gives the test distance interval, assumed to be in centimeters. The bandwidth is calculated based on this value and the crystal number density.

Sample shape - This is a very important setting. If this is set at “Sides”, the behavior is the older style - uses all the crystals, but it’s very computationally intensive. 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. This will, however, discard a large number of crystals that fall outside the bounds of this new, inset, primitive. The user can optionally choose to use an exscribed primitive instead; see below. (Note that by far the best option is to include explicit bounds of the data volume in terms of a cylinder or a rectangular prism right in the input file.)
Make exscribed primtive - This option will, after creating the (sides-based) convex hull, attempt to make the smallest primitive of the given type (cylinder or rectangular prism) that fits around all crystals in the data set. This option will include the most crystals, but the user cannot be perfectly certain that there is no "empty" volume also included in the primitive. This option is included as a way to have rapid calculations even with small data sets (for which using an inscribed primitive would discard too many crystals).
Shrink exscribed primitive - Shrinks the exscribed primitive by the specified dimensions (this dimension is used as length/width/height/diameter (not radius), depending on the primtive type). This option is included as a way to reduce the probability that any empty volume is included in the exscribed primitive, and would also serve to remove any positive bias of the volume fraction engendered by a tight fitting of a primtive around the data set.

Envelopes - These settings control how the interface-control null hypothesis runs are calculated.

Number of envelope runs - How many null-hypothesis simulations are produced for the null-hypothesis regions.
Match volume fraction in envelope sims - Deprecated. Alters crystal radii in null hypothesis simulations to match the volume fraction of the array of crystals being measured. This is problematic, because you essentially force the null-hypothesis simulations to look too much like your rock in terms of the amount of impingement.
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.
Observability Filter - See Hirsch, et al. (2000) and Ketcham, et al. (2005) for details. Filters out simulation crystals that would be unobservable based on the two parts of the criterion. These values must be carefuly tuned for the data collection method, which Reduce3D can do for you, if you choose to set the observability factors from the data set. Using this filter ensures that your null hypothesis simulations do not contain crystal pairs that might exist in the rock from which your dataset is derived, but that your data collection method is unable to detect.
- Set factors directly - Enter the observability criteria directly.
- Set factors from data - The data set's impinged pairs will be examined, and the observability criterion set to the value that would exclude n% of the pairs, where n is set below.
- Exclude least-observable % - This value determines how much of the data would be classified as unobservable if the observability filter were applied to the data. Zero means that the least-observable pair of crystals would be included if the observability filter were applied to the data set. (Enter this as 0-100, not 0-1.0).
- Separation / Int. Plane Factor - Dictates how close together crystals may be and still be recognizable as separate.
- Pair len. / smaller radius factor - Dictates the minimum aspect ratio necessary for crystals to be separately recognizable.
- Apply observability filter to main dataset - You can also run the filter on your data set itself; this would typically be performed in order to determine how many of your crystals would be rejected by the filter settings.

Output - These settings deal with other files that may be output.

Output Reduce3D text file - This is the main file. It will be marked as belonging to GraphCFs for easy graphing.
Output individual crystal data - Whether the set of crystal data should be included in the Reduce3D file.
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.
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.

Miscellaneous - Various other settings, including algorithm parameters.

Random seed - This allows for deterministic, random behavior.
Tidy up files - This subjects the incoming crystal array (the data we’re measuring) to the same observability tests as the envelope simulations.
Verbose - Saves a file on the desktop with information about program operation.
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.

Shave - Settings for “Shaving” volume off the input volume, and how to deal with the gradually reduced volumes.

Do Shave analysis - turns on shaving
Keep aspect ratio - shave in all dimensions, or only one?
X / Y / Z - Which dimension to shave, if not keeping aspect ratio
Percent field - Thickness of shavings
Outside Popup - Shave from low values, high values, or both (“outside”). This applies to 1-D or 3-D shaving
Percent bound - Minimum percent of original left at end.
Crystal bound - Minimum number of crystals left at end.
Aspect Ratio bound - Maximum aspect ratio at end. Only applies to 1-D shaving.
Larger / Smaller - 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”.
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.