PySeison - Tutorial 3: ADCP class

In [1]:
%pylab inline
Populating the interactive namespace from numpy and matplotlib

1. PySeidon-dvt - ADCP object initialisation

Similarly to the "TideGauge class" and the "Drifter class", the "ADCP class" is a measurement-based object.

1.1. Package importation

As any other library in Python-dvt, PySeidon has to be first imported before to be used. Here we will use an alternative import statement compared to the one previoulsy presented:

In [2]:
from pyseidon_dvt import *

Star here means all. Usually this form of statements would import the entire library. In the case of PySeidon-dvt, this statement will import the following object classes: FVCOM, Station, Validation, ADCP, Tidegauge and Drifter. Only the ADCP class will be tackle in this tutorial. However note should note that the architecture design and functioning between each classes are very similar.

1.2. Object definition

Python is by definition an object oriented language...and so is matlab. PySeidon-dvt is based on this notion of object, so let us define our first "ADCP" object.

Exercise 1:

  • Unravel ADCP documentation with Ipython shortcuts

Answer:

In [5]:
ADCP?

According to the documentation, in order to define a ADCP object, the only required input is a *filename. This string input represents path to a file (e.g. testAdcp=ADCP('./path_to_matlab_file/filename') and whose file must be a matlab file (i.e. *.mat).

Note that, at the current stage, the package only handle fully processed ADCP matlab data previously quality-controlled as well as formatted through "EnsembleData_FlowFile" matlab script at the mo. All the tool necessary for this processing and quality-control can be found in ./pyseidon_dvt/utilities/BP_tools.py and save_FlowFile_BPFormat.py. Additionally, a template for the ADCP file is provided in the package under data4tutorial

Exercise 2:

  • define a adcp object named adcp from the following template: ./data4tutorial/adcp_GP_01aug2013.mat
  • Tip: adapt the file's path to your local machine.

Answer:

In [3]:
adcp=ADCP('./data4tutorial/adcp_GP_01aug2013.mat')

1.3. Object attributes, functions, methods & special methods

The ADCP object possesses 3 attributes and 3 methods. They would appear by typing adcp. Tab for instance.

An attribute is a quantity intrinsic to its object. A method is an intrinsic function which changes an attribute of its object. Contrarily a function will generate its own output:

object.method(inputs) output = object.function(inputs)

The Station attributes are:

  • History: history metadata that keeps track of the object changes
  • Data: gathers the raw/unchanged data of the specified *.mat file
  • Variables: gathers the hydrodynamics related data. Note that methods will generate new fields in this attribute

The Station methods & functions are:

  • Utils: gathers utility methods and functions for use with 2D and 3D variables
  • Plots: gathers plotting methods for use with 2D and 3D variables
  • dump_profile_data: dumps profile data (x,y) in a *.csv file.

2. PySeidon-dvt - Hands-on (15 mins)

Utils

Exercise 3:

  • Print the (lon,lat) coordinates of the adcp object (hint: look into Variables)
  • Use Utils.velo_norm to compute the velocity norm over all time steps and all vertical levels...and accessorily plot the mean velocity vertical profile.
  • Use Utils.ebb_flood_split function to get the ebb and flood time indices of the time series.
  • Plot the flood flow speed hitogram
  • Compute & Plot the ebb vertical shear
  • Perform a harmonic analysis of the velocities and print out the result
  • Reconstruction these velocities based on the harmonic results of the previous question

Answer:

In [4]:
print "(lon, lat) coordinates: ("+str(adcp.Variables.lon)+", "+str(adcp.Variables.lat)+")"
vel = adcp.Utils.velo_norm()
fI, eI, pa, pav = adcp.Utils.ebb_flood_split()
adcp.Utils.speed_histogram(time_ind=fI)
dveldz = adcp.Utils.verti_shear(time_ind=eI)
harmo = adcp.Utils.Harmonic_analysis(elevation=False, velocity=True)
print harmo
velos = adcp.Utils.Harmonic_reconstruction(harmo)
(lon, lat) coordinates: (-66.3390666667, 44.2799166667)
solve: 
matrix prep ... 
Solution ...
diagnostics...
Done.

Lsmaj    :                            [ 1.92087736]
Lsmaj_ci :                            [ 0.02495443]
Lsmin    :                            [ 0.02102549]
Lsmin_ci :                            [ 0.01190183]
aux      : frq     :                             [ 0.0805114]
lat     :                            44.2799166667
lind    :                                     [47]
opt     : cnstit      :                                     auto
conf_int    :                                     True
diagnminsnr :                                        2
diagnplots  :                                        0
equi        :                                    False
gwchlint    :                                    False
gwchnone    :                                    False
infer       :                                       []
inferaprx   :                                        0
linci       :                                     True
lsfrqosmp   :                                        1
method      :                                      ols
newopts     : MC_n         :                           200
Rayleigh_min :                             1
conf_int     :                        linear
constit      :                          auto
infer        :                          none
method       :                           ols
nodal        :                          True
phase        :                     Greenwich
robust_kw    : {'weight_function': 'cauchy'}
trend        :                          True
white        :                         False

nodesatlint :                                    False
nodesatnone :                                    False
nodiagn     :                                        0
nodsatlint  :                                        0
nodsatnone  :                                        0
notrend     :                                    False
nrlzn       :                                      200
ordercnstit :                                     None
prefilt     :                                       []
rmin        :                                        1
runtimedisp :                                      yyy
tunrdn      :                                        1
twodim      :                                     True
white       :                                    False

reftime :                            735448.001987

diagn    : {'SNR': array([ 18546.23695224]), 'name': array([u'M2  '], 
      dtype='<U4'), 'PE': array([ 100.])}
g        :                          [ 347.97287404]
g_ci     :                            [ 0.72494198]
name     :                                [u'M2  ']
theta    :                           [ 83.74403207]
theta_ci :                            [ 0.36470506]
umean    :                          0.0151540354014
uslope   :                        -0.00784641470595
vmean    :                          0.0254322275605
vslope   :                         -0.0182159475527
weights  : [ 1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.
  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.
  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.
  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.
  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.  1.
  1.  1.  1.  1.  1.  1.]

reconstruct:
prep/calcs...
Done.

/usr/local/lib/python2.7/dist-packages/matplotlib/figure.py:387: UserWarning: matplotlib is currently using a non-GUI backend, so cannot show the figure
  "matplotlib is currently using a non-GUI backend, "

Save functions

Exercise 5:

  • Dump depth-averaged velocity and time step data in a *.csv file
  • Hint: use numpy for averaging

Answer:

In [7]:
import numpy as np
da_vel = np.nanmean(vel,axis=1)
station.dump_profile_data(adcp.Variables.matlabTime[:], da_vel, title='flow_speed_time_series', xlabel='matlab time', ylabel='speed')

4. Bug patrol & steering committee

4.1. Bug report

As beta tester, your first assignement is to report bugs...yet not everything is a bug. The first thing to check before to report a bug is to verify that your version of PySeidon-dvt is up-to-date. The best way to keep up with the package evolution is to git to clone the repository, use pull to update it and re-install it if needed.

The second thing to check before to report a bug is to verify that the bug is reproducible. When running into a bug, double check that your inputs fit the description of the documentation then turn the debug flag on (e.g. output = adcpobject.function(inputs, debug=True)) and submit the command again. If the error re-occurs then report it (i.e. copy entire error message + command and send it to package administrator)

4.2. Suggestions & critics

Your second role as beta-tester is to submit suggestions and critics to the developpers regarding the functioning and functionality of the package. Beta testing phase is the best opportunity to steer a project towards the applications you would like to be tackled...