tutorial: global improvements:

- use string syntax to generate axes
- removed the warning box about how to define Session objects before Python 3.6 (Python version previous to 3.6 are too old now)
- removed other axis (it is unlikely that users will mix letters and numbers when generating labels with the syntax start..end)
- do not use numpy randint() function to generate fake data (to avoid to confuse readers)
- avoid to define anonymous axes when calling function to create arrays with predefined values (confusing)
- removed example explaining how to create Session objects with Python 3.5- (versions 3.5 or less are too old)
- added example using argument after instead of before with the insert() method
- added a warning box to explain why we don't use the print() function to display the content of a variable in the tutorial
- added warning and examples about how LArray infer type of labels
- added explanation about how to create a unique group using slices and individual labels together

Author: alixdamman

doc/source/tutorial/getting_started.ipyml

@@ -27,6 +27,35 @@ cells:
     __version__
 
 
+- markdown: |
+    <div class="alert alert-warning">
+    
+    **Note:** 
+    The tutorial is generated from Jupyter notebooks which work in the "interactive" mode (like in the LArray Editor console). 
+    In the interactive mode, there is no need to use the print() function to display the content of a variable.
+    Simply writing its name is enough.
+    The same remark applies for the returned value of an expression.<br><br>
+    In a Python script (file with .py extension), you always need to use the print() function to display the content of 
+    a variable or the value returned by a function or an expression.
+        
+    </div>
+
+
+- code: |
+    s = 1 + 2
+    
+    # In the interactive mode, there is no need to use the print() function 
+    # to display the content of the variable 's'.
+    # Simply typing 's' is enough
+    s
+
+
+- code: |
+    # In the interactive mode, there is no need to use the print() function 
+    # to display the result of an expression
+    1 + 2
+
+
 - markdown: |
     ## Create an array
 
@@ -40,9 +69,9 @@ cells:
 
 - code: |
     # define some axes to be used later
-    age = Axis(['0-9', '10-17', '18-66', '67+'], 'age')
-    gender = Axis(['female', 'male'], 'gender')
-    time = Axis([2015, 2016, 2017], 'time')
+    age = Axis('age=0-9,10-17,18-66,67+')
+    gender = Axis('gender=female,male')
+    time = Axis('time=2015..2017')
 
 
 - markdown: |
@@ -429,16 +458,6 @@ cells:
     demography_session['foreigners'] = zeros([age, gender, time])
 
 
-- markdown: |
-    <div class="alert alert-warning">
-        If you are using a Python version prior to 3.6, you will have to pass a list of pairs
-        to the Session constructor otherwise the arrays will be stored in an arbitrary order in
-        the new session. For example, the session above must be created using the syntax:
-        
-        `demography_session=Session([('population', population), ('births', births), ('deaths', deaths)])`.
-    </div>
-
-
 - markdown: |
     One of the main interests of using sessions is to save and load many arrays at once:
 
@@ -536,7 +555,7 @@ metadata:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.7
 nbformat: 4
 nbformat_minor: 2
 

doc/source/tutorial/getting_started.ipynb

@@ -46,6 +46,48 @@
     "__version__"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "**Note:** \n",
+    "The tutorial is generated from Jupyter notebooks which work in the \"interactive\" mode (like in the LArray Editor console). \n",
+    "In the interactive mode, there is no need to use the print() function to display the content of a variable.\n",
+    "Simply writing its name is enough.\n",
+    "The same remark applies for the returned value of an expression.<br><br>\n",
+    "In a Python script (file with .py extension), you always need to use the print() function to display the content of \n",
+    "a variable or the value returned by a function or an expression.\n",
+    "    \n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "s = 1 + 2\n",
+    "\n",
+    "# In the interactive mode, there is no need to use the print() function \n",
+    "# to display the content of the variable 's'.\n",
+    "# Simply typing 's' is enough\n",
+    "s"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# In the interactive mode, there is no need to use the print() function \n",
+    "# to display the result of an expression\n",
+    "1 + 2"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -70,9 +112,9 @@
    "outputs": [],
    "source": [
     "# define some axes to be used later\n",
-    "age = Axis(['0-9', '10-17', '18-66', '67+'], 'age')\n",
-    "gender = Axis(['female', 'male'], 'gender')\n",
-    "time = Axis([2015, 2016, 2017], 'time')"
+    "age = Axis('age=0-9,10-17,18-66,67+')\n",
+    "gender = Axis('gender=female,male')\n",
+    "time = Axis('time=2015..2017')"
    ]
   },
   {
@@ -739,19 +781,6 @@
     "demography_session['foreigners'] = zeros([age, gender, time])"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "<div class=\"alert alert-warning\">\n",
-    "    If you are using a Python version prior to 3.6, you will have to pass a list of pairs\n",
-    "    to the Session constructor otherwise the arrays will be stored in an arbitrary order in\n",
-    "    the new session. For example, the session above must be created using the syntax:\n",
-    "    \n",
-    "    `demography_session=Session([('population', population), ('births', births), ('deaths', deaths)])`.\n",
-    "</div>"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -885,7 +914,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.7"
   }
  },
  "nbformat": 4,

doc/source/tutorial/tutorial_aggregations.ipyml

@@ -86,6 +86,35 @@ cells:
     population.sum(gender, (benelux, fr_de))
 
 
+- markdown: |
+    <div class="alert alert-warning">
+    
+    **Warning:** Mixing slices and individual labels inside the `[ ]` will generate **several groups** (a tuple of groups) instead of a single group.<br>If you want to create a single group using both slices and individual labels, you need to use the `.union()` method (see below).
+      
+    </div>
+
+
+- code: |
+    # mixing slices and individual labels leads to the creation of several groups (a tuple of groups)
+    except_2016 = time[:2015, 2017]
+    except_2016
+
+
+- code: |
+    # leading to potentially unexpected results
+    population.sum(except_2016)
+
+
+- code: |
+    # the union() method allows to mix slices and individual labels to create a single group
+    except_2016 = time[:2015].union(time[2017])
+    except_2016
+
+
+- code: |
+    population.sum(except_2016)
+
+
 # The lines below here may be deleted if you do not need them.
 # ---------------------------------------------------------------------------
 metadata:
@@ -102,7 +131,7 @@ metadata:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.7
 nbformat: 4
 nbformat_minor: 2
 

doc/source/tutorial/tutorial_aggregations.ipynb

@@ -147,6 +147,58 @@
    "source": [
     "population.sum(gender, (benelux, fr_de))"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "**Warning:** Mixing slices and individual labels inside the `[ ]` will generate **several groups** (a tuple of groups) instead of a single group.<br>If you want to create a single group using both slices and individual labels, you need to use the `.union()` method (see below).\n",
+    "  \n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# mixing slices and individual labels leads to the creation of several groups (a tuple of groups)\n",
+    "except_2016 = time[:2015, 2017]\n",
+    "except_2016"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# leading to potentially unexpected results\n",
+    "population.sum(except_2016)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# the union() method allows to mix slices and individual labels to create a single group\n",
+    "except_2016 = time[:2015].union(time[2017])\n",
+    "except_2016"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "population.sum(except_2016)"
+   ]
   }
  ],
  "metadata": {
@@ -165,7 +217,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.7"
   }
  },
  "nbformat": 4,

doc/source/tutorial/tutorial_combine_arrays.ipyml

@@ -15,14 +15,28 @@ cells:
 - code: |
     # load the 'demography_eurostat' dataset
     demography_eurostat = load_example_data('demography_eurostat')
+    
+    # load 'gender' and 'time' axes
+    gender = demography_eurostat.gender
+    time = demography_eurostat.time
 
 
 - code: |
     # load the 'population' array from the 'demography_eurostat' dataset
     population = demography_eurostat.population
+    
+    # show 'population' array 
     population
 
 
+- code: |
+    # load the 'population_benelux' array from the 'demography_eurostat' dataset
+    population_benelux = demography_eurostat.population_benelux
+    
+    # show 'population_benelux' array 
+    population_benelux
+
+
 - markdown: |
     The LArray library offers several methods and functions to combine arrays:
 
@@ -38,13 +52,19 @@ cells:
 
 
 - code: |
-    other_countries = zeros((Axis('country=Luxembourg,Netherlands'), population.gender, population.time), dtype=int)
+    other_countries = zeros((Axis('country=Luxembourg,Netherlands'), gender, time), dtype=int)
 
     # insert new countries before 'France'
     population_new_countries = population.insert(other_countries, before='France')
     population_new_countries
 
 
+- code: |
+    # insert new countries after 'France'
+    population_new_countries = population.insert(other_countries, after='France')
+    population_new_countries
+
+
 - markdown: |
     See [insert](../_generated/larray.Array.insert.rst#larray.Array.insert) for more details and examples.
 
@@ -66,7 +86,7 @@ cells:
 
 
 - code: |
-    population_lux = Array([-1, 1], population.gender)
+    population_lux = Array([-1, 1], gender)
     population_lux
 
 
@@ -97,7 +117,7 @@ cells:
 
 - markdown: |
     ## Extend
-    
+        
     Extend an array along an axis with another array *with* that axis (but other labels)
 
 
@@ -123,6 +143,13 @@ cells:
     population_fr = population['France']
     population_de = population['Germany']
 
+    print(population_be)
+    print(population_fr)
+    print(population_de)
+
+
+- code: |
+    # create a new array with an extra axis 'country' by stacking the three arrays population_be/fr/de
     population_stacked = stack({'Belgium': population_be, 'France': population_fr, 'Germany': population_de}, 'country')
     population_stacked
 
@@ -147,7 +174,7 @@ metadata:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.7
 nbformat: 4
 nbformat_minor: 2