ENCN305 MatLab Programming Assignment, 2012

Due: 5pm, Wed 25 April.

Introduction
Congratulations on your recent appointment to the role of junior engineer in the newly-established company Canterbury Water Wizards Ltd, which hopes to offer consultancy services in the lucrative Canterbury water-wars industry. You have been given the role of writing some Matlab software to process some of the available on-line hydrology datasets, starting with rainfalls and river flow rates from the NIWA databases.

Goals
You are supplied with a rainfall data file LakeTaylorStn.txt that contains several years of rainfall data recorded at Lake Taylor Station in the Hurunui River catchment area. This data was obtained from the National Climate Database, accessed via http://cliflo.niwa.co.nz/ You're also given a number of files of river flow rates from the Hurunui/Mandamus river gauge, which monitors the flow in the Hurunui River upstream from the confluence with the Mandamus River. This data comes from Environmental Data Explorer website, http://edenz.niwa.co.nz/map/riverflow. Each file contains all the river flow records for a given year, with each line specifying the date and time of a sample and the flow rate in "cumecs", i.e., cubic metres per second. You are to write a program that will take data from both these sources and display graphs of the data for a user-selected year and that will attempt to relate the two by giving statistics on total rainfall and total river flow. The program you hand in must be in a single .m file, but you may wish to develop it in smaller pieces to simplify debugging. 80% of your grade will come from how much of the functionality you correctly implement and 20% from your programming style. Note that you are not expected to keep all functions down to the very tight 10 line limit used in lab 4, but the 40 lines per function limit in the lecture notes (excluding comments) does still apply. Grading is discussed in more detail later in this spec.

Steps
Step 1: Processing the rainfall file [ 12 marks ]
Write a Matlab program in a file assignment.m with a main function main() that behaves as follows: (a) When first run, and after executing each command except Quit, the program displays a menu containing the following commands: Choose rainfall file, Choose year, Total rainfall, Plot rainfall, Quit (b) The Choose rainfall file command will prompt the user for the name of a text file containing one or more years of rainfall data in the format of the supplied file LakeTaylorStn.txt. This is essentially a multi-year version of the file used in lab 4, but with some minor formatting changes that will break the existing code. You may assume that the file contains n >= 1 sets of full (i.e., all 12-months worth) rainfall data but you may not assume any particular value of n nor may you make assumptions about what years of data are provided. Your program should also work for different rainfall stations (i.e. with different-length station name and different station stats) but otherwise you may assume that any other rainfall data supplied to the program will be in the same format as the supplied file. You may assume that the file is small enough that its entire contents can be read into memory (and this is the recommended approach -- see the note at the end of this step). (c) When a valid rainfall file is chosen by the user, the program will output to the command window the name of the station, its latitude and longitude and a list of years for which data is available. (d) Until a valid rainfall file has been chosen, all menu commands except Quit should simply display a message Please choose a rainfall file first. (e) The Choose year command should bring up a menu containing all the years for which data is available (and only those years), allowing the user to select a year for use with the Total rainfall and Plot rainfall commands. (f) Until a year has been chosen, the Total rainfall and Plot rainfall commands should just display a message Please select a year of interest first. (g) The Total rainfall command should output a line such as Total rainfall (mm) at Lake Taylor Station during 2008: 123.45, using the actual station name and date. (h) The Plot rainfall command should plot all the daily totals for the year in a bar chart form. [Note this is not the same as in lab 4.] The station name and the year concerned should be displayed in the graph title and axes should

-1-

be labelled. Before plotting the data, call figure() so that a new figure is created, leaving the old one on the screen, allowing you to compare the various figures generated by the program as it is used. The recommended approach in this step is to first write a function that reads the entire file into a struct, from which you can then extract the station name, a list of years containing data and the actual rainfall data for use in all the other commands.

Step 2: Plotting river flow rate [ 6 marks ]

In this step, we add to the program the capability to plot a graph of river flow rate for the selected year, using data in a csv file of daily river flow rates. The files HurunuiFlowsnnnn.csv are the river flow rates in cubic metres per second for years nnnn from 2005 through 2011. Note that the samples are not taken at regular intervals; it is acceptable for our purposes (though bad science) to average all the flow rate figures for one given day to get an estimate of the average flow rate, and hence the total flow, over that day. Add a menu item Plot river flow that plots a line graph of the total daily flow volumes, in cubic metres, for the currently selected year, using the appropriate Hurunui flow rate file. You do not need to prompt for the name of the file: you may assume the required file is present in the current directory. The year should be included in the graph title. You may make any assumptions you like regarding the input file format, provided your assumptions are satisfied by all the supplied files. Note that a .csv file is just text, so can be read with fopen ... fgetl just like the rainfall files.

Step 3: Hydrology stats [ 2 marks ]

In this last step, we extend the Total rainfall command so that now, instead of simply printing the total rainfall for the year it prints the total rainfall (in mm), the total river flow (in cubic metres), and the total estimated precipitation volume in cubic metres over the Hurunui catchment, assuming the rainfall is constant across the whole catchment area, which we'll estimate to be 820 km 2. Lastly, it prints the rainfall capture ratio, which we'll define as the ratio of total water flowing past the Hurunui river guage to the total precipitation volume over the catchment 1.

Marking
To mark your program we will test drive it with the supplied data and probably also with a different rainfall file from a different station and over different years. However, only the supplied river flow data files will be used. Correctness marks, out of a maximum of 20, will be allocated according to how much of the functionality is working correctly. Additionally we will assess the style of your program using a checklist based on the rules given in lectures. This will include checks like: Is there a comment at the top of the file defining the role of the file and giving the author and date? Do all functions have an explanatory comment? Have good identifiers been used throughout? Is the layout as specified, with proper indentation and use of whitespace? Has the complexity been kept under control, with good use of functions (all under 40 lines long) and no more than 4 levels of indentation? This assessment will yield a "style factor" in the range 0 - 1. This style factor will then be combined with your correctness mark to yield a mark out of 25 according to the formula finalMark = correctnessMark + 5 * styleFactor * (correctnessMark / 20) Note the style factor is multipled by your "correctness factor", so that beautifully written code that doesn't work is still worth zero. 1. 2. 3. 4. 5.

Submitting
Submit your code to the dropbox on Learn. It must be in a single file called assignment.m. Make sure this file works in isolation from the rest of your functions before submitting it. To check this, create a new folder containing just the file assignment.m plus the various data files, and make that the current directory. Then test your program, taking it through all its paces. You may submit as individuals or as pairs. Marking will be the same either way, and in the case of pair assignments,
1 Expect to get a silly answer here. I'm still trying to work out exactly why, but my suspicion is that the rain gauge doesn't measure snowfall, which is likely to be a major contributor to the total precipiation. Possibly you guys already knew this, but hey I'm not an engineer.

-2-

both students will receive the same mark. You should choose whether or not to work in pairs according to what will give you the best overall learning outcome for the course as a whole this is probably not the same as selecting the approach that will give you the highest mark just for this assignment. Whether or not you work in pairs, the code submitted for each assignment should be unique to that assignment copying of code from other students' assignment is regarded as cheating.

PS ...
Don't forget to Have

Fun!

-3-