Merge branch 'develop'

CHANGELOG.md

@@ -6,6 +6,21 @@ Most recent releases are shown at the top. Each release shows:
 - **Changed**: Additional parameters, changes to inputs or outputs, etc
 - **Fixed**: Bug fixes that don't change documented behaviour
 
+## 0.18.2 (2020-07-08)
+
+### New:
+- N/A
+
+### Changed
+- updated doc comments in core module
+- removed unused `nosave` parameter from `reset_weights`
+- added warning about obsolete `show_wd` parameter in `print_layers` method
+- pin to `scipy==1.4.1` due to TensorFlow requirement
+
+### Fixed:
+- N/A
+
+
 ## 0.18.1 (2020-07-07)
 
 ### New:

README.md

@@ -8,7 +8,8 @@
 
 ### News and Announcements
 - **2020-07-07:**  
-  - ***ktrain*** **v0.18.x is released** and now includes support for TensorFlow 2.2.0.  TensorFlow 2.1.0 will be used when possible (e.g., on Python 3.6/3.7 systems) due to TF 2.2.0 issues.
+  - ***ktrain*** **v0.18.x is released** and now includes support for TensorFlow 2.2.0. Due to various TensorFlow 2.2.0 bugs, TF 2.2.0 is only installed if Python 3.8 is being used. 
+    Otherwise,  TensorFlow 2.1.0 is always installed (i.e., on Python 3.6 and 3.7 systems).
 - **2020-06-26:**  
   - ***ktrain*** **v0.17.x is released** and includes support for **language translation**. See the [example language translation notebook](https://nbviewer.jupyter.org/github/amaiya/ktrain/blob/develop/examples/text/language_translation_example.ipynb) for more information.  <sub><sup>(This feature currently requires that PyTorch be installed.)</sup></sub>
 ```python
@@ -284,17 +285,16 @@ Using *ktrain* on **Google Colab**?  See these Colab examples:
 
 ### Installation
 
-*ktrain* currently uses [TensorFlow 2.1.0 and 2.2.0](https://www.tensorflow.org/install/pip?lang=python3), which will be installed automatically when installing *ktrain*. 
-TensorFlow 2.1.0 will be installed as dependency on Python 3.6 and 3.7 systems.  TensorFlow 2.2.0 will be installed only if using Python 3.8.
-While *ktrain* will probably work with other versions of TensorFlow 2.x, v2.1.0 is the current recommended and tested versions.
+*ktrain* currently uses [TensorFlow 2.1.0 or 2.2.0](https://www.tensorflow.org/install/pip?lang=python3), which will be installed automatically when installing *ktrain*. 
+TensorFlow 2.1.0 will be installed as a dependency on Python 3.6 and 3.7 systems.  TensorFlow 2.2.0 will be installed only if using Python 3.8 (as TF 2.1.0 does not support Python 3.8).
+ On systems where Python 3.8 is the default (e.g., Ubuntu 20.04), we strongly recommend installing and using Python 3.6/3.7 and TensorFlow 2.1.0 with *ktrain* due to problems that currently exist 
+in versions of TensorFlow >= 2.2.0.
 
 1.  Make sure pip is up-to-date with: `pip3 install -U pip`
 
 2. Install *ktrain*: `pip3 install ktrain`
 
 **Some things to note:**
-- *ktrain* will automatically install TensorFlow 2.1.0 as a dependency on Python 3.6/3.7 systems and only use TensorFlow 2.2.0 on Python 3.8 systems. This is due
-  to a number of issues in TensorFlow 2.2.0. TensorFlow 2.2.0 is only installed if using Python 3.8 because it is the only version that supports Python 3.8.
 - Since some *ktrain* dependencies have not yet been migrated to `tf.keras` in TensorFlow 2 (or may have other issues), 
   *ktrain* is temporarily using forked versions of some libraries. Specifically, *ktrain* uses forked versions of the `eli5` and `stellargraph` libraries.  If not installed, *ktrain* will complain  when a method or function needing 
   either of these libraries is invoked.

ktrain/core.py

@@ -68,7 +68,15 @@ def set_weight_decay(self, wd=U.DEFAULT_WD):
 
     def evaluate(self, test_data=None, print_report=True, class_names=[]):
         """
-        alias for self.validate()
+        alias for self.validate().
+        Returns confusion matrix and optionally prints
+        a classification report.
+        This is currently only supported for binary and multiclass
+        classification, not multilabel classification.
+
+        By default, this uses val_data, as supplied to ktrain.get_learner().
+        Other validation or test data can be optionally be supplied as argument via <test_data> argument.
+        Supply class_names to include labels instead of intenger class integer values in classification report.
         """
         return self.validate(val_data=test_data, print_report=print_report, class_names=class_names)
 
@@ -83,6 +91,7 @@ def validate(self, val_data=None, print_report=True, class_names=[]):
 
         By default, this uses val_data, as supplied to ktrain.get_learner().
         Other validation or test data can be optionally be supplied as argument.
+        Supply class_names to include labels instead of intenger class integer values in classification report.
         """
         if val_data is not None:
             val = val_data
@@ -230,7 +239,7 @@ def top_losses(self, n=4, val_data=None, preproc=None):
 
     def view_top_losses(self, n=4, preproc=None, val_data=None):
         """
-        Views observations with top losses in validation set.
+        View observations with top losses in validation set.
         Musta be overridden by Learner subclasses.
         """
         raise NotImplementedError('view_top_losses must be overriden by Learner subclass')
@@ -250,6 +259,10 @@ def _make_model_folder(self, fpath):
     def save_model(self, fpath):
         """
         a wrapper to model.save
+        Args:
+          fpath(str): path to folder in which to save model
+        Returns:
+          None
         """
         self._make_model_folder(fpath)
         self.model.save(os.path.join(fpath, U.MODEL_NAME), save_format='h5')
@@ -258,7 +271,7 @@ def save_model(self, fpath):
 
     def load_model(self, fpath, custom_objects=None, **kwargs):
         """
-        loads model from file path to folder.
+        loads model from folder.
         Note: **kwargs included for backwards compatibility only, as TransformerTextClassLearner.load_model was removed in v0.18.0.
         Args:
           fpath(str): path to folder containing model
@@ -384,23 +397,10 @@ def unfreeze(self, exclude_range=None):
         return
 
 
-    def reset_weights(self, nosave=False, verbose=1):
+    def reset_weights(self, verbose=1):
         """
-        Re-initializes network - use with caution, as this may not be robust
+        Re-initializes network with original weights
         """
-        #initial_weights = self.model.get_weights()
-        #backend_name = K.backend()
-        #if backend_name == 'tensorflow': 
-            #k_eval = lambda placeholder: placeholder.eval(session=K.get_session())
-        #elif backend_name == 'theano': 
-            #k_eval = lambda placeholder: placeholder.eval()
-        #else: 
-            #raise ValueError("Unsupported backend")
-        #new_weights = [k_eval(glorot_uniform()(w.shape)) for w in initial_weights]
-        #if nosave: return new_weights
-        #self.model.set_weights(new_weights)
-        #self.history = None
-        #print('Weights of moedl have been reset.')
 
         if os.path.isfile(self._original_weights):
             self.model.load_weights(self._original_weights)
@@ -496,7 +496,7 @@ def lr_find(self, start_lr=1e-7, lr_mult=1.01, max_epochs=None,
             return
 
         # re-load current weights
-        # 2020-0707: temporarily use load_model instead of load_weights due to https://github.com/tensorflow/tensorflow/issues/41116
+        # dep_fix: temporarily use load_model instead of load_weights due to https://github.com/tensorflow/tensorflow/issues/41116
         #self.model.load_weights(weightfile)
         self.load_model(temp_folder)
 
@@ -598,6 +598,7 @@ def print_layers(self, show_wd=False):
         """
         prints the layers of the model along with indices
         """
+        if show_wd: warnings.warn('set_weight_decay now uses AdamWeightDecay instead of kernel_regularizers.')
         for i, layer in enumerate(self.model.layers):
             if show_wd and hasattr(layer, 'kernel_regularizer'):
                 reg = layer.kernel_regularizer
@@ -1248,7 +1249,7 @@ def fit(self, lr, n_cycles, cycle_len=None, cycle_mult=1,
     def layer_output(self, layer_id, example_id=0, batch_id=0, use_val=False):
         """
         Prints output of layer with index <layer_id> to help debug models.
-        Uses first example (example_id=0) from training set, by default.
+        Uses first example (example_id=0) from first batch from training set, by default.
         """
 
         inp = self.model.layers[0].input

ktrain/version.py

@@ -1,2 +1,2 @@
 __all__ = ['__version__']
-__version__ = '0.18.1'
+__version__ = '0.18.2'

setup.py

@@ -4,7 +4,6 @@
 if sys.version_info.minor == 8:
     tf_version_str = 'tensorflow==2.2.0'
 
-
 from distutils.core import setup
 import setuptools
 
@@ -30,7 +29,7 @@
   keywords = ['tensorflow', 'keras', 'deep learning', 'machine learning'],
   install_requires=[
           tf_version_str,
-          'scipy>=1.4.1', # was previously pinned to 1.4.1 due to TF 2.1.0 issue
+          'scipy==1.4.1', # pinned to 1.4.1 due to TF 2.1.0/2.2.0 setup.py requirement
           'scikit-learn==0.21.3', # affects format of predictor.explain
           'matplotlib >= 3.0.0',
           'pandas >= 1.0.1',