 |
|
 |
JGView Usage Documentation Usage Documentation | Installation | Usage Examples
Introduction | Screen
Layout | Selecting
Data | Criteria
| Viewing
| Exporting
Extending JGView | Troubleshooting 1.0 Introduction1.1 General OverviewJGView, a platform-independent computer program written in Java, provides a graphical user interface for subselection, viewing, and export of data collected for U.S. JGOFS. JGView enables the user to browse through the catalog of U.S. JGOFS data, select any set of parameters from a data file, define subselection criteria for those parameters, view the data in tabular form, and export the subselected data in a variety of file formats. These file formats include, Ocean Data View (ODV) Generic and General Formats, MATLAB format, and Tab/Comma Delimited formats.1.2 Look and FeelJGView comprises three window panes. The upper-left pane holds the catalog of the U.S. JGOFS dataset within a tree-structure used for browsing. Once a data file selection has been made, the window pane to the upper-right asks for parameter criteria for targeting the desired data within that data file. After the criteria have been established, this window pane will display the selected data in tabular form. Finally, the pane below both the catalog and the data is the documentation pane. The documentation pane displays metadata for the presently selected data file.1.3 Ease of UseJGView was designed to provide quick and easy access to a data collection and enable subselection of data to suit a user's needs. The U.S. JGOFS Process Study data has been cataloged into a tree-like browsing structure allowing users to locate data of interest. After selecting a data file, JGView supports subselection of the data within that file based on selection criteria associated with each parameter. Once selection criteria have been set, data can be viewed in the data window pane or simply exported to a file in one of the various file formats. As an alternative to browsing through the tree, JGView has a search function that can search the catalog for a user-specified data parameter and return a list of hypertext links to data entities in which the parameter was found.1.4 JGView Data FilesThe data files used by JGView are all in tab-separated value format (.tsv files). The data files can be found in the /data directory on the CD-ROM. JGView mirrors the exact file structure of this data directory to use as the tree catalog. JGView uses support files to help gather information such as parameter descriptions, units, and metadata about the selected data file. These support files have the same basename as the data file, but with different file extensions. The .ndx files are used to display metadata and .htm files are parsed for the parameter descriptions and units. For the Merged Product files, the parameter information comes from the param_master.dct (U.S. JGOFS master parameter dictionary) file at the top of the /data directory. Every time a data file is selected from within JGView, the metadata for that data file is displayed in the lower documentation window pane. The parameter descriptions and units are used in naming the catalog entities and helping with the subset, view, and export functions.1.5 Running JGViewThe U.S. JGOFS dataset is extremely large. Running JGView from the CD-ROM preserves space-efficiency. However, to gain optimal performance, we recommend copying the CD-ROM to your hard disk. JGView will always try to find the data directory relative to its location. The relative path defaults to ../../data. If the /data directory is not found at the default location, JGView prompts for new locations for the /data, /docs and /images directories. This feature permits users to arrange their file system in a manner that suits their capabilities while ensuring that JGView will continue to function properly. See section 7.1 Moving JGView off the CD-ROM.
1.6 Getting StartedWhen JGView starts up, it loads the Java Virtual Machine. This can take up to one minute depending on the operating environment. JGView displays a U.S. JGOFS splash screen image while it loads all files in the data directory. After the splash screen disappears, you may begin subsetting data. Navigate through the data catalog tree to a data file of interest. Expand the data file so that its parameters are displayed in the data catalog tree. Highlight the parameters that you would like to subset from the data file and press the 'Subset' button. In the right pane, define the selection criteria for these parameters and press either the 'View Data' button to see the selected data or the 'Export' button to save the data to a file in any of the supported file formats. Information about the currently selected data file is displayed below in the Documentation window pane. Press the blue info icon or the 'Info' button from
the toolbar to view detailed documentation about the data file in your
system's default browser. Use the toolbar 'Search' button to search the
data catalog tree. The search generates a link list in the documentation
window which can be used to locate data files within the data catalog
tree.
2.0 JGView Screen LayoutThe JGView window consists of a main menu bar and toolbar at the top, the data catalog window pane on the left, the data subset and viewing window pane on the right, and the documentation window pane at the bottom. Window pane sizes can be changed by dragging the bars that separate them.2.1 Main MenuFile:
Edit:
Help:
2.2
Toolbar
2.3 Data Catalog TreeThe window pane on the left of the application is the data catalog tree, and it is a tree-structured representation of the file system holding the U.S. JGOFS data files. All of the data is stored in the /data directory on the CD-ROM. Each directory on the file system, is represented by a folder icon. Each data file within these folders, is indicated by an INFO icon.
Each parameter within the data file, is indicated by a leaf icon  .The data is categorized at the first level of the tree according to the basin in which the data was collected. The four U.S. JGOFS basin studies were North Atlantic, Equatorial Pacific, Arabian Sea and Southern Ocean. At the next level the data has been grouped according to 'data type' or oceanographic discipline. This level comprises labels such as Biological, Chemical, Metadata, Sediment Core, etc. All categories are designated by the folder icon  .
Data files within the 'data type' categories are identified by an information icon . Clicking on an information
icon opens the corresponding HTML information file in a browser window
(same as the INFO button on the Toolbar). Each data file's parameters
are listed below its description. All parameters are designated by the
file icon,  on Windows and on the other operating systems.
2.4 Data View PaneThe window pane on the right of the application display is the Data View pane. This pane has two purposes 1) to display the selection criteria for selected parameters when the 'Subset' button has been clicked, and 2) to display selected data when the 'View Data' button has been clicked.The selection criteria are displayed in tabular form with each selected parameter occupying one row. The 'Reset Criteria' button, atop the table, resets all selection criteria back to their default settings. The display of selected data is also presented in tabular form with each parameter occupying one column. These columns can be rearranged by clicking on the column header and dragging to the desired location within the table. 2.5 Documentation PaneThe documentation window pane occupies the lower portion of the JGView display screen. It is used to 1) display data file information whenever a data file has been selected, and 2) display search results.2.6 Documentation and Data View BordersWhenever the documentation pane or data view pane is displaying data file information, its border will display the file system path to that data file. For example, the biology file N_uptake_atlantisII from the North Atlantic basin would be expressed in the border as its true file path North_Atlantic/Biological/Productivity/N-uptake_atlantisII.3.0 Selecting DataData can be selected for any number of parameters within one data file. When expanding the data file to view its parameters, all parameters are selected by default, except for data files in the Merged Product category which do not select all parameters by default. To modify a data selection click on the parameters listed beneath the data description to either add/remove it to/from the selection based on its previous state. To finish the selection, click the 'Subset' button from the Toolbar to display the selected parametersÂ’ selection criteria. At any time, you may add or remove parameters from the selection by clicking them in the catalog tree and then clicking 'Subset'. Previously established selection criteria will be unaffected by the addition or removal of parameters.Selections cannot be made between two or more data files. If an invalid selection is requested, JGView will indicate the remedial action.
3.1 Using the Data Catalog TreeTo subset data, highlight any combination of parameters so long as those parameters are all in the same data file. The parameters of a data file are always the leaf icons of the tree (they cannot be expanded). When a data file becomes highlighted (selected), an arrow will appear to it's left. This signifies that it is now the active file for subsetting. If a data file has been highlighted and not expanded, pressing 'Subset' will include all of the data file's parameters in the next step, defining the extraction criteria. Expanding the data file will show that all parameters are highlighted meaning they are selected to be subsetted. Clicking a highlighted parameter will deselect it, vice versa. By clicking on parameters, the user either selects or deselects that parameter depending on its previous state.Collapsing a data file will remove all selections from within that data file. This includes collapsing any path to that data file. For instance, if N_uptake_atlantisII in the North_Atlantic/Chemical/Chem path is the current data file, collapsing any of the North_Atlantic, Chemical or Chem entities will remove all selections made for the N_updake_atlantisII file. No warning of this removal will occur unless you have previously clicked the 'Subset' button. If 'Subset' was previously clicked, the user is given the option of continuing with the new operation and losing the current work or to return to the current work and restore JGView to its previous state. If a subset had not been taking place, JGView assumes that you never intended to work on the selected data since you have collapsed it. This same warning behavior occurs if a selection is made outside the current data file. The warning gives you the option to continue or cancel the new selection and return to the current subset. Parameters cannot be selected across more than one file. If you are working on a current subset and click within that same data file to either add or remove parameters, this is allowed. If you click on another data file, you will be notified of this and have the choice to either continue and lose your current subset or return back to your current subset. 3.1.1 Merged ProductsMerged products exist as a grouping under each basin and these data files operate slightly different from what is described above. For a given merged product data file, the parameters below it are also grouped. Like the other data files, highlighting the data file entity in the tree includes all parameters into the subset. Also, by highlighting a grouping under the data file entity in the tree, the subset will include the parameters within that grouping. For example, by highlighting the 'Chemical' grouping under a merged product data file, the subsequent subset will only contain the parameters under the Chemical grouping. The difference between these data files and the other data files with respect to how they operate in the tree, is that as you expand the groupings, the parameters are not highlighted. So, to include all of the parameters for a given group, regardless of whether that grouping is closed or expanded, so long as that grouping entity in the tree is highlighted, all of its parameters will be in the selected subset. To select individual parameters from a grouping, click the desired parameters. By clicking parameters, they become highlighted (selected). Only the highlighted parameters will be included so long as the grouping itself is not highlighted. This functionality was implemented so that by not highlighting all parameters, when expanding a grouping, a user would not have to click the undesired parameters to remove them from the selection. This way, a user can include all parameters if desired by highlighting the grouping entity, or select only the desired parameters by clicking those parameters.
Note: if event, year, sta, lat, lon, depth exist as parameters under the Sampling Attributes group of any merged product data file, they are automatically included in your subset. You can remove them from your selection once you get to defining the criteria by simply unchecking the box in the Subset column. Deselecting these parameters from the data catalog tree does not remove them from the subset. Since these data files have their parameters grouped, collapsing the groups after you have made selections under that group does not remove them from the selection. This is allowed to save viewing room when working in these data files. Therefore, you may make selection within one grouping, collapse it, and make selections within another grouping without losing any of your previous selections.
3.2 Clearing SelectionsAny selection can be cleared by selecting 'File -> Start Over' from the Main Menu.3.3 Searching for DataJGView can search through the entire U.S. JGOFS dataset for any instance of a string of characters found within a parameter's name or description. The Search capability is only available while you are not working within a dataset either defining criteria or viewing data. To perform a Search, click the 'Search' button from the toolbar. Type a character string in the text entry box. Click the [Go] button and JGView will search the entire data catalog for this text string.Search results are displayed in the documentation window pane at the bottom of the application. Each result is a clickable link that will navigate you directly to that instance of data in the catalog tree. From there you may either click on a new result or begin to make parameter selections within the catalog tree. Once you do start to make selections within the tree, your search results will be replaced with the documentation for the data file from which you are currently working. So, at the top of the results, there is a clickable link that allows you to print these results. If you would like to copy the results or a section of the search results to your clipboard, highlight the section of interest using the mouse or other mechanism, and from the Main Menu, select 'Edit -> Copy Search Results'. The search function remembers the last value you searched for, so if you would like to run the search again, click 'Search' and the last character string will be placed in the text field for searching.
4.0 Defining CriteriaAfter you have made a selection of parameters and pressed the 'Subset' button, the data window pane provides the option of specifying certain selection criteria that would reduce the number of results returned. After defining the desired criteria, pressing 'View Data' will list the selected data in the data window pane and pressing 'Export' will export the selected data to file. Only data in rows that match every set of criteria will appear in the data view window pane or the exported data set.Subset selection criteria are presented in tabular form. Every selected parameter occupies a row in the criteria table. Each parameter can have one criteria expression such as 'depth > 200'. If you would like to apply more than one criteria expression to a certain parameter see Section 7.3 Extending Criteria Expressions. The columns of the Subset Criteria are as follows:
Values can include integers (23 or -2), floating point numbers (1.375 or -32.0), text ('ttn-043'), or alphanumeric strings ('S4'). For instance, if one of the parameters is 'standard_station identifier' and only data that is desired by the user are data from station N7, the user can set the 'Criteria' column for the 'standard_station identifier' row to '=' and the 'Value' column to 'N7' (without the quotes otherwise it will look for text with single quotes around the text N7). Parameters can be added to the criteria by selecting them from the catalog tree and pressing the 'Subset' button again. This will not drop previously defined criteria, and this process of add/removing parameters and redefining criteria may be repeated as many times as needed. After viewing or exporting the data, press 'Subset' to return to the criteria table and further refine you selection. To clear all criteria, press the 'Reset Criteria' button that is displayed above the criteria table. 5.0 Viewing the DataAfter defining selection criteria, if any, to view the selected data, press the 'View Data' button from the toolbar. JGView reads the data file and returns a table of rows that match the selection criteria. While the data is being read, JGView provides a progress monitor to indicate how much of the file has been read, the name of the file being read, and a 'Cancel' button that will abort the read operation and return to the criteria table. Having specific criteria makes the viewing process run quickly and efficiently.When the table of selected data has been completed, the columns may be rearranged to any order by dragging them by their column headers. At this time, to export the selected data to a file, press the 'Export' button on the toolbar. To return to your criteria table, press the 'Subset' button from the toolbar. 5.1 Viewing large data filesSome data files are very large (more than 20 MB). Loading large data files into memory might cause the computer to operate slowly, and JGView may run out of memory. The reason JGView runs out of memory is that the table in the data view pane that holds the selected data has become too large. If this occurs, JGView will notify you that the program has run out of memory and is unable to complete the viewing operation. This notification also provides the number of parameters that were being selected, the percentage of reading that JGView was able to complete, and the size in megabytes of the data file. This information should help to determine how much the selection criteria need to be refined. Even though viewing the data may cause these memory problems, exporting the data will always work regardless of file size. If you encounter a problem viewing the data, you still have the option of exporting large data selections.
JGView runs within the Java Virtual Machine (JVM) which acts like
its own operating system. The default memory space assigned to the JVM
is 64 MB. With data files as large as 51 MB, the 64 MB available to JGView
will be insufficient to view data from such large files. In order to increase
the memory allocated to the JVM, some parameters need to be added to the
execution command that runs JGView. Note: these parameters can only be
used when running the JGView.jar file and cannot be used with the JGView.exe
file. The JGView.exe file has these commands embedded, and since it is
unknown what the memory limitations of the computer systems running JGView
will be, the JGView.exe file has been set to allocate 128 MB of memory
to JGView. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 |
||
| Tab Separated (.tsv): | each value is separated by the TAB character. | |
|
||
| Comma Separated (.csv): | each value is separated by the COMMA character. | |
|
||
| Ocean Data View General (.*): | TAB separated list with special headers for use with the Ocean Data View application. Replaces nd values with [blank] (nothing) and creates a .info header file. | |
|
||
| Ocean Data View Generic (.txt): | TAB Separated list with required parameters (date, time, sta,
lat, lon, depth) for complete compatibility with the Ocean Data
View application. Replaces nd values with [blank] (nothing) and
creates a .info header file.
|
|
|
||
| Matlab (.dat): | TAB separated list of values to be imported into the Matlab
application. This file format replaces nd values with 'NaN' and
write Matlab compatible header lines.
|
|
|
||
Ocean Data View Home Page for ODV information and downloads |
If
a directory is selected that is not the directory JGView is looking
for, the file chooser will ask to find the directory again. If you are
sure you have the correct directory, JGView is looking for specific
files in each to verify that you have selected the correct directory.
In the case of the /data directory, JGView looks for the 'param_master.dct'
file, /images looks for the 'datarealm.gif' file, and /docs looks for
the 'site_map.htm' file.
Note: Rearranging
any of the files in these directories will affect how JGView operates.
Adding files to these directories does not affect JGView, rather by
adding .TSV files to the data directory, a user can include
their own data files within the data catalog tree. See section 7.2 Importing
Data for more information.
.
 |