diff --git a/docs/examples.rst b/docs/examples.rst index 330ecbc8f215fef1c9d16e926f9646b8d6feeb52..41901ed4eecdb89c4d1e80bbf0413a5293106f9a 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 b65b4733fed447d95046f424f57b136a6e953fe0..c1a0907aeb21b8f34f183cdf0cd89fe09ea99c06 100644 --- a/docs/scripts.rst +++ b/docs/scripts.rst @@ -1,3 +1,5 @@ +.. _scripts: + Scripts =======