Contents of /MITgcm_contrib/darwinview/src/darwinView_guide

The darwinView User's Guide

 Marissa Weichman
 Chris Hill

Background

 Darwin project is exploring marine biogeochemistry by populating oceanic
configurations of the M.I.T General Circulation Model (MITgcm) with "virtual"
biologeochemical species that can interact and evolve. Different species
are characterized by their combinations of different physiology ranges,
over which a species can flourish. For example, some species may be very
sensitive to ocean temperature or nutrient concentrations while other species
may thrive over a wide temperature range but require high levels of
solar radiation to flourish. By seeding an ocean circulation model with
ensembles of different species, with probability distributions guided by
biological measurement, we can use this approach to develop an understanding
of the actual and potential biodiversity in the marine ecosystem.

The darwinView project

 At a practical level the modeling in Darwin yields three-dimensional, time
evolving maps of species distributions that are studied to help us understand
the marine ecosystem. The distributions are embedded in three-dimensional,
time evolving maps of nutrient, and physical field distributions. The result is
a high-dimensional "space" of output which we wish to explore and from
which we want to extract understanding.

 The goal of darwinView is to develop some quick-look, interactive,
visualization tools that can allow researchers to rapidly explore Darwin
project outputs from MITgcm. Detailed studies of simulation outputs employ
analytical packages like Matlab and Ferret. The idea of a quick look tool
is not to try and replicate the functionality of these systems, but to
make a tool for visually quickly scanning outputs to identify interesting
behaviors.

What is darwinView

1 - a program to display multiple panels of Darwin project outputs
   from MITgcm at once.

2 - allows moving through data in space (up-down, east-west, north-south depending
   on view) and time over a many fields at once.

3 - movement through data can be manual or automatic (scripted or autoplay).

4 - can display to a single screen or to a walled display.

5 - displayed fields are annotated with scale, coordinates, key etc.

6 - some limited controls on display are available.
        o user-set color scale
        o log scale
        o global scale over all fields
        o local scale for each species, depth and time

7 - can read data from both binary (big or little endian) and NetCDF files


How to Use darwinView

* Before You Compile the Program:

- Make sure you have all the components necessary to run the program:

        o darwin.bash   - bash script that handles data files   
        o darwin.c      - the main OpenGL program
        o netcdf.c      - the program that handles NetCDF files
        o jet.h         - a table of color values

- Make sure the following are installed on your computer:

        o Bash Unix shell       
        o gcc C compiler        
        o C programming libraries
        o OpenGL libraries
        o NetCDF libraries, if you intend to read from NetCDF files

- Make sure your data is organized correctly:

        o Binary data should be organized in a directory whose only contents are subdirectories
        representing different time steps. Each subdirectory should contain one binary file for
        each variable (species concentration, compound concentration or otherwise). Each binary
        file should contain data for all three dimensions (x, y and z) for its timestep. In
        addition, the user must prepare a file containing a list of the variables that will be
        displayed. The variable names should be on one line, separated by spaces. The user will
        be prompted for the name of this file.
 
        o NetCDF files should all be placed in one directory. Make sure all the tiles for the
        desired timesteps are present. In addition, the user must prepare three files: one 
        containing a list of variables that will be displayed, one containing a list of 
        tiles that make up each plot, and one containing a list of the desired time steps. In
        each file, the variable names should be on one line, separated by spaces. The user will
        be prompted for the names of these three files. Finally, the program handles NetCDF files
        by converting them to binary. Therefore, a directory must be created for the program to
        write to. The user will be prompted for the name of this directory. 

        o The darwinView program has the option of scaling the z-axis, so depth levels aren't
        equally spaced. If you plan to use this feature, a file must be prepared containing a list
        of the depths of each layer. The list should begin with the layer closest to the surface
        and progress down the water column, one depth per line. The number of lines should be 
        equal to the z-dimension (number of depth layers). The user will be prompted for the name
        of this file when the scaled z-axis feature is enabled.
        
* Compiling the Program:

- The darwinView program is called through a bash script which prompts for information the program 
needs to run. Type "bash darwin.bash" to run the script.

        o First, the script prompts for the format of the data. If you are using binary files,
        type "binary" then type enter. If you are using NetCDF files, type "netcdf", then enter. 

        o The script then asks if the user would like to use the default settings. If you have run 
        the program before and none of your settings have changed, type "y" for yes, then hit
        enter. If you have not run the program before, or would like to change your settings,
        type "n" for no, then hit enter.

        o If you typed "n", the program should begin running, and you can skip to the section
        "running the program". If you typed "y", it will prompt for more information.

        o Next, the program asks for the dimensions of the data, meaning the x, y and z values
        of the data. These are entered in the format "x y z". For example, a set of data might
        cover 360 longitude steps, 160 latitude steps and 20 depth steps. The user would
        therefore enter "360 160 20".

        o Next, the user is prompted for the dimensions of the data sets. darwinView is designed
        to graph several different sets of data simultaneously. For example, if a user were 
        graphing concentrations of four species of phytoplankton, and wanted them arranged in a
        square, he would enter "2x2". For a horizontal line, he would enter "4x1", and for a
        vertical line he would enter "1x4".

        o If you are using the program to read from binary files, you are then prompted for the 
        directory containing the data to be read from. This directory should contain a
        subdirectory for each timestep, as described in the section "Before You Compile the 
        Program." Finally, you are prompted for the name of the file containing the list of 
        variable names as described in the section "Before You Compile the Program." The 
        program should now begin running, and you can skip to the section "Running the Program."
        (Note: all of the input asked for up until this point is saved in the file 
        .darwinview/binconfig. If your settings have not changed by the next time you run the
        program, you can simply select "use default settings" to skip retyping the information.)

        o If you are using the program to read from NetCDF files, you are then prompted for the
        directory containing the data to be read from. This directory should contain all the 
        tiles for the necessary timesteps, as described in the section "Before You Compile the
        Program."

        o Next, you are prompted for the directory to write to. This directory should be empty.

        o Finally, you are prompted for the names of the three files: one containing a list of
        desired variable names, one containing a list of tile names, and one containing a list of
        time steps (as described in the section "Before You Compile the Program). The program 
        should now begin running. (Note: all of the input asked for up until this point is saved 
        in the files .darwinview/netcdf and .darwinview/ncconfig. If your settings have not changed 
        by the next time you run the program, you can simply select "use default settings" to skip
        retyping the information.)

* Running the Program

- When the program window first comes up, you should see the x-y plane of each data set. The 
default color scale is set to local. At the top of each graph, the name of the file being read 
from, the depth level being viewed and the time step being viewed are labeled. 

-The right mouse button brings up a menu with the following options:
        - Local color scale     - switch to the local color scale, where the maximum and minimum
                                  values are specific for each variable, time and level. Default
                                  when the program begins running.
        - Global color scale    - switch to the global color scale, where the maximum and minimum
                                  are calculated based on the entire data set (all variables, times
                                  and levels).
        - User-set color scale  - switch to the user-set color scale, where the user is prompted
                                  for the maximum and minimum. All variables are then scaled 
                                  according to these values.
        - Log scale             - toggles the log scale on/off. The log scale can be used in
                                  conjunction with any of the color scale options listed above.
        - Allow negatives       - toggles the allowance of negatives on/off. When the program 
                                  begins running, off is the default. In off mode, all negative
                                  values are set to the lowest positive value.
        - Switch endian         - toggles between big and little endian. Default is big endian.

-There are also a number of key commands:
        - left arrow key   - move all plots forward one time step. If the animate feature is
                             set, pushing this key cycles forwards through the time steps. 
        - right arrow key  - move all plots back one time step. If the animate feature is set,
                             pushing this key cycles backwards through the time steps.
        - down arrow key   - in the xy view, move down one depth level. In the xz view, move
                             down one North-South slice. In the yz slice, move right one 
                             East-West slice. If the animate feature is set, pushing this key
                             cycles downwards through the depth levels in the xy view, down
                             the North-South slices in the xz view, and right across the 
                             East-West slices in the yz view.
        - up arrow key     - in the xy view, move up one depth level. In the xz view, move up 
                             one North-South slice. In the yz view, move left one East-West
                             slice. If the animate feature is set, pushing this key cycles 
                             upwards through the depth levels in the xy view, up the North-
                             South slices in the xz view, and left across the East-West slices
                             in the yz view. 
        - r                - reset the view (return to the xy plane at the first time and level)
        - a                - toggle the animate feature on/off  
        - x                - toggle between xy and xz view, which plots how a certain North-South 
                             slice changes over depth.
        - y                - toggle between xy and yz view, which plots how a certain East-West 
                             slice changes over depth.
        - z                - toggles scaling of the z-axis when the program is in the xz or yz 
                             view. The user will be prompted for the name of the file containing
                             containing the depth information the first time "z" is pressed (as
                             described in the section "Before you Compile the Program").
        - q                - quit the program
 
1	The darwinView User's Guide
2
3	Marissa Weichman
4	Chris Hill
5
6	Background
7
8	Darwin project is exploring marine biogeochemistry by populating oceanic
9	configurations of the M.I.T General Circulation Model (MITgcm) with "virtual"
10	biologeochemical species that can interact and evolve. Different species
11	are characterized by their combinations of different physiology ranges,
12	over which a species can flourish. For example, some species may be very
13	sensitive to ocean temperature or nutrient concentrations while other species
14	may thrive over a wide temperature range but require high levels of
15	solar radiation to flourish. By seeding an ocean circulation model with
16	ensembles of different species, with probability distributions guided by
17	biological measurement, we can use this approach to develop an understanding
18	of the actual and potential biodiversity in the marine ecosystem.
19
20	The darwinView project
21
22	At a practical level the modeling in Darwin yields three-dimensional, time
23	evolving maps of species distributions that are studied to help us understand
24	the marine ecosystem. The distributions are embedded in three-dimensional,
25	time evolving maps of nutrient, and physical field distributions. The result is
26	a high-dimensional "space" of output which we wish to explore and from
27	which we want to extract understanding.
28
29	The goal of darwinView is to develop some quick-look, interactive,
30	visualization tools that can allow researchers to rapidly explore Darwin
31	project outputs from MITgcm. Detailed studies of simulation outputs employ
32	analytical packages like Matlab and Ferret. The idea of a quick look tool
33	is not to try and replicate the functionality of these systems, but to
34	make a tool for visually quickly scanning outputs to identify interesting
35	behaviors.
36
37	What is darwinView
38
39	1 - a program to display multiple panels of Darwin project outputs
40	from MITgcm at once.
41
42	2 - allows moving through data in space (up-down, east-west, north-south depending
43	on view) and time over a many fields at once.
44
45	3 - movement through data can be manual or automatic (scripted or autoplay).
46
47	4 - can display to a single screen or to a walled display.
48
49	5 - displayed fields are annotated with scale, coordinates, key etc.
50
51	6 - some limited controls on display are available.
52	o user-set color scale
53	o log scale
54	o global scale over all fields
55	o local scale for each species, depth and time
56
57	7 - can read data from both binary (big or little endian) and NetCDF files
58
59
60	How to Use darwinView
61
62	* Before You Compile the Program:
63
64	- Make sure you have all the components necessary to run the program:
65
66	o darwin.bash - bash script that handles data files
67	o darwin.c - the main OpenGL program
68	o netcdf.c - the program that handles NetCDF files
69	o jet.h - a table of color values
70
71	- Make sure the following are installed on your computer:
72
73	o Bash Unix shell
74	o gcc C compiler
75	o C programming libraries
76	o OpenGL libraries
77	o NetCDF libraries, if you intend to read from NetCDF files
78
79	- Make sure your data is organized correctly:
80
81	o Binary data should be organized in a directory whose only contents are subdirectories
82	representing different time steps. Each subdirectory should contain one binary file for
83	each variable (species concentration, compound concentration or otherwise). Each binary
84	file should contain data for all three dimensions (x, y and z) for its timestep. In
85	addition, the user must prepare a file containing a list of the variables that will be
86	displayed. The variable names should be on one line, separated by spaces. The user will
87	be prompted for the name of this file.
88
89	o NetCDF files should all be placed in one directory. Make sure all the tiles for the
90	desired timesteps are present. In addition, the user must prepare three files: one
91	containing a list of variables that will be displayed, one containing a list of
92	tiles that make up each plot, and one containing a list of the desired time steps. In
93	each file, the variable names should be on one line, separated by spaces. The user will
94	be prompted for the names of these three files. Finally, the program handles NetCDF files
95	by converting them to binary. Therefore, a directory must be created for the program to
96	write to. The user will be prompted for the name of this directory.
97
98	o The darwinView program has the option of scaling the z-axis, so depth levels aren't
99	equally spaced. If you plan to use this feature, a file must be prepared containing a list
100	of the depths of each layer. The list should begin with the layer closest to the surface
101	and progress down the water column, one depth per line. The number of lines should be
102	equal to the z-dimension (number of depth layers). The user will be prompted for the name
103	of this file when the scaled z-axis feature is enabled.
104
105	* Compiling the Program:
106
107	- The darwinView program is called through a bash script which prompts for information the program
108	needs to run. Type "bash darwin.bash" to run the script.
109
110	o First, the script prompts for the format of the data. If you are using binary files,
111	type "binary" then type enter. If you are using NetCDF files, type "netcdf", then enter.
112
113	o The script then asks if the user would like to use the default settings. If you have run
114	the program before and none of your settings have changed, type "y" for yes, then hit
115	enter. If you have not run the program before, or would like to change your settings,
116	type "n" for no, then hit enter.
117
118	o If you typed "n", the program should begin running, and you can skip to the section
119	"running the program". If you typed "y", it will prompt for more information.
120
121	o Next, the program asks for the dimensions of the data, meaning the x, y and z values
122	of the data. These are entered in the format "x y z". For example, a set of data might
123	cover 360 longitude steps, 160 latitude steps and 20 depth steps. The user would
124	therefore enter "360 160 20".
125
126	o Next, the user is prompted for the dimensions of the data sets. darwinView is designed
127	to graph several different sets of data simultaneously. For example, if a user were
128	graphing concentrations of four species of phytoplankton, and wanted them arranged in a
129	square, he would enter "2x2". For a horizontal line, he would enter "4x1", and for a
130	vertical line he would enter "1x4".
131
132	o If you are using the program to read from binary files, you are then prompted for the
133	directory containing the data to be read from. This directory should contain a
134	subdirectory for each timestep, as described in the section "Before You Compile the
135	Program." Finally, you are prompted for the name of the file containing the list of
136	variable names as described in the section "Before You Compile the Program." The
137	program should now begin running, and you can skip to the section "Running the Program."
138	(Note: all of the input asked for up until this point is saved in the file
139	.darwinview/binconfig. If your settings have not changed by the next time you run the
140	program, you can simply select "use default settings" to skip retyping the information.)
141
142	o If you are using the program to read from NetCDF files, you are then prompted for the
143	directory containing the data to be read from. This directory should contain all the
144	tiles for the necessary timesteps, as described in the section "Before You Compile the
145	Program."
146
147	o Next, you are prompted for the directory to write to. This directory should be empty.
148
149	o Finally, you are prompted for the names of the three files: one containing a list of
150	desired variable names, one containing a list of tile names, and one containing a list of
151	time steps (as described in the section "Before You Compile the Program). The program
152	should now begin running. (Note: all of the input asked for up until this point is saved
153	in the files .darwinview/netcdf and .darwinview/ncconfig. If your settings have not changed
154	by the next time you run the program, you can simply select "use default settings" to skip
155	retyping the information.)
156
157	* Running the Program
158
159	- When the program window first comes up, you should see the x-y plane of each data set. The
160	default color scale is set to local. At the top of each graph, the name of the file being read
161	from, the depth level being viewed and the time step being viewed are labeled.
162
163	-The right mouse button brings up a menu with the following options:
164	- Local color scale - switch to the local color scale, where the maximum and minimum
165	values are specific for each variable, time and level. Default
166	when the program begins running.
167	- Global color scale - switch to the global color scale, where the maximum and minimum
168	are calculated based on the entire data set (all variables, times
169	and levels).
170	- User-set color scale - switch to the user-set color scale, where the user is prompted
171	for the maximum and minimum. All variables are then scaled
172	according to these values.
173	- Log scale - toggles the log scale on/off. The log scale can be used in
174	conjunction with any of the color scale options listed above.
175	- Allow negatives - toggles the allowance of negatives on/off. When the program
176	begins running, off is the default. In off mode, all negative
177	values are set to the lowest positive value.
178	- Switch endian - toggles between big and little endian. Default is big endian.
179
180	-There are also a number of key commands:
181	- left arrow key - move all plots forward one time step. If the animate feature is
182	set, pushing this key cycles forwards through the time steps.
183	- right arrow key - move all plots back one time step. If the animate feature is set,
184	pushing this key cycles backwards through the time steps.
185	- down arrow key - in the xy view, move down one depth level. In the xz view, move
186	down one North-South slice. In the yz slice, move right one
187	East-West slice. If the animate feature is set, pushing this key
188	cycles downwards through the depth levels in the xy view, down
189	the North-South slices in the xz view, and right across the
190	East-West slices in the yz view.
191	- up arrow key - in the xy view, move up one depth level. In the xz view, move up
192	one North-South slice. In the yz view, move left one East-West
193	slice. If the animate feature is set, pushing this key cycles
194	upwards through the depth levels in the xy view, up the North-
195	South slices in the xz view, and left across the East-West slices
196	in the yz view.
197	- r - reset the view (return to the xy plane at the first time and level)
198	- a - toggle the animate feature on/off
199	- x - toggle between xy and xz view, which plots how a certain North-South
200	slice changes over depth.
201	- y - toggle between xy and yz view, which plots how a certain East-West
202	slice changes over depth.
203	- z - toggles scaling of the z-axis when the program is in the xz or yz
204	view. The user will be prompted for the name of the file containing
205	containing the depth information the first time "z" is pressed (as
206	described in the section "Before you Compile the Program").
207	- q - quit the program
208