lhcsmapi 1.5.21
A package with an API for signal access and processing for the LHC Signal Monitoring project.

# LHC Signal Monitoring API Package
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-api/raw/master/figures/logo.png" width=25%>

This is a package with an API for signal access and processing for the LHC Signal Monitoring project.

The API documentation is available at <https://sigmon.docs.cern.ch/api>

The User Guide is available at <https://sigmon-docs.web.cern.ch/>

## Installation
There are two ways of using the API in your code:

1. Loading preinstalled packages from an EOS project folder (in SWAN environment)
2. Manual installation (in any environment)

The first option guarantees the use of the most recent code version without manual installation. The second one is more time consuming, however, works in environments with no access to the EOS folder (e.g., Apache Airflow scheduler). In addition, the second method allows to install a selected version (`pip install package_name=version`).

### Preinstalled Packages
To use the set of pre-installed packages please follow these three steps:
0. Contact the Signal Monitoring team (mailto:lhc-signal-monitoring@cern.ch) in order to get read access to the EOS folder with pre-installed packages.
1. (optional) Uninstall existing packages.  
Historically, the initial way of installing the packages was by manual installation discussed in Section Manual Installation.
Thus, to avoid double reference to a package, please uninstall (with `pip uninstall package_name`) all packages needed for the API to work (tzlocal, tqdm, influxdb, plotly, lhcsmapi). This operation has to be done only once provided that the packages were installed (to check if a package was installed use `pip list | grep package_name` in SWAN Command Line Interface).
2. While logging to SWAN service, please add the environment script as `/eos/project/l/lhcsm/public/packages.sh`
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-api/raw/master/figures/swan_environment_script.png" width=25%>

### Manual Installation
In order to use the API, it has to be installed with a python package installer as

```python
pip install --user lhcsmapi
```
Check the latest version at <a href="https://pypi.org/project/lhcsmapi/">https://pypi.org/project/lhcsmapi/</a>

The API relies on several external python packages which have to be installed in a similar manner. The list of packages is stored in the <u><i>requirements.txt</i></u> file.

If you use SWAN, the service provides a set of pre-installed python packages through CVMFS. The LHC-SM notebooks require installation of several additional packages on top of CVMFS. In order to install a package, please open a SWAN Terminal by clicking [>_] icon in the top right corner.

![SWAN CLI Button](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/swan-cli-button.png)

Five additional python packages have to be installed:
- tzlocal - for time zone convertion
- tqdm - for progress bar to track queries
- influxdb - for communication with an Influxdb
- plotly - for interactive plotting of circuit schematics 
- lhcsmapi - for LHC-SM API
In order to install a package please execute the following command
```
$ pip install --user package_name
```

The expected output, after installing all packages, is presented in five figures below.

- SWAN Terminal output after successful installation of tzlocal package.
![SWAN pip install tzlocal](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/swan-pip-install-tzlocal.png)

- SWAN Terminal output after successful installation of tqdm package.
![SWAN pip install tqdm](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/swan-pip-install-tqdm.png)

- SWAN Terminal output after successful installation of influxdb package.
![SWAN pip install influxdb](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/swan-pip-install-influxdb.png)

- SWAN Terminal output after successful installation of plotly package.
![SWAN pip install plotly](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/swan-pip-install-plotly.png)

- SWAN Terminal output after successful installation of lhcsmapi package.
![SWAN pip install lhcsmapi](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/swan-pip-install-lhcsmapi.png)

### Updating lhcsmapi Package

Please note that the first four packages (tzlocal, tqdm, influxdb, plotly) have to be installed only once while the last one is still in the development phase and subject to frequent updates. Please send us an e-mail request (mailto:lhc-signal-monitoring@cern.ch) if you want to subscribe for updates. In order to update the lhcsmapi package, please execute the following command.
```
$ pip install --user --upgrade lhcsmapi
```

### Known Issues
At times, in order to update the lhcsmapi package one has to execute the command
```
pip install --user --upgrade lhcsmapi
```
twice while using the SWAN terminal (cf. an error message in the figure below).
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-api/raw/master/figures/double_reinstallation_error.png">


In case this command returns an error, please try to execute it again. Should that operation also fail, please uninstall the package by executing
```
$ pip uninstall lhcsmapi
```

and performing a fresh installation the package
```
$ pip install --user lhcsmapi
```

Should you experience any further issues with installing a package, please contact <a href="https://swan.web.cern.ch">SWAN support</a> or use the preinstalled package with the environment script.

### NXCALS Access with SWAN
The API allows to perform a query of signals from PM and NXCALS. The NXCALS database requires an assignment of dedicated access rights for a user. 
If you want to query NXCALS with the API, please follow a procedure below on how to request the NXCALS access.

1. Go to http://nxcals-docs.web.cern.ch/current/user-guide/data-access/nxcals-access-request/ for most updated procedure
2. Send an e-mail to mailto:acc-logging-support@cern.ch with the following pieces of information:
 - your NICE username
 - system: WinCCOA, CMW
 - NXCALS environment: PRO
 
Optionally one can mention that the NXCALS database will be accessed through SWAN.
Once the access is granted, you can use NXCALS with SWAN.