[WIP] distribution classes

doc/api.rst

@@ -6,14 +6,32 @@ API Documentation
 
 .. currentmodule:: pyglmnet
 
-Classes
-=======
+GLM Classes
+===========
 
-.. autoclass:: GLM
-   :members:
+.. currentmodule:: pyglmnet
+
+.. autosummary::
+   :toctree: generated/
+
+   GLM
+   GLMCV
+
+Distribution Classes
+====================
+
+.. currentmodule:: pyglmnet.distributions
+
+.. autosummary::
+   :toctree: generated/
 
-.. autoclass:: GLMCV
-  :members:
+   BaseDistribution
+   Poisson
+   PoissonSoftplus
+   NegBinomialSoftplus
+   Binomial
+   Probit
+   GammaSoftplus
 
 
 Datasets

examples/plot_custom_distributions.py

@@ -0,0 +1,76 @@
+"""
+======================
+Rolling out custom GLM
+======================
+
+This is an example demonstrating rolling out your custom
+GLM class using Pyglmnet.
+"""
+########################################################
+
+# Author: Pavan Ramkumar <[email protected]>
+# License: MIT
+
+from sklearn.model_selection import train_test_split
+from pyglmnet import GLMCV, datasets
+
+########################################################
+# Download and preprocess data files
+
+X, y = datasets.fetch_community_crime_data()
+n_samples, n_features = X.shape
+
+########################################################
+# Split the data into training and test sets
+
+X_train, X_test, y_train, y_test = \
+    train_test_split(X, y, test_size=0.33, random_state=0)
+
+########################################################
+# Now we define our own distribution class. This must
+# inherit from BaseDistribution. The BaseDistribution
+# class requires defining the following methods:
+#   - mu: inverse link function
+#   - grad_mu: gradient of the inverse link function
+#   - log_likelihood: the log likelihood function
+#   - grad_log_likelihood: the gradient of the log
+#     likelihood.
+# All distributions in pyglmnet inherit from BaseDistribution
+#
+# This is really powerful. For instance, we can start from
+# the existing Binomial distribution and override mu and grad_mu
+# if we want to use the cloglog link function.
+
+import numpy as np  # noqa: E402
+from pyglmnet.distributions import Binomial  # noqa: E402
+
+
+class CustomBinomial(Binomial):
+    """Custom binomial distribution."""
+
+    def mu(self, z):
+        """clogclog inverse link"""
+        mu = 1 - np.exp(-np.exp(z))
+        return mu
+
+    def grad_mu(self, z):
+        """Gradient of inverse link."""
+        grad_mu = np.exp(1 - np.exp(z))
+        return grad_mu
+
+
+distr = CustomBinomial()
+
+########################################################
+# Now we pass it to the GLMCV class just as before.
+
+# use the default value for reg_lambda
+glm = GLMCV(distr=distr, alpha=0.05, score_metric='pseudo_R2', cv=3,
+            tol=1e-4)
+
+# fit model
+glm.fit(X_train, y_train)
+
+# score the test set prediction
+y_test_hat = glm.predict_proba(X_test)
+print("test set pseudo $R^2$ = %f" % glm.score(X_test, y_test))

pyglmnet/__init__.py

@@ -19,7 +19,7 @@
 __version__ = '1.2.dev0'
 
 
-from .pyglmnet import GLM, GLMCV, _grad_L2loss, _L2loss, simulate_glm, _gradhess_logloss_1d, _loss, ALLOWED_DISTRS
+from .pyglmnet import GLM, GLMCV, _grad_L2loss, _L2loss, simulate_glm, _loss, ALLOWED_DISTRS
 from .utils import softmax, label_binarizer, set_log_level
 from .datasets import fetch_tikhonov_data, fetch_rgc_spike_trains, fetch_community_crime_data, fetch_group_lasso_data
 from . import externals