@elaraai/east-py-datascience 1.0.1 → 1.0.2

package/dist/src/ngboost/ngboost.js

@@ -0,0 +1,231 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * NGBoost platform functions for East.
+ *
+ * Provides probabilistic predictions with natural gradient boosting.
+ * Returns mean, standard deviation, and confidence intervals.
+ * Uses cloudpickle for model serialization.
+ *
+ * @packageDocumentation
+ */
+import { East, StructType, VariantType, OptionType, IntegerType, FloatType, BlobType, NullType, } from "@elaraai/east";
+import { VectorType, MatrixType } from "../types.js";
+// Re-export shared types for convenience
+export { VectorType, MatrixType } from "../types.js";
+// ============================================================================
+// Enum Types
+// ============================================================================
+/**
+ * Distribution type for NGBoost.
+ */
+export const NGBoostDistributionType = VariantType({
+    /** Normal (Gaussian) distribution */
+    normal: NullType,
+    /** Log-normal distribution (for positive targets) */
+    lognormal: NullType,
+});
+// ============================================================================
+// Config Types
+// ============================================================================
+/**
+ * Configuration for NGBoost models.
+ */
+export const NGBoostConfigType = StructType({
+    /** Number of boosting rounds (default 500) */
+    n_estimators: OptionType(IntegerType),
+    /** Learning rate / step size shrinkage (default 0.01) */
+    learning_rate: OptionType(FloatType),
+    /** Fraction of samples to use in each iteration (default 1.0) */
+    minibatch_frac: OptionType(FloatType),
+    /** Fraction of features to use in each iteration (default 1.0) */
+    col_sample: OptionType(FloatType),
+    /** Random seed for reproducibility */
+    random_state: OptionType(IntegerType),
+    /** Distribution type (default normal) */
+    distribution: OptionType(NGBoostDistributionType),
+});
+/**
+ * Configuration for NGBoost predictions with uncertainty.
+ */
+export const NGBoostPredictConfigType = StructType({
+    /** Confidence level for intervals (default 0.95) */
+    confidence_level: OptionType(FloatType),
+});
+// ============================================================================
+// Result Types
+// ============================================================================
+/**
+ * Result type for probabilistic predictions.
+ */
+export const NGBoostPredictResultType = StructType({
+    /** Point predictions (mean) */
+    predictions: VectorType(FloatType),
+    /** Standard deviation */
+    std: OptionType(VectorType(FloatType)),
+    /** Lower confidence interval */
+    lower: OptionType(VectorType(FloatType)),
+    /** Upper confidence interval */
+    upper: OptionType(VectorType(FloatType)),
+});
+// ============================================================================
+// Model Blob Types
+// ============================================================================
+/**
+ * Model blob type for serialized NGBoost models.
+ */
+export const NGBoostModelBlobType = VariantType({
+    /** NGBoost regressor model */
+    ngboost_regressor: StructType({
+        /** Cloudpickle serialized model */
+        data: BlobType,
+        /** Distribution type used */
+        distribution: NGBoostDistributionType,
+        /** Number of input features */
+        n_features: IntegerType,
+    }),
+});
+// ============================================================================
+// Platform Functions
+// ============================================================================
+/**
+ * Train an NGBoost regression model with probabilistic output.
+ *
+ * @param X - Feature matrix
+ * @param y - Target vector
+ * @param config - NGBoost configuration
+ * @returns Model blob containing trained regressor
+ */
+export const ngboost_train_regressor = East.platform("ngboost_train_regressor", [MatrixType(FloatType), VectorType(FloatType), NGBoostConfigType], NGBoostModelBlobType);
+/**
+ * Make point predictions (mean) with a trained NGBoost regressor.
+ *
+ * @param model - Trained regressor model blob
+ * @param X - Feature matrix
+ * @returns Predicted values (mean of predictive distribution)
+ */
+export const ngboost_predict = East.platform("ngboost_predict", [NGBoostModelBlobType, MatrixType(FloatType)], VectorType(FloatType));
+/**
+ * Get predictions with full uncertainty from NGBoost regressor.
+ *
+ * Returns mean, standard deviation, and confidence intervals.
+ *
+ * @param model - Trained regressor model blob
+ * @param X - Feature matrix
+ * @param config - Prediction configuration (confidence level)
+ * @returns Predictions with uncertainty estimates
+ */
+export const ngboost_predict_dist = East.platform("ngboost_predict_dist", [NGBoostModelBlobType, MatrixType(FloatType), NGBoostPredictConfigType], NGBoostPredictResultType);
+// ============================================================================
+// Grouped Export
+// ============================================================================
+/**
+ * Type definitions for NGBoost functions.
+ */
+export const NGBoostTypes = {
+    /** Distribution type for NGBoost */
+    NGBoostDistributionType,
+    /** NGBoost configuration type */
+    NGBoostConfigType,
+    /** Prediction configuration type */
+    NGBoostPredictConfigType,
+    /** Prediction result type */
+    NGBoostPredictResultType,
+    /** Model blob type for NGBoost models */
+    ModelBlobType: NGBoostModelBlobType,
+};
+/**
+ * NGBoost probabilistic gradient boosting.
+ *
+ * Provides regression with uncertainty quantification using natural gradient boosting.
+ *
+ * @example
+ * ```ts
+ * import { East, variant } from "@elaraai/east";
+ * import { NGBoost } from "@elaraai/east-py-datascience";
+ *
+ * const train = East.function([], NGBoost.Types.ModelBlobType, $ => {
+ *     const X = $.let([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0], [7.0, 8.0]]);
+ *     const y = $.let([1.0, 2.0, 3.0, 4.0]);
+ *     const config = $.let({
+ *         n_estimators: variant('some', 100n),
+ *         learning_rate: variant('some', 0.01),
+ *         minibatch_frac: variant('none', null),
+ *         col_sample: variant('none', null),
+ *         random_state: variant('some', 42n),
+ *         distribution: variant('none', null),
+ *     });
+ *     return $.return(NGBoost.trainRegressor(X, y, config));
+ * });
+ * ```
+ */
+export const NGBoost = {
+    /**
+     * Train an NGBoost regression model with probabilistic output.
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType, MatrixType, VectorType, variant } from "@elaraai/east";
+     * import { NGBoost, NGBoostConfigType } from "@elaraai/east-py-datascience";
+     *
+     * const train = East.function([], NGBoost.Types.ModelBlobType, ($) => {
+     *     const X = $.let([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0], [7.0, 8.0]]);
+     *     const y = $.let(new Float64Array([1.0, 2.0, 3.0, 4.0]));
+     *     const config = $.let({
+     *         n_estimators: variant("some", 100n), learning_rate: variant("some", 0.01),
+     *         minibatch_frac: variant("none", null), col_sample: variant("none", null),
+     *         random_state: variant("some", 42n), distribution: variant("none", null),
+     *     }, NGBoostConfigType);
+     *     return $.return(NGBoost.trainRegressor(X, y, config));
+     * });
+     * ```
+     */
+    trainRegressor: ngboost_train_regressor,
+    /**
+     * Make point predictions with a trained NGBoost regressor.
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType, MatrixType, VectorType } from "@elaraai/east";
+     * import { NGBoost } from "@elaraai/east-py-datascience";
+     *
+     * const predictFn = East.function(
+     *     [NGBoost.Types.ModelBlobType, MatrixType(FloatType)],
+     *     VectorType(FloatType),
+     *     ($, model, X) => {
+     *         return $.return(NGBoost.predict(model, X));
+     *     }
+     * );
+     * ```
+     */
+    predict: ngboost_predict,
+    /**
+     * Get predictions with uncertainty estimates (confidence intervals, std).
+     *
+     * @example
+     * ```ts
+     * import { East, FloatType, MatrixType, variant } from "@elaraai/east";
+     * import { NGBoost, NGBoostPredictConfigType } from "@elaraai/east-py-datascience";
+     *
+     * const predictFn = East.function(
+     *     [NGBoost.Types.ModelBlobType, MatrixType(FloatType)],
+     *     NGBoost.Types.NGBoostPredictResultType,
+     *     ($, model, X) => {
+     *         const config = $.let({
+     *             confidence_level: variant("some", 0.95),
+     *         }, NGBoostPredictConfigType);
+     *         const result = $.let(NGBoost.predictDist(model, X, config));
+     *         // result.predictions => point predictions
+     *         // result.lower, result.upper => confidence interval
+     *         return $.return(result);
+     *     }
+     * );
+     * ```
+     */
+    predictDist: ngboost_predict_dist,
+    /** Type definitions */
+    Types: NGBoostTypes,
+};
+//# sourceMappingURL=ngboost.js.map

package/dist/src/ngboost/ngboost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngboost.js","sourceRoot":"","sources":["../../../src/ngboost/ngboost.ts"],"names":[],"mappings":"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"}