From 36b72d009fe48d901ff868f7083a738b6a1aeb7e Mon Sep 17 00:00:00 2001
From: Operateur <operateur@synchrotron-soleil.fr>
Date: Tue, 6 Feb 2024 11:10:19 +0100
Subject: [PATCH] fix(README): update it
---
README.md | 105 +++++++++++++++++++-----------------------------------
1 file changed, 36 insertions(+), 69 deletions(-)
diff --git a/README.md b/README.md
index 4098332..13d0aed 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,11 @@
-# pySoleilControl
-Useful python tools for SOLEIL control system.
-
-The ultimate aim is to provide tools that can be used in a shell prompt, ipython prompt or in python applications (such as GUI).
-
-Under construction, the first brick is a module to retrieve data from the Tango Archiver.
-
-## ArchiveExtractor
+# ArchiveExtractor
This module brings some functions to extract data from HDB/TDB.
+## Quick example
Usage example, with an ipython prompt
```python
-In [1]: import pySoleilControl.ArchiveExtractor as AE
+In [1]: import ArchiveExtractor as AE
In [2]: # Looking for an attribute in HDB
...: AE.findattr("ans/dg/*dcct*")
@@ -24,7 +18,7 @@ Out[2]:
'ANS/DG/DCCT-CTRL/lifeTimeErr']
In [3]: # Get data between two dates, this return a pandas.Dataframe object
- ...: AE.ExtrBetweenDates('ANS/DG/DCCT-CTRL/current', '2021-12-13', '2021-12-13-12:00')
+ ...: AE.extract('ANS/DG/DCCT-CTRL/current', '2021-12-13', '2021-12-13-12:00')
INFO:Perform ExtractBetweenDates (ans/dg/dcct-ctrl/current, 2021-12-13 00:00:00, 2021-12-13 12:00:00)
Out[3]:
2021-12-13 00:00:00 450.993568
@@ -40,75 +34,48 @@ Out[3]:
2021-12-13 12:00:00 15.005410
Length: 42725, dtype: float64
-In [4]: # Get min, max and mean with a 10 minute window
- ...: d=AE.ExtrBetweenDates_MinMaxMean('ANS/DG/DCCT-CTRL/current', '2021-12-13', '2021-12-13-12:00', timeInterval='10m')
-
-In [5]: d
-Out[5]:
- Min Mean Max
-2021-12-13 00:05:00 449.762286 450.619654 451.617095
-2021-12-13 00:15:00 449.761171 450.676306 451.595391
-2021-12-13 00:25:00 449.764910 450.684333 451.606520
-2021-12-13 00:35:00 449.766284 450.688881 451.655843
-2021-12-13 00:45:00 449.766808 450.716444 451.678886
-... ... ... ...
-2021-12-13 11:15:00 15.435944 15.495834 15.552427
-2021-12-13 11:25:00 15.325022 15.383286 15.437459
-2021-12-13 11:35:00 15.214556 15.270340 15.326395
-2021-12-13 11:45:00 15.106309 15.163566 15.219333
-2021-12-13 11:55:00 15.003812 15.056515 15.110022
-
-[72 rows x 3 columns]
-
-
-In [6]: # Activate inline matplotlib
- ...: %matplotlib
-Using matplotlib backend: TkAgg
-
-In [6]: # Simply plot
- ...: d.plot()
-
-In [7]: # ipython prompt supports autocompletion. The doc of function can be quickly read by adding a '?'
- ...: AE.ExtrBetweenDates?
-Signature: AE.ExtrBetweenDates(attribute, dateStart, dateStop=None, db='H')
+```
+## Main function help
+
+
+```
+Signature: AE.extract(attr, date1, date2=None, method='nearest', db='H')
Docstring:
-Query attribute data from an archiver database, get all points between dates.
-Use ExtractBetweenDates.
+Access function to perform extraction between date1 and date2.
+Can extract one or several attributes.
+date1 and date2 can be both exact date, or one of two can be a time interval that will be taken relative to the other.
-Parameters
-----------
-attribute : String
- Name of the attribute. Full Tango name i.e. "test/dg/panda/current".
-dateStart : datetime.datetime, string
- Start date for extraction. If string, it will be parsed.
- Example of string format %Y-%m-%d-%H:%M:%S or less precise.
+Parameters:
+-----------
+attr: string, list, dict
+ Attribute(s) to extract.
+ If string, extract the given attribute, returning a pandas.Series.
+ If list, extract attributes and return a list of pandas.Series.
+ If a dict, extract attributes and return a dict of pandas.Series with same keys.
-dateStop : datetime.datetime, string, None
- Stop date for extraction.
+date1, date2: string, datetime.datetime, datetime.timedelta, None
+ Exact date, or duration relative to date2.
If string, it will be parsed.
- Example of string format %Y-%m-%d-%H:%M:%S or less precise.
- If None, it takes the current date and time.
- Default is None (now).
+ A start date can be given with string format '%Y-%m-%d-%H:%M:%S' or less precise (ie '2021-02', '2022-11-03' '2022-05-10-21:00'.i..).
+ A duration can be given with string format 'Xu' where X is a number and u is a unit in ('m':minutes, 'h':hours, 'd':days, 'M':months)
+ A datetime.datetime object or datetime.timedelta object will be used as is.
+ date2 can be None. In that case it is replaced by the current time.
+
+method: str
+ Method of extraction
+ 'nearest': Retrieve nearest value of date1, date2 is ignored.
+ 'between': Retrive data between date1 and date2.
db: str
Which database to look in, 'H' or 'T'.
-Exceptions
-----------
-ValueError
- The attribute is not found in the database.
+```
-Returns
--------
-[date, value] : array
- date : numpy.ndarray of datetime.datime objects
- Dates of the values
- value : numpy.ndarray
- Archived values
-File: ~/GrpDiagnostics/RBT/pySoleilControl/ArchiveExtractor.py
-Type: function
+## For developpers
+### Contribute
+There is a simple test directory with only a manual test scipt.
+Please run and check it before proposing merge.
-```
--
GitLab