Metadata-Version: 2.1
Name: ecalic
Version: 0.0.7
Summary: A package to handle CMS Ecal InterCalibration constants and Ecal geometry
Home-page: https://gitlab.cern.ch/cms-ecal-dpg/ecalic
Author: Fabrice Couderc
Author-email: fabrice.couderc@cern.ch
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=2.7
Description-Content-Type: text/markdown
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: lxml
Requires-Dist: numpy

# ecalic package

This package handles CMS Ecal Intercalibration Constant (IC) and IC-like operation and visualisation.
This applies to several type of Ecal conditions which have a value per crystal, for example:
- EcalIntercalibConstantsRcd
- EcalLaserAPDPNRatiosRcd
- EcalChannelStatusRcd
- EcalPedestalsRcd (pedestal or rms)

The package contains two modules:
- `ecalic.iov` decodes ecal conditions (xml format)
- `ecalic.ic` the main module

To install the package (dependencies should be automatically downloaded):
```
pip install --user ecalic
pip install --user matplotlib
pip install --user lxml
pip install --user pandas
pip install --user numpy
```

All the examples below were tested in `ipython`, to try them:
- install ipython
```
pip install --user ipython
```
- start by typing `ipython`
- copy-paste the block of commands

## ecalic.iov

Use this module to decode an xml file downloaded from the database.
The example (the commands can be run in `ipython`) below will transform a pedestal xml file
in a txt file format (`ix iy iz ic`) where `ic` is the pedestal RMS in gain 6

```
import ecalic.iov as iov, ecalic.cmsStyle as cms

### for python2 python3 compatibility
try:
   from urllib.request import urlopen
except ImportError:
   from urllib2 import urlopen

### input files
www = 'https://ecaldpg.web.cern.ch/ecaldpg/users/fcouderc/examples/ecalic/'
pedestal_file =  urlopen(www + '/pedestals_hlt_run324773.xml' )
i = iov.xml( pedestal_file, type = 'noise6' )
i.dump_txt('noise_gain6.txt')
```
The available types `type` can be found in the help
```
? iov.xml
```

## ecalic.ic

This is the heart of the package. It contains:
- the class `icCMS` which represents the IC
- the `geom` variable which handles all the different crystal properties (pandas DataFrame)
- the function `icCovCor` to get the correlation and covariance between different IC sets.


A first simple example to see and plot crystal properties
```
import matplotlib.pyplot as plt
import ecalic.ic as ic, ecalic.iov as iov

### activate pyplot visualisation
plt.ion()
plt.show()

### dump the properties of 2 first crytals
ic.geom.head(2)

### define an empty icCMS instance
i = ic.icCMS()

### plot the FED in 2D
i.plot(var= 'FED', title = 'FED number')

### plot the crytal type (BTCP or SIC)
i.plot(var='fabric', title = 'producer')

### EB plot only
i.plot(var='fabric', title = 'producer',ecalpart = 'eb')
```
Note that the `cmsStyle` package is provided for plot polishing and is not mandatory.

The different methods from the `icCMS` class can be found:
```
dir(ic.icCMS)
```

### use-case example

In this example we do some simple `ecalic.ic` operations.  
```
try:
   from urllib.request import urlopen
except ImportError:
   from urllib2 import urlopen

### getting the example txt file from the web
www = 'https://ecaldpg.web.cern.ch/ecaldpg/users/fcouderc/examples/ecalic/'
inputtxt = urllib2.urlopen(www + '/ic_example.txt')
with open( 'ic.test.txt','w') as ftest: ftest.write( inputtxt.read())
ftest.close()
```

And try the commands:
```
import matplotlib.pyplot as plt
import ecalic.ic

###create an instance of ecalic.ic
i =  ecalic.ic.icCMS( 'ic.test.txt' , 'example IC' )

### help for each method
?i.etaRingNorm(

### normalize to 1 per eta ring
i.etaRingNorm()

### plot 2D
i.plot( zRange_eb = [0.98,1.02], zRange_ee = [0.95,1.05], title = 'IC test'  )

### average per harness and plot,
### remove 10% of the most tailish cristals (left and right from mean)

# add a variable with the average
# trim = remove 10% of the most tailish cristals (left and right from mean)
i['ic_av'] = i.average( groupby='harness', trim = 0.10 )
# plot the average
i.plot( var = 'ic_av', zRange_eb = [0.98,1.02], zRange_ee = [0.95,1.05], title = 'IC test average'  )
plt.show()
```


### A more involved example
In the following example we will:
- get the noise (in gain 12) from two different runs (xml included in the package)
- get the corresponding channel status
- mask the bad channel in the noise ics
- plot the noise in 2D
- profile these noise along `ieta`
- get the correlation between the 2 ics

Get the example script at [testNoise.py](https://gitlab.cern.ch/cms-ecal-dpg/ecalic/raw/master/ecalic/test/testNoise.py?inline=false)

And run the script
```
python testNoise.py
```


