From 779480acac74cf72ef06d3cd666c76f6554a0d22 Mon Sep 17 00:00:00 2001 From: Julian Gethmann Date: Sat, 31 Mar 2018 21:11:05 +0200 Subject: [PATCH] Update documentation * Add examples for the `pvs2pd` function --- docs/examples.rst | 36 +++++++++++++++++++++++++++++++++++- docs/scripts.rst | 2 ++ 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/examples.rst b/docs/examples.rst index 330ecbc..41901ed 100644 --- a/docs/examples.rst +++ b/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 ` 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 diff --git a/docs/scripts.rst b/docs/scripts.rst index b65b473..c1a0907 100644 --- a/docs/scripts.rst +++ b/docs/scripts.rst @@ -1,3 +1,5 @@ +.. _scripts: + Scripts ======= -- GitLab