Last updated: 21-January-2014
Overview of Features
Menu Item Explanations
Scenario 1. Measuring a new series
Scenario 2. Appending a new series to an existing file of measurements
Scenario 3. Appending or inserting measurements to an existing series
Scenario 4. Editing an existing series
Scenario 5. Measuring Earlywood/Latewood
Appendix 1. Raw data 'decadal' format description
Appendix 2. Description of 'csv' (comma separated value) format
Appendix 3.Change in File, Save Behaviour from V3.x to V4.x
The MeasureJ2X program is a full featured program for measuring tree rings. The program enables capture of measurements from a variety of measuring stage/encoder/digital readout units and has features for creating measurements of new series or editing existing series. The editing capabilities include being able to append, insert or delete measurements from a series and shift a series forwards or backwards in time. The program reads and writes files of series in the "decadal" format, allowing its output to be used with analysis programs available from the Dendrochronology Program Library (DPL).
The details of the interface with the measuring stage and encoder and associated digital readout units are covered in the Installation Guide.
Much of the use of the program is self-explanatory through menu options and choice box selections. There are a variety of user options that change the behaviour of the program which are described below. There are also step-by-step measuring scenarios for some of the more common situations. It is recommended that you follow a measuring scenario with a test series to gain familiarity with the program and to understand how to save measurements to a file.
Overview of Features
MeasureJ2X provides features for measuring total ring width and earlywood/latewood ring width series. It allows for measuring the series in either direction (from bark to pith or pith to bark), for inserting measurements into an already measured series and provides features for editing an already measured series.
The V5.x releases (first released Sept, 2013) added support for controlling the zeroing and sending of measurements from the digital readout using the keyboard or mouse, added support for new digital readouts, added the ability to save files in 'csv' format for direct input into spreadsheet programs for quick plotting and data checking, and added support for 'incremental' mode measuring in which the readout is zeroed after each measurement.
The V4.x releases (first released June, 2007) added the ability to measure earlywood/latewood, among other enhancements, including adding support for extended series ids, files with metadata, an autosave option, and has the ability to manually enter and edit values.
There is an important change in behaviour relating to the way files are saved in the V4.x releases. Users upgrading from a V3.x release should review the description of the changes before measuring.
The V3.x releases (first released 2002) added support for Java 2 which improved the user interface in a number of areas.
The V2.x releases were the first releases and had features for measuring and editing total ring width series.
For a complete description of the releases and features added, please see the release notes.
Menu Item Explanations
The choices in the File Menu allow manipulation of files of measurements. The operations act on files in a standard way, as they would in any other program such as a word processor or spreadsheet program.
Files contain one or more series. A series is a group of measurements with a unique identifier (Series ID) and usually represents the measurements for a single sample (core, disk or otherwise). The default file format is the format commonly referred to as the 'decadal' format. Further description of the 'decadal' format is given in Appendix 1. This format is appropriate for use with other programs that are commonly used to analyze tree ring data. For more information on tree ring analysis programs, see the section on "DPL - Dendrochronology Program Library" at http://www.ltrr.arizona.edu/software.htm.
A file may also be saved in the 'csv' (comma separated values) format which allows the file to be directly imported into a spreadsheet program such as Excel allow the ability to review data, compare series and make graphs or plots of the series. A description of the 'csv' file created is given in Appendix 2. The 'csv' file format does not save any metadata.
File Open, opens an existing file of measurements.
File Open is not used to create a new file of measurements and there is no explicit File, New operation. To create a new file of measurements, one simply begins measuring new series with Series, New. A new file is written when File, Save (As) is used and a new file name for measurements is given.
To edit existing and previously saved measurements, first open the file with File, Open and then use Series, Edit to edit the series.
File Save (As)
File, Save (As) writes the series and related measurements to a file. The series that will be written to the file are the "current" series group, which are those listed in the Series, Statistics window. This will include any additional series measured since the last File, Open and any changes made to existing series using Series, Edit. Use Series, Statistics to confirm what the "current" set of series is and what will be written to the file. File, Close clears the "current" series group.
The format of the file is specified by selecting the appropriate choice in the 'Files of type:' dropdown in the File, Save dialog. If an extension is not given, the default extension for the file type will be appended. The default extensions are the first listed in the the 'Files of type:' dropdown for each file type:
- Raw Measurements - decadal (tucson) format (*.raw)
- Raw Measurements - csv (spreadsheet/excel) format (*.raw.csv)
- Raw/Ew/Lw Measurements - decadal (tucson) format (*.rwl, *.ewr, *.lwr)
- Raw/Ew/Lw Measurements - csv (spreadsheet/excel) format (*.rwl.csv, *.ewr.csv, *.lwr.csv)
When measuring earlywood/latewood, the filename specified for File, Save (As) is the name of the total ring width measurements. The associated earlywood and latewood files will be created using the basename specified for the total ring width measurements and the extensions specified in Setup, Ew/Lw File Extensions.
If an existing file is specified when using File, Save (As), the program will prompt the user to indicate whether to 'Append' or 'Overwrite' the file. Specifying 'Append' will append (add) the "current" series (i.e those listed in Series, Statistics) to the existing file. Specifying 'Overwrite' will overwrite the contents of the file with the "current" series.
Note on 'Append' option: File, Save (As) does not clear the set of "current" series. File, Close must be used explicitly to clear the "current" series and start a new group of series. Because of this, be careful about using File, Save (As), and specifing 'Append' multiple times without an intervening File, Close. This is usually not the behaviour that is desired as it will result in multiple instances of the same series in the file.
For example, if a series, 'test1', is measured, then File, Save (As) is used, the series 'test1' will be written to the file. If a second series, 'test2' is then measured, the "current" series group, as listed in the Series, Statistics window, is composed of 2 series: 'test1' and 'test2' . If File, Save(As) is then used again with the same filename and the 'Append' option, this will append 'test1' and test2' (the "current" series) to the file, appending them after the existing contents of 'test1'. This will result in a file with 3 series written to it: 'test1' from the first File, Save (As) operation, followed by 'test1' and 'test2' from the 2nd File, Save(As) operation. The series 'test1' will then present in the file 2 times.
File, Close must be used before opening another file, as only one file of measurements can be open at a time. If File, Close is issued and changes have been made to the file of measurements and not saved, a warning will be issued. This can be used to discard changes, if desired.
File, Close clears and resets the "current" set of series (i.e. those show in Series, Statistics).
File, Exit causes the program to exit. If File, Exit it issued and changes have been made (new series measured or existing series edited) and they have not been saved, there will be a warning and an opportunity to save the changes.
Used to start measuring a new series. Selecting this will first display a pop up window for entering the basic information about a series: Series Id, Start Year, Extended Id (optional) and then will display a window for measuring a new series. The length of the Series Id and the Extended Id are limited by the use of the'decadal' format (see Appendix 1.).
Allows editing of a series by opening a measuring window with the existing series measurements displayed and providing access to the Shift, Delete and measuring stop and start buttons.
If the 'Direct Edit Mode' option is selected, the window will allow editing of a measurement using the keyboard (rather than only being able to enter it by sending from the digital readout).
Deletes an entire series from the current set of measurements
Displays a window with current statistics (id, start year, end year, # of measurements, mean measurement, extended id) for all series currently known to the program. This can be used at any time and is very helpful to verify what will be saved when File, Save (As) is used (see also File Open, Save (As) ).
Displays a window with any metadata that was read with File, Open. If earlywood/latewood is selected, there will be 3 groups of metadata corresponding to the metadata headers lines found in each of the files. This can be used at any time and will verify what metadata will be written to the file(s) when File, Save (As) is used. In order to read metadata in existing files, the number of metadata lines has to be first set in Setup, Metadata lines.
Settings for various optional features. Early/Late Wood Measurement and Direct Edit Mode apply to a whole file or series group and must be set prior to opening a file or measuring a new series and cannot be changed until File, Close is used.
Initial Value Prompt - Whether or not to show the initial value read from the measuring device before proceeding with measurement. Some people find this prompt useful while measureing to confirm their device is communicating properly, while some people find the need to confirm this prompt before proceeding with measuring unnecessary and slows the measurement process. The default is to display the prompt.
Decade Audio Signal - Whether or not to sound a beep when measuring a value for an even decade (1900, 1910, etc.). This is useful to allow a person measuring to ensure they have not missed a ring value. The default is on.
Early/Late Wood Measurement - Whether or not to measure a series by measuring the intermediate earlywood and latewood periods of a ring width. In this mode, the program expects the first measurement of a ring to represent the earlywood width and the second measurement to represent the latewood width. The program automatically calculates the total ring width as a sum of the earlywood and latewood widths and displays it in the measuring window.
AutoSave Mode - Whether or not to automatically save a series to a file after measurement of a series is complete. With AutoSave mode turned on, when the measurement of the first series has been completed and the measuring window is closed, the program will automatically prompt for a filename to use for autosaving. Typically, a new filename is specified, and the program will write the first series to it. When the measurement of subsequent series are completed (signalled by the closing of the measuring window) the program will automatically save the newly measured series to the file specified.
Direct Edit Mode for Total Measurement - Whether or not measurement values can be edited by entering a value using the keyboard. This option only applies to total ring width files. Direct editing is the default for Early/Late Wood Measurement and doesn't need to be set. Without Direct Edit Mode turned on, the only way to change a measurement value is to set the value on the encoder and use the Measure: Stop/Start buttons to send it to the measuring window.
Setup, Measuring System
Sets up the characteristics of the measuring system, including measuring system type and precision. These must be set correctly for the equipment for measurements to be received and interpreted properly. If you have not already done so, please see the Installation Guide for a full explanation of these setttings and how to set up the MeasureJ2X program.
Digital Readout Type - the type (brand) of digital readout (DRO) being used in conjunction with the measuring stage and encoder
Other - this is a custom setting allowing the program to interface with any measuring system device meeting a small set of requirements. It requires a custom module for the measuring system device to be available to the program. Please contact email@example.com if you have a measuring system/digital readout that is not listed in the setup menu and you would like to use with the program.
Precision - typically set to 0.001, but must match the encoder that is being used
Mode - The way the program will process measurements. Absolute mode is the default and is the typical method of measuring. In this mode the program will calculate the difference between successive measurements to compute a ring width. Incremental mode will zero the counter in between measurements and use the value sent or received from the digital readout as the measurement without further calculation. Incremental mode is more appropriate for certain types of encoders (ie magnetic strip) that may accumulate errors over longer distances. Incremental mode requires 2-way communication with the readout so is not available for the older Boekler and Measuchron readouts.
Sets up the characteristics of the connection to the measuring system, including the communications port, speed, data bits, stop bits and parity settings. These must be set correctly for measurements received to be interpreted properly. The proper settings for the standard measuring systems are explained in the Installation Guide.
Setup, Ew/Lw File Extensions
Available only when Options, Early/Late Wood Measurement is selected and allows entering the file extensions that will be used to read or write the earlywood and latewood files. The extensions will be used along with the base file name from the total ring width file entered for File, Save (As). For example, if the filename 'site105.rwl' is entered when using File, Save (As), then the default extensions of '.ewr' and '.lwr' would cause the earlywood file to be named 'site105.ewr' and the latewood file to be named 'site105.lwr'.
Setup, Metadata Lines
Sets the number of lines at the beginning of the file that will be read as metadata headers. Be cautious to set this number appropriately for the file you are opening. Setting it larger than the number of metadata lines that actually exist will result in measurement data being skipped and read as metadata.
Setup, Save Settings
This allows the settings in the Setup, Measuring System and Setup, Connection menu items to be saved as they are set and be used the next time the program starts up. This is typically used once to save the settings after testing and the program is communicating properly with the encoder.
The measuring window appears when either Series, New or Series, Edit has been issued. The window allows measuring of a series to begin, or manipulation of series, such as changing its starting or ending year.
At the top of the measuring window appear the menu items for Delete and Shift and at the bottom of the window the measuring toolbar with the Measuring Stop/Start buttons and the Measuring Mode selection box appears. The measuring toolbar can be independently dragged to a different window location if desired by selecting the vertical bar in the far left of the toolbar and dragging to the desired location.
Measuring Start/Stop buttons
These buttons control measuring. The Start button is pressed to begin measuring, the Stop button is pressed to pause or end measuring. The Start and Stop buttons can be repeatedly pressed in a measuring session. The Stop button is used when it is necessary to reposition the sample on the measuring stage. It can also be used in the middle of measuring a sample to assure measurements are not inadvertently entered while taking a break from measuring or leaving the measuring system unattended. Once the Start button is pressed, the measuring mode can not be changed.
Enter Measurements Manually
This box is used in conjunction with the Measuring Start/Stop buttons. If this box is checked when the Start button is pressed, a dialog box will bedisplayed allowing the measurement to be entered directly from the keyboard rather than a measuring device. If no communication port is available a warning will be displayed to indicate that a measuring device will not work without a communication port but the user will be allowed to continue entering measurements manually.
There are 4 "measure" modes which are set from the drop down box on the right hand side of the measuring window. The best way to become familiar with the way the measuring modes work is to run through some scenarios on a test series to see how the program behaves.
1. App-FixFYOG - "Append, Fix First Year of Growth"
This will append measurements to the series by adding the new measurement as the most recent (last) year in the series. This causes the first year of growth (least recent) of the series to remain fixed, while incrementing the last year of growth (most recent) with each measurement. This mode is used when measuring from the pith towards the bark. In this mode, new measurements will always appear at the bottom of the measuring window as series are always displayed from least recent to most recent.
2. Mode: App-FixLYOG - "Append, Fix Last Year of Growth"
This will append measurements to the series by adding the new measurement as the least recent (first) year in the series. This causes the last year of growth (most recent) of the series to remain fixed, while incrementing the first year of growth (least recent) with each measurement. This mode is used when measuring from the bark towards the pith. In this mode, new measurements will always appear at the top of the measuring window as series are always display from least recent to most recent.
3. Mode: Ins-Fix FYOG - "Insert, Fix First Year of Growth "
This mode will insert measurements into the series beginning at the measurement that is selected. The location for insertion must be selected prior to the start of measuring by pointing, clicking and highlighting a cell displaying a measurement value (not a year or display value cell). Subsequent insertions will cause the first year of growth (least recent) of the series to remain fixed, while forcing the last year of growth (most recent) to be incremented, and causing the measurement window to grow towards the bottom of the window. This mode is used when measuring from the pith towards the bark.
4. Mode: Ins-FixLYOG - "Insert, Fix Last Year of Growth"
This mode will insert measurements into the series beginning at the year of the measurement that is selected. The location for insertion must be selected prior to the start of measuring by pointing, clicking and highlighting a cell displaying a measurement value (not a year or display value cell). Subsequent insertions will cause the last year of growth (most recent) of the series to remain fixed, while forcing the first year of growth (least recent) to be incremented, and causing the measurement window to grow towards the top of the window. This mode is used when measuring from the bark towards the pith.
Will shift the entire series forward or backward in time the number of years indicated. A negative number indicates a shift backwards in time. For example, entering -2 for a series that currently has a start year of 1900, will cause the series to have a new start year of 1898.
Delete: Fix First Year of Growth
This will delete a consecutive range of measurements that are currently selected. Measurements are selected by pointing, dragging, and highlighting the measurements to be deleted. The deletion will done such that the first year of growth (i.e. oldest) remains fixed, while the last year of growth (i.e. most recent) will be decreased by the number of measurements deleted.
Delete: Fix Last Year of Growth
This will delete a consecutive range of measurements that are currently selected. Measurements are selected by pointing, dragging, and highlighting the measurements to be deleted. The deletion will done such that the last year of growth (i.e. most recent) remains fixed, while the first year of growth (i.e.oldest) will be increased by the number of measurements deleted.
Scenario 4. Provides and example of using the delete operation and describes it in more detail.
Scenario 1. Measuring a new series
A measuring window for the series will appear with the starting year.
6.1 If the program is not able to open and communicate with the serial port, you will get a dialog box with a message like "Sorry, unable to open COM1". If you get this message, check your connection and measuring system settings by using the Setup, Connection and Setup, Measuring System menu items (you do not have to leave the measuring window). If you make changes, press the ‘Measure’ button again and it will use the new settings.
Note: The Setup, Connection and Setup, Measuring System menu items can be set at any point before the first time the Measure button is pressed and measuring begins successfully. After measurement has begun, the Setup menu items are no longer available until you close the measuring window. You can then reset the connection, if you needed to, but there should be no reason to set it differently.
6.2 If you continue to have troubles with getting started with measuring, refer to the instructions in the Section 4. ‘Measuring System Setup’ of the Installation Guide.
Note to users of the PJK program: This ends measuring. There is not requirement to send a value less than the previous to indicate you are finished with measuring.
Once the filename is entered the program will respond with a confirmation message indicating the number of series that were successfully saved to the file.
Scenario 2. Appending new series to an existing file of measurements
You can append a new series to an existing file by using File, Save (As), specifying an existing file and selecting 'Append':
Note: With AutoSave mode turned on, the end result will be 2 files. The autosave file will contain just the newly measured series and the existing file will contain the previously measured series, and the new series that were appended to it.
Scenario 3. Appending or inserting measurements to an existing series
You can append or insert measurements to an existing series by first opening the file of existing measurements and then using the Series, Edit menu item to add measurements to the series.
Scenario 4. Editing an existing series
An existing series can be changed by using the 'Delete' or 'Shift' menu items or by appending or inserting measurements as described in Scenario 3. The 'Delete' and 'Shift' menu items are described briefly above.
For deletion, measurements to be deleted are indicated by highlighting with a range of measurements with the mouse. If the measurements to be deleted span more than one line, they must be deleted in 2 operations. Due to the way the measurements get reassociated with years upon deletion, it is simpler to delete the oldest measurements first when using ' 'Delete, Fix First Yr of Growth' or to delete the earliest measurement first when using ''Delete, First Last Yr of Growth'. For example, to delete measurements from 1905 to 1915, when using 'Delete, Fix First Yr of Growth', one would first select the measurements associated with 1910-1915 and choose 'Delete, Fix First Yr of Growth' from the 'Delete' menu and then select the measurements associated with '1905-1909' and again choose 'Delete, Fix First Yr of Growth' from the 'Delete' menu.
After making changes to the series, you can do any of several things:
- You can use the Series, Statistics menu item to review what the program has for statistics on the edited series.
- You can close the measuring window control in the upper right hand corner (X on the PC and a square box on the Mac) and save the edited series to a file using the File, Save (As) menu item.
Scenario 5. Measuring Earlywood/Latewood
Measuring an earlywood/latewood series is similar to measuring any new series as described in Scenario 1. 'Measuring a New Series', but you must set the option 'Early/Late Wood Measurement' in the Options menu before starting a new series using Series, New.
When measuring, the program will interpret the first measurement sent as the earlywood measurement and the second measurement sent at the latewood measurement. The program will automatically calculate the total width from the first 2 measurements as described in the menu description for Options, Early/Late wood measurement.
The program requires that you have both an earlywood and latewood measurement for each year before you can close the measuring window for the series. If you do not, it will present a warning and request that you enter additional values so that each year of measurement has both values.
When you use File, Save (As) in this mode, you will specify the filename for the total ring widths. The program will then use the file extensions specified in Setup, Ew/Lw File extensions to form the names for the earlywood and late wood files. See Setup, Ew/Lw File extensions for further information.
Each line of the raw data file can be described by the Fortran I/O descriptor (a8,i4,10i6,1x,a7) or by the description in the following table.
The first lines of the file may optionally contain metadata information. To read a file with metadata headers, the number of lines to be read as metadata must be set in the Setup, Metadata lines menu item. The metadata can be in any format and if read upon input, will be written to the output file in the same format it was read when File, Save (As) is used.
|Start Column||End Column||Column Size||Field Type||Field Description||Fortran I/O Descriptor|
|9||12||4||integer||start year or decade1||i4|
|13||18||6||integer||value for start year or decade1||i6|
|19||24||6||integer||value for (decade+1)2||i6|
|25||30||6||integer||value for (decade+2)2||i6|
|31||36||6||integer||value for (decade+3)2||i6|
|37||42||6||integer||value for (decade+4)2||i6|
|43||48||6||integer||value for (decade+5)2||i6|
|49||54||6||integer||value for (decade+6)2||i6|
|55||60||6||integer||value for (decade+7)2||i6|
|61||66||6||integer||value for (decade+8)2||i6|
|67||72||6||integer||value for (decade+9)2||i6|
|74||80||7||character||extended id field||a7|
1On the first line of data, the year given is the starting year of the data set. The corresponding value for the start year appears in the first value column (columns 13-18). The values for the remainder of the decade appear in the subsequent value columns. For example, the first line of data may contain 1905 as the year in columns 9-12, then the line will contain the value for 1905 in columns 13-18, the value for 1906 in columns 19-24, the values for 1907 in columns 25-30, ..., the value for 1909 in columns 37-42. The remainder of the line, up to column 74 , will be blank.
2Value or sentinel when end of data set. Sentinal is either '-9999' for values with precision of '0.001' or '999' for values with precision of '0.01'. A value of '0234' in a dataset with a sentinal of '-9999' represents a measurement of '0.234' (0234 * 0.001). A value of '0234' in a dataset with a sentinel of '999' represents a measurement of '2.34' (0234 * 0.01).
An example of a file in the 'decadal' format:
TW9901 1900 449 608 529 902 759 732 TW9901 1910 929 828 1067 909 1180 1032 1127 739 1177 1151 TW9901 1920 687 624 552 559 579 864 703 612 819 824 TW9901 1930 793 990 -9999 TW9902 1900 450 609 530 901 758 TW9902 1910 345 393 347 331 401 347 331 401 247 395 TW9902 1920 731 374 507 532 636 525 399 321 644 749 TW9902 1930 696 991 -9999
Appendix 2. Description of 'csv' (comma separated value) format
The 'csv' format will create a text file with each series arranged as a column of data. The first line of the file is a header line that labels the columns, with the first column labeled with 'Year' and the subsequent columns labeled with the Series Id's as they were entered upon measuring. The subsequent lines of the file contain an actual year followed by the measurements for each series for that year, with each value separated by a comma. If the series does not have a measurement for a particular year, it is blank.
This format is typically able to be read directly into spreadsheet programs such as Excel without the need for any setup within the spreadsheet program or modification of the data file. The can be useful for quickly comparing data and creating line graphs.
An example of a file in 'csv' format:
Year, 8, 7B, 6A 1325, 3.80, 1.062, 0.313 1326, 2.06, 0.654, 0.388 1327, 3.18, 0.489, 0.38 1328, 3.76, 0.701, 0.207 1329, 3.02, 0.475, 0.326 1330, 3.09, 0.453, 0.277 1331, , 0.351, 0.296 1332, , 0.203, 0.289 1333, , 0.233, 0.255 1334, , 0.298, 0.435 1335, , 0.159, 0.371
Example of 'csv' file after opening in Excel:
Appendix 3. Change in File, Save Behaviour from V3.x to V4.x
There is an important change in behaviour from V3.x to V4.x relating to the way files are saved:
You no longer need to first use File, Open and open an existing file of measurements in order to be able to append newly measured series to an existing file of measurements. Once a new series, or group of new series are measured, you may use File, Save (As) and specify an existing file of measurements. By specifying an existing file of measurements, you will be prompted to either 'Append' or 'Overwrite' the file. Specifying 'Append' will append the new series (or group of new series) to the existing file. This is now the recommended way to append new series to an existing file of measurements. Append mode will not disturb existing data.
Turning on the new AutoSave mode (Options, AutoSave mode), provides an additional level of protection for newly measured data by automatically saving series to a file after the measurement of a series is complete. With AutoSave mode turned on, when the measurement of the first series has been completed and the measuring window is closed, the program will automatically prompt for a filename to use for autosaving. Typically, a new filename is specified, and the program will write the first series to it. When the measurement of subsequent series are completed (signaled by the closing of the measuring window) the program will automatically save the newly measured series to the file. The older method of using File, Save (As) after completing the measurement of each series to perform a 'manual autosave' is no longer recommended in preference to using the new AutoSave mode feature.
To append a newly measured group of series to an existing file of measurements with AutoSave mode turned on, the filename specified for autosaving should be a new file. At the end of measuring the new group of series to append to an existing file of measurements, use File, Save (As), specify an existing file, and choose the 'Append' option. This will result in 2 files. The file specified for autosaving will be a newly created file that contains just the newly measured series and the file specified for File, Save (As) will be an existing file with the newly measured series appended to it.
Series, Statistics can still be used to determine what data the MeasureJ2X program will write to a file. The list of series contained in the Series, Statistics window is the list of series that the program will write to a file, whether append or overwrite is specified.
The new behaviour for File, Save (As) and the new AutoSave mode do not replace the need for backing up data files. As for all electronically stored data, it is recommended that files be appropriately backed up at the end of a measuring session and that files that will be used for appending to are backed up prior to appending new series.