Merge 1144b5c into 3b4e8d9

.vscode/settings.json

@@ -4,8 +4,11 @@
     "bivariate",
     "bs",
     "chargino",
+    "colorama",
+    "coloredlogs",
     "cteq",
     "imul",
+    "inplace",
     "interp",
     "isnan",
     "issubdtype",

README.md

@@ -1,6 +1,9 @@
 [![Build Status](https://api.travis-ci.org/misho104/susy_cross_section.svg?branch=master)](https://travis-ci.org/misho104/susy_cross_section)
 [![Coverage Status](https://coveralls.io/repos/github/misho104/susy_cross_section/badge.svg?branch=master)](https://coveralls.io/github/misho104/susy_cross_section?branch=master)
+[![Doc Status](http://readthedocs.org/projects/susy-cross-section/badge/)](https://susy-cross-section.readthedocs.io/)
+[![PyPI version](https://badge.fury.io/py/susy-cross-section.svg)](https://badge.fury.io/py/susy-cross-section)
 [![License: MIT](https://img.shields.io/badge/License-MIT-ff25d1.svg)](https://github.com/misho104/susy_cross_section/blob/master/LICENSE)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 [susy_cross_section](https://github.com/misho104/susy_cross_section): Table-format cross-section data handler
 =============================================================================================================
@@ -16,17 +19,91 @@ Install simply via PyPI and use a script as:
 
 ```console
 $ pip install susy-cross-section
-$ susy-xs-get 13TeV.n2x1+.wino 500
+$ susy-xs get 13TeV.n2x1+.wino 500
 (32.9 +2.7 -2.7) fb
-$ susy-xs-get 13TeV.n2x1+.wino 513.3
+$ susy-xs get 13TeV.n2x1+.wino 513.3
 (29.4 +2.5 -2.5) fb
 ```
 
 which gives the 13 TeV LHC cross section to wino-like neutralino-chargino pair-production (`p p > n2 x1+`), etc.
 The values are taken from [LHC SUSY Cross Section Working Group](https://twiki.cern.ch/twiki/bin/view/LHCPhysics/SUSYCrossSections13TeVn2x1wino#Envelope_of_CTEQ6_6_and_MSTW_AN1) with interpolation if needed.
 
-You can find a list of supported processes in [susy_cross_section/config.py](https://github.com/misho104/susy_cross_section/blob/master/susy_cross_section/config.py).
-It is also straight forward to parse your own table files once you provide `.info` files as you find in [susy_cross_section/data/](https://github.com/misho104/susy_cross_section/tree/master/susy_cross_section/data/).
+To see more information, you will use `show` sub-command, which displays the cross-section table with physical attributes.
+
+```console
+$ susy-xs show 13TeV.n2x1+.wino
+
+------------------------------------------------------------------------
+TABLE "xsec" (unit: fb)
+------------------------------------------------------------------------
+               value        unc+        unc-
+m_wino
+100     13895.100000  485.572000  485.572000
+125      6252.210000  222.508000  222.508000
+150      3273.840000  127.175000  127.175000
+...              ...         ...         ...
+475        41.023300    3.288370    3.288370
+500        32.913500    2.734430    2.734430
+525        26.602800    2.299570    2.299570
+...              ...         ...         ...
+1950        0.005096    0.001769    0.001769
+1975        0.004448    0.001679    0.001679
+2000        0.003892    0.001551    0.001551
+
+[77 rows x 3 columns]
+
+collider: pp-collider, ECM=13TeV
+calculation order: NLO+NLL
+PDF: Envelope by LHC SUSY Cross Section Working Group
+included processes:
+  p p > wino0 wino+
+```
+
+You may also notice that the above value for 513.3GeV is obtained by interpolating the grid data.
+
+You can list all the available tables, or search for tables you want, by `list` sub-command:
+
+```console
+$ susy-xs list
+13TeV.n2x1-.wino       lhc_susy_xs_wg/13TeVn2x1wino_envelope_m.csv
+13TeV.n2x1+.wino       lhc_susy_xs_wg/13TeVn2x1wino_envelope_p.csv
+13TeV.n2x1+-.wino      lhc_susy_xs_wg/13TeVn2x1wino_envelope_pm.csv
+13TeV.slepslep.ll      lhc_susy_xs_wg/13TeVslepslep_ll.csv
+13TeV.slepslep.maxmix  lhc_susy_xs_wg/13TeVslepslep_maxmix.csv
+13TeV.slepslep.rr      lhc_susy_xs_wg/13TeVslepslep_rr.csv
+...
+
+$ susy-xs list 7TeV
+7TeV.gg.decoup  nllfast/7TeV/gdcpl_nllnlo_mstw2008.grid
+7TeV.gg.high    nllfast/7TeV/gg_nllnlo_hm_mstw2008.grid
+7TeV.gg         nllfast/7TeV/gg_nllnlo_mstw2008.grid
+...
+7TeV.ss10       nllfast/7TeV/ss_nllnlo_mstw2008.grid
+7TeV.st         nllfast/7TeV/st_nllnlo_mstw2008.grid
+
+$ susy-xs list 8t decoup
+8TeV.gg.decoup    nllfast/8TeV/gdcpl_nllnlo_mstw2008.grid
+8TeV.sb10.decoup  nllfast/8TeV/sdcpl_nllnlo_mstw2008.grid
+```
+
+and run for it:
+
+```console
+$ susy-xs get 8TeV.sb10.decoup 1120
+(0.00122 +0.00019 -0.00019) pb
+```
+
+For more help, try to run with `--help` option.
+
+```console
+$ susy-xs --help
+Usage: susy-xs [OPTIONS] COMMAND [ARGS]...
+...
+
+$ susy-xs get --help
+Usage: susy-xs get [OPTIONS] TABLE [ARGS]...
+...
+```
 
 You can uninstall this package as simple as
 
@@ -41,57 +118,32 @@ Introduction
 ------------
 
 Production cross sections are the most important values for high-energy physics collider experiments.
-There are many sources for the values, evaluated in various tools or schemes.
-For SUSY scenarios, the values provided by [LHC SUSY Cross Section Working Group](https://twiki.cern.ch/twiki/bin/view/LHCPhysics/SUSYCrossSections) are the most famous source of the "nominal" cross section expectation.
-However, their results as well as results provided in other references are not in machine-readable format and the data are provided in various format.
+Many collaborations publish their cross-section tables, calculated in various tools or schemes, which are available on the WWW.
+For SUSY scenarios, the values provided by [LHC SUSY Cross Section Working Group](https://twiki.cern.ch/twiki/bin/view/LHCPhysics/SUSYCrossSections) are the most famous source of the "nominal" cross section expectation for the LHC, while [NNLL-fast](https://www.uni-muenster.de/Physik.TP/~akule_01/nnllfast/) collaboration publishes those for colored process at the very high precision.
 
-This package provides a module `susy_cross_section` to handle those data.
-Any table-like files can be interpreted and read as a [https://pandas.pydata.org/](pandas) DataFrame object, once an annotation file (`info` files in JSON format) is provided, so that one can easily interpolate the grid by, e.g., [scipy.interpolate](https://docs.scipy.org/doc/scipy/reference/interpolate.html).
+However, these results are provided in various format; for example, some are in HTML with absolute combined symmetric uncertainties, and others are in CSV files with relative asymmetric uncertainties.
 
-For simpler use-case, a command-line script `susy-xs-get` is provided, with which one can get the cross section in several simple scenarios.
+This package `susy_cross_section` is provided to handle those data regardless of their format.
+This package reads any table-like grid files with help of [pandas](https://pandas.pydata.org/) DataFrame, and interpret any format of uncertainties once an annotation file  (`info` files) written in JSON format is provided, which allows one to interpolate the grid easily, e.g., by using [scipy.interpolate](https://docs.scipy.org/doc/scipy/reference/interpolate.html) package.
 
-Several data tables are included in this package, which is taken from, e.g., [LHC SUSY Cross Section Working Group](https://twiki.cern.ch/twiki/bin/view/LHCPhysics/SUSYCrossSections).
-In addition, one can use their own files by writing annotations, so that they interpolate their data with pre-installed interpolator.
+For simpler use-case, a command-line script `susy-xs` is provided, with which one can get the cross section in several simple scenarios.
+For more customization, you can use this package from your own code with more detailed interpolator options (linear-interpolation, loglog-spline-interpolation, etc.) or with your interpolator.
 
-More information to use as a Python package will be given in API references (to be written), and to use as a script can be found in their help:
+Document
+--------
 
-```console
-$ susy-xs-get --help
-Usage: susy-xs-get [OPTIONS] TABLE ARGS...
-
-  Interpolate cross-section data using the standard scipy interpolator (with
-  log-log axes).
-
-Options:
-  ...
-```
+The document is provided on [readthedocs.io](https://susy-cross-section.readthedocs.io), together with [API references](https://susy-cross-section.readthedocs.io/en/latest/susy_cross_section.html).
 
-License
--------
+License and Citation Policy
+---------------------------
 
 The program codes included in this repository are licensed by [Sho Iwamoto / Misho](https://www.misho-web.com) under [MIT License](https://github.com/misho104/SUSY_cross_section/blob/master/LICENSE).
 
+The non-program-code documents are licensed by [Sho Iwamoto / Misho](https://www.misho-web.com) under [CC BY-NC 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/) License.
+
 Original cross-section data is distributed by other authors, including
 
 * [LHC SUSY Cross Section Working Group](https://twiki.cern.ch/twiki/bin/view/LHCPhysics/SUSYCrossSections).
+* [NNLL-fast](https://www.uni-muenster.de/Physik.TP/~akule_01/nnllfast/)
 
-References (original data)
---------------------------
-
-* https://twiki.cern.ch/twiki/bin/view/LHCPhysics/SUSYCrossSections
-
-* C. Borschensky, M. Krämer, A. Kulesza, M. Mangano, S. Padhi, T. Plehn, X. Portell,
-  *Squark and gluino production cross sections in pp collisions at \sqrt(s) = 13, 14, 33 and 100 TeV,*
-  [Eur. Phys. J. **C74** (2014) 12](https://doi.org/10.1140/epjc/s10052-014-3174-y)
-  [[arXiv:1407.5066](http://arxiv.org/abs/1407.5066)].
-
-* M. Krämer, A. Kulesza, R. Leeuw, M. Mangano, S. Padhi, T. Plehn, X. Portell,
-  *Supersymmetry production cross sections in pp collisions at sqrt{s} = 7 TeV,*
-  [arXiv:1206.2892](https://arxiv.org/abs/1206.2892).
-
-* NNLL-fast: https://www.uni-muenster.de/Physik.TP/~akule_01/nnllfast/
-
-* W. Beenakker, C. Borschensky, M. Krämer, A. Kulesza, E. Laenen,
-  *NNLL-fast: predictions for coloured supersymmetric particle production at the LHC with threshold and Coulomb resummation,*
-  [JHEP **1612** (2016) 133](https://doi.org/10.1007/JHEP12(2016)133)
-  [[arXiv:1607.07741](https://arxiv.org/abs/1607.07741)].
+Full list of references are shown in [citations.pdf](https://github.com/misho104/susy_cross_section/blob/master/contrib/citations.pdf) distributed with this package, where you will find the citation policy for this package.

contrib/.gitignore

@@ -0,0 +1,8 @@
+*.bak
+
+*.aux
+*.bbl
+*.blg
+*.fdb_latexmk
+*.fls
+*.out