-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathtech_help.html
More file actions
178 lines (153 loc) · 10.7 KB
/
tech_help.html
File metadata and controls
178 lines (153 loc) · 10.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Seasonal Forecast - Technical Help</title>
<!-- Bootstrap -->
<link href="bootstrap/css/bootstrap.min.css" rel="stylesheet">
<link href="custom_style.css" rel="stylesheet">
<link rel="stylesheet" href="jquery_ui/jquery-ui.css">
<!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<div id="main_content">
<!-- Fixed navbar -->
<nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container-fluid">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="glyphicon glyphicon-list"></span>
</button>
<img class="navbar-brand" src="page_images/MO_Landscape_W.png">
<strong class="navbar-brand">Forecast PDF</strong>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav pull-right">
<li><a href="forecast_tool.html">Forecast</a></li>
<li><a href="user_guide.html">User Guide</a></li>
<li class="active"><a href="tech_help.html">Technical Help</a></li>
</ul>
</div><!--/.nav-collapse -->
</div><!--/.container -->
</nav>
<div class="container-fluid help_main">
<div class="row">
<div class="col-sm-2 col-md-2 sidebar">
<h1>Contents</h1><br>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#set_up">Set up</a></li>
<li><a href="#run_tool">Running the tool</a></li>
<li><a href="#code">The code</a>
<ul>
<li><a href="#structure">Structure</a></li>
<li><a href="#debugging">Debugging</a></li>
</ul>
</li>
</ul>
</div>
<div class="col-sm-10 col-sm-offset-2 col-md-10 col-md-offset-2 help_content">
<h1 id="introduction">Introduction</h1><br>
<p>This help page is a techinical guide to running and maintaining the forecast PDF tool.
The tool is written in Python2.7 so knowledge of the language will help a great deal in fixing or changing how the tool works.
Note, the tool relies on data only accessible from within the Met Office, it will not work outside the building.
</p><br>
<h1 id="set_up">Set up</h1>
<p>There is a very basic set up required to make sure the tool is reading and writing with the correct folders.
At the top of the file <i>cgi-bin/forecast_handler.py</i> (found in the SeasonalForecastPDF directory. See <a href="#run_tool">below</a> for more details), directly under the imports, there are 3 directories to specify:
</p>
<ol>
<li><b>import_directory</b> - This is the only directory that MUST be correct. The tool loads all the initial data from this directory and expects a very specific file format. At time of writing, this folder is:<br><br>
/home/h02/frgo/TEST/jhirst_plots/new_caboff_plots/plots_N216/</li><br>
<li><b>operational_dir</b> - The directory for exported data when working operationally.</li><br>
<li><b>testing_dir</b> - The directory for exported data when testing.</li>
</ol>
<i>Note, the choice between using the operational and the testing directory is made in the settings, before data is imported. When exporting with the tool, you are told the filepath where the output files have beed saved.</i>
<br><br>
<h1 id="run_tool">Running the tool</h1><br>
<p>All the code for the tool is self contained in a folder called SeasonalForecastPDF. This is located here (at the time of writing):<br><br>
/net/home/h02/sstanley/packages/SeasonalForecastPDF/<br><br>
To run the Python scripts which fetch the data, the page requires a server. As it happens, Python has a module which turns any computer into a simple server, perfect for these purposes.</p>
<p>The simplist way to do this is to run the shell script <i>fcst_tool_server.sh</i> found in the SeasonalForecastPDF directory:</p>
<ol>
<li><p>Open up a terminal and run:</p>
<p style='font-family:"Courier New", Courier, monospace'>/net/home/h02/sstanley/packages/SeasonalForecastPDF/fcst_tool_server.sh</p></li>
<p><i>Note, this is assuming the SeasonalForecastPDF directory has not been moved.</i></p>
</ol>
<p>You should get a message something like "Serving HTTP on 0.0.0.0 port 8000 ...". Printed just above this is the url to the forecast tool, something like "http://eld123:8000/forecast_tool.html".</p>
<br>
<p>If for some reason the script is not working, you can get the server running mannually with follow these steps:</p>
<ol>
<li><p>Open up a terminal and move to the tool's directory. This is the above directory unless it has been moved.</p>
<p style='font-family:"Courier New", Courier, monospace'>cd /net/home/h02/sstanley/packages/SeasonalForecastPDF/</p></li>
<li><p>Then run:</p>
<p style='font-family:"Courier New", Courier, monospace'>python2.7 -m CGIHTTPServer 8000</p>
<p><i>Note, the final number (8000) is the port number and can be changed to any 4 digit number higher than 1000. It is usual to use 8000 but if a port is already in use try another.</i></p></li>
<li><p>You should get a message something like "Serving HTTP on 0.0.0.0 port 8000 ...". This terminal is now the acting server and must not be closed or stopped whilst running the tool.</p></li>
<li><p>You can now access the tool via the browser with an address like this:</p>
<p><i>http://eldxxx:8000/forecast_tool.html</i></p>
<p>"eldxxx" must be replaced with the machine number running the server (this is your machine unless you've ssh'd somewhere else), and ":8000" refers to the port number so if you chose another (in step 2), change this to match.</p></li>
</ol><br>
<h1 id="code">The code</h1><br>
<p>Here we take a closer look at the code running all this. The aim is to provide a clear understanding of what each bit does and how it all fits together giving you a good idea of where to look if something goes wrong.
</p><br>
<h3 id="structure">Structure</h3><br>
<p>This diagram represents the overall code structure.</p>
<img src="page_images/code_structure.png" class="help_img_sm"><br><br>
<p>Let's take a general look at what each of the files do. File paths are given from the SeasonalForecastPDF directory.</p>
<ul>
<li><b>forecast_tool.html</b> (along with <b>custom_style.css</b>) - These do the page formatting. Uses <a href="http://getbootstrap.com/" target="_blank">Bootstrap</a>.</li><br>
<li><b>js/tool_functions.js</b> - This is written using <a href="http://jquery.com/" target="_blank">jQuery</a>. It has a 2 jobs:
<ol>
<li>Makes the page dynamic, i.e. handles button pressing, window pop ups and animations.</li>
<li>Sends relevant data (e.g. forecast issue date) from the page, to the Python script <i>forecast_handler.py</i>. It also recieves the returned data and plots it (using <a href="http://www.flotcharts.org/" target="_blank">Flot</a>).</li>
</ol>
</li><br>
<li><b>cgi-bin/forecast_handler.py</b> - This is where most of the work is done. It can do one of three jobs: load, modify or export data. When <i>tool_functions.js</i> sends data from the tool (via <a href="http://www.json.org/" target="_blank">JSON</a>),
it specifies which of these jobs it needs to do.</li><br>
<li><b>cgi-bin/DataSets.py</b> - This module contains two classes:
<ol>
<li>IssuedForecastData - for retrieving UK forecast data.</li>
<li>NCICTextData - for retrieving NCIC observations. This is used by the IssuedForecastData class to calculate climatologies.</li>
</ol>
<i>forecast_handler.py</i> imports IssuedForecastData and uses it to handle all data collection from source.
</li><br>
<li><b>cgi-bin/stats_functions.py</b> - This just contains pre-written statistical functions such as PDF probability calculaters. <i>forecast_handler.py</i> imports all the functions from this it needs.</li><br>
</ul>
<p>The best place to find out the more specific workings of each script is to look at the code itself.
All code is documented and commented on (apart from <i>forecast_tool.html</i> and <i>custom_style.css</i>).</p><br>
<h3 id="debugging">Debugging</h3><br>
<p>There are two likely outcomes if an error occurs:</p>
<ol>
<li>The "importing" message box won't close - This, ironically, is likely to be an import error in the <i>forecast_handler.py</i> script.
Assuming this is the case, it means the script can not see one of the imports in its $PYTHONPATH.
See below to help solve this.</li><br>
<li>A (potentially strange) message appeared in the text area (top right) of the tool - This is the error message returned from the <i>forecast_handler.py</i> script.
Hopefully it says something sensible like "There is no data for the selected period", but if it is a bit more criptic,
see below to help solve this.</li><br>
</ol>
<p>The best first step to debug a problem is to run the <i>cgi-bin/forecast_handler.py</i> script manually (not using the tool), this way you get the full error traceback.
Here are the steps to run the script manually:
</p><br>
<ol>
<li>Open the file <i>cgi-bin/forecast_handler.py</i></li><br>
<li>At the bottom of the file there is an "if __name__ == '__main__':" statement.</li><br>
<li>To run the script manually you must comment out all the code inbetween "# Example JSONs for testing and debugging." and the "if __name__ == '__main__':" statement. Then un-comment one of the example JSONs.
Which, depends on where the error occured, during importing, modifying or exporting?
If needed, the JSONs can be edited to replicate information the tool sent when the error occured.</li><br>
</ol>
</div>
</div>
</div>
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="bootstrap/js/bootstrap.min.js"></script>
</body>
</html>