Update user-friendly name for specimen_from_organism schema

[malloryfreeberg]

For which schema is a change/update being suggested?

I would like to request an update to the specimen_from_organism.json schema.

What should the change/update be?

I would like to change the user-friendly name of the specimen from organism schema to "Primary tissue" to more accurately describe that the specimen schema is to be used to describe a primary tissue sample taken directly from a donor/mouse.

Related to #389 which proposed to change the whole schema name (a major and disruptive change). This ticket is just for updating the user-friendly name of the schema.

What new field(s) need to be changed/added?

No new fields.

Why is the change requested?

I would like the Data Browser to be able to display the "type" of sample in a project as either "Organoid", "Cell line", or "Primary tissue", which are the 3 major categories of sample types we have. The terms "Organoid" and "Cell line" can be retrieved from the user-friendly term of the corresponding schemas, but for "Primary tissue", the schema name is actually "Specimen from organism", which is a bit confusing. Changing the user-friendly name of the specimen schema is a patch update that will provide a mechanism for the Browser to retrieve the standardized sample type names.

[malloryfreeberg]

Thoughts @hannes-ucsc @NoopDog ?

The idea is to go from this:

to more like this:

@hannes-ucsc I know you had some thoughts on what to replace "specimen" with (biospecimen, tissue, tissue sample). We can change the actual name of the schema later (major change) but change the user-friendly name now to help with displays.

[hannes-ucsc]

Good idea. See DataBiosphere/azul#1026

[hannes-ucsc]

I have to back track from my initial enthusiasm. The column value in the data browser isn't the only place where our users encounter the specimen_from_organism misnomer. It manifests itself in the manifest and the full metadata TSV. I worry that this would actually increase the confusion among our users. We introduced the concept of "user friendly" name but does that mean that our schema uses "user-unfriendly" names? We do expect users to consume the metadata, do we not? Above all, I (and our users) value low entropy and consistency. I think this change would increase entropy and reduce consistency.

Furthermore, while I look forward to the renaming of the actual metadata entity—and I think it could be absorbed relatively easily—I don't want to spend any time on a cosmetic issue that I'll have to redo when the actual entity gets renamed.

One could still argue that this could be implemented at the presentation layer in the Data Browser. Not for me to decide. The entropy and consistency concern however would still apply.

[diekhans]

display_name would have been a better name of the field than user_friendly. The current schema entity structure was developed rather quickly and does need review, especially from a consumer point of view. It will be improved, but not in a piecemeal approach.

However, until we get a system in place to migrate entities to new metadata schema versions, these changes become quite painful, because both old and new entities need to be supported. Updating the used_friendly name is a non-breaking change, so it gives us a chance to improve usability quickly.

For user_unfriendly, we have UUIDs ;-)

[hannes-ucsc]

+1 on display_name but having display_name be "Primary Tissue" while the entity is called specimen_from_organism too far a leap, IMO.

[diekhans]

there is already a ticket on specimen_from_organism being a bad name:
#389

I don't think you will get any argument about that. We don't have the tools to make it not painful yet .

[diekhans]

I created a meta-ticket to collect these kinds of issues for review:

Do a top-down review of metadata entity names and structure. #994

this is already in there, but feel free to complain about similar issues

[hannes-ucsc]

@malloryfreeberg I think I got a little confused. This is a presentational issue that Azul should not be involved in. Azul will convert from "specimen" to "primary_tissue" when the actual entity is being renamed. That way Azul's service reponse will be consistent with the manifest and metadata TSVs that it generates. I would caution against doing a cosmetic renaming at the presentation layer (i.e. Data Browser) but that's not for me to decide.

[diekhans]

@hannes-ucsc, I am confused. where are you getting the name "specimen" from? We should always be looking up display names, not translating programming names. We might need to add something for you look up.

[malloryfreeberg]

@diekhans @hannes-ucsc Azul/Browser should be getting the display name from the schema using the title attribute. E.g.:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "Information about the cell line or cell culture biomaterial.",
    "additionalProperties": false,
    "title": "Cell line",
    "name": "cell_line",

I don't think Azul/Browser are doing this at moment, because instead of "Cell line" I see "cellLine" in the Browser. User-unfriendly names are the programmatic names (e.g. "cell_line").

Azul/Browser should be able to get all display names by introspecting the schema and not have to hard-code names (like "cellLine").

[hannes-ucsc]

@diekhans, Azul does not use display names because it is not a GUI. It's a service designed for programmatic consumption and should therefore be consistent with the canonical naming of entities and properties as defined in the schema. We may provide an endpoint that the Data Browser can use to determine the display name mapping for all fields. Because Azul indexes all metadata, it is in a good position to populate an exhaustive mapping across all schema versions found in the wild.

The use of specimen has historical reasons. We inherited it from our predecessors and never changed it to specimen_from_organism because it seemed awkwardly long and a discussion of renaming it had already been started.

[hannes-ucsc]

@malloryfreeberg, agreed. In this case would be helpful, though, to distinguish between Azul and the Data Browser. I think Azul should not use the title property from the schema other than to back a service endpoint that enables the Data Browser to determine the title of any given entity or property. For example, for a sample that is a cell line, the Azul service response should read …, {"sample": [{ …, "type": "cell_line"}, …], "cell_line": [{…, "model_organ": …, …}, …], …}. The data browser should translate cell_line to Cell line before displaying that response. The translation will be driven by a mapping that was retrieved from Azul before any other requests are made to it.

[diekhans]

@hannes-ucsc I though azul was the data browser

what do I know???

yes, if it is a programmatic api it should use the field names as defined. Until we have schema migration, we need to go slow (just like everything cross box) 👎