PAS calibrations python library
===============================
We wrote a C software python library to read PAS calibration files.
== Download python library
* link:documents/IRAP/pas-calib.1.0.tar.gz[]
== Requirements
The PAS calibration python library needs :
* a valid gcc compiler
* python 3.x version 3.4 or greater
* numpy installed for that python release
* spacepy/pycdf library to read CDF files (not mandatory)
== Installation
=== Download and extract sources
Download the pas-calib.1.0.tar.gz in a given directory.
Extract source :
----
$ tar xvzf pas-calib.v1.0.tar.gz
----
You will get the following directory tree :
* pas-calib.1.0/profile : definition of some environment variables
* pas-calib.1.0/build : script to build python library
* pas-calib.1.0/tools : low-level C tools library
* pas-calib.1.0/calib : low-level C library used to read and parse PAS calibration files
* pas-calib.1.0/calib/python : Python C API used to read calibration from python
=== Environment profile
Use pas-calib.1.0/profile to set some environment variable to use python calibration library :
- PYTHONPATH : needed by python to find directory where calibration library is installed
- CALIB_DIR : needed to find directory where calibration files are installed
----
$ cd pas-calib.1.0
$ . profile
----
=== Build library
Run the build script :
----
$ cd pas-calib.1.0
$ . profile
$ ./build
----
That will generates and test the python calibration library.
The test script is located on :
pas-calib.1.0/calib/python/test_calib.py
It is run automatically after build process, and should display something like :
----
Logfile : calib.log
Calibrations for 2020-06-26T16:53:54
Azimuths : [-21.673 -14.561501 -8.610001 -2.7020001 3.1375 9.018499
14.91 20.663 27.381 33.321 39.103 ]
Elevations : [-17.082 -13.976 -10.379 -6.0695 -0.51549995
5.2869997 10.726999 15.2095 19.874 ]
Energies : [18450.5 17398.822 16407.09 15471.888 14589.988
13758.356 12974.129 12234.612 11537.236 10879.615
10259.478 9674.685 9123.228 8603.206 8112.822
7650.391 7214.3184 6803.106 6415.328 6049.6553
5704.8237 5379.649 5073.0107 4783.85 4511.1675
4254.0283 4011.5527 3782.896 3567.269 3363.9368
3172.194 2991.377 2820.8655 2660.0747 2508.4497
2365.4714 2230.6394 2103.4893 1983.591 1870.5297
1763.9104 1663.3638 1568.5496 1479.1431 1394.8345
1315.3286 1240.3561 1169.6562 1102.9851 1040.1171
980.8327 924.9216 872.1995 822.48584 775.60095
731.3901 689.70306 650.3899 613.3159 578.3611
545.3951 514.3035 484.99127 457.348 431.27936
406.69476 383.5099 361.64926 341.03827 321.60147
303.2694 285.9818 269.67886 254.31061 239.8167
226.14255 213.25328 201.09833 189.63336 178.8281
168.63736 159.02144 149.95546 141.40912 133.34755
125.74587 118.57895 111.82191 105.44959 99.43713
93.769684 88.42693 83.38402 78.631226 74.15311
69.92481 ]
----
=== Installation notes
The python library will be generated in user directory, generally :
----
${HOME}/.local/lib/python3.6/site-package
----
You can find the directory corresponding to your python release with :
----
$ python -m site --user-site
----
CAUTION: This directory has to be added in the PYTHONPATH environment variable (done by the environment profile).
== User manual
=== Import library
----
$ python
>>> import calib
Logfile : calib.log
----
Low-level calibration messages or errors are stored in calib.log, in current directory.
=== Getting help
----
>>>> help(calib)
Help on module calib:
NAME
calib - Solar Orbiter Calibration library
FUNCTIONS
catalog(...)
catalog() -- return calibration catalog filename
init(...)
init() -- Initialise calibration catalog
read(...)
read(datetime, key) -- return numpy array
test(...)
test() -- test purpose function
FILE
/home/solar/.local/lib/python3.6/site-packages/calib.cpython-36m-x86_64-linux-gnu.so
----
=== Getting calibration data
You must use the calib.read (datetime, key) function, with 2 parameters :
- datetime : a valid python datetime object (calibration files could change)
- key : a valid calibration key, corresponding to keys found in calibration catalalog.
If return a numpy array (or record-array), depending on the key type
Valid keys are :
- AZS : Azimuth simplified table
- AZF : Azimuth full table
- ELS : Elevation simplified table
- ELF : Elevation full table
- EVS : Energy simplifier table
- EVF : Energy full table
- CNF : Moment correction coefficients
- GFF : geometrical factors
- etc...
Read calibration catalog to get a full list of allowed calibration keys.
.Exemple
----
>>> from datetime import *
>>> now = datetime.now()
>>> azs = calib.read (now, "AZS")
>>> gff = calib.read (now, "GFF")
----
=== Azimuth or Elevation tables
Return value is a numpy record array, with a given shape and a given dtype, that contains:
- amin : angle bin min value
- amoy : angle bin median value
- amax : angle bin max value
- sin : sin of median angle value
- cos : cos of median angle value
.Exemple
----
>>>> azs = calib.read (now, "AZS")
>>> azs.shape
(11,)
>>> azs.dtype
dtype((numpy.record, [('amin', '<f4'), ('amoy', '<f4'), ('amax', '<f4'), ('sin', '<f4'), ('cos', '<f4')]))
>>> azf = calib.read (now,"AZF")
>>> azf.shape
(11, 9)
>>> azf.dtype
dtype((numpy.record, [('amin', '<f4'), ('amoy', '<f4'), ('amax', '<f4'), ('sin', '<f4'), ('cos', '<f4')]))
----
You can get amin, amoy, amax, sin of cos field name, for a single azimuth, whole table, or sub-set.
.Exemple of use
----
# Get Azimtuths median values
>>> azs.amoy
array([-21.673 , -14.561501 , -8.610001 , -2.7020001, 3.1375 ,
9.018499 , 14.91 , 20.663 , 27.381 , 33.321 ,
39.103 ], dtype=float32)
# Get given Azimuth values
>>> azs[2].moy
-8.610001
# Get all fields for a given azimuth
>>> azs [0]
(-25.229, -21.673, -18.117, -0.3693089, 0.9293067)
----
=== Energy tables
Return value is a numpy record array, with a given shape and a given dtype, that contains:
- emin : energy bin min value
- emoy : energy bin median value
- emax : energy bin max value
.Exemple
----
>>> evs = calib.read(now,"EVS")
>>> evs.shape
(96,)
>>> evs.dtype
dtype((numpy.record, [('emin', '<f4'), ('emoy', '<f4'), ('emax', '<f4')]))
>>> evf = calib.read(now,"EVF")
>>> evf.shape
(11, 9, 96)
>>> evf.dtype
dtype((numpy.record, [('emin', '<f4'), ('emoy', '<f4'), ('emax', '<f4')]))
----
You can get, emin, emoy or emax values, for a single, sub-set or whole energy bins.
----
>>> evs.emoy
>>> evs [0]
>>> evs.emoy [67]
>>> evs.emoy [0:16]
----
=== Other calibration tables
Other calibration tables are normal numpy array, with a given shape and dtype = float32
.Exemple
----
>>> cnf = calib.read(now,"CNF")
>>> cnf.shape
(11, 9, 96)
>>> yil = calib.read(now,"YIL")
>>> yil.shape
(11, 9, 11, 9)
>>> yil.dtype
dtype('float32')
----
