QuanTAlib/lib/numerics/sigmoid/Sigmoid.md

SIGMOID: Logistic Function

The sigmoid function is the S-curve that turns messy reality into neat probabilities—a mathematical diplomat that insists every answer must be between 0 and 1.

Property	Value
Category	Numeric
Inputs	Source (close)
Parameters	k (default 1.0), x0 (default 0.0)
Outputs	Single series (Sigmoid)
Output range	Varies (see docs)
Warmup	0 bars
PineScript	sigmoid.pine

• The Sigmoid (Logistic) transformer maps any real-valued input to the bounded range (0, 1) using the standard logistic function.
• Trading note: Sigmoid function; maps values to (0,1). Used for probability-like scaling of indicator outputs.
• Validated against TA-Lib, Skender, and Tulip reference implementations where available.

The Sigmoid (Logistic) transformer maps any real-valued input to the bounded range (0, 1) using the standard logistic function. Its characteristic S-shaped curve makes it indispensable for probability estimation, neural network activations, and any scenario requiring bounded outputs from unbounded inputs.

Mathematical Foundation

Core Formula

S(x) = \frac{1}{1 + e^{-k(x - x_0)}}

where:

• x is the input value
• k is the steepness factor (default 1.0)
• x_0 is the midpoint where S(x_0) = 0.5 (default 0.0)
• e \approx 2.71828... is Euler's number

Key Properties

Property	Formula	Description
Midpoint	S(x_0) = 0.5	Centered at x_0
Symmetry	S(x_0 + d) + S(x_0 - d) = 1	Point symmetry about (x_0, 0.5)
Limits	\lim_{x \to -\infty} S(x) = 0, \lim_{x \to +\infty} S(x) = 1	Asymptotic bounds
Derivative	S'(x) = k \cdot S(x) \cdot (1 - S(x))	Self-referential gradient
Monotonicity	S'(x) > 0 for all x	Strictly increasing
Steepness	Higher k → steeper transition	Controls sensitivity

Domain and Range

	Value
Domain	(-\infty, +\infty)
Range	(0, 1) exclusive

The sigmoid accepts any real number and always produces outputs strictly between 0 and 1 (never exactly 0 or 1).

Financial Applications

Probability-like Outputs

Convert any signal to a pseudo-probability:

P_{signal} = S(z\text{-score})

where large positive z-scores approach 1, negative approach 0.

Bounded Confidence Indicators

Transform unbounded oscillators to fixed ranges:

\text{BoundedRSI} = S(k \cdot (\text{RSI} - 50))

Regime Classification

Soft classification between bullish (1) and bearish (0) regimes:

\text{Regime} = S(k \cdot \text{TrendStrength})

Position Sizing

Map conviction signals to allocation weights:

\text{Weight} = S(\text{ConvictionScore})

Parameter Guide

Steepness (k)

k Value	Behavior	Use Case
0.1	Very gradual	Smooth transitions, noise reduction
0.5	Gentle	Conservative probability mapping
1.0	Standard	General purpose (default)
2.0	Steep	Quick regime detection
5.0+	Very steep	Near binary classification

Midpoint (x_0)

x_0 Value	Behavior
0.0	Standard (default), symmetric about origin
Mean	Centers output around data average
Threshold	Custom decision boundary

Implementation Details

Overflow Handling

For extreme inputs, the exponential can overflow:

• When -k(x - x_0) > 700: return 0.0 (avoid exp overflow)
• When -k(x - x_0) < -700: return 1.0 (exp underflows to 0)

Precision Considerations

Input Range	Output Precision
$	k(x-x_0)
$	k(x-x_0)

Streaming Characteristics

Metric	Value
Warmup Period	0
Memory	O(1)
Complexity	O(1) per update

Performance Profile

Operation Count (Scalar)

Operation	Count	Notes
SUB	1	x - x_0
MUL	1	k \times (x - x_0)
NEG	1	Negate for exp
EXP	1	Hardware instruction
ADD	1	1 + \exp(...)
DIV	1	Final division
Total	~25-30 cycles	Dominated by EXP

Quality Metrics

Metric	Score	Notes
Accuracy	10/10	IEEE 754 compliant
Timeliness	10/10	Zero lag
Smoothness	10/10	Infinitely differentiable
Boundedness	10/10	Guaranteed (0, 1) output

Usage Examples

Basic Usage

// Create Sigmoid with default parameters
var sigmoid = new Sigmoid();

// Transform z-score to probability-like value
var zscore = new TValue(DateTime.UtcNow, 2.0);
var probability = sigmoid.Update(zscore);  // ≈ 0.881

Custom Steepness

// Steep sigmoid for quick transitions
var steepSigmoid = new Sigmoid(k: 3.0);

var x = new TValue(DateTime.UtcNow, 1.0);
var result = steepSigmoid.Update(x);  // ≈ 0.953 (steeper than default 0.731)

Custom Midpoint

// Center sigmoid at RSI neutral level (50)
var rsiSigmoid = new Sigmoid(k: 0.1, x0: 50);

var rsiValue = new TValue(DateTime.UtcNow, 70);
var bullishProbability = rsiSigmoid.Update(rsiValue);  // ≈ 0.881

Span API for Batch Processing

double[] inputs = { -2, -1, 0, 1, 2 };
double[] outputs = new double[inputs.Length];

Sigmoid.Calculate(inputs, outputs, k: 1.0, x0: 0.0);
// outputs ≈ { 0.119, 0.269, 0.500, 0.731, 0.881 }

Common Pitfalls

1. Not Exactly 0 or 1: Sigmoid asymptotically approaches but never reaches 0 or 1. If you need exact binary outputs, apply a threshold post-sigmoid.

2. Vanishing Gradients: For very large or small inputs, S'(x) \approx 0. This is a feature for boundedness but can cause issues if the sigmoid is part of a learning system.

3. Scale Sensitivity: The default k=1 assumes inputs are roughly in the range [-5, 5]. For inputs with different scales, adjust k or normalize inputs first.

4. Midpoint Confusion: Remember x_0 shifts where 0.5 occurs, not where 0 occurs. Sigmoid never outputs exactly 0.

5. Symmetry Assumption: Sigmoid imposes symmetric transition behavior. For asymmetric responses, consider other activation functions.

Validation

Test	Status
Midpoint S(x₀) = 0.5	✅
Symmetry Property	✅
Range (0, 1)	✅
Monotonicity	✅
Steepness Effect	✅
Limit Behavior	✅
Overflow Guards	✅

References

• Verhulst, P.-F. (1838). "Notice sur la loi que la population suit dans son accroissement." Correspondance Mathématique et Physique.
• Rumelhart, D., Hinton, G., & Williams, R. (1986). "Learning representations by back-propagating errors." Nature.
• Bishop, C. (2006). Pattern Recognition and Machine Learning. Springer.