# 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 use name as the principal identifier for readability. We also annotate a column by unit, which is str that is passed to Unit().

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 to Unit().

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. ColumnInfo – Constructed instance. 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.
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 has ColumnInfo.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. ParameterInfo – Constructed instance. 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 by unc_p and unc_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.
validate()[source]

Validate the content.

classmethod from_json(json_obj)[source]

Initialize an instance from valid json data.

Parameters: json_obj (typing.Any) – a valid json object. ValueInfo – Constructed instance. 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.
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 of parameters and values. The information about them is stored as lists of ColumnInfo, ParameterInfo, and ValueInfo objects. In addition, reader_options can be specified, which is directly passed to pandas.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 of pandas.read_csv() are available.
validate()[source]

Validate the content.

classmethod load(source)[source]

Load and construct FileInfo from a json file.

Parameters: source (pathlib.Path or str) – Path to the json file. 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. ColumnInfo – The column with name name. KeyError – If no column is found.
formatted_str()[source]

Return the formatted string.

Returns: str – Dumped data.

### 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 of file are delegated to the DataFrame object.

Variables: file (BaseFile, optional) – File object containing this table. name (str, optional) – Name of this table. This is provided so that ValueInfo can be obtained from file.
__getattr__(name)[source]

Fall-back method to delegate any operations to the DataFrame.

__setitem__(name, obj)[source]

Perform DataFrame.__setitem__.

__getitem__(name)[source]

Perform DataFrame.__getitem__.

__str__()[source]

Dump the data-frame.

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 and tables (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. 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 in info, 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.
validate()[source]

Validate the Table data.

__getitem__(key)[source]

Return the specied table data.

Parameters: key (str) – One of The key of the data to return. pandas.DataFrame – One of the data tables specified by key.
dump(keys=None)[source]

Return the dumped string of the data tables.

Parameters: keys (list of str, optional) – if specified, specified data are only dumped. str – Dumped data.

## 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.
formatted_str()[source]

Return the formatted string.

Returns: str – Dumped data.
class Table(obj=None, file=None, name=None)[source]

Table object with annotations.

__str__()[source]

Dump the data-frame with information.

unit

Return the unit of table values.

attributes

Return the information associated to this table.

class File(table_path, info_path=None)[source]

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 to Table 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,

$(x_{n1}, \dots, x_{nd}; y_n)$

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

$(x_{n1}, \dots, x_{nd}; y_n),$

with $$d+1$$ functions $$w_1, \dots, w_d$$ and $$w_{\mathrm y}$$ into

$X_{ni}=w_i(x_{ni}), \qquad Y_{n} = w_{\mathrm y}(y_n)$

and derive the interpolation function $$\bar f$$ based on $$({\boldsymbol X}_n; Y_n)$$. Then, the interpolated result is given by

$f({\boldsymbol x}) = w_{\mathrm y}^{-1}\Bigl(\bar f\bigl(w_1(x_1), \dots, w_d(x_d)\bigr)\Bigr).$
Type Aliases: VT (= float)¶ Type representing elements of data points. FT (= Callable[[VT], VT])¶ Type for wrapper functions w. XT (= List[VT])¶ Type for parameters x. YT (= VT)¶ Type for the value y.
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: wx (list of FT) – Wrapper functions (or names) for parameters x. wy (FT) – Wrapper function for the value y. wy_inv (FT) – The inverse function of wy.
static identity(x)[source]

Identity function as a wrapper.

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 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: f_bar (function of XT to YT) – The interpolating function in the modified axes. type_check (bool) – To perform type-check or not. 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: InterpType (= Callable[[Sequence[float]], float])¶ Type representing an interpolation function.
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 attribute param_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. 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)
__call__(*args, **kwargs)

Function call is alias of f0().

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.

unc_m_at(*args, **kwargs)[source]

Return the interpolated value of negative uncertainty.

Returns: float – interpolated result of negative uncertainty.
class AbstractInterpolator[source]

Bases: object

A base class of interpolator for values with uncertainties.

Actual interpolator should implement _interpolate() method, which accepts a pandas.DataFrame object with one value-column and returns an interpolating function (InterpType).

interpolate(table)[source]

Perform interpolation for values with uncertainties.

Parameters: cross_section_table (File) – A cross-section data table. name (str) – Value name of the table to interpolate. Interpolation – The interpolation result.
class Scipy1dInterpolator(kind='linear', axes='linear')[source]

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. 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. uses scipy.interpolate.PchipInterpolator. This method is recommended for most cases, especially if monotonic, but not suitable for oscillatory data. uses scipy.interpolate.Akima1DInterpolator. For oscillatory data this is preferred to Pchip interpolation.
• axes (str) –

Specifies the axes preprocess types.

linear: does no preprocess. uses log-axis for values (y). uses log-axis for parameters (x). 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 for scipy.interpolate.interp1d, but they except for “cubic” are not recommended for cross-section data. The option “cubic” calls scipy.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".

class ScipyGridInterpolator(kind='linear', axes_wrapper=None)[source]

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. alias of “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.

## 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)]
inverse()[source]

Return an inverted unit.

Returns: Unit – The inverted unit of self.
__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. Unit – The product.
__truediv__(other)[source]

Return division of two units.

Parameters: other (float, str, or Unit) – Another unit as a divider. 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. 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: value (float) – Central value. unc_p (float) – Positive-direction absolute uncertainty. unc_m (float) – Negative-direction absolute uncertainty. unit (str, optional) – Unit of the value and the uncertainties. relative (bool) – Whether to show the uncertainties in relative. 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”. Tuple[pathlib.Path, pathlib.Path] – Paths to data file and info file; absolute if preconfigured. FileNotFoundError – If one of the specified files is not found.
class TypeCheck[source]

Bases: object

Singleton class for methods to type assertion.

static is_list(obj, element_type=None)[source]

Return if obj is a list with elements of specified type.

Parameters: obj – object to test. element_type (type or list of type, optional) – Allowed types for elements. bool – Validation result.
static is_dict(obj, key_type=None, value_type=None)[source]

Return if obj is a dict with keys/values of specified type.

Parameters: obj – object to test. key_type (type or list of type, optional) – Allowed types for keys. key_type – Allowed types for values. bool – Validation result.

## 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), or table_file_path if info_file_path is given by replacing the extension of table_file_path to .info. The path is calculated relative to table_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/latest')

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. 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: key (str) – The key of cross-section table. absolute (bool) – Whether to return absolute paths or not. 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.