Merge pull request #50 from AUAS-Pulsar/waterfall-docs

added docs for waterfall

Author: TVH7

README.md

@@ -38,7 +38,13 @@ Creating a free and open source framework that contains the generic algorithms a
     1. [PSD](docs/plots.md#41-psd)
         1. [Parameters](docs/plots.md#411-parameters)
         2. [Returns](docs/plots.md#412-returns)
-        1. [Example usage](docs/plots.md#413-example-usage)
+        3. [Example usage](docs/plots.md#413-example-usage)
+    2. [Waterfall](docs/plots.md#41-psd)
+        1. [Construction](docs/plots.md#421-parameters)
+        2. [Methods](docs/plots.md#422-returns)
+        3. [Example usage](docs/plots.md#423-example-usage)
+            1. [With discrete data](docs/plots.md#4231-with-discrete-data)
+            2. [With stream data](docs/plots.md#4232-with-stream-data)
 5. [Timeseries](docs/timeseries.md)
     1. [Initialize timeseries object](docs/timeseries.md#51-initialize-the-timeseries-object)
     2. [Retrieve timeseries](docs/timeseries.md#521-retrieve-timeseries-object)

docs/plots.md

@@ -60,4 +60,68 @@ plt.plot(freqs, power_levels)
 plt.show()
 ```
 
+## 4.2 Waterfall
+The `plot.waterfall.Waterfall` class can be used to generate waterfall plots. 
+
+### 4.2.1 Construction
+
+| Parameter | Description |
+| --- | --- |
+| filter_bank | A `filterbank` object. |
+| center_freq | The center frequency of the signal in the filterbank object |
+| sample_freq | The sample frequency of the signal in the filterbank object|
+| fig | An imaging object, like `pyplot.figure()` |
+| mode | String `{discrete, stream}`. The mode to operate on. Use discrete for discrete datasets, and stream for stream data. Defaults to `stream`. |
+
+### 4.2.2 Methods
+| Method | Description |
+| --- | --- |
+| init_plot(self) | Initialize the plot |
+| update_plot_labes(self) | Generate the plot labels |
+| get_next(self) | Returns the next row of data in the filterbank object |
+| get_image(self) | Returns the image data of the full dataset, if using a discrete dataset. |
+| update(self, i) | Updates the image with the next row of data, when using a continuous datastream. |
+| animated_plotter(self) | Returns the figure and update function for matplotlib animation |
+| get_center_freq(self) | Returns the center frequency stored in the filterbank header |
+
+### 4.2.3 Example Usage
+#### 4.2.3.1 With discrete data
+```python
+import matplotlib.animation as animation
+from filterbank.header import read_header
+from filterbank.filterbank import Filterbank
+from plot import waterfall
+import pylab as pyl
+from plot.plot import next_power_of_2
+
+fb = Filterbank(filename='./pspm32.fil', read_all=True)
+
+wf = waterfall.Waterfall(filter_bank=fb, fig=pyl.figure(), mode="discrete")
+
+img = wf.get_image()
+
+pyl.show(img)
+```
+
+#### 4.2.3.2 With stream data
+```python
+import matplotlib.animation as animation
+from filterbank.header import read_header
+from filterbank.filterbank import Filterbank
+from plot import waterfall
+import pylab as pyl
+from plot.plot import next_power_of_2
+
+
+fb = Filterbank(filename='./pspm32.fil')
+
+wf = waterfall.Waterfall(fb=fb, fig=pyl.figure(), mode="stream")
+
+fig, update, frames, repeat = wf.animated_plotter()
+
+ani = animation.FuncAnimation(fig, update, frames=frames,repeat=repeat)
+pyl.show()
+```
+
+
 [Back to table of contents](../README.md)