datajoint / datajoint-docs-original Goto Github PK

The PDF version of the site does not show a version number; it just says "Release python".

• Describe the use of Navicat, HeidiSQL
• Describe the use an deployment of Helium, add references and example.
• Describe the use of LIMS and mLIMS in particular, add references.

Docker should be capitalized. MATLAB should be in all caps. Python should be capitalized.

The issue was reported by @mjlm originally in datajoint/datajoint-matlab#114

On my system, the part table example given in the documentation (here) lacks a (SetAccess=protected), causing Matlab to throw this error:

The definition of property 'master' in class 'test.SegmentationROI ' differs
from its definition in the superclass 'dj.Part'. This is caused by either
conflicting access permissions or differing values of the Constant attribute.
The error is fixed by adding (SetAccess=protected) to the properties section:

classdef SegmentationROI < dj.Part
    properties(SetAccess=protected)
        master = test.Segmentation
    end
    methods
        function makeTuples(self, key)
            image = fetch1(test.Image & key, 'image');
            [roi_pixels, roi_weighs] = mylib.segment(image);
            for roi=1:length(roi_pixels)
                tuple = key;
                tuple.roi_pixels = roi_pixels{roi};
                tuple.roi_weights = roi_weights{roi};
                self.insert(tuple)
            end
        end
    end
end

The content needs to be modified to fit within a page width, or the table needs to be truncated/split.

Text: "This is a detailed manual for active users of DataJoint in Python and MATLAB." Should be split.

Spaces following periods in "e.g.", "i.e.", and others should be followed by a backslash or replaced with a tilde, as in ".\ nextWord" or ".~nextWord".

Describe examples of poorly normalized designs and show how they can be normalized.

0. Secondary attributes that do not directly apply to entity of the set --> extract into separate entity set.
1. Repeated attributes --> Separate entity set
2. E.g. Mouse death does not belong in Mouse.
3. Optional attributes broken into separate entity sets.
4. Specialization pattern: common attributes in a table and special attributes in dependent specialization tables.

The PDF rendering uses framed tables, but separating columns by background color would look better.

In Python: len and bool

In MATLAB: count and exists

python/pydoc: http://www.sphinx-doc.org/es/stable/ext/autodoc.html
matlab: https://github.com/sphinx-contrib/matlabdomain

Regular web links should be in-line and do not need to be spelled out, e.g. the word "Docker" should be a link to https://docker.com.

References to publications should have proper citations, rendered as links but without explicit web addresses in the text.

Original figures are rather high resolution. The PDF version appears to be downsampled.

Section.aggr(Enroll, n: count()) does not work, the correct syntax seems to be: Section.aggr(Enroll, n: "count(*)")

Doc is missing a good explanation the concept of key_source all together. Should cover the following cases:

1. Discuss what is the default key_source equivalent to
2. Discuss how this can be modified/overridden by using either

key_source = table1 * tabel2

or

@property
def key_source(self):
    # allows for more complex operations to arrive at the key_source
    return table1 * table2

For example, I didn't see skip_duplicates, or ignore_errors mentioned in the documentation.

Noticed that sphinx has a glosssary facility which can then be hyperlinked into the main document:

http://www.sphinx-doc.org/en/stable/markup/para.html#glossary

this might make sense both in terms of providing convenient lookup for users, and also getting all the definitions 'on the same page', literally.

-> A
---
(x1, y1) -> B(x, y)

If B contains another attribute z in the primary key, and z is not part of the primary key attributes in A, it will throw an error. To include this extra attribute z, we would have to say (x1, y1, z) -> B(x, y, z), or rename it such as(x1, y1, z1) -> B(x, y, z)

Add figure where it says <<Figure>>: a screenshot of the preview of a query result.

It is rather obscure to find description about how to use and configure external field only under the Server Administration section. It would make it easier to navigate if we make an entry in datatypes page that can then link to the more specific page.

Formatting needs to be corrected.

Currently, the PDF renders sections as chapters (60 chapters!) and does not reflect the high-level organization: Introduction, Server Administration, Client Setup, ...

Please modify the PDF rendering to include the high-level organization.

References should be allowed to the entire chapter rather than to the individual sections. E.g. Input/Output line 61 should point to Queries rather than queries/01-Queries.rst.

please include package names in table names, e.g. university.Department.

There should be a single example schema design used across all sections of the documentation.

Because it is not required for the master class to be an ancestor of the part table, you can fall into situations as seen in datajoint/datajoint-python#421 that requires you to delete/drop the part table directly. This is actually possible via force=True option but this is not documented explicitly.

a good clarifying pointer for people comparison shopping between various systems, software, etc.

thinking X might be best addressed categorically with examples

such as:

how does datajoint compare to a Laboratory Information System (LIMS, e.g: Alyx, mLIMS, etc)

and:

how does datajoint compare to a Object Relational Mapper (ORM, e.g: Django ORM, SQLAlchemy, etc)

and so on..

Figures are larger than their native size/resolution on PDF.

Describe what should happen when restricting by an empty table, an empty collection, or an empty AndList:

tab - []
tab & []
tab - AndList([])
tab & AndList([])

Describe what happens when restricting by a dict with no common attributes.

tab & {'one': 1}
tab - {}

Describe what happens when restricting by a query expression that has no common attributes with tab.

tab & expr

• Explain why
• Explain how to create cyclic relationship

Fetch documentation in split version doesn't cover 'order by' in python;
more generally, the coverage of fetch is more in depth on the matlab side.

while some features are language specific, general topic coverage applicable to both should be consistent (inc. 'order by')

matlab current topics in fetch page:

• fetch
• fetch1
• fetch key
• fetch entire result
• fetch as separate variables
• pkey with values
• renaming fetches
• order-by / sort / limit

python current topics in fetch page:

• fetch
• fetch entire result
• fetch as separate variables
• fetch primary key
• usage with pandas (python specific)

ideally, the general structure should match for both and coverage should be similar to resolve this issue

The PDF rendering uses borders, but a background color would look better.

Content needs to be added.

Our chapters are big enough that they should become foldable on the website.

Content needs to be expanded. Additional questions can be added as appropriate.

Date, time, and timestamp are listed in data types, but datetime is absent.

ERDs draw themselves using _repr_html_ -- explain how that works. Using the draw method is not required.

Currently the documentation doesn't make it obvious what values are allowed as the value for the default value setting syntax (i.e. attr1 = "val"). A few concrete examples for different data types along with a specific explanation for NULL as a default value and its interpretation (i.e. basically, an optional attribute), should be mentioned.