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

# # PySeison - Tutorial 5: Drifter class

# In[1]:


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


# ## 1. PySeidon - Drifter object initialisation

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

# ### 1.1. Package importation

# As any other library in *Python*, 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 import *


# *** Star *** here means *all*. Usually this form of statements would import the entire library. In the case of *PySeidon*, 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* is based on this notion of object, so let us define our first "Drifter" object.

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

# ***Answer: ***

# In[3]:


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


# According to the documentation, in order to define a Drifter object, the only required input is a ***filename**. This string input represents path to a file (e.g. *testAdcp=Drifter('./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 drifter object named *drift* from the following template: **./data4tutorial/drifter_GP_01aug2013.mat**
# - Tip: adapt the file's path to your local machine. 
# 
# ***Answer: ***

# In[4]:


drift = Drifter('./data4tutorial/drifter_GP_01aug2013.mat')


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

# The TideGauge object possesses 3 attributes and 2 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:
# - ***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 - Hands-on (10 seconds)

# ### Plots

# ***Exercise 3: ***
# - Plot drifter's trajectorie
# 
# ***Answer: ***

# In[5]:


drift.Plots.trajectories()


# ### More to come in next version of Pyseidon...

# ## 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* 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...