Last updated: 2-Jul-2007
New Features in Version 4.1.1
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
The MeasureJ2X program is a full featured software 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.
The program has a menu driven graphical user interface and thus, much of its use is self-explanatory. 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.
New Features in V4.1.1
Version 4.1.1, released in June, 2007 adds the following new main features to the MeasureJ2X program:
- measurement of earlywood/latewood series
- autosave mode
- support for extended ids
- support for manual input of measurements
- support for reading files containing metadata
- integrated help system
Important Note to Current Users
If you are a current user of MeasureJ2X please note the following important change in behaviour 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.
Menu Item Explanations
The choices in the File Menu allow manipulation of files of measurements.
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 file format used 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
File Open, Save (As)
These operations act on files in a standard way, such as they would in a word processor. The data in a file are measurements for one or more series. File Open, opens an existing file of measurements. File, Save (As) saves the existing set of measurements to the file specified, including any changes made since the last File, Open. Changes may include a new series being measured with Series, New or an existing series being edited with Series, Edit. In order to be able to edit exiting measurements with Series, Edit, the file must first be opened with File, Open.
There is no explicit File, New operation. To create a new file of measurements, one simply begins measuring a new series with Series, New. The new file will be created when File, Save (As) is issued for the first time.
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 series (or group of new series) to the existing file. Specifying 'Overwrite' will delete the current contents of the file and write the existing series to the file.
The series that the program will write to the file when either 'Append' or 'Overwrite' is specified is the group of series that is listed in the Series, Statistics window.
File, Save (As) does not close the file. File, Close must be used explicitly to close a file and start a new file of measurements. See more on File, Close below.
Be careful about using File, Save (As), specifing an existing file of measurements, and specifing 'Append' multiple times without an intervening File, Close. This is usually not the behaviour that is desired as it will save a given series multiple times to a file. For example, if one series, 'test1', is measured, the series 'test1' will be appended to the file. If a second series, 'test2' is measured, and File, Save(As) to the same file, with 'Append' chosen, will append 'test1' and test2' to the file. The file will then have 3 series appended to it: 'test1' from the first operation, and 'test1' and 'test2' from the 2nd operation.
Turning on the new AutoSave mode (Options, AutoSave mode), will automatically prompt for a filename to save newly measured series upon completing measurement. See Options, AutoSave mode for a full explanation. This is now the recommended way to perform incremental file saves. The previous method of performing a manual autosave by using File, Save (As) in between measurements of each series to perform an incremental save of everything measured up to that point in time is still available but no longer recommended. To do a 'manual autosave', the same filename is specified each time and 'Overwrite' mode is chosen.
To append a series to an existing set of measurements, use File, Save (As) and specify an existing file of measurements. By specifying an existing file of measurements, you will be prompted to indicated whether you wish to '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. This method has the benefit of protecting existing data by assuring that if for some reason errors exist in writing new series, the program will not disturb existing data.
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.
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, 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, a warning will be issued.
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 via the encoder).
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.
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.
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 system type and precision. 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.
'Other' Measuring System - 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 compiled and available to the program. Please contact firstname.lastname@example.org before using this option.
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.
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':
Once the filename is entered the program will respond with a confirmation message indicating the number of series that were successfully appended to the file.
Note: With AutoSave mode turned on, the end result will be 2 files. The autosave file that contains just the newly measured series and the existing file that the new series were appended to.
Existing users of MeasureJ2X may wish to review the Important Note to Current Users regarding the change in behaviour regarding appending new series.
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