Module pyfx.pricingscience.winrate

Functions and utilities for quote win rate analysis.

Contains formulas to sample data from EBM model output and fit a function that will be more easily used for optimal price search.

Functions

def angle_between(p1: numpy.ndarray, p2: numpy.ndarray, p3: numpy.ndarray, epsilon: float = 1e-08) ‑> float

Computes the angle between (p1, p2) and (p2, p3).

Args

p1

first point array of coordinates

p2

second and summit of angle point array of coordinates

p3

third point array of coordinates

epsilon

very small float value to avoid division by zero

Returns

angle value in radians [0, pi]

def combined_sigmoid(x: Union[numpy.ndarray, float], l1: float, x01: float, k1: float, b1: float, l2: float, x02: float, k2: float, b2: float, l3: float, x03: float, k3: float, b3: float) ‑> Union[numpy.ndarray, float]

Computes the sum of three sigmoid functions applied to input x.

This function models complex, smooth, and bounded nonlinear behavior (e.g., from model explanations or response curves) by summing three parameterized sigmoids. It is useful when a single sigmoid is not sufficient to capture the shape of the function.

Args

x

the input value(s) at which to evaluate the combined sigmoid function.

li

(for i = 1 to 3) the amplitudes (scaling factors) of the three sigmoid components.

x0i

(for i = 1 to 3) the centers (inflection points) of the three sigmoid components.

ki

(for i = 1 to 3) the steepness (slope) of each sigmoid component, negative values produce descending sigmoids.

bi

(for i = 1 to 3) vertical shifts (biases) of each sigmoid component.

Returns

The value(s) of the combined sigmoid function at input x.

def fit_sigmoid(feature_points: numpy.ndarray, k_ref: float = -1, epsilon: float = 1e-06, base_angle_deg: float = 3.0, density_power: float = 1.5) ‑> Optional[pandas.core.frame.DataFrame]

Fits a sum of three sigmoids to a 1D feature contribution curve.

This function is intended to approximate the shape of a model explanation curve (e.g., from an EBM model) by using a sum of three sigmoïd functions. It performs smoothing, adaptive sampling, and then curve fitting using nonlinear least squares optimization.

Args

feature_points

The feature points coordinates (typically a 2D numeric array, [x, f_x]).

k_ref

reference k value for sigmoïds steepness -1 for decreasing and 1 for increasing.

epsilon

very small float value to avoid division by zero.

base_angle_deg

the base angular threshold in degrees used to detect curvature.

density_power

controls how strongly local density affects the adaptive angle threshold, higher values make the angle more sensitive in dense regions.

Returns

A DataFrame with the fitted sigmoid parameters:

• 'l' : Amplitude of the sigmoid.
• 'x0' : Center of the sigmoid (inflection point).
• 'k' : Steepness of the sigmoid.
• 'b' : Vertical shift (bias). Each row corresponds to one of the three sigmoids used in the sum. Returns None if input is empty or fitting fails.

def hyper_adaptive_sampler(points: numpy.ndarray, base_angle_deg: float = 2, density_power: float = 1.5, epsilon: float = 1e-08) ‑> numpy.ndarray

Selects a subset of points from a polyline based on local curvature and point density.

This function uses an adaptive angle-based sampling method, is meant to reduce the number of points in a curve while preserving important shape features, especially corners or areas of high curvature:

• The function calculates the angle between points(p_prev, p_curr, p_next).
• The angle threshold is decreased in dense regions and increased in sparse regions.
• This method helps retain key structural features of a curve with fewer points.

Args

points

array of shape (N, 2) representing a sequence of (x, y) points.

base_angle_deg

the base angular threshold in degrees used to detect curvature, this threshold is adaptively scaled based on local point density.

density_power

controls how strongly local density affects the adaptive angle threshold, higher values make the angle more sensitive in dense regions.

epsilon

very small float value to avoid division by zero.

Returns

np.ndarray

a subset of the original points array, including endpoints and points where the angle between segments exceeds the adaptive threshold.

def sigmoid(x: Union[numpy.ndarray, float], amplitude: float, x0: float, k: float, b: float) ‑> Union[numpy.ndarray, float]

Computes the image f(x) by a sigmoid functions f applied to input x.

Args

x

the input value(s) at which to evaluate the combined sigmoid function.

amplitude

the amplitude (scaling factors) of the sigmoid.

x0

the center (inflection points) of the sigmoid.

k

the steepness (slope) of the sigmoid. Negative values produce descending sigmoids.

b

the vertical shift (bias) of the sigmoid.

Returns

The value(s) of the sigmoid function at input x.