Update textual_definitions_SOP.md

[dosumis]

Fixes #2556
Fixes #2385

Still to fix: Advice on extended descriptions for T-types.

[aleixpuigb]

Is there a reason for the double double-apostrophes? In the next paragraphs only single apostrophes are used.

[aleixpuigb]

Suggested change

	Similarly, a perfectly accurate minimal definition of a type II pneumocyte is an epithelial cell that has an 'alveolar lamellar body' (a unique structure only found in these cell types). But this is useless information to a user who knows nothing about this structure (many biologists) or who is annotating data that does not resolve this structure.
	Similarly, a perfectly accurate minimal definition of an 'pulmonary alveolar type 2 cell' is an epithelial cell that has an 'alveolar lamellar body' (a unique structure only found in these cell types). But this is useless information to a user who knows nothing about this structure (many biologists) or who is annotating data that does not resolve this structure.

[aleixpuigb]

Suggested change

A second use of ontologies is to encode knowledge in the form of useful formal links between ontology terms. For example, in CL, we record function and cell components via links to gene ontology terms, location via links to CL, and lineage via links to other CL terms. Not all of this information is particularly useful for recognizing a cell type, but it is of use to our users and so we often record it in CL using formal relationships. This is relevant to ontology definitions because it is good practice for formal and textual definitions to match, and textual definitions are the place we encode supporting references. It’s essential that textual definitions capture the assertions made in the formal relationships as closely as possible without becoming stilted and difficult to read.

A second use of ontologies is to encode knowledge in the form of useful formal links between ontology terms. For example, in CL, we record function and cell components via links to gene ontology terms, location via links to Uberon, and lineage via links to other CL terms. Not all of this information is particularly useful for recognizing a cell type, but it is of use to our users and so we often record it in CL using formal relationships. This is relevant to ontology definitions because it is good practice for formal and textual definitions to match, and textual definitions are the place we encode supporting references. It’s essential that textual definitions capture the assertions made in the formal relationships as closely as possible without becoming stilted and difficult to read.

[aleixpuigb]

Not all of this information is particularly useful for recognizing a cell type, but it is of use to our users and so we often record it in CL using formal relationships.

I don't agree, location and cell markers are useful to recognize a cell. I would remove this sentence as is repetitive with the previous sentences.

[aleixpuigb]

This is relevant to ontology definitions because it is good practice for formal and textual definitions to match, and textual definitions are the place we encode supporting references.

I think separating the sentences would improve readability. The second sentence can even go at the end of the paragraph:

This is relevant to ontology definitions because it is good practice for formal and textual definitions to match. Textual definitions also provide a place to include supporting references.

[aleixpuigb]

Suggested change

	Text in the definition field should be no longer than one short paragraph. The text should be referenced following standard academic practice, i.e. use in-line citations, e.g., Avola et al., 2024). It should follow a classic genus, differentia, and gloss type structure:
	Text in the definition field should be no longer than one short paragraph. The text should be referenced following standard academic practice, i.e. use in-line citations (e.g., Avola et al., 2024). It should follow a classic genus, differentia, and gloss type structure:

[aleixpuigb]

Suggested change

	-**Do not include the name of the cell type being defined at the start of the definition.** Instead, the genus cell type should be named here.
	- **Do not include the name of the cell type being defined at the start of the definition.** Instead, the genus cell type should be named here.

[aleixpuigb]

Suggested change

Some cell types are defined with reference to transcriptomic data. This is especially common in brain datasets. In these cases, naming is often based on semi-automated transfer of names that are based on some specific set of properties. We do not always know how widely those properties apply, so we need to be careful in choosing them for differentia. Extended multi-modal descriptions may be available, for example, based on patch-seq data, but this is typically derived from very sparse data, so such information belongs in the extended definition, along with details of the brain regions where these properties have been assayed.

Some cell types are defined with references to transcriptomic data. This is especially common in brain datasets. In these cases, naming is often based on semi-automated transfer of names that are based on some specific set of properties. We do not always know how widely those properties apply, so we need to be careful in choosing them for differentia. Extended multi-modal descriptions may be available, for example, based on patch-seq data, but this is typically derived from very sparse data, so such information belongs in the extended definition, along with details of the brain regions where these properties have been assayed.

[aleixpuigb]

I think the Label is missing, and this paragraph should be definition. The double double-apostrophes are present again. Also, Comment is in bold, but label is not. I would not capitalize to differentiate with NOTE later.

[aleixpuigb]

I don't understand the second sentence, is something missing?

[github-actions]

This PR has not seen any activity in the past month; if nobody comments or reviews it in the next week, the PR editor will be allowed to proceed with merging without explicit approval, should they wish to do so.