5. API Reference: susy_cross_section¶
Module to handle CSV-like data of SUSY cross section.
5.1. susy_cross_section.base subpackage¶
Table of values with asymmetric uncertainties.
BaseFile
carries grid tables as BaseTable
and annotations as FileInfo
.
The FileInfo
class contains the other three classes as sub-information.
base.table.BaseFile |
contains FileInfo and multiple BaseTable |
base.table.BaseTable |
represents the grid data for cross section. |
base.info.FileInfo |
has file-wide properties and ColumnInfo ,
ParameterInfo , and ValueInfo |
base.info.ColumnInfo |
has properties of each column |
base.info.ParameterInfo |
annotates a column as a parameter |
base.info.ValueInfo |
defines a value from columns |
5.1.1. susy_cross_section.base.info module¶
Classes to describe annotations of general-purpose tables.
This module provides annotation classes for CSV-like table data. The data is a two-dimensional table and represents functions over a parameter space. Some columns represent parameters and others do values. Each row represents a single data point and corresponding value.
Two structural annotations and two semantic annotations are defined. FileInfo
and ColumnInfo
are structural, which respectively annotate the whole file and
each columns. For semantics, ParameterInfo
collects the information of
parameters, each of which is a column, and ValueInfo
is for a value. A value
may be given by multiple columns if, for example, the value has uncertainties
or the value is given by the average of two columns.
-
class
ColumnInfo
(index, name, unit='')[source]¶ Bases:
object
Stores information of a column.
Instead of the int identifier
index
, we usename
as the principal identifier for readability. We also annotate a column byunit
, which is str that is passed toUnit()
.Variables: - index (int) –
The zero-based index of column.
The columns of a file should have valid
index
, i.e., no overlap, no gap, and starting from zero. - name (str) –
The human-readable and machine-readable name of the column.
As it is used as the identifier, it should be unique in one file.
- unit (str) –
The unit of column, or empty string if the column has no unit.
The default value is an empty str
''
, which means the column has no unit. Internally this is passed toUnit()
.
Note
As for now,
unit
is restricted as a str object, but in future a float should be allowed to describe “x1000” etc.-
classmethod
from_json
(json_obj)[source]¶ Initialize an instance from valid json data.
Parameters: json_obj (Any) – a valid json object. Returns: ColumnInfo – Constructed instance. Raises: ValueError
– If json_obj has invalid data.
-
to_json
()[source]¶ Serialize the object to a json data.
Returns: dict(str, str or int) – The json data describing the object.
-
validate
()[source]¶ Validate the content.
Raises: TypeError
– If any attributes are invalid type of instance.ValueError
– If any attributes have invalid content.
- index (int) –
-
class
ParameterInfo
(column='', granularity=None)[source]¶ Bases:
object
Stores information of a parameter.
A parameter set defines a data point for the functions described by the file. A parameter set has one or more parameters, each of which corresponds to a column of the file. The
column
attribute hasColumnInfo.name
of the column.Since the parameter value is read from an ASCII file, float values might have round-off errors, which might cause grid misalignments in grid- based interpolations. To have the same float expression on the numbers that should be on the same grid,
granularity
should be provided.Variables: - column (str) – Name of the column that stores this parameter.
- granularity (int or float, optional) –
Assumed presicion of the parameter.
This is used to round the parameter so that a data point should be exactly on the grid. Internally, a parameter is rounded to:
round(value / granularity) * granularity
For example, for a grid
[10, 20, 30, 50, 70]
, it should be set to 10 (or 5, 1, 0.1, etc.), while for[33.3, 50, 90]
, it should be 0.01.
-
classmethod
from_json
(json_obj)[source]¶ Initialize an instance from valid json data.
Parameters: json_obj (Any) – a valid json object. Returns: ParameterInfo – Constructed instance. Raises: ValueError
– If json_obj has invalid data.
-
to_json
()[source]¶ Serialize the object to a json data.
Returns: dict(str, str or float) – The json data describing the object.
-
validate
()[source]¶ Validate the content.
Raises: TypeError
– If any attributes are invalid type of instance.ValueError
– If any attributes have invalid content.
-
class
ValueInfo
(column='', attributes=None, unc_p=None, unc_m=None)[source]¶ Bases:
object
Stores information of value accompanied by uncertainties.
A value is generally composed from several columns. In current implementation, the central value must be given by one column, whose name is specified by
column
. The positive- and negative-direction uncertainties are specified byunc_p
andunc_m
, respectively, which are dict(str, str).Variables: - column (str or List[str]) –
Names of the column that stores this value.
The string, or each element of the list, must match one of the
ColumnInfo.name
in the file. If multiple columns are specified, the largest value among the columns (compared in each row) is used. - attributes (dict (str, Any)) – Physical information annotated to this value.
- unc_p (dict (str, str)) –
The sources of “plus” uncertainties.
Multiple uncertainty sources can be specified. Each key corresponds
ColumnInfo.name
of the source column, and each value denotes the “type” of the source. Currently, two types are implementend:"relative"
for relative uncertainty, where the unit of the column must be dimension-less."absolute"
for absolute uncertainty, where the unit of the column must be the same as that of the value column up to a factor."absolute,signed"
or"relative,signed"
for absolute/relative uncertainty but using the columns with correct sign.
- unc_m (dict(str, str)) –
The sources of “minus” uncertainties.
Details are the same as
unc_p
.
-
classmethod
from_json
(json_obj)[source]¶ Initialize an instance from valid json data.
Parameters: json_obj (typing.Any) – a valid json object. Returns: ValueInfo – Constructed instance. Raises: ValueError
– If json_obj has invalid data.
- column (str or List[str]) –
-
class
FileInfo
(document=None, columns=None, parameters=None, values=None, reader_options=None)[source]¶ Bases:
object
Stores file-wide annotations.
A table structure is given by
columns
, while in semantics a table consists ofparameters
andvalues
. The information about them is stored as lists ofColumnInfo
,ParameterInfo
, andValueInfo
objects. In addition,reader_options
can be specified, which is directly passed topandas.read_csv()
.The attribute
document
is provided just for documentation. The information is guaranteed not to modify any functionality of codes or packages, and thus can be anything.Developers must not use
document
information except for displaying them. If one needs to interpret some information, one should extend this class to provide other data-storage for such information.Variables: - document (dict(Any, Any)) – Any information for documentation without physical meanings.
- columns (list of ColumnInfo) – The list of columns.
- parameters (list of ParameterInfo) – The list of parameters to define a data point.
- values (list of ValueInfo) – The list of values described in the file.
- reader_options (dict(str, Any)) –
Options to read the CSV
The values are directly passed to
pandas.read_csv()
as keyword arguments, so all the options ofpandas.read_csv()
are available.
-
classmethod
load
(source)[source]¶ Load and construct FileInfo from a json file.
Parameters: source (pathlib.Path or str) – Path to the json file. Returns: FileInfo – Constructed instance.
-
get_column
(name)[source]¶ Return a column with specified name.
Return
ColumnInfo
of a column with name name.Parameters: name – The name of column to get. Returns: ColumnInfo – The column with name name. Raises: KeyError
– If no column is found.
5.1.2. susy_cross_section.base.table module¶
Tables representing values with asymmetric uncertainties.
This module provides a class to handle CSV-like table data representing values
with asymmetric uncertainties. Such tables are provided in various format; for
example, the uncertainty may be relative or absolute, or with multiple sources.
The class BaseFile
interprets such tables based on FileInfo
annotations.
-
class
BaseTable
(obj=None, file=None, name=None)[source]¶ Bases:
object
Table object with annotations.
This is a wrapper class of
pandas.DataFrame
. Any methods except for read/write offile
are delegated to the DataFrame object.Variables:
-
class
BaseFile
(table_path, info_path=None)[source]¶ Bases:
typing.Generic
File with table data-sets and annotations.
An instance has two main attributes:
info
(FileInfo) as the annotation andtables
(dict of BaseTable) as the data tables.Parameters: - table_path (str or pathlib.Path) – Path to the csv data file.
- info_path (str or pathlib.Path, optional) –
Path to the corresponding info file.
If unspecified,
table_path
with suffix changed to".info"
is used.
Variables: - table_path (pathlib.Path) – Path to the csv data file.
- info_path (pathlib.Path) – Path to the info file.
- raw_data (pandas.DataFrame) – the content of
table_path
. - info (FileInfo) – the content of
info_path
. - tables (dict(str, BaseTable)) –
The table parsed according to the annotation.
Each value is practically a
pandas.DataFrame
object and indexed according to the parameter specified ininfo
, having exactly three value-columns:"value"
,"unc+"
, and"unc-"
for the central value and positive- and negative- directed absolute uncertainty, respectively. The content of"unc-"
is non-positive.
-
__getitem__
(key)[source]¶ Return the specied table data.
Parameters: key (str) – One of The key of the data to return. Returns: pandas.DataFrame – One of the data tables specified by key.
5.2. susy_cross_section.table module¶
Classes for annotations to a table.
CrossSectionAttributes | represents physical property of cross section. |
Table | extends BaseTable to handle cross-section
specific attributes |
File | extends BaseFile to carry Table objects. |
-
class
CrossSectionAttributes
(processes='', collider='', ecm='', order='', pdf_name='')[source]¶ Bases:
object
Stores physical attributes of a cross section table.
These information is intended to be handled by program codes, so the content should be neat, clear, and ready to be standardized.
Variables: - processes (list of str) – The processes included in the cross section values. MadGraph5 syntax is recommended. Definiteness should be best respected.
- collider (str) – The type of collider, e.g.,
"pp"
,"e+e-"
. - ecm (str) – The initial collision energy with unit.
- order (str) – The order of the cross-section calculation.
- pdf_name (str) –
The name of PDF used in calculation.
The LHAPDF’s set name is recommended.
-
validate
()[source]¶ Validate the content.
Type is also strictly checked in order to validate info files.
Raises: TypeError
– If any attributes are invalid type of instance.ValueError
– If any attributes have invalid content.
-
class
Table
(obj=None, file=None, name=None)[source]¶ Bases:
susy_cross_section.base.table.BaseTable
Table object with annotations.
-
unit
¶ Return the unit of table values.
-
attributes
¶ Return the information associated to this table.
-
-
class
File
(table_path, info_path=None)[source]¶ Bases:
susy_cross_section.base.table.BaseFile
Data of a cross section with parameters, read from a table file.
Contents are the same as superclass but each table is extended from
BaseTable
toTable
class.Variables: - table_path (pathlib.Path) – Path to the csv data file.
- info_path (pathlib.Path) – Path to the info file.
- raw_data (pandas.DataFrame) – the content of
table_path
. - info (FileInfo) – the content of
info_path
. - tables (dict(str, Table)) – The cross-section table parsed according to the annotation.
5.3. susy_cross_section.interp subpackage¶
A subpackage to perform interpolation.
At the subpackage-level, the following modules and class aliases are defined.
module interp.axes_wrapper |
has axis preprocessors for interpolation |
module interp.interpolator |
has interpolator classes |
interp.Scipy1dInterpolator |
= interp.interpolator.Scipy1dInterpolator |
interp.ScipyGridInterpolator |
= interp.interpolator.ScipyGridInterpolator |
This subpackage contains the following class. Actual interpolators are
subclasses of AbstractInterpolator
and not listed here.
classes | |
---|---|
interp.axes_wrapper.AxesWrapper |
axis preprocessor |
interp.interpolator.Interpolation |
interpolation result |
interp.interpolator.AbstractInterpolator |
base class for interpolators |
Note
Interpolation of \(N\) data points,
for \(n=1, ..., N\) and \(d\) is the dimension of parameter space, i.e., the number of parameters, returns a continuous function \(f\) satisfying \(f({\boldsymbol x}_n)=y_n\).
Warning
One should distinguish an interpolation \(f\) from fitting functions. An interpolation satisfies \(f({\boldsymbol x}_n)=y_n\) but this does not necessarily hold for fitting functions. Meanwhile, an interpolation is defined patch by patch, so its first or higher derivative can be discontinuous, while usually a fit function is globally defined and class \(C^\infty\).
5.3.1. susy_cross_section.interp.axes_wrapper module¶
Axis preprocessor for table interpolation.
This module provides a class AxesWrapper
for advanced interpolation. Each
type of modifiers are provided as two functions: parameters-version and value-
version, or one for ‘x’ and the other for ‘y’. The former always returns a
tuple of floats because there might be multiple parameters, while the latter
returns single float value.
Note
Here we summarize interpolations with modified axes. In axis-modification process, we modify the data points
with \(d+1\) functions \(w_1, \dots, w_d\) and \(w_{\mathrm y}\) into
and derive the interpolation function \(\bar f\) based on \(({\boldsymbol X}_n; Y_n)\). Then, the interpolated result is given by
Type Aliases: |
|
---|
-
class
AxesWrapper
(wx, wy, wy_inv=None)[source]¶ Bases:
object
Toolkit to modify the x- and y- axes before interpolation.
In initialization, one can specify wrapper functions predefined, where one can omit wy_inv argument. The following functions are predefined.
- “identity” (or “id”, “linear”)
- “log10” (or “log”)
- “exp10” (or “exp”)
Variables: -
static
log10
(x)[source]¶ Log function (base 10) as a wrapper.
Note that this is equivalent to natural-log function as a wrapper.
-
static
exp10
(x)[source]¶ Exp function (base 10) as a wrapper.
Note that this is equivalent to natural-exp function as a wrapper.
-
wrapped_x
(xs)[source]¶ Return the parameter values after axes modification.
Parameters: xs (XT) – Parameters in the original axes Returns: XT – Parameters in the wrapped axes. Note
The argument xs is \((x_1, x_2, \dots, x_d)\), while the returned value is \((X_1, \dots, X_d) = (w_1(x_1), \dots, w_d(x_d))\).
-
wrapped_f
(f_bar, type_check=True)[source]¶ Return interpolating function for original data.
Return the interpolating function applicable to the original data set, given the interpolating function in the modified axes.
Parameters: Returns: function of XT to YT – The interpolating function in the original axes.
Note
The argument f_bar is \(\bar f\), which is the interpolation function for \(({\boldsymbol X}_n; Y_n)\), and this method returns the function \(f\), which is
\[f({\boldsymbol x}) = w_{\mathrm y}^{-1}\bigl(\bar f({\boldsymbol X})\bigr),\]where \(\boldsymbol X\) is given by applying
wrapped_x()
to \(\boldsymbol x\).
5.3.2. susy_cross_section.interp.interpolator module¶
Interpolators of cross-section data.
Type Aliases: |
|
---|
-
class
Interpolation
(f0, fp, fm, param_names=None)[source]¶ Bases:
object
An interpolation result for values with uncertainties.
This class handles an interpolation of data points, where each data point is given with uncertainties, but does not handle uncertainties due to interpolation.
In initialization, the interpolation results f0, fp, and fm should be specified as functions accepting a list of float, i.e.,
f0([x1, ..., xd])
etc. If the argument param_names is also specified, the attributeparam_index
is set, which allows users to call the interpolating functions with keyword arguments.Parameters: - f0 (InterpType) – Interpolating function of the central values.
- fp (InterpType) – Interpolating function of values with positive uncertainty added.
- fm (InterpType) – Interpolating function of values with negative uncertainty subtracted.
- param_names (list[str], optional) – Names of parameters.
Variables: param_index (dict(str, int)) – Dictionary to look up parameter’s position from a parameter name.
-
f0
(*args, **kwargs)[source]¶ Return the interpolation result of central value.
The parameters can be specified as arguments, a sequence, or as keyword arguments if
param_index
is set.Returns: float – interpolated central value. Examples
For an interpolation with names “foo”, “bar”, and “baz”, the following calls are equivalent:
f0([100, 20, -1])
f0(100, 20, -1)
f0(numpy.array([100, 20, -1]))
f0(100, 20, baz=-1)
f0(foo=100, bar=20, baz=-1)
f0(0, 0, -1, bar=20, foo=100)
-
fp
(*args, **kwargs)[source]¶ Return the interpolation result of upper-fluctuated value.
Returns: float – interpolated result of central value plus positive uncertainty.
-
fm
(*args, **kwargs)[source]¶ Return the interpolation result of downer-fluctuated value.
Returns: float – interpolated result of central value minus negative uncertainty.
-
tuple_at
(*args, **kwargs)[source]¶ Return the tuple(central, +unc, -unc) at the point.
Returns: tuple(float, float, float) – interpolated central value and positive and negative uncertainties.
-
unc_p_at
(*args, **kwargs)[source]¶ Return the interpolated value of positive uncertainty.
This is calculated not by interpolating the positive uncertainty table but as a difference of the interpolation result of the central and upper - fluctuated values.
Returns: float – interpolated result of positive uncertainty. Warning
This is not the positive uncertainty of the interpolation because the interpolating uncertainty is not included. The same warning applies for: meth:
unc_m_at
.
-
class
AbstractInterpolator
[source]¶ Bases:
object
A base class of interpolator for values with uncertainties.
Actual interpolator should implement
_interpolate()
method, which accepts apandas.DataFrame
object with one value-column and returns an interpolating function (InterpType).-
interpolate
(table)[source]¶ Perform interpolation for values with uncertainties.
Parameters: Returns: Interpolation – The interpolation result.
-
-
class
Scipy1dInterpolator
(kind='linear', axes='linear')[source]¶ Bases:
susy_cross_section.interp.interpolator.AbstractInterpolator
Interpolator for one-dimensional data based on scipy interpolators.
Parameters: - kind (str) –
Specifies the interpolator types.
linear: uses scipy.interpolate.interp1d
(kind="linear"
), which performs piece-wise linear interpolation.spline: uses scipy.interpolate.CubicSpline
, which performs cubic-spline interpolation. The natural boundary condition is imposed. This is simple and works well if the grid is even-spaced, but is unstable and not recommended if not even-spaced.pchip: uses scipy.interpolate.PchipInterpolator
. This method is recommended for most cases, especially if monotonic, but not suitable for oscillatory data.akima: uses scipy.interpolate.Akima1DInterpolator
. For oscillatory data this is preferred to Pchip interpolation. - axes (str) –
Specifies the axes preprocess types.
linear: does no preprocess. log: uses log-axis for values (y). loglinear: uses log-axis for parameters (x). loglog: uses log-axis for parameters and values.
Warning
Users should notice the cons of each interpolator, e.g., “spline” and “akima” methods are worse for the first and last intervals or if the grid is not even-spaced, or “pchip” cannot capture oscillations.
Note
kind
also accepts all the options forscipy.interpolate.interp1d
, but they except for “cubic” are not recommended for cross-section data. The option “cubic” callsscipy.interpolate.interp1d
, but it uses the not-a-knot boundary condition, while “spline” uses the natural condition, which imposes the second derivatives at the both ends to be zero.Note
Polynomial interpolations (listed below) are not included because they are not suitable for cross-section data. They yield in globally-defined polynomials, but such uniformity is not necessary for our purpose and they suffer from so-called Runge phenomenon. If data is expected to be fit by a polynomial, one may use “linear” with
axes="loglog"
.- kind (str) –
-
class
ScipyGridInterpolator
(kind='linear', axes_wrapper=None)[source]¶ Bases:
susy_cross_section.interp.interpolator.AbstractInterpolator
Interpolator for multi-dimensional structural data.
Parameters: - kind (str) –
Specifies the interpolator types. Spline interpolators can be available only for two-parameter interpolations.
linear: uses scipy.interpolate.RegularGridInterpolator
with method=”linear”, which linearly interpolates the grid mesh.spline: alias of “spline33”. spline33: uses scipy.interpolate.RectBivariateSpline
with order (3, 3); the numbers may be 1 to 5, but “spline11” is equivalent to “linear”. - axes_wrapper (AxesWrapper, optional) – Object for axes preprocess. If unspecified, no preprocess is performed.
- kind (str) –
5.4. susy_cross_section.utility module¶
Utility functions and classes.
Unit |
describing a physical unit. |
value_format |
give human-friendly string representation of values. |
get_paths |
parse and give paths to data and info files |
-
class
Unit
(*args)[source]¶ Bases:
object
A class to handle units of physical values.
This class handles units associated to physical values. Units can be multiplied, inverted, or converted. A new instance is equivalent to the product of
*args
; each argument can be a str, a Unit, or a float (as a numerical factor).Parameters: *args (float, str, or Unit) – Factors of the new instance. -
definitions
= {'': [1], '%': [0.01], 'pb': [1000, 'fb']}¶ The replacement rules of units.
This dictionary defines the replacement rules for unit conversion. Each key should be replaced with the product of its values.
Type: dict[str, list of (float or str)]
-
__imul__
(other)[source]¶ Multiply by another unit.
Parameters: other (float, str, or Unit) – Another unit as a multiplier.
-
__mul__
(other)[source]¶ Return products of two units.
Parameters: other (float, str, or Unit) – Another unit as a multiplier. Returns: Unit – The product.
-
__truediv__
(other)[source]¶ Return division of two units.
Parameters: other (float, str, or Unit) – Another unit as a divider. Returns: Unit – The quotient.
-
__float__
()[source]¶ Evaluate as a float value if this is a dimension-less unit.
Returns: float – The number corresponding to this dimension-less unit. Raises: ValueError
– If not dimension-less unit.
-
-
value_format
(value, unc_p, unc_m, unit=None, relative=False)[source]¶ Return human-friendly text of an uncertainty-accompanied value.
Parameters: Returns: str – Formatted string describing the given value.
-
get_paths
(data_name, info_path=None)[source]¶ Return paths to data file and info file.
Parameters: - data_name (pathlib.Path or str) –
Path to grid-data file or a table name predefined in configuration.
If a file with data_name is found, the file is used. Otherwise, data_name must be a pre-defined table key, or raises KeyError.
- info_path (pathlib.Path or str, optional) –
Path to info file, which overrides the default setting.
The default setting is the grid-file path with suffix changed to “.info”.
Returns: Tuple[pathlib.Path, pathlib.Path] – Paths to data file and info file; absolute if preconfigured.
Raises: FileNotFoundError
– If one of the specified files is not found.- data_name (pathlib.Path or str) –
-
class
TypeCheck
[source]¶ Bases:
object
Singleton class for methods to type assertion.
5.5. susy_cross_section.config module¶
Configuration data of this package.
-
table_names
= {name: data_path or Tuple[data_path, info_path], ...}¶ Preset table names and paths to files.
A dict object, where the values show the paths to table and info files. Values are a tuple
(table_file_path, info_file_path)
, ortable_file_path
if info_file_path is given by replacing the extension of table_file_path to.info
. The path is calculated relative totable_dir
.Type: dict[str, str or tuple[str, str]]
-
table_dir
= 'susy_cross_section/data'¶ Base directory for table data, relative to the package directory.
Type: str
-
package_dir
= PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/susy-cross-section/checkouts/0.1.1')¶ The package diretory, usually no need to change.
Type: pathlib.Path
-
parse_table_value
(obj)[source]¶ Parse the table values, which might be str or tuple, to a tuple.
Parameters: obj (str or tuple[str, str]) – The value of table_names
.Returns: tuple[str, str or None] – The path to grid file and (if specified) to info file.
-
table_paths
(key, absolute=False)[source]¶ Return the relative paths to table file and info file.
Parameters: Returns: Tuple[pathlib.Path, pathlib.Path] – The relative path to the grid file and the info file.
The path for info file is returned only if it is configured. The paths are calculated relative to the package directory.
5.6. susy_cross_section.scripts module¶
Scripts for user’s ease of handling the data.
For details, see the manual or try to execute with --help
option.