#!/usr/bin/env python
# coding: utf-8

# # PySeison - Tutorial 4: TideGauge class

# In[1]:


get_ipython().run_line_magic('pylab', 'inline')


# ## 1. PySeidon-dvt - TideGauge object initialisation

# Similarly to the "ADCP class" and the "Drifter class", the "TideGauge 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 TideGauge 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**](http://www.tutorialspoint.com/python/python_classes_objects.htm)...and so is *matlab*. *PySeidon-dvt* is based on this notion of object, so let us define our first "Tidegauge" object.

# ***Exercise 1: ***
# - Unravel TideGauge documentation with Ipython ***shortcuts***

# ***Answer: ***

# In[3]:


get_ipython().run_line_magic('pinfo', 'TideGauge')


# According to the documentation, in order to define a TideGauge object, the only required input is a ***filename**. This string input represents path to a file (e.g. *testAdcp=TideGauge('./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 a certain type of file and data format. A template for the TideGauge file/data format is provided in the package under *data4tutorial*

# ***Exercise 2: ***
# - define a tide gauge object named *tg* from the following template: **./data4tutorial/tidegauge_GP_01aug2013.mat**
# - Tip: adapt the file's path to your local machine. 
# 
# ***Answer: ***

# In[3]:


tg = TideGauge('./data4tutorial/tidegauge_GP_01aug2013.mat')


# ### 1.3. Object attributes, functions, methods & special methods

# The TideGauge object possesses 3 attributes and 3 methods. They would appear by typing ***tg. 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 (2 mins)

# ### Utils & Plots

# ***Exercise 3: ***
# - Perform a harmonic analysis of the elevation and print out the result
# - Reconstruction these elevation based on the harmonic results of the previous question
# - Convert matlabtime in datetime
# - Plot the elevation-minus-reconstructed-elevation time series.
# 
# ***Answer: ***

# In[4]:


harmo = tg.Utils.harmonics()
recons = tg.Utils.reconstr(harmo)
times = map(tg.Utils.mattime2datetime, tg.Variables.matlabTime[:])
ini_minus_recons = ini_minus_recons = tg.Variables.el - recons['h']
tg.Plots.plot_xy(times, ini_minus_recons, title='Residual tidal signal', xLabel='Time', yLabel='Elevation (m)')


# ### Save functions

# ***Exercise 5: ***
# - ***Dump*** depth-averaged velocity and time step data in a *.csv file
# 
# ***Answer: ***

# In[7]:


tg.dump_profile_data(times, ini_minus_recons, title='Residual_tidal_signal', xLabel='Time', yLabel='Elevation (m)')


# ## 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***](http://git-scm.com/) 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 = tidegaugeobject.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...