1 """The sub-module stream_gauging is used to do all things stream gauging:
2 1. stage measurements
3 2. conductivity measurements
4 3. conductivity sensor calibration
5 4. dilution gauging
6 5. stage-discharge relation
7 6. discharge time series
8
9 0 Example
10 =========
11 Probably it is easiest to go by an example which is located in the
12 folder fieldpy/stream_gauging/example_stream_site_2010/. There look
13 through the script in analyse_it.py which follows the layout below.
14 If you like it, then the best way of using it is to copy the
15 contents of the fieldpy/stream_gauging/template/ folder to where you
16 have your data and edit it accordingly.
17
18 1 Stage measurements
19 ====================
20 The stage measurements are done by the SR50 ultrasonic depth gauge.
21
22 B{Workflow stage measurements:}
23
24 1. Create a L{logged_data.Stage} instance by::
25 st = Stage([filenames_of_TOA5_file])
26 2. plot it with L{logged_data.Stage.plot_date}
27 3. Filter it by running L{logged_data.Stage.apply_all_filters}
28
29 2 Conductivity measurements
30 ===========================
31 The conductivity measurements are done by Garry Clarke's home made
32 conductivity sensor. Note that the sensor reading is not the actual
33 conductivity but the ratio between measured and excitation voltage.
34
35 B{Workflow conductivity measurements:}
36
37 1. Create a L{logged_data.Conductivity} instance by::
38 ec = Conductivity([filenames_of_TOA5_file])
39 2. plot it with L{logged_data.Conductivity.plot_date}
40 3. Filter it by running L{logged_data.Conductivity.apply_all_filters}
41
42
43 3 Conductivity sensor calibration
44 =================================
45 This is handled by the classes in L{calibration}.
46
47 B{Workflow calibration:}
48
49 1. For each calibration make a .maw file like e.g.::
50 #maw 1st Conductivity Calibration 13 July 2010
51 #
52 # Calibration of the older conductivity sensor in the proglacial river of
53 # GL1 on 13 July at 10:30.
54 #
55 # Note: Times in calibration are not accurate.
56 #
57 # Calibration was done by premixing 20g NaCl in 2L of water, to get a 10g/L solution.
58 # This solution was then added into a 5000mL bucket of water, in the steps written below.
59 #
60 # Metadata:
61 #metadata.experimenter = 'MAW + UM'
62 #metadata.bucket_size = 5.0
63 #metadata.bucket_size_units = 'l'
64 #metadata.calibaration_solution_concentration = 10.0
65 #metadata.calibaration_solution_concentration_units = 'g/l'
66 #metadata.sensor = 'older Garry sensor'
67 #metadata.reference_resistor = 10e3
68 #metadata.reference_resistor_units = 'Ohm'
69 #metadata.note = 'Times in calibration are not accurate'
70 #
71 # Format:
72 # time (UTC-7) [time_str], calibration_solution (ml) [float], sensor_readout () [float]
73 "2010-07-13 10:30:00",0, 0.3030
74 "2010-07-13 10:31:00",1.25, 0.2965
75 "2010-07-13 10:32:00",2.5, 0.2890
76 "2010-07-13 10:33:00",3.75, 0.2815
77 "2010-07-13 10:34:00",5, 0.2730
78 "2010-07-13 10:35:00",7.5, 0.2595
79 "2010-07-13 10:36:00",10, 0.2500
80 "2010-07-13 10:37:00",15, 0.2320
81 "2010-07-13 10:38:00",20, 0.2175
82 "2010-07-13 10:39:00",25, 0.2055
83 "2010-07-13 10:40:00",30, 0.1945
84 "2010-07-13 10:41:00",35, 0.1860
85 "2010-07-13 10:42:00",40, 0.1760
86 "2010-07-13 10:43:00",45, 0.1685
87 "2010-07-13 10:44:00",50, 0.1620
88
89 2. Create an L{calibration.AllCalibrations} instance which holds
90 all the calibrations of a season::
91 ac = AllCalibartions(list_of_calibration_files)
92 3. Check that all the calibrations are suitably similar by:
93 - check the output of the program and see whether the slopes are similar
94 (the 'a' in the printout)
95 - plot all calibrations with
96 L{calibration.AllCalibrations.plot_all} and see if they look
97 good. It's ok for the lines to be offset but the slope
98 should be identical-ish.
99
100 4 Dilution gauging
101 ==================
102 The dilution gauging will consist of individual salt injections
103 recorded as conductivity change of the water. This is translated
104 into a concentration with the help of the calibration. Then the
105 concentration is related to the discharge via:
106
107 M / S{int} c dt = Q
108
109 where M is the amount of injected salt, c is the concentration and Q
110 is the discharge.
111
112 B{Workflow dilution gauging:}
113 1. have the stage, conductivity and calibrations set-up as above
114 2. Create a .maw file listing all salt injections with the
115 following format::
116 #maw Dilution gauging injections from 13 July 2010
117 #
118 # Metadata:
119 #metadata.experimenter = 'MAW + UM'
120 #metadata.injection_point = "MAW's injection point"
121 #metadata.sensor = 'older Garry sensor'
122 #
123 # Format:
124 # time (UTC-7) [time_str], amount (kg) [float]
125 "2010-07-13 09:07:00", 0.2
126 "2010-07-13 09:22:45", 0.4
127 "2010-07-13 11:17:00", 0.4
128 "2010-07-13 13:16:00", 0.4
129 "2010-07-13 13:16:00", 0.4
130
131 3. create a L{dilution_gauging.DilutionGauging} instance like so::
132 dilg = DilutionGauging(injections_maw_file, (0,150), ec, ac, st)
133 4. Check that you're happy with the windows chosen for the injections::
134 dilg.plot_all()
135 5. Make the stage-discharge relation for the day::
136 dilg.make_stage_discharge_relation(verbose_=True, order_of_poly=2)
137
138 5 Stage-discharge relation
139 ==========================
140
141 With the L{dilution_gauging.DilutionGauging} we created a
142 stage-discharge relation for one day of dilution-gauging
143 experiments. But presumably more than one day of dilution gauging
144 was done, so these need to be combined to lead to a stage-discharge
145 relation for the whole season. Which is done with the
146 L{stage2discharge.Stage2Discharge} class.
147
148 B{Workflow stage-discharge relation:}
149 1. have the stage, conductivity, calibrations and dilution-gauging
150 set-up as above.
151 2. make a L{stage2discharge.Stage2Discharge} instance::
152 s2d = stage2discharge.Stage2Discharge(xxx)
153 3. have a look how the individual stage-discharge relations compare::
154 s2d.plot_all()
155
156 6 Discharge time series
157 =======================
158 Now, finally we are in a position to convert the stage records into
159 a discharge time series.
160
161 B{Workflow discharge time series:}
162 1. have the stage, conductivity, calibrations, dilution-gauging
163 and stage-discharge relation made as above.
164
165 2. tell your L{logged_data.Stage} instance how to convert the
166 stage into a discharge::
167 st.set_stage2discharge_method(s2d.stage2discharge)
168 note you can choose here from different methods (once
169 implemented):
170 - L{stage2discharge.Stage2Discharge.stage2dis_average}
171 3. convert the stage::
172 st.make_discharge()
173 4. admire (and check) it:
174 st.plot_date('discharge')
175 5. THE END
176
177
178 """
179 __all__ = ['calibration', 'dilution_gauging', "stream_gauging"]
180