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 |
|