@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/methods/cost/README.md

@@ -198,6 +198,57 @@ Targets may be soft labels and are expected to sum to 1 (will be re-normalized i
 
 ## methods/cost/cost.utils.ts
 
+### BINARY_CLASSIFICATION_THRESHOLD
+
+Threshold for binarizing probabilities into class predictions.
+
+### clampProbability
+
+```ts
+clampProbability(
+  probability: number,
+): number
+```
+
+Clamps a probability into the inclusive bounds defined by PROBABILITY_LOWER_BOUND and PROBABILITY_UPPER_BOUND.
+
+Parameters:
+- `probability` - - Raw probability value to bound.
+
+Returns: Probability constrained to the numeric stability range.
+
+### classifyBinary
+
+```ts
+classifyBinary(
+  probability: number,
+): number
+```
+
+Converts a probability into a binary class label using the configured threshold.
+
+Parameters:
+- `probability` - - Probability to classify.
+
+Returns: POSITIVE_CLASS_LABEL when above or equal to threshold; otherwise NEGATIVE_CLASS_LABEL.
+
+### computeBinaryError
+
+```ts
+computeBinaryError(
+  targets: number[],
+  outputs: number[],
+): number
+```
+
+Computes binary classification error rate.
+
+Parameters:
+- `targets` - - Target labels (0 or 1).
+- `outputs` - - Predicted probabilities.
+
+Returns: Proportion of misclassified samples.
+
 ### computeCrossEntropy
 
 ```ts
@@ -215,56 +266,62 @@ Parameters:
 
 Returns: Mean cross-entropy error across all samples.
 
-### computeSoftmaxCrossEntropy
+### computeFocalLoss
 
 ```ts
-computeSoftmaxCrossEntropy(
+computeFocalLoss(
   targets: number[],
   outputs: number[],
+  gamma: number,
+  alpha: number,
 ): number
 ```
 
-Computes the softmax cross entropy given targets and raw score outputs.
+Computes focal loss for imbalanced classification tasks.
 
 Parameters:
-- `targets` - - Desired target probabilities that should sum to 1 (will be normalized if not).
-- `outputs` - - Raw logits or scores for each class.
+- `targets` - - Target labels (0 or 1) or soft labels.
+- `outputs` - - Predicted probabilities.
+- `gamma` - - Focusing parameter controlling hard example emphasis.
+- `alpha` - - Balancing parameter for class weighting.
 
-Returns: Total (non-averaged) softmax cross-entropy loss.
+Returns: Mean focal loss.
 
-### computeMeanSquaredError
+### computeHingeLoss
 
 ```ts
-computeMeanSquaredError(
+computeHingeLoss(
   targets: number[],
   outputs: number[],
 ): number
 ```
 
-Computes mean squared error between targets and outputs.
+Computes hinge loss for margin-based classification.
 
 Parameters:
-- `targets` - - Desired target values.
-- `outputs` - - Model outputs.
+- `targets` - - Target labels encoded as -1 or 1.
+- `outputs` - - Model outputs (raw scores).
 
-Returns: Mean squared error.
+Returns: Mean hinge loss.
 
-### computeBinaryError
+### computeLabelSmoothingLoss
 
 ```ts
-computeBinaryError(
+computeLabelSmoothingLoss(
   targets: number[],
   outputs: number[],
+  smoothing: number,
 ): number
 ```
 
-Computes binary classification error rate.
+Computes cross entropy with label smoothing applied to targets.
 
 Parameters:
-- `targets` - - Target labels (0 or 1).
+- `targets` - - Target labels (0 or 1) or soft labels.
 - `outputs` - - Predicted probabilities.
+- `smoothing` - - Smoothing factor between 0 and 1.
 
-Returns: Proportion of misclassified samples.
+Returns: Mean cross-entropy loss with smoothed targets.
 
 ### computeMeanAbsoluteError
 
@@ -300,151 +357,101 @@ Parameters:
 
 Returns: Mean absolute percentage error (fractional form).
 
-### computeMeanSquaredLogarithmicError
+### computeMeanSquaredError
 
 ```ts
-computeMeanSquaredLogarithmicError(
+computeMeanSquaredError(
   targets: number[],
   outputs: number[],
 ): number
 ```
 
-Computes mean squared logarithmic error between targets and outputs.
+Computes mean squared error between targets and outputs.
 
 Parameters:
-- `targets` - - Desired non-negative target values.
-- `outputs` - - Model outputs (expected non-negative).
+- `targets` - - Desired target values.
+- `outputs` - - Model outputs.
 
-Returns: Mean squared logarithmic error.
+Returns: Mean squared error.
 
-### computeHingeLoss
+### computeMeanSquaredLogarithmicError
 
 ```ts
-computeHingeLoss(
+computeMeanSquaredLogarithmicError(
   targets: number[],
   outputs: number[],
 ): number
 ```
 
-Computes hinge loss for margin-based classification.
+Computes mean squared logarithmic error between targets and outputs.
 
 Parameters:
-- `targets` - - Target labels encoded as -1 or 1.
-- `outputs` - - Model outputs (raw scores).
+- `targets` - - Desired non-negative target values.
+- `outputs` - - Model outputs (expected non-negative).
 
-Returns: Mean hinge loss.
+Returns: Mean squared logarithmic error.
 
-### computeFocalLoss
+### computeSoftmaxCrossEntropy
 
 ```ts
-computeFocalLoss(
+computeSoftmaxCrossEntropy(
   targets: number[],
   outputs: number[],
-  gamma: number,
-  alpha: number,
 ): number
 ```
 
-Computes focal loss for imbalanced classification tasks.
+Computes the softmax cross entropy given targets and raw score outputs.
 
 Parameters:
-- `targets` - - Target labels (0 or 1) or soft labels.
-- `outputs` - - Predicted probabilities.
-- `gamma` - - Focusing parameter controlling hard example emphasis.
-- `alpha` - - Balancing parameter for class weighting.
+- `targets` - - Desired target probabilities that should sum to 1 (will be normalized if not).
+- `outputs` - - Raw logits or scores for each class.
 
-Returns: Mean focal loss.
+Returns: Total (non-averaged) softmax cross-entropy loss.
 
-### computeLabelSmoothingLoss
+### crossEntropyTerm
 
 ```ts
-computeLabelSmoothingLoss(
-  targets: number[],
-  outputs: number[],
-  smoothing: number,
+crossEntropyTerm(
+  targetProbability: number,
+  clampedProbability: number,
 ): number
 ```
 
-Computes cross entropy with label smoothing applied to targets.
+Computes the cross-entropy contribution for a single target/output pair.
 
 Parameters:
-- `targets` - - Target labels (0 or 1) or soft labels.
-- `outputs` - - Predicted probabilities.
-- `smoothing` - - Smoothing factor between 0 and 1.
-
-Returns: Mean cross-entropy loss with smoothed targets.
-
-### LENGTH_MISMATCH_MESSAGE
-
-Error message thrown when target and output arrays differ in length.
-
-### POSITIVE_CLASS_LABEL
-
-Canonical positive label used by binary-oriented helpers.
-
-### NEGATIVE_CLASS_LABEL
-
-Canonical negative label used by binary-oriented helpers.
-
-### BINARY_CLASSIFICATION_THRESHOLD
+- `targetProbability` - - Target probability for the sample (may be soft).
+- `clampedProbability` - - Output probability already clamped for stability.
 
-Threshold for binarizing probabilities into class predictions.
+Returns: Cross-entropy term for the sample.
 
-### HINGE_MARGIN
+### DEFAULT_FOCAL_ALPHA
 
-Margin enforced by hinge loss.
+Default class balancing parameter for focal loss.
 
 ### DEFAULT_FOCAL_GAMMA
 
 Default focusing parameter for focal loss.
 
-### DEFAULT_FOCAL_ALPHA
-
-Default class balancing parameter for focal loss.
-
 ### DEFAULT_LABEL_SMOOTHING
 
 Default smoothing factor for label smoothing.
 
-### LABEL_SMOOTHING_BASELINE
-
-Baseline probability used when smoothing targets.
-
-### SOFTMAX_SUM_GUARD
-
-Lower bound for softmax denominator to avoid division by zero.
-
-### clampProbability
-
-```ts
-clampProbability(
-  probability: number,
-): number
-```
-
-Clamps a probability into the inclusive bounds defined by PROBABILITY_LOWER_BOUND and PROBABILITY_UPPER_BOUND.
+### HINGE_MARGIN
 
-Parameters:
-- `probability` - - Raw probability value to bound.
+Margin enforced by hinge loss.
 
-Returns: Probability constrained to the numeric stability range.
+### LABEL_SMOOTHING_BASELINE
 
-### crossEntropyTerm
+Baseline probability used when smoothing targets.
 
-```ts
-crossEntropyTerm(
-  targetProbability: number,
-  clampedProbability: number,
-): number
-```
+### LENGTH_MISMATCH_MESSAGE
 
-Computes the cross-entropy contribution for a single target/output pair.
+Error message thrown when target and output arrays differ in length.
 
-Parameters:
-- `targetProbability` - - Target probability for the sample (may be soft).
-- `clampedProbability` - - Output probability already clamped for stability.
+### NEGATIVE_CLASS_LABEL
 
-Returns: Cross-entropy term for the sample.
+Canonical negative label used by binary-oriented helpers.
 
 ### normalizeTargets
 
@@ -461,35 +468,9 @@ Parameters:
 
 Returns: Normalized target probabilities; returns a shallow copy when the sum is zero.
 
-### stableSoftmax
-
-```ts
-stableSoftmax(
-  outputs: number[],
-): number[]
-```
-
-Computes a numerically stable softmax from raw output scores.
-
-Parameters:
-- `outputs` - - Raw logits or scores.
-
-Returns: Softmax probabilities corresponding to the inputs.
-
-### classifyBinary
-
-```ts
-classifyBinary(
-  probability: number,
-): number
-```
-
-Converts a probability into a binary class label using the configured threshold.
-
-Parameters:
-- `probability` - - Probability to classify.
+### POSITIVE_CLASS_LABEL
 
-Returns: POSITIVE_CLASS_LABEL when above or equal to threshold; otherwise NEGATIVE_CLASS_LABEL.
+Canonical positive label used by binary-oriented helpers.
 
 ### smoothTarget
 
@@ -507,3 +488,22 @@ Parameters:
 - `smoothing` - - Smoothing factor between 0 and 1.
 
 Returns: Smoothed target probability.
+
+### SOFTMAX_SUM_GUARD
+
+Lower bound for softmax denominator to avoid division by zero.
+
+### stableSoftmax
+
+```ts
+stableSoftmax(
+  outputs: number[],
+): number[]
+```
+
+Computes a numerically stable softmax from raw output scores.
+
+Parameters:
+- `outputs` - - Raw logits or scores.
+
+Returns: Softmax probabilities corresponding to the inputs.

package/src/methods/rate/README.md

@@ -271,32 +271,41 @@ Returns: A function that calculates the decayed learning rate for a given iterat
 Learning rate schedule signature that maps a base rate and iteration index to a rate value.
 Useful for each stateless schedule strategy.
 
-### createFixedRateSchedule
+### createCosineAnnealingRateSchedule
 
 ```ts
-createFixedRateSchedule(): RateSchedule
+createCosineAnnealingRateSchedule(
+  period: number,
+  minimumRate: number,
+): RateSchedule
 ```
 
-Returns a schedule that always yields the base learning rate.
+Returns a cosine annealing learning rate schedule.
 
-Returns: A learning rate schedule that ignores iteration and returns baseRate.
+Parameters:
+- `period` - Length of a full cosine cycle.
+- `minimumRate` - Minimum rate reached at the end of a cycle.
 
-### createStepRateSchedule
+Returns: A learning rate schedule implementing cosine annealing.
+
+### createCosineAnnealingWarmRestartsSchedule
 
 ```ts
-createStepRateSchedule(
-  decayFactor: number,
-  decayStepSize: number,
+createCosineAnnealingWarmRestartsSchedule(
+  initialPeriod: number,
+  minimumRate: number,
+  periodGrowthMultiplier: number,
 ): RateSchedule
 ```
 
-Returns a step decay learning rate schedule.
+Returns a cosine annealing schedule with warm restarts and growing cycles.
 
 Parameters:
-- `decayFactor` - Multiplicative decay applied at each decay step.
-- `decayStepSize` - Number of iterations before applying another decay step.
+- `initialPeriod` - Length of the initial cycle.
+- `minimumRate` - Minimum learning rate reached at the end of each cycle.
+- `periodGrowthMultiplier` - Multiplier applied to the period after each restart.
 
-Returns: A learning rate schedule implementing step decay.
+Returns: A learning rate schedule implementing SGDR-style warm restarts.
 
 ### createExponentialRateSchedule
 
@@ -313,6 +322,16 @@ Parameters:
 
 Returns: A learning rate schedule implementing exponential decay.
 
+### createFixedRateSchedule
+
+```ts
+createFixedRateSchedule(): RateSchedule
+```
+
+Returns a schedule that always yields the base learning rate.
+
+Returns: A learning rate schedule that ignores iteration and returns baseRate.
+
 ### createInverseRateSchedule
 
 ```ts
@@ -330,42 +349,6 @@ Parameters:
 
 Returns: A learning rate schedule implementing inverse decay.
 
-### createCosineAnnealingRateSchedule
-
-```ts
-createCosineAnnealingRateSchedule(
-  period: number,
-  minimumRate: number,
-): RateSchedule
-```
-
-Returns a cosine annealing learning rate schedule.
-
-Parameters:
-- `period` - Length of a full cosine cycle.
-- `minimumRate` - Minimum rate reached at the end of a cycle.
-
-Returns: A learning rate schedule implementing cosine annealing.
-
-### createCosineAnnealingWarmRestartsSchedule
-
-```ts
-createCosineAnnealingWarmRestartsSchedule(
-  initialPeriod: number,
-  minimumRate: number,
-  periodGrowthMultiplier: number,
-): RateSchedule
-```
-
-Returns a cosine annealing schedule with warm restarts and growing cycles.
-
-Parameters:
-- `initialPeriod` - Length of the initial cycle.
-- `minimumRate` - Minimum learning rate reached at the end of each cycle.
-- `periodGrowthMultiplier` - Multiplier applied to the period after each restart.
-
-Returns: A learning rate schedule implementing SGDR-style warm restarts.
-
 ### createLinearWarmupDecaySchedule
 
 ```ts
@@ -400,34 +383,26 @@ Parameters:
 
 Returns: A stateful schedule that reacts to lack of improvement.
 
-### RateSchedule
+### createStepRateSchedule
 
 ```ts
-RateSchedule(
-  baseRate: number,
-  iteration: number,
-): number
+createStepRateSchedule(
+  decayFactor: number,
+  decayStepSize: number,
+): RateSchedule
 ```
 
-Learning rate schedule signature that maps a base rate and iteration index to a rate value.
-Useful for each stateless schedule strategy.
-
-### ReduceOnPlateauSchedule
+Returns a step decay learning rate schedule.
 
-```ts
-ReduceOnPlateauSchedule(
-  baseRate: number,
-  iteration: number,
-  lastError: number | undefined,
-): number
-```
+Parameters:
+- `decayFactor` - Multiplicative decay applied at each decay step.
+- `decayStepSize` - Number of iterations before applying another decay step.
 
-Stateful ReduceLROnPlateau schedule signature that can react to a loss signal.
-The third argument is optional and only needed when monitoring validation error.
+Returns: A learning rate schedule implementing step decay.
 
-### DEFAULT_STEP_DECAY_FACTOR
+### DEFAULT_COSINE_PERIOD
 
-Step decay multiplier (close to 1 slows decay; smaller drops faster).
+Length of one cosine annealing cycle in iterations.
 
 ### DEFAULT_DECAY_STEP_SIZE
 
@@ -437,6 +412,10 @@ Step decay interval in iterations; larger values mean fewer decay events.
 
 Per-iteration exponential decay factor; values just below 1 create gentle decay.
 
+### DEFAULT_INITIAL_PERIOD
+
+Initial period length for cosine-with-restarts before growth is applied.
+
 ### DEFAULT_INVERSE_DECAY_FACTOR
 
 Inverse decay multiplier; higher values push the denominator up faster and shrink the rate sooner.
@@ -445,46 +424,67 @@ Inverse decay multiplier; higher values push the denominator up faster and shrin
 
 Inverse decay exponent; 1 makes decay linear in iteration, 2 makes it quadratic.
 
-### DEFAULT_COSINE_PERIOD
+### DEFAULT_LINEAR_END_RATE
 
-Length of one cosine annealing cycle in iterations.
+Target rate after warmup-decay finishes; often zero or a small floor.
 
 ### DEFAULT_MINIMUM_RATE
 
 Floor learning rate for cosine schedules; keeps the rate from reaching zero.
 
-### DEFAULT_INITIAL_PERIOD
-
-Initial period length for cosine-with-restarts before growth is applied.
-
 ### DEFAULT_PERIOD_GROWTH_MULTIPLIER
 
 Multiplier applied to the cosine cycle length after each restart (>= 1).
 
-### DEFAULT_LINEAR_END_RATE
-
-Target rate after warmup-decay finishes; often zero or a small floor.
-
-### DEFAULT_WARMUP_RATIO
+### DEFAULT_REDUCE_ON_PLATEAU_COOLDOWN
 
-Default warmup share of the schedule; 0.1 means 10% of total steps.
+Cooldown iterations after a reduction to avoid rapid successive cuts.
 
 ### DEFAULT_REDUCE_ON_PLATEAU_FACTOR
 
 Reduce-on-plateau shrink factor; halving (0.5) is a common conservative step.
 
+### DEFAULT_REDUCE_ON_PLATEAU_MIN_DELTA
+
+Minimum required improvement to count as progress when monitoring error.
+
+### DEFAULT_REDUCE_ON_PLATEAU_MIN_RATE
+
+Minimum rate allowed during reduce-on-plateau adjustments.
+
 ### DEFAULT_REDUCE_ON_PLATEAU_PATIENCE
 
 Patience for reduce-on-plateau in iterations before triggering a cut.
 
-### DEFAULT_REDUCE_ON_PLATEAU_MIN_DELTA
+### DEFAULT_STEP_DECAY_FACTOR
 
-Minimum required improvement to count as progress when monitoring error.
+Step decay multiplier (close to 1 slows decay; smaller drops faster).
 
-### DEFAULT_REDUCE_ON_PLATEAU_COOLDOWN
+### DEFAULT_WARMUP_RATIO
 
-Cooldown iterations after a reduction to avoid rapid successive cuts.
+Default warmup share of the schedule; 0.1 means 10% of total steps.
 
-### DEFAULT_REDUCE_ON_PLATEAU_MIN_RATE
+### RateSchedule
 
-Minimum rate allowed during reduce-on-plateau adjustments.
+```ts
+RateSchedule(
+  baseRate: number,
+  iteration: number,
+): number
+```
+
+Learning rate schedule signature that maps a base rate and iteration index to a rate value.
+Useful for each stateless schedule strategy.
+
+### ReduceOnPlateauSchedule
+
+```ts
+ReduceOnPlateauSchedule(
+  baseRate: number,
+  iteration: number,
+  lastError: number | undefined,
+): number
+```
+
+Stateful ReduceLROnPlateau schedule signature that can react to a loss signal.
+The third argument is optional and only needed when monitoring validation error.