Update documentation

* Add examples for the `pvs2pd` function

docs/examples.rst

@@ -17,7 +17,7 @@ Beside the examples given here, *please* also have look at the examples given in
 Scripts
 -------
 
-At the moment there is just the `get_mean_values` script that you can call with the `-h` or `--help` option flag to get further information how to use it. Please feel free to provide an example.
+At the moment there is just the `get_mean_values` :ref:`scripts <scripts>` that you can call with the `-h` or `--help` option flag to get further information how to use it. Please feel free to provide an example.
 
 Classes
 -------
@@ -95,3 +95,37 @@ Cassandra objects
 One example for a script that fetches the data for the main magnets and plots them can be written like this.
 
 .. literalinclude:: ../bin/plot_two.py
+
+Pandas DataFrames
+~~~~~~~~~~~~~~~~~
+
+As you might have noticed, until now all the examples needed a for loop for dealing with different PVs. But there is also
+the possibility to ask for several PVs at once. For this you need to have pandas_ installed.
+
+Then it is as simple to get a DataFrame with the timestamps as keys and the PVs as columns as shown in the following command::
+
+    from cassandra.pd import pvs2pd
+    df = pvs2pd(start=start, end=end, pvs=["nu_x", "nu_y", "energy"])
+
+Now you have got the values for the horizontal and vertical tunes and the energy from the start time to the end time.
+The times can be :obj:`datetime.datetime` objects as well as strings of the time as you would expect.
+The list of PVs can also contain the keys of the :obj:`Pvs.pv` dictionary or the PV name itself.
+
+In contrast to the normal Cassandra class there are further additional features.
+The probably most important one is the `upsample` option that lets you sample all data to the same sampling rate that
+can be one of the `offset-aliases`_.
+That implies that you can get a proper mean value instead of just a wrongly sampled mean.
+
+code::
+
+    df = pvs2pd(start=start, end=end, pvs=["nu_x", "nu_y", "energy"], upsample="ms")
+    df.mean()
+
+In the last example we upsampled the data to `ms` which should be ok for a proper mean of the tunes and the `df.mean()`
+returns the mean values of the tunes and the energy then.
+
+Another nice feature is that you can set the flag `save_local=True` and all the JSON data is saved to files in the
+current directory.
+
+.. _pandas: https://pandas.pydata.org
+.. _`offset-aliases`: http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases

docs/scripts.rst

+.. _scripts:
+
 Scripts
 =======