Merge branch 'server_renaming'

Make "Live Test" Server usage more user-friendly

Now the user can use the Live Test tool, from code, in a much clearer
and user-friendly way by importing ``Live_Test`` and then using the
``run`` method:

>>> from pyss3.server import Live_Test
>>> Live_Test.run(...)

Instead of the old version:

>>> from pyss3.server import Server
>>> Server.serve(...)

which was somewhat misleading... Server? what does it serve? not a
single clue that this is linked to the Live Test tool...

README.md

@@ -26,7 +26,7 @@ The SS3 text classifier is a novel supervised machine learning model for text cl
 
 ## What is PySS3?
 
-[PySS3](https://github.com/sergioburdisso/pyss3) is a Python package that allows you to work with SS3 in a very straightforward, interactive and visual way. In addition to the implementation of the SS3 classifier, PySS3 comes with a set of tools to help you developing your machine learning models in a clearer and faster way. These tools let you analyze, monitor and understand your models by allowing you to see what they have actually learned and why. To achieve this, PySS3 provides you with 3  main components: the ``SS3`` class, the ``Server`` class and the ``PySS3 Command Line`` tool, as pointed out below.
+[PySS3](https://github.com/sergioburdisso/pyss3) is a Python package that allows you to work with SS3 in a very straightforward, interactive and visual way. In addition to the implementation of the SS3 classifier, PySS3 comes with a set of tools to help you developing your machine learning models in a clearer and faster way. These tools let you analyze, monitor and understand your models by allowing you to see what they have actually learned and why. To achieve this, PySS3 provides you with 3  main components: the ``SS3`` class, the ``Live_Test`` class and the ``PySS3 Command Line`` tool, as pointed out below.
 
 
 ### The `SS3` class
@@ -40,17 +40,17 @@ which implements the classifier using a clear API (very similar to that of `skle
     y_pred = clf.predict(x_test)
 ````
 
-### The `Server` class
+### The `Live_Test` class
 
 which allows you to interactively test your model and visually see the reasons behind classification decisions, **with just one line of code**:
 ```python
-    from pyss3.server import Server
+    from pyss3.server import Live_Test
     from pyss3 import SS3
 
     clf = SS3(name="my_model")
     ...
     clf.fit(x_train, y_train)
-    Server.serve(clf, x_test, y_test) # <- this one! cool uh? :)
+    Live_Test.run(clf, x_test, y_test) # <- this one! cool uh? :)
 ```
 As shown in the image below, this will open up, locally, an interactive tool in your browser which you can use to (live) test your models with the documents given in `x_test` (or typing in your own!). This will allow you to visualize and understand what your model is actually learning.
 

docs/index.rst

@@ -15,7 +15,7 @@ to help you developing your machine learning models in a clearer and
 faster way. These tools let you analyze, monitor and understand your
 models by allowing you to see what they have actually learned and why. To
 achieve this, PySS3 provides you with 3 main components: the ``SS3``
-class, the ``Server`` class and the ``PySS3 Command Line`` tool, as
+class, the ``Live_Test`` class and the ``PySS3 Command Line`` tool, as
 pointed out below.
 
 
@@ -34,21 +34,21 @@ of ``sklearn``):
         y_pred = clf.predict(x_test)
 
 
-The ``Server`` class
+The ``Live_Test`` class
 ~~~~~~~~~~~~~~~~~~~~
 
 which allows you to interactively test your model and visually see the
 reasons behind classification decisions, **with just one line of code**:
 
 .. code:: python
 
-        from pyss3.server import Server
+        from pyss3.server import Live_Test
         from pyss3 import SS3
 
         clf = SS3(name="my_model")
         ...
         clf.fit(x_train, y_train)
-        Server.serve(clf, x_test, y_test) # <- this one! cool uh? :)
+        Live_Test.run(clf, x_test, y_test) # <- this one! cool uh? :)
 
 As shown in the image below, this will open up, locally, an interactive
 tool in your browser which you can use to (live) test your models with

docs/tutorials/movie-review-notebook.rst

@@ -16,7 +16,7 @@ Before we begin, let's import needed modules...
 
     from pyss3 import SS3
     from pyss3.util import Dataset
-    from pyss3.server import Server
+    from pyss3.server import Live_Test
     
     from sklearn.metrics import accuracy_score
 
@@ -107,7 +107,7 @@ analyze what our model has actually learned by using the interactive
 
 .. code:: python
 
-    Server.serve(clf, x_test, y_test)
+    Live_Test.run(clf, x_test, y_test)
 
 Makes sense to you? (remember you can select "words" as the
 Description Level if you want to know based on what words is making
@@ -181,7 +181,7 @@ sequences of words when using the interactive "live test"
 
 .. code:: python
 
-    Server.serve(clf, x_test, y_test)
+    Live_Test.run(clf, x_test, y_test)
 
 
 .. _movie-review-notebook-continue:

docs/tutorials/topic_categorization-notebook.rst

@@ -17,7 +17,7 @@ Before we begin, let's import needed modules...
 
     from pyss3 import SS3
     from pyss3.util import Dataset
-    from pyss3.server import Server
+    from pyss3.server import Live_Test
     
     from sklearn.metrics import accuracy_score
 
@@ -109,20 +109,20 @@ Not bad using the default :ref:`hyperparameter <ss3-hyperparameter>` values... l
 manually analyze what this model has actually learned by using the
 interactive "live test". Note that since we are not going to use the
 ``x_test`` for this live test\ **(\*)** but instead the documents in
-"datasets/topic/live\_test", we must use the ``set_testset_from_files``
+``"datasets/topic/live\_test"``, we must use the ``set_testset_from_files``
 method to tell the server to load documents from there instead.
 
 **(\*)** *try it if you want but since* ``x_test`` *contains
 (preprocessed) tweets, they don't look really good and clean.*
 
 .. code:: python
 
-    # Server.serve(clf, x_test, y_test)  # <- this visualization doesn't look really clean and good so, instead,
-                                         #    we will use the documents in "live_test" folder:
+    # Live_Test.run(clf, x_test, y_test)  # <- this visualization doesn't look really clean and good so, instead,
+                                          #    we will use the documents in "live_test" folder:
     
-    Server.set_testset_from_files("datasets/topic/live_test")
+    Live_Test.set_testset_from_files("datasets/topic/live_test")
     
-    Server.serve(clf)
+    Live_Test.run(clf)
 
 
 Live test doesn't look bad, however, we will create a "more intelligent"
@@ -189,7 +189,7 @@ category). Let's see...
 
 .. code:: python
 
-    Server.serve(clf)
+    Live_Test.run(clf)
 
 Fortunately, our model has learned to recognize these important
 sequences (such as "artificial intelligence" and "machine learning" in
@@ -238,7 +238,7 @@ learned and how it is classifying the documents...
 
 .. code:: python
 
-    Server.serve(clf)
+    Live_Test.run(clf)
 
 Perfect! now the documents are classified properly! (including *doc_3.txt*) :D
 

examples/movie_review.ipynb

@@ -26,7 +26,7 @@
    "source": [
     "from pyss3 import SS3\n",
     "from pyss3.util import Dataset\n",
-    "from pyss3.server import Server\n",
+    "from pyss3.server import Live_Test\n",
     "\n",
     "from sklearn.metrics import accuracy_score"
    ]
@@ -167,8 +167,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "Server.serve(clf, x_test, y_test)  # <- ONLY WORKS if you're working locally, sorry :(\n",
-    "                                   #    if you're working online through Binder, it won't work"
+    "Live_Test.run(clf, x_test, y_test)  # <- ONLY WORKS if you're working locally, sorry :(\n",
+    "                                    #    if you're working online through Binder, it won't work"
    ]
   },
   {
@@ -248,7 +248,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "Server.serve(clf, x_test, y_test)  # <- ONLY WORKS if you're working locally, sorry :(\n",
+    "Live_Test.run(clf, x_test, y_test)  # <- ONLY WORKS if you're working locally, sorry :(\n",
     "                                   #    if you're working online through Binder, it won't work\n",
     "\n",
     "# (!) Remember: to stop the server, press `Esc` and then the `I` key twice"
@@ -317,7 +317,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "Server.serve(clf, x_test, y_test)  # <- ONLY WORKS if you're working locally, sorry :(\n",
+    "Live_Test.run(clf, x_test, y_test)  # <- ONLY WORKS if you're working locally, sorry :(\n",
     "                                   #    if you're working online through Binder, it won't work\n",
     "\n",
     "# (!) Remember: to stop the server, press `Esc` and then the `I` key twice"

examples/movie_review.py

@@ -9,7 +9,7 @@
 # Before we begin, let's import needed modules...
 from pyss3 import SS3
 from pyss3.util import Dataset
-from pyss3.server import Server
+from pyss3.server import Live_Test
 
 from sklearn.metrics import accuracy_score
 from os import system
@@ -50,7 +50,7 @@
 
 # Not bad using the default hyper-parameters values, let's now manually
 # analyze what our model has actually learned by using the interactive "live test".
-Server.serve(clf, x_test, y_test)
+Live_Test.run(clf, x_test, y_test)
 
 # Makes sense to you?
 # (remember you can select "words" as the Description Level if you want to know
@@ -83,7 +83,7 @@
 # using the interactive "live test" to observe what our model has learned (like
 # "was supposed to", "has nothing to", "low budget", "your money", etc. for the
 # "negative" class). Let's see...
-Server.serve(clf, x_test, y_test)
+Live_Test.run(clf, x_test, y_test)
 
 # As described in the "Hyper-parameter Optimization" section of the tutorial,
 # (https://pyss3.readthedocs.io/en/latest/tutorials/movie-review.html#hyper-parameter-optimization)

examples/topic_categorization.ipynb

@@ -26,7 +26,7 @@
    "source": [
     "from pyss3 import SS3\n",
     "from pyss3.util import Dataset\n",
-    "from pyss3.server import Server\n",
+    "from pyss3.server import Live_Test\n",
     "\n",
     "from sklearn.metrics import accuracy_score"
    ]
@@ -169,13 +169,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Server.serve(clf, x_test, y_test)  # <- this visualization doesn't look really clean and good so, instead,\n",
-    "                                     #    we will use the documents in \"live_test\" folder:\n",
+    "# Live_Test.run(clf, x_test, y_test)  # <- this visualization doesn't look really clean and good so, instead,\n",
+    "                                      #    we will use the documents in \"live_test\" folder:\n",
     "\n",
-    "Server.set_testset_from_files(\"datasets/topic/live_test\")\n",
+    "Live_Test.set_testset_from_files(\"datasets/topic/live_test\")\n",
     "\n",
-    "Server.serve(clf)  # <- ONLY WORKS if you're working locally, sorry :(\n",
-    "                   #    if you're working online through Binder, it won't work"
+    "Live_Test.run(clf)  # <- ONLY WORKS if you're working locally, sorry :(\n",
+    "                    #    if you're working online through Binder, it won't work"
    ]
   },
   {
@@ -253,8 +253,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "Server.serve(clf)  # <- ONLY WORKS if you're working locally, sorry :(\n",
-    "                   #    if you're working online through Binder, it won't work\n",
+    "Live_Test.run(clf)  # <- ONLY WORKS if you're working locally, sorry :(\n",
+    "                    #    if you're working online through Binder, it won't work\n",
     "\n",
     "# (!) Remember: to stop the server, press `Esc` and then the `I` key twice"
    ]
@@ -326,8 +326,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "Server.serve(clf)  # <- ONLY WORKS if you're working locally, sorry :(\n",
-    "                   #    if you're working online through Binder, it won't work\n",
+    "Live_Test.run(clf)  # <- ONLY WORKS if you're working locally, sorry :(\n",
+    "                    #    if you're working online through Binder, it won't work\n",
     "\n",
     "# (!) Remember: to stop the server, press `Esc` and then the `I` key twice"
    ]

examples/topic_categorization.py

@@ -9,7 +9,7 @@
 # Before we begin, let's import needed modules...
 from pyss3 import SS3
 from pyss3.util import Dataset
-from pyss3.server import Server
+from pyss3.server import Live_Test
 
 from sklearn.metrics import accuracy_score
 from os import system
@@ -62,12 +62,12 @@
 # (*) try it if you want but since `x_test` contains (preprocessed) tweets,
 # they don't look really good and clean.
 #
-# Server.serve(clf, x_test, y_test)  # <- this visualization doesn't look really clean and good so,
-#                                    #     instead, we will use the documents in "live_test" folder:
+# Live_Test.run(clf, x_test, y_test)  # <- this visualization doesn't look really clean and good so,
+#                                     #     instead, we will use the documents in "live_test" folder:
 
-Server.set_testset_from_files("datasets/topic/live_test")
+Live_Test.set_testset_from_files("datasets/topic/live_test")
 
-Server.serve(clf)
+Live_Test.run(clf)
 
 # Live test doesn't look bad, however, we will create a "more intelligent" version of this model,
 # a version that can recognize variable-length word n-grams "on the fly". Thus, when calling the
@@ -99,7 +99,7 @@
 # interactive "live test" to observe what our model has learned (like "machine learning",
 # "artificial intelligence", "self-driving cars", etc. for the "science&technology" category.
 # Let's see...
-Server.serve(clf)
+Live_Test.run(clf)
 
 # Fortunately, our model has learned to recognize these important sequences (such as
 # "artificial intelligence" and "machine learning" in doc_2.txt,  "self-driving cars"
@@ -127,7 +127,7 @@
 #
 # Let's perform the last check and visualize what our final model has
 # learned and how it is classifying the documents...
-Server.serve(clf)
+Live_Test.run(clf)
 
 
 # Perfect! now the documents are classified properly! (including *doc_3.txt*) :D

pyss3/server.py

@@ -90,7 +90,7 @@ def get_http_contlength(http_request):
 
 
 class Server:
-    """SS3 HTTP server wrapper."""
+    """SS3's Live Test HTTP server class."""
 
     __port__ = 0  # any (free) port
     __clf__ = None
@@ -403,7 +403,7 @@ def start_listening(port=0):
         Server.__port__ = server_socket.getsockname()[1]
 
         Print.info(
-            "PySS3 server started (listening on port %d)" % Server.__port__,
+            "Live Test server started (listening on port %d)" % Server.__port__,
             force_show=True
         )
 
@@ -498,6 +498,9 @@ def serve(
             if quiet:
                 Print.verbosity_region_end()
 
+# more user-friendly aliases
+Live_Test = Server
+Live_Test.run = Server.serve
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description='PySS3 Live Test Server')