- added references to API Reference page + other sections of the tutorial in the tutorial_presenting_larray_objects notebook

- updated the subsection Session of the tutorial_presenting_larray_objects notebook

Author: alixdamman

doc/source/tutorial/tutorial_presenting_larray_objects.ipyml

@@ -9,7 +9,6 @@ cells:
     import warnings
     warnings.filterwarnings("ignore", message=r'.*numpy.dtype size changed*')
 
-  id: 0
   metadata:
     nbsphinx: hidden
 
@@ -20,7 +19,6 @@ cells:
 - code: |
     from larray import *
 
-  id: 1
 
 - markdown: |
     Check the version of LArray:
@@ -30,7 +28,6 @@ cells:
     from larray import __version__
     __version__
 
-  id: 2
 
 - markdown: |
     ## Axis
@@ -53,7 +50,10 @@ cells:
 
     age, sex, time, other
 
-  id: 3
+
+- markdown: |
+    See the [Axis](../api.rst#axis) section of the API Reference to explore all methods of Axis objects.
+
 
 - markdown: |
     ## Groups
@@ -75,7 +75,6 @@ cells:
 
     teens
 
-  id: 4
 
 - markdown: |
     It is possible to set a name or to rename a group after its declaration: 
@@ -90,12 +89,19 @@ cells:
 
     teens
 
-  id: 5
+
+- markdown: |
+    See the [Group](../api.rst#group) section of the API Reference to explore all methods of Group objects.
+
 
 - markdown: |
     ## LArray
 
-    A ``LArray`` object represents a multidimensional array with labeled axes (#ref needed).
+    A ``LArray`` object represents a multidimensional array with labeled axes.
+    
+    See the [LArray](../api.rst#larray) section of the API Reference to explore all methods of LArray objects.
+    
+    To know how to save and load arrays in CSV, Excel or HDF format, please refer to the [Loading and Dumping Arrays](tutorial_IO.ipynb#Loading-and-Dumping-Arrays) section of the tutorial.
 
     ### Create an array from scratch
 
@@ -116,7 +122,6 @@ cells:
     arr = LArray(data, axes, meta=meta)
     arr
 
-  id: 6
 
 - markdown: |
     Metadata can be added to an array at any time using: 
@@ -127,7 +132,6 @@ cells:
 
     arr.meta
 
-  id: 7
 
 - markdown: |
     <div class="alert alert-warning">
@@ -172,14 +176,12 @@ cells:
     # start defines the starting value of data
     ndtest(['age=0..2', 'sex=M,F', 'time=2007..2009'], start=-1)
 
-  id: 8
 
 - code: |
     # start defines the starting value of data
     # label_start defines the starting index of labels
     ndtest((3, 3), start=-1, label_start=2)
 
-  id: 9
 
 - code: |
     # empty generates uninitialised array with correct axes
@@ -190,24 +192,20 @@ cells:
     # will be overridden.
     empty(['age=0..2', 'sex=M,F', 'time=2007..2009'])
 
-  id: 10
 
 - code: |
     # example with anonymous axes
     zeros(['0..2', 'M,F', '2007..2009'])
 
-  id: 11
 
 - code: |
     # dtype=int forces to store int data instead of default float
     ones(['age=0..2', 'sex=M,F', 'time=2007..2009'], dtype=int)
 
-  id: 12
 
 - code: |
     full(['age=0..2', 'sex=M,F', 'time=2007..2009'], 1.23)
 
-  id: 13
 
 - markdown: |
     All the above functions exist in *(func)_like* variants which take axes from another array
@@ -216,7 +214,6 @@ cells:
 - code: |
     ones_like(arr)
 
-  id: 14
 
 - markdown: |
     Create an array using the special ``sequence`` function (see link to documention of ``sequence`` in API reference for more examples):
@@ -226,7 +223,6 @@ cells:
     # With initial=1.0 and inc=0.5, we generate the sequence 1.0, 1.5, 2.0, 2.5, 3.0, ...
     sequence('sex=M,F', initial=1.0, inc=0.5)
 
-  id: 15
 
 - markdown: |
     ### Inspecting LArray objects
@@ -236,7 +232,6 @@ cells:
     # create a test array
     arr = ndtest([age, sex, time, other])
 
-  id: 16
 
 - markdown: |
     Get array summary : dimensions + description of axes
@@ -245,7 +240,6 @@ cells:
 - code: |
     arr.info
 
-  id: 17
 
 - markdown: |
     Get axes
@@ -254,7 +248,6 @@ cells:
 - code: |
     arr.axes
 
-  id: 18
 
 - markdown: |
     Get array dimensions
@@ -263,7 +256,6 @@ cells:
 - code: |
     arr.shape
 
-  id: 19
 
 - markdown: |
     Get number of elements
@@ -272,7 +264,6 @@ cells:
 - code: |
     arr.size
 
-  id: 20
 
 - markdown: |
     Get size in memory
@@ -281,7 +272,6 @@ cells:
 - code: |
     arr.memory_used
 
-  id: 21
 
 - markdown: |
     Display the array in the viewer (graphical user interface) in read-only mode.
@@ -306,39 +296,63 @@ cells:
     A ``Session`` object is a dictionary-like object used to gather several arrays, axes and groups. 
     A session is particularly adapted to gather all input objects of a model or to gather the output arrays from different scenarios. Like with arrays, it is possible to associate metadata to sessions.
 
-    In addition to act like dictionaries, sessions offer several specific methods, like:
-    - ``save`` and ``load`` to save and load all arrays of a session at once in/from CSV or Excel or HDF5 file(s),
-    - ``equals`` and ``array_equals`` to compare arrays between two sessions (scenarios) one by one,
-    - ``apply`` to apply a function to all arrays of a session.
+    See the [Session](../api.rst#session) section of the API Reference to explore all methods of Session objects.
+    
+    To know how to save and load sessions in CSV, Excel or HDF format, please refer to the [Loading and Dumping Sessions](tutorial_IO.ipynb#Loading-and-Dumping-Sessions) section of the tutorial.
 
-    See the API Reference section to explore all methods of Session objects.
+    To see how to work with sessions, please read the [Working With Sessions](tutorial_sessions.ipynb#Working-With-Sessions) section of the tutorial.
 
 
 - markdown: |
-    ### Create a Session
+    ### Creating Sessions
 
-    Create an empty session and populate it:
+    To create a session, you can first create an empty session and then populate it with arrays, axes and groups:
 
 
 - code: |
     # create an empty session
-    s = Session()
+    s_pop = Session()
 
-    # populate the session (with arrays, axes or groups) using 2 ways:
-    # 1) with syntax: session.object_name = object 
-    s.axisa = Axis('a=a0..a2')
-    s.arr1 = ndtest(s.axisa)
-    # 2) like a dictionary: session['object_name'] = object
-    s['axisb'] = Axis('b=b0..b3')
-    s['arr2'] = ndtest((s['axisa'], s['axisb']))
+    # add axes to the session
+    gender = Axis("gender=Male,Female")
+    s_pop.gender = gender
+    time = Axis("time=2013,2014,2015")
+    s_pop.time = time
+    
+    # add arrays to the session
+    s_pop.pop = zeros((gender, time))
+    s_pop.births = zeros((gender, time))
+    s_pop.deaths = zeros((gender, time))
 
     # add metadata after creation
-    s.meta.title = 'Input objects'
-    s.meta.description = 'Input axes and arrays for the model X'
+    s_pop.meta.title = 'Demographic Model of Belgium'
+    s_pop.meta.description = 'Modelize the demography of Belgium'
+    
+    # print content of the session
+    print(s_pop.summary())
+
+
+- markdown: |
+    or you can create and populate a session in one step:
+
+
+- code: |
+    gender = Axis("gender=Male,Female")
+    time = Axis("time=2013,2014,2015")
+    
+    # create and populate a new session in one step
+    # Python <= 3.5
+    s_pop = Session([('gender', gender), ('time', time), ('pop', zeros((gender, time))), 
+                    ('births', zeros((gender, time))), ('deaths', zeros((gender, time)))], 
+                    meta=[('title', 'Demographic Model of Belgium'),('description', 'Modelize the demography of Belgium')])
+    # Python 3.6+
+    s_pop = Session(gender=gender, time=time, pop=zeros((gender, time)), 
+                    births=zeros((gender, time)), deaths=zeros((gender, time)), 
+                    meta=Metadata(title='Demographic Model of Belgium', description='Modelize the demography of Belgium'))
 
-    s
+    # print content of the session
+    print(s_pop.summary())
 
-  id: 22
 
 - markdown: |
     <div class="alert alert-warning">
@@ -348,29 +362,14 @@ cells:
         <li>Contrary to array metadata, saving and loading session metadata is supported for
             all current session file formats: Excel, CSV and HDF (.h5).</li>
         <li>Metadata is not kept when actions or methods are applied on a session
-            except for operations modifying a session in-place, such as: `s['arr1'] = 0`.
+            except for operations modifying a session in-place, such as: `s.arr1 = 0`.
             Do not add metadata to a session if you know you will apply actions or methods
             on it before dumping it.</li>
       </ul>
 
     </div>
 
 
-- markdown: |
-    Load a session from a file:
-
-
-- code: |
-    # get the filepath of the example file to be read
-    filepath = get_example_filepath('demography.h5')
-    
-    # load session
-    s2 = Session(filepath)
-    
-    s2
-
-  id: 23
-
 # The lines below here may be deleted if you do not need them.
 # ---------------------------------------------------------------------------
 metadata:
@@ -395,16 +394,3 @@ metadata:
 nbformat: 4
 nbformat_minor: 2
 
-# ---------------------------------------------------------------------------
-data:
-  [{execution_count: null, outputs: []}, {execution_count: null, outputs: []}, {execution_count: null,
-      outputs: []}, {execution_count: null, outputs: []}, {execution_count: null, outputs: []},
-    {execution_count: null, outputs: []}, {execution_count: null, outputs: []}, {execution_count: null,
-      outputs: []}, {execution_count: null, outputs: []}, {execution_count: null, outputs: []},
-    {execution_count: null, outputs: []}, {execution_count: null, outputs: []}, {execution_count: null,
-      outputs: []}, {execution_count: null, outputs: []}, {execution_count: null, outputs: []},
-    {execution_count: null, outputs: []}, {execution_count: null, outputs: []}, {execution_count: null,
-      outputs: []}, {execution_count: null, outputs: []}, {execution_count: null, outputs: []},
-    {execution_count: null, outputs: []}, {execution_count: null, outputs: []}, {execution_count: null,
-      outputs: []}, {execution_count: null, outputs: []}]
-