Sample names

The naming scheme for samples is an important aspect of your samples database. In order to support you with that, JuliaBase allows the definition of so-called name formats. These are string patterns that describe all valid sample names. They are defined in settings.py like this:

SAMPLE_NAME_FORMATS = {
    "provisional": {"possible_renames": {"new"}},
    "old":         {"pattern": r"{short_year}[A-Z]-\d{{3,4}}([-A-Za-z_/][-A-Za-z_/0-9#()]*)?",
                    "possible_renames": {"new"}},
    "new":         {"pattern": r"({short_year}-{user_initials}|{external_contact_initials})"
                               r"-[-A-Za-z_/0-9#()]+"}
}

In this example, three name formats are defined, namely “provisional”, “old”, and “new”. They are mapped to dictionaries which contain their properties.

Note

There is a length limit of 30 characters for sample names. This is hard-wired in JuliaBase.

Name format properties

"pattern"

This is the regular expression pattern for this name format. It should match sample names of this format and only these. In other words, every sample name should be identified unambiguously with a name format. JuliaBase appends an implicit \Z so that the whole sample name must match.

You can use some placeholder in the pattern that are interpreted by JuliaBase to enforce additional constraints to new sample names. These are:

{year}
the current year as a four-digit number
{short_year}
the current year as a two-digit number
{user_initials}
the initials of the currently logged-in user
{external_contact_initials}
the initials of an external contact (a.k.a. external operator) of the currently logged-in user
{combined_initials}
any of the initials above

Because placeholders are embraced with {...}, you have to double any curly braces used in the pattern itself, as can be seen at the {{3,4}} in the example above.

"possible_renames"

Default: set() (empty set)

This is a set containing all name formats into which this name format can be renamed by the user. Of course, Python code can rename a sample to anything – although it will cause trouble if the new name is not matched by any name format. However, this property sets limits to what the user can explicitly do. In the JuliaBase code, it affects the bulk-rename view as well as the split-and-rename view. And you may enforce it in your own code.

"verbose_name"

This property contains a human-friendly name for the format name. You should enclose it with _("...") to make it translatable.

Provisional sample names

There is a special name format in JuliaBase called “provisional”. It has a fixed pattern r"\*\d{5}$" and a default verbose name. It is used for newly created samples and usually immediately replaced by something real in the “bulk rename” view. You should never use a provisional name outside JuliaBase, e.g. on sample boxes, in lab notebooks, or emails! And, you should never allow renaming of any format into provisional names. In other words, one should get rid of a provisional name as quickly as possible.

Initials

Initials are a way to generate namespaces for samples. This way, name collisions may be prevented. For example, the probability that the researcher John Doe and the researcher Paula Poe both call their sample “sample-1” is pretty high. However, if they put their initials somewhere in the sample name, the samples may be called “JD-sample-1” and “PP-sample-1”; problem solved.

When it comes to choosing initials, JuliaBase follows the first come first served principle. If John Doe chooses initials after Jane Doe has picked “JD”, he must use “JD1” or “JDOE” or whatever. They cannot be changed anymore by the user.

Initials are at most 4 characters long. Apart from that, JuliaBase is configurable with the setting INITIALS_FORMATS. It is a dictionary mapping "user" and "external_contact" to a properties dictionary. The allowed properties are the following:

"pattern"

This is a regular expression pattern. The whole initials must match it. In contrast to SAMPLE_NAME_FORMATS, this pattern cannot contain placeholders, and therefore, you must not double any curly brackets.

For example, if you want to restrict user initials to two or three uppercase letters, you simply add to settings.py:

INITIALS_FORMATS["user"] = {
    "pattern": "[A-Z]{2,3}",
    "description": _("The initials consist of two or three uppercase letters.")}

"description"

This is translatable string describing the pattern in a Human-friendly way. It is used for error messages.

Name prefix templates

In the bulk rename sample view (the view to which the user is redirected after having created new samples, in order to give them a name), the user can select a name prefix, which is then prepended to every new name. This is partly for convenience and partly for name policy enforcement. With the setting NAME_PREFIX_TEMPLATES, you can configure this behaviour:

NAME_PREFIX_TEMPLATES = ["{short_year}-{user_initials}-", "{external_contact_initials}-"]

This example defines two prefixes. You may use the following placeholders in the templates:

{year}
the current four-digit year
{short_year}
the current two-digit year
{user_initials}
the initials of the currently logged-in user
{external_contact_initials}
the initials of any external contact of the currently logged-in user

You may also add the empty string "" as a template. Then, the user may also choose to not use any prefix, and the new names are taken as is.