[GitHub] [madlib] orhankislal commented on a change in pull request #406: user docs for madlib-keras deep learning

[GitBox <gi...@apache.org>]

orhankislal commented on a change in pull request #406: user docs for madlib-keras deep learning
URL: https://github.com/apache/madlib/pull/406#discussion_r291614169
 
 

 ##########
 File path: src/ports/postgres/modules/deep_learning/madlib_keras.sql_in
 ##########
 @@ -28,6 +28,1355 @@
 
 m4_include(`SQLCommon.m4')
 
+/**
+@addtogroup grp_keras
+
+<div class="toc"><b>Contents</b><ul>
+<li class="level1"><a href="#keras_fit">Fit</a></li>
+<li class="level1"><a href="#keras_evaluate">Evaluate</a></li>
+<li class="level1"><a href="#keras_predict">Predict</a></li>
+<li class="level1"><a href="#example">Examples</a></li>
+<li class="level1"><a href="#notes">Notes</a></li>
+<li class="level1"><a href="#background">Technical Background</a></li>
+<li class="level1"><a href="#literature">Literature</a></li>
+<li class="level1"><a href="#related">Related Topics</a></li>
+</ul></div>
+
+\warning <em> This MADlib method is still in early stage development.
+Interface and implementation are subject to change. </em>
+
+This module allows you to use SQL to call deep learning
+models designed in Keras [1], which is a high-level neural
+network API written in Python.
+Keras was developed for fast experimentation.  It can run
+on top of different backends and the one that is currently
+supported by MADlib is TensorFlow [2].  The implementation
+in MADlib is distributed and designed to train
+a single large model across multiple segments (workers)
+in a Greenplum database.
+
+The main use case is image classification
+using sequential models, which are made up of a
+linear stack of layers.  This includes multilayer perceptrons (MLPs)
+and convolutional neural networks (CNNs).  Regression is not
+currently supported.
+
+Before using Keras in MADlib you will need to mini-batch
+your training and evaluation datasets by calling the
+<a href="group__grp__input__preprocessor__dl.html">Preprocessor
+for Images</a> which is a utility that prepares image data for
+use by models that support mini-batch as an optimization option.
+This is a one-time operation and you would only
+need to re-run the preprocessor if your input data has changed.
+The advantage of using mini-batching is that it
+can perform better than stochastic gradient descent
+because it uses more than one training example at a time,
+typically resulting faster and smoother convergence [3].
+
+@brief Solves image classification problems by calling
+the Keras API
+
+@anchor keras_fit
+@par Fit
+The fit (training) function has the following format:
+
+<pre class="syntax">
+madlib_keras_fit(
+    source_table,
+    model,
+    model_arch_table,
+    model_arch_id,
+    compile_params,
+    fit_params,
+    num_iterations,
+    gpus_per_host,
+    validation_table,
+    metrics_compute_frequency,
+    warm_start,
+    name,
+    description
+    )
+</pre>
+
+\b Arguments
+<dl class="arglist">
+  <dt>source_table</dt>
+  <dd>TEXT. Name of the table containing the training data.
+  This is the name of the output
+  table from the image preprocessor.  Independent
+  and dependent variables are specified in the preprocessor
+  step which is why you do not need to explictly state
+  them here as part of the fit function.</dd>
+
+  <dt>model</dt>
+  <dd>TEXT. Name of the output table containing the model.
+  Details of the output table are shown below.
+  </dd>
+
+  <dt>model_arch_table</dt>
+  <dd>TEXT. Name of the table containing the model
+  architecture and (optionally) initial weights to use for
+  training.
+  </dd>
+
+  <dt>model_arch_id</dt>
+  <dd>INTEGER. This is the id in 'model_arch_table'
+  containing the model architecture and (optionally)
+  initial weights to use for training.
+  </dd>
+
+  <DT>compile_params</DT>
+  <DD>TEXT.
+    Parameters passed to the compile method of the Keras
+    model class [4].  These parameters will be passed through as is
+    so they must conform to the Keras API definition.
+    As an example, you might use something like: <em>loss='categorical_crossentropy', optimizer='adam', metrics=['acc']</em>.
+    The mandatory parameters that must be specified are 'optimizer'
+    and 'loss'.  Others are optional and will use the default
+    values as per Keras if not specified here.  Also, when
+    specifying 'loss' and 'metrics' do <em>not</em> include the
+    module and submodule prefixes
+    like <em>loss='losses.categorical_crossentropy'</em>
+    or <em>optimizer='keras.optmizers.adam'</em>.
+
+    @note
+    The following loss function is
+    not supported: <em>sparse_categorical_crossentropy</em>.
+    The following metrics are not
+    supported: <em>sparse_categorical_accuracy, top_k_categorical_accuracy, sparse_top_k_categorical_accuracy</em> and custom metrics.
+
+  </DD>
+
+  <DT>fit_params </DT>
+  <DD>TEXT.  Parameters passed to the fit method of the Keras
+    model class [4].  These will be passed through as is
+    so must conform to the Keras API definition.
 
 Review comment:
   so must -> so they must

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services