Creating Tables

Classes represent tables

To make it easy to work with tables in MATLAB and Python, DataJoint programs create a separate class for each table. Computer programmers refer to this concept as object-relational mapping. For example, the class experiment.Subject in the DataJoint client language may correspond to the table called subject on the database server. Users never need to see the database directly; they only interact with data in the database by creating and interacting with DataJoint classes.

Data tiers

The table class must inherit from one of the following superclasses to indicate its data tier: dj.Lookup, dj.Manual, dj.Imported, dj.Computed, or dj.Part. See Data Tiers and Master-Part Relationship.

Defining a table

To define a DataJoint table in Python:

  1. Define a class inheriting from the appropriate DataJoint class: dj.Lookup, dj.Manual, dj.Imported or dj.Computed.
  2. Decorate the class with the schema object (see Creating Schemas)
  3. Define the class property definition to define the table heading.

For example, the following code defines the table Person:

import datajoint as dj
schema = dj.schema('alice_experiment')

@schema
class Person(dj.Manual):
    definition = '''
                username : varchar(20)   # unique user name
    ---
    first_name : varchar(30)
    last_name  : varchar(30)
    '''

The @schema decorator uses the class name and the data tier to check whether an appropriate table exists on the database. If a table does not already exist, the decorator creates one on the database using the definition property. The decorator attaches the information about the table to the class, and then returns the class.

The class will become usable after you define the definition property as described in Table Definition.

DataJoint classes in Python

DataJoint for Python is implemented through the use of classes providing access to the actual tables stored on the database. Since only a single table exists on the database for any class, interactions with all instances of the class are equivalent. As such, most methods can be called on the classes themselves rather than on an object, for convenience. Whether calling a DataJoint method on a class or on an instance, the result will only depend on or apply to the corresponding table. All of the basic functionality of DataJoint is built to operate on the classes themselves, even when called on an instance. For example, calling Person.insert(...) (on the class) and Person.insert(...) (on an instance) both have the identical effect of inserting data into the table on the database server. DataJoint does not prevent a user from working with instances, but the workflow is complete without the need for instantiation. It is up to the user whether to implement additional functionality as class methods or methods called on instances.

Valid class names

Note that in both MATLAB and Python, the class names must follow the CamelCase compound word notation:

  • start with a capital letter and
  • contain only alphanumerical characters (no underscores).

Examples of valid class names:

TwoPhotonScan, Scan2P, Ephys, MembraneVoltage

Invalid class names:

Two_photon_Scan, twoPhotonScan, 2PhotonScan, membranePotential, membrane_potential