datajoint · eywalker · Oct 15, 2018 · Oct 15, 2018 · Oct 15, 2018
diff --git a/docs/admin/5-blob-config_lang1.rst b/docs/admin/5-blob-config_lang1.rst
diff --git a/docs/computation/01-autopopulate_lang1.rst b/docs/computation/01-autopopulate_lang1.rst
@@ -0,0 +1,22 @@
+
+|matlab| MATLAB
+
+.. code-block:: MATLAB
+
+    %{
+    # Filtered image
+    -> test.Image
+    ---
+    filtered_image : longblob
+    %}
+
+    classdef FilteredImage < dj.Computed
+        methods(Access=protected)
+            function make(self, key)
+                img = fetch1(test.Image & key, 'image');
+                key.filtered_image = myfilter(img);
+                self.insert(key)
+            end
+        end
+    end
+
diff --git a/docs/computation/01-autopopulate_lang2.rst b/docs/computation/01-autopopulate_lang2.rst
@@ -0,0 +1,6 @@
+
+|matlab| MATLAB
+
+.. code-block:: matlab
+
+    populate(test.FilteredImage)
diff --git a/docs/computation/04-master-part_lang1.rst b/docs/computation/04-master-part_lang1.rst
@@ -0,0 +1,54 @@
+
+|matlab| MATLAB
+---------------
+In MATLAB, the master and  part tables are declared in a separate ``classdef`` file.
+The name of the part table must begin with the name of the master table.
+The part table must declare the property ``master`` containing an object of the master.
+
+``+test/Segmentation.m``
+
+.. code-block:: matlab
+
+    %{
+    # image segmentation
+    -> test.Image
+    %}
+    classdef Segmentation < dj.Computed
+        methods(Access=protected)
+            function make(self, key)
+                self.insert(key)
+                make(test.SegmentationRoi, key)
+            end
+        end
+    end
+
+``+test/SegmentationROI.m``
+
+.. code-block:: matlab
+
+   %{
+   # Region of interest resulting from segmentation
+   -> Segmentation
+   roi  : smallint   # roi number
+   ---
+   roi_pixels  : longblob   #  indices of pixels
+   roi_weights : longblob   #  weights of pixels
+   %}
+
+   classdef SegmentationROI < dj.Part
+       properties(SetAccess=protected)
+           master = test.Segmentation
+       end
+       methods
+           function make(self, key)
+               image = fetch1(test.Image & key, 'image');
+               [roi_pixels, roi_weighs] = mylib.segment(image);
+               for roi=1:length(roi_pixels)
+                   entity = key;
+                   entity.roi_pixels = roi_pixels{roi};
+                   entity.roi_weights = roi_weights{roi};
+                   self.insert(entity)
+               end
+           end
+       end
+   end
diff --git a/docs/computation/04-master-part_lang2.rst b/docs/computation/04-master-part_lang2.rst
@@ -0,0 +1,6 @@
+
+|matlab|
+
+.. code-block:: matlab
+
+    populate(Segmentation)
diff --git a/docs/computation/06-distributed-computing_lang1.rst b/docs/computation/06-distributed-computing_lang1.rst
@@ -0,0 +1,4 @@
+
+|matlab|
+In MATLAB job reservations are activated by replacing ``populate`` calls with identical ``parpopulate`` calls.
+
diff --git a/docs/computation/06-distributed-computing_lang2.rst b/docs/computation/06-distributed-computing_lang2.rst
@@ -0,0 +1,3 @@
+
+.. todo: matlab
+
diff --git a/docs/computation/06-distributed-computing_lang3.rst b/docs/computation/06-distributed-computing_lang3.rst
@@ -0,0 +1,3 @@
+
+.. todo: similarly, in matlab (blah)
+
diff --git a/docs/computation/06-distributed-computing_lang4.rst b/docs/computation/06-distributed-computing_lang4.rst
@@ -0,0 +1,3 @@
+
+.. todo: similarly, in matlab (blah)
+
diff --git a/docs/computation/06-distributed-computing_lang5.rst b/docs/computation/06-distributed-computing_lang5.rst
@@ -0,0 +1,3 @@
+
+.. todo: similarly, in matlab (blah)
+
diff --git a/docs/concepts/empty.txt b/docs/concepts/empty.txt
diff --git a/docs/definition/01-Creating-Schemas_lang1.rst b/docs/definition/01-Creating-Schemas_lang1.rst
@@ -0,0 +1,62 @@
+
+|matlab| MATLAB
+---------------------------
+A schema can be created in MATLAB either automatically using the ``dj.createSchema`` script or manually.
+While ``dj.createSchema`` simplifies the process, the manual approach yields a better understanding of what actually takes place, so both approaches are listed below.
+
+Manual
+^^^^^^^^^^^^
+**Step 1.**  Create the database schema
+
+Use the following command to create a new schema on the database server:
+
+.. code-block:: matlab
+
+    query(dj.conn, 'CREATE SCHEMA `alice_experiment`')
+
+Note that you must have create privileges for the schema name pattern (as described in :ref:`hosting`).
+It is a common practice to grant all privileges to users for schemas that begin with the username, in addition to some shared schemas.
+Thus the user ``alice`` would be able to perform any work in any schema that begins with ``alice_``.
+
+**Step 2.**  Create the MATLAB package
+
+DataJoint for MATLAB organizes schemas as MATLAB **packages**.
+If you are not familiar with packages, please review:
+
+* `How to work with MATLAB packages <https://www.mathworks.com/help/matlab/matlab_oop/scoping-classes-with-packages.html>`_
+* `How to manage MATLAB's search paths <https://www.mathworks.com/help/matlab/search-path.html>`_
+
+In your project directory, create the package folder, which must begin with a ``+`` sign.
+For example, for the schema called ``experiment``, you would create the folder ``+experiment``.
+Make sure that your project directory (the parent directory of your package folder) is added to the MATLAB search path.
+
+**Step 3.**  Associate the package with the database schema
+
+In this step, we tell DataJoint that all classes in the package folder ``+experiment`` will work with tables in the database schema ``alice_experiment``.
+Each package in MATLAB corresponds to exactly one schema.
+In some special cases, multiple packages may all relate to a single database schema, but in most cases there will be a one-to-one relationship between packages and schemas.
+
+In the ``+experiment`` folder, create the file ``getSchema.m`` with the following contents:
+
+.. code-block:: matlab
+
+    function obj = getSchema
+    persistent OBJ
+    if isempty(OBJ)
+        OBJ = dj.Schema(dj.conn, 'experiment', 'alice_experiment');
+    end
+    obj = OBJ;
+    end
+
+This function returns a persistent object of type ``dj.Schema``, establishing the link between the ``experiment`` package in MATLAB and the schema ``alice_experiment`` on the database server.
+
+Automatic
+^^^^^^^^^^^^^
+
+Alternatively, you can execute
+
+.. code-block:: matlab
+
+    >> dj.createSchema
+
+This automated script will walk you through the steps 1--3 above and will create the schema, the package folder, and the ``getSchema`` function in that folder.
diff --git a/docs/definition/02-Creating-Tables_lang1.rst b/docs/definition/02-Creating-Tables_lang1.rst
@@ -0,0 +1,45 @@
+
+|matlab| MATLAB
+^^^^^^^^^^^^^^^
+
+DataJoint for MATLAB provides the interactive script ``dj.new`` for creating a new table.
+It will prompt to enter the new table's class name in the form ``package.ClassName``.
+This will create the file ``+package/ClassName.m``.
+
+For example, define the table ``experiment.Person``
+
+.. code-block:: matlab
+
+	>> dj.new
+	Enter <package>.<ClassName>: experiment.Person
+
+	Choose table tier:
+	  L=lookup
+	  M=manual
+	  I=imported
+	  C=computed
+	  P=part
+	 (L/M/I/C/P) > M
+
+This will create the file ``+experiment/Person.m`` with the following contents:
+
+.. code-block:: matlab
+
+	%{
+	# my newest table
+	# add primary key here
+	-----
+	# add additional attributes
+	%}
+
+	classdef Person < dj.Manual
+	end
+
+While ``dj.new`` adds a little bit of convenience, some users may create the classes from scratch manually.
+
+Each newly created class must inherit from the DataJoint class corresponding to the correct :ref:`data tier <tiers>`: ``dj.Lookup``, ``dj.Manual``, ``dj.Imported`` or ``dj.Computed``.
+
+The most important part of the table definition is the comment preceding the ``classdef``.
+DataJoint will parse this comment to define the table.
+
+The class will become usable after you edit this comment as described in :ref:`definitions`.
diff --git a/docs/definition/03-Table-Definition_lang1.rst b/docs/definition/03-Table-Definition_lang1.rst
@@ -0,0 +1,19 @@
+
+|matlab| MATLAB
+
+In MATLAB, the table definition is contained in the first block comment in the class definition file.
+Note that although it looks like a mere comment, the table definition in MATLAB is parsed by DataJoint.
+This solution is thought to be convenient since MATLAB does not provide convenient syntax for multiline strings.
+
+.. code-block:: matlab
+
+	%{
+	# database users
+	username : varchar(20)   # unique user name
+	---
+	first_name : varchar(30)
+	last_name  : varchar(30)
+	role : enum('admin', 'contributor', 'viewer')
+	%}
+	classdef User < dj.Manual
+	end
diff --git a/docs/definition/03-Table-Definition_lang2.rst b/docs/definition/03-Table-Definition_lang2.rst
@@ -0,0 +1,2 @@
+
+In MATLAB, the table is created upon the first attempt to use the class for manipulating its data (e.g. inserting or fetching entities).
diff --git a/docs/definition/03-Table-Definition_lang3.rst b/docs/definition/03-Table-Definition_lang3.rst
@@ -0,0 +1,7 @@
+
+|matlab| MATLAB
+
+.. code-block:: matlab
+
+	s = describe(lab.User)
+
diff --git a/docs/definition/03-Table-Definition_lang4.rst b/docs/definition/03-Table-Definition_lang4.rst
@@ -0,0 +1,9 @@
+
+Furthermore, DataJoint for MATLAB provides the ``syncDef`` method to update the ``classdef`` file definition string for the table with the definition in the actual table:
+
+|matlab| MATLAB
+
+.. code-block:: matlab
+
+	syncDef(lab.User)    % updates the table definition in file +lab/User.m
+
diff --git a/docs/definition/07-Primary-Key_lang1.rst b/docs/definition/07-Primary-Key_lang1.rst
@@ -0,0 +1,4 @@
+.. code-block:: matlab
+
+    key.scah_idx = fetch1(Scan & key, 'next=max(scan_idx)+1')
+
diff --git a/docs/definition/10-Dependencies_lang1.rst b/docs/definition/10-Dependencies_lang1.rst
@@ -0,0 +1,7 @@
+
+You can examine the resulting table heading in MATLAB with
+
+.. code-block:: matlab
+
+    show(mp.BrainSlice)
+
diff --git a/docs/definition/11-ERD_lang1.rst b/docs/definition/11-ERD_lang1.rst
@@ -0,0 +1,23 @@
+
+|matlab| MATLAB
++++++++++++++++
+
+In MATLAB, the schema object for a package can be obtained using its ``getSchema`` function.
+(See :ref:`schema`.)
+
+.. code-block:: matlab
+
+    draw(dj.ERD(seq.getSchema))   % draw the ERD
+
+MATLAB provides shortcuts to plot ERD of a table neighborhood or a schema using the ``erd`` command:
+
+.. code-block:: matlab
+
+    % plot the ERD of the stimulus schema
+    erd stimulus
+
+    % plot the neighborhood of the stimulus.Trial table
+    erd stimulus.Trial
+
+    % plot the stimulus and experiment schemas and the neighborhood of preprocess.Sync
+    erd stimulus experiment preprocess.Sync
diff --git a/docs/definition/11-ERD_lang2.rst b/docs/definition/11-ERD_lang2.rst
@@ -0,0 +1,6 @@
+
+|matlab|
+
+.. code-block:: matlab
+
+    draw(dj.ERD(seq.Genome))
diff --git a/docs/definition/11-ERD_lang3.rst b/docs/definition/11-ERD_lang3.rst
@@ -0,0 +1,7 @@
+
+|matlab|
+
+.. code-block:: matlab
+
+    % matlab: plot the ERD with tables Genome and Species from package +seq.
+    draw(dj.ERD(seq.Genome) + dj.ERD(seq.Species))
diff --git a/docs/definition/11-ERD_lang4.rst b/docs/definition/11-ERD_lang4.rst
@@ -0,0 +1,17 @@
+
+|matlab| MATLAB
+
+.. code-block:: matlab
+
+    % Plot all the tables directly downstream from ``seq.Genome``:
+    draw(dj.ERD(seq.Genome)+1)
+
+.. code-block:: matlab
+
+    % Plot all the tables directly upstream from ``seq.Genome``:
+    draw(dj.ERD(seq.Genome)-1)
+
+.. code-block:: matlab
+
+    % Plot the local neighborhood of ``seq.Genome``
+    draw(dj.ERD(seq.Genome)+1-1+1-1)
diff --git a/docs/definition/12-Example_lang1.rst b/docs/definition/12-Example_lang1.rst
@@ -0,0 +1,50 @@
+
+|matlab| MATLAB
+
+File ``+experiment/Animal.m``
+
+.. code-block:: matlab
+
+    %{
+      # information about animal
+      animal_id : int  # animal id assigned by the lab
+      ---
+      -> experiment.Species
+      date_of_birth=null : date  # YYYY-MM-DD optional
+      sex='' : enum('M', 'F', '')   # leave empty if unspecified
+    %}
+    classdef Animal < dj.Manual
+    end
+
+File ``+experiment/Session.m``
+
+.. code-block:: matlab
+
+    %{
+      # Experiment Session
+      -> experiment.Animal
+      session  : smallint  # session number for the animal
+      ---
+      session_date : date  # YYYY-MM-DD
+      -> experiment.User
+      -> experiment.Anesthesia
+      -> experiment.Rig
+    %}
+    classdef Session < dj.Manual
+    end
+
+File ``+experiment/Scan.m``
+
+.. code-block:: matlab
+
+    %{
+      # Two-photon imaging scan
+      -> experiment.Session
+      scan : smallint  # scan number within the session
+      ---
+      -> experiment.Lens
+      laser_wavelength : decimal(5,1)  # um
+      laser_power      : decimal(4,1)  # mW
+    %}
+    classdef Scan < dj.Manual
+    end