Skip to content

Commit

Permalink
Merge branch 'master' into issue392-docs-frontpage
Browse files Browse the repository at this point in the history
  • Loading branch information
@matentzn
matentzn committed Nov 4, 2024
2 parents 8239dee + c09299b commit 561df2b
Show file tree
Hide file tree
Showing 3 changed files with 144 additions and 79 deletions.
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ markdown_extensions:
- pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
- admonition
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
Expand Down
105 changes: 81 additions & 24 deletions src/doc-templates/index.md.jinja2
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,94 @@
# {% if schema.title %}{{ schema.title }}{% else %}{{ schema.name }}{% endif %}
# SSSOM Official Data Model Documentation

![SSSOM banner](images/sssom-banner.png)

{% if schema.description %}{{ schema.description }}{% endif %}

URI: {{ schema.id }}
**Schema PURL**: {{ schema.id }}

## Introduction

While the SSSOM model is quite general and mappings can be shared in different formats, the most common format is the [SSSOM/TSV format](spec-formats-tsv.md).
Here is a tabular representation of some example mappings for illustration purposes:

| subject_id | subject_label | predicate_id | object_id | object_label | mapping_justification | author_id | confidence | comment |
|---------------|---------------|-----------------|-----------------|----------------------|-----------------------------|-------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------|
| KF_FOOD:F001 | apple | skos:exactMatch | FOODON:00002473 | apple (whole) | semapv:ManualMappingCuration | orcid:0000-0002-7356-1779 | 0.95 | "We could map to FOODON:03310788 instead to cover sliced apples, but only 'whole' apple types exist." |
| KF_FOOD:F002 | gala | skos:exactMatch | FOODON:00003348 | Gala apple (whole) | semapv:ManualMappingCuration | orcid:0000-0002-7356-1779 | 1.0 | |
| KF_FOOD:F003 | pink | skos:exactMatch | FOODON:00004186 | Pink apple (whole) | semapv:ManualMappingCuration | orcid:0000-0002-7356-1779 | 0.9 | "We could map to FOODON:00004187 instead which more specifically refers to 'raw' Pink apples. Decided against to be consistent with other mapping choices." |
| KF_FOOD:F004 | braeburn | skos:broadMatch | FOODON:00002473 | apple (whole) | semapv:ManualMappingCuration | orcid:0000-0002-7356-1779 | 1.0 | |

In the TSV format, mapping set metadata is included at the top of the file, before the mappings themselves, in yaml-like key-value pairs:


!!! info "Example header (YAML format)"

<pre>
curie_map:
FOODON: http://purl.obolibrary.org/obo/FOODON_
KF_FOOD: https://kewl-foodie.inc/food/
orcid: https://orcid.org/
mapping_set_id: https://w3id.org/sssom/tutorial/example1.sssom.tsv
mapping_set_description: >
Manually curated alignment of KEWL FOODIE INC internal food and
nutrition database with Food Ontology (FOODON). Intended to be
used for ontological analysis and grouping of KEWL FOODIE INC
related data.
license: https://creativecommons.org/licenses/by/4.0/
mapping_date: 2022-05-02
</pre>

See [here](https://github.com/mapping-commons/sssom/tree/master/examples/schema) for concrete examples.

Name: {{ schema.name }}

{% if include_top_level_diagram %}
## Mapping metadata elements

{% for c in gen.all_class_objects()|sort(attribute=sort_by) -%}
{% if c.name == "mapping" %}
{{gen.link(c)}}: {{c.description|enshorten}}

| Column/Field | Description | Required |
|--------------------|---------------------------------------------------------|-------------|
{%- for slot in c.slots %}
{%- set slot_info = schemaview.get_slot(slot) %}
| **{{ gen.link(slot) }}** | {{ slot_info.description | default("No description") }} | {% if slot_info.required | default(false) %}Required{% elif slot_info.recommended | default(false) %}Recommended{% else %}Optional{% endif %} |
{%- endfor %}
{%- endif %}
{%- endfor %}

## Mappings set metadata elements

{% for c in gen.all_class_objects()|sort(attribute=sort_by) -%}
{% if c.name == "mapping set" %}
{{gen.link(c)}}: {{c.description|enshorten}}

| Column/Field | Description | Required |
|--------------------|---------------------------------------------------------|-------------|
{%- for slot in c.slots %}
{%- set slot_info = schemaview.get_slot(slot) %}
| **{{ gen.link(slot) }}** | {{ slot_info.description | default("No description") }} | {% if slot_info.required | default(false) %}Required{% elif slot_info.recommended | default(false) %}Recommended{% else %}Optional{% endif %} |
{%- endfor %}
{%- endif %}
{%- endfor %}

{#
## Schema Diagram
```{{ gen.mermaid_directive() }}
{{ gen.mermaid_diagram() }}
```
{% endif %}
#}
## Index (all classes, enums and elements)

## Classes
### Columns/Slots/Fields

| Slot | Description |
| --- | --- |
{% for s in gen.all_slot_objects()|sort(attribute=sort_by) -%}
| {{gen.link(s)}} | {{s.description|enshorten}} |
{% endfor %}

### Classes

| Class | Description |
| --- | --- |
Expand All @@ -29,34 +102,18 @@ Name: {{ schema.name }}
{% endfor %}
{% endif %}

## Slots

| Slot | Description |
| --- | --- |
{% for s in gen.all_slot_objects()|sort(attribute=sort_by) -%}
| {{gen.link(s)}} | {{s.description|enshorten}} |
{% endfor %}

## Enumerations
### Enumerations

| Enumeration | Description |
| --- | --- |
{% for e in gen.all_enum_objects()|sort(attribute=sort_by) -%}
| {{gen.link(e)}} | {{e.description|enshorten}} |
{% endfor %}

## Types
### Types

| Type | Description |
| --- | --- |
{% for t in gen.all_type_objects()|sort(attribute=sort_by) -%}
| {{gen.link(t)}} | {{t.description|enshorten}} |
{% endfor %}

## Subsets

| Subset | Description |
| --- | --- |
{% for ss in schemaview.all_subsets().values()|sort(attribute='name') -%}
| {{gen.link(ss)}} | {{ss.description|enshorten}} |
{% endfor %}
117 changes: 62 additions & 55 deletions src/doc-templates/slot.md.jinja2
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
# Slot: {{ gen.name(element) }}
# {{ gen.name(element) }}

{%- if header -%}
{{header}}
{%- endif -%}
**URI**: {{ gen.uri_link(element) }}

{% if element.description %}
{% set element_description_lines = element.description.split('\n') %}
{% for element_description_line in element_description_lines %}
_{{ element_description_line }}_
{% endfor %}
{% endif %}

URI: {{ gen.uri_link(element) }}
**Applicable to**: {% for c in schemaview.get_classes_by_slot(element, include_induced=True) %}{{ gen.link(c) }}{% if not loop.last %}, {% endif %}{% endfor -%}

{%- if element.description %}
{%- set element_description_lines = element.description.split('\n') %}
!!! info "Description"

{% for element_description_line in element_description_lines %}
_{{ element_description_line }}_
{%- endfor %}
{%- endif -%}
{#
{% if schemaview.slot_parents(element.name) or schemaview.slot_children(element.name, mixins=False) %}
## Inheritance
Expand All @@ -24,19 +23,10 @@ URI: {{ gen.uri_link(element) }}
{% endif %}
{% if schemaview.get_classes_by_slot(element, include_induced=True) %}

## Applicable Classes

| Name | Description | Modifies Slot |
| --- | --- | --- |
{% for c in schemaview.get_classes_by_slot(element, include_induced=True) -%}
{{ gen.link(c) }} | {{ schemaview.get_class(c).description|enshorten }} | {% if c in schemaview.get_classes_modifying_slot(element) %} yes {% else %} no {% endif %} |
{% endfor %}

{% endif %}


#}
{#
{% if schemaview.is_mixin(element.name) %}
## Mixin Usage
| mixed into | description | range | domain |
Expand All @@ -45,31 +35,18 @@ URI: {{ gen.uri_link(element) }}
| {{ gen.link(s) }} | {{ schemaview.get_slot(s).description|enshorten }} | {{ schemaview.get_slot(s).range }} | {{ schemaview.get_classes_by_slot(schemaview.get_slot(s))|join(', ') }} |
{% endfor %}
{% endif %}

#}
## Properties

* Range: {{gen.link(element.range)}}
{% if element.multivalued %}
* Multivalued: {{ element.multivalued }}
{% endif -%}
{% if element.required %}
* Required: {{ element.required }}
{% elif element.recommended %}
* Recommended: {{ element.recommended }}
{% endif -%}
{% if element.minimum_value is not none %}
* Minimum Value: {{ element.minimum_value|int }}
{% endif -%}
{% if element.maximum_value is not none %}
* Maximum Value: {{ element.maximum_value|int }}
{% endif -%}
{% if element.pattern %}
* Regex pattern: {{ '`' }}{{ element.pattern }}{{ '`' }}
{% endif -%}
{% if schemaview.is_mixin(element.name) %}
* Mixin: {{ element.mixin }}
{% endif -%}

* **Range**: {{gen.link(element.range)}}. The range of the element is the type of the value that can be assigned to it.
{% if element.multivalued %}* **Multivalued**: {{ element.multivalued }}. If the element is multivalued, more than one value can be attached to the same field. In the TSV format, these are `|` separated.{% endif %}
* **Required?**: {% if element.required %}Required (element has to be added to the mapping or mapping set.)
{% elif element.recommended %}Recommended (We suggest adding this element to the mapping or mapping set, but it is not required.
{% else %}Optional (You can add this element to the mapping or mapping set, but it is not required.){% endif -%}
{% if element.minimum_value is not none %}* **Minimum Value**: {{ element.minimum_value|int }}{% endif -%}
{% if element.maximum_value is not none %}* **Maximum Value**: {{ element.maximum_value|int }}{% endif -%}
{% if element.pattern %}* **Regex pattern**: {{ '`' }}{{ element.pattern }}{{ '`' }}{% endif -%}
{#
{% if schemaview.usage_index().get(element.name) %}
## Usages
Expand All @@ -80,17 +57,47 @@ URI: {{ gen.uri_link(element) }}
| {{gen.link(usage.used_by)}} | {{gen.link(usage.slot)}} | {{usage.metaslot}} | {{ gen.link(usage.used) }} |
{% endfor %}
{% endif %}
#}
{% if element.examples %}
## Examples

{% for x in element.examples -%}
!!! example "Example: {{ x.value }}"

<strong>Example value</strong>:

```
{{ x.value }}
```

{% if x.description %}<strong>Description</strong>: {{ x.description }}{% endif %}
{% endfor %}
{% endif -%}

{% if element.comments -%}
## Comments

{% include "common_metadata.md.jinja2" %}
{% for x in element.comments -%}
* {{x}}
{% endfor %}
{% endif -%}

{% if element.see_also -%}
## See Also

## LinkML Source
These are some relevant resources you might find useful to get additional information about the element,
such as example implementations, issues and pull requests.

{% for x in element.see_also -%}
* {{ gen.uri_link(x) }}
{% endfor %}
{% endif -%}

## Schema developer documentation

<details><summary>LinkML source</summary>

<details>
```yaml
{{ gen.yaml(element) }}
```
</details>

{%- if footer -%}
{{footer}}
{%- endif -%}
</details>

0 comments on commit 561df2b

Please sign in to comment.