From 8bde14369090c8ef1b8b7b7d1bf368b5a40616e5 Mon Sep 17 00:00:00 2001 From: kara-mela Date: Fri, 19 Jun 2026 11:21:16 +0200 Subject: [PATCH 1/2] Init Best Practice for New Terms Motivation The new structure of PaNET brings more possibilities, but also more challenges for creating a new term. To help researchers and PaNET members adding new terms, we should provide a best practice document on our webpage. Modification An initial version of the Best Practice document has been added. This also required to add some images and to update the css file as well as to link it in the navigation bar. Result Better guidance. --- docs/_data/navigation.yml | 3 + docs/assets/css/custom.css | 92 +++++-- docs/assets/images/new_issue.svg | 47 ++++ docs/assets/images/new_term_request.svg | 47 ++++ docs/best_practice_new_term.html | 317 ++++++++++++++++++++++++ 5 files changed, 489 insertions(+), 17 deletions(-) create mode 100644 docs/assets/images/new_issue.svg create mode 100644 docs/assets/images/new_term_request.svg create mode 100644 docs/best_practice_new_term.html diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml index 803edf1..b3e6669 100644 --- a/docs/_data/navigation.yml +++ b/docs/_data/navigation.yml @@ -30,6 +30,9 @@ - name: Code of Conduct link: "/CODE_OF_CONDUCT.html" description: Guidelines for ethical behaviour, respectful interactions, and community standards. + - name: Add a New Term + link: "/best_practice_new_term.html" + description: Guidelines for adding a new technique to PaNET. - name: Technical References link: "/build.html" diff --git a/docs/assets/css/custom.css b/docs/assets/css/custom.css index 01dfc01..eb62cfe 100644 --- a/docs/assets/css/custom.css +++ b/docs/assets/css/custom.css @@ -2,13 +2,14 @@ :root { /* New PANET color palette */ - --panet-pink: rgb(186, 69, 118); - --panet-purple: rgb(101, 109, 177); - --panet-blue-cyan: rgb(129, 183, 228); - --panet-dark-blue: rgb(16, 55, 100); - --panet-black: rgb(17, 33, 62); - --panet-light-grey: rgb(248, 249, 250); + --panet-pink: rgb(186, 69, 118); + --panet-purple: rgb(101, 109, 177); + --panet-blue-cyan: rgb(129, 183, 228); + --panet-dark-blue: rgb(16, 55, 100); + --panet-black: rgb(17, 33, 62); + --panet-light-grey: rgb(248, 249, 250); --panet-border-grey: rgb(220, 224, 228); + --panet-light-blue: rgb(208, 226, 240); } /* Fixed Header Styles */ @@ -71,6 +72,11 @@ body { box-shadow: 0 0 20px rgba(17, 33, 62, 0.1); } +mark { + color: var(--panet-dark-blue); + background-color: var(--panet-light-blue); +} + #content { display: flex; width: 100%; @@ -254,7 +260,27 @@ body { } } -.content-section h2 { +.hidden { + position: absolute; + left: -1000px; + top: -1000px; + width: 0; + height: 0; + overflow: hidden; + display: inline; +} + +.content-section h1, summary.h1 { + color: var(--panet-purple); + font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; + font-size: 2rem; /* Reduced from 2.2rem to 2rem */ + margin: 35px 0 20px 0; /* Reduced margins from 40px 0 25px 0 */ + font-weight: 600; + border-left: 5px solid var(--panet-pink); + padding-left: 20px; +} + +.content-section h2, summary.h2 { color: var(--panet-dark-blue); font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; font-size: 2.8rem; /* Reduced from 3.2rem to 2.8rem */ @@ -266,22 +292,54 @@ body { text-shadow: 0 1px 2px rgba(17, 33, 62, 0.1); } -.content-section h1 { - color: var(--panet-purple); - font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; - font-size: 2rem; /* Reduced from 2.2rem to 2rem */ - margin: 35px 0 20px 0; /* Reduced margins from 40px 0 25px 0 */ +.content-section h3, summary.h3 { + color: var(--panet-dark-blue); + font-size: 1.4rem; /* Reduced from 1.6rem to 1.4rem */ font-weight: 600; - border-left: 5px solid var(--panet-pink); - padding-left: 20px; + margin: 25px 0 15px 0; /* Reduced margins from 30px 0 20px 0 */ + font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; } -.content-section h3 { +#scope-sidebar h4, summary.h4 { color: var(--panet-dark-blue); - font-size: 1.4rem; /* Reduced from 1.6rem to 1.4rem */ + font-size: 1.4rem; font-weight: 600; - margin: 25px 0 15px 0; /* Reduced margins from 30px 0 20px 0 */ + margin: 15px 0 5px 0; + font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; + font-style: italic; +} + +#scope-sidebar h5, summary.h5 { + color: var(--panet-dark-blue); + font-size: 1.2rem; + font-weight: normal; + margin: 10px 0 5px 0; font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; + font-style: italic; +} + +.code-block { + background: var(--panet-light-grey); + color: var(--panet-black); + padding: 8px; + border-radius: 8px; + border: 2px solid var(--panet-border-grey); + overflow-x: auto; + font-family: 'Fira Code', monospace; + line-height: 1.5; +} + +#ID_ranges { + padding-left: 24px; +} + +#ID_ranges td, th { + padding: 4px 12px; +} + +#ID_ranges td:nth-child(2), +#ID_ranges td:nth-child(3) { + text-align: right; } .content-section p { diff --git a/docs/assets/images/new_issue.svg b/docs/assets/images/new_issue.svg new file mode 100644 index 0000000..ac40a07 --- /dev/null +++ b/docs/assets/images/new_issue.svg @@ -0,0 +1,47 @@ + + + + diff --git a/docs/assets/images/new_term_request.svg b/docs/assets/images/new_term_request.svg new file mode 100644 index 0000000..20a32af --- /dev/null +++ b/docs/assets/images/new_term_request.svg @@ -0,0 +1,47 @@ + + + + diff --git a/docs/best_practice_new_term.html b/docs/best_practice_new_term.html new file mode 100644 index 0000000..3d02350 --- /dev/null +++ b/docs/best_practice_new_term.html @@ -0,0 +1,317 @@ +--- +--- + +

Best Practice: New Terms

+ +

+ The text is mainly written for researchers to guide them in adding a new term to PaNET. +

+ +Blue texts are additional information for the PaNET maintenance group and can be ignored. + + +A new term can be a technique, a specifier, and/or a relationship. + +
+ Technical Steps to Request a New Term + + +
    +
  1. + Make sure that the term is note yet listed in PaNET, e.g. search this page. +
    2. +
  2. + Create a new issue by clicking the green "New issue" button on the "Issues" page. + screenshot of the PaNET GitHub webpage with the location of the 'new issue' button.
    + Use the template "New term request".
    + screenshot of the PaNET GitHub webpage after pressing the 'new issue' button. +
    3. +
  3. + Follow the recommendations on Required Information. +
    4. +
  4. + Publish the Issue by clicking the green "Create" button at the bottom. +
    5. +
  5. + Wait for approval by the PaNET team, often after a discussion. +
    6. +
  6. + Create a pull request. This step should be taken by the requester, but can also be handled by any other participant of the discussion. This might depend on how familiar the requester is with handling the PaNET.csv. Follow the recommendations on Pull Request for New Terms. +
    7. +
+
+ +
+ Required Information + + +

+ Decide what kind of term you want to add: +

+

+ +

Title

+ +

+ Create a meaningful title, e.g. "New term: X-ray Absorption Spectroscopy". +

+ +

New term label

+ +

+ Assign a fitting name to the term. If multiple options are suitable, choose a full-text representation, you can designate abbreviations and additional names as synonyms later on. +

+ +

Definition

+ +

+ Use a self-explanatory, short description. Please avoid explaining a term with itself. +

+ +

Position in the ontology

+ +

+ The position in the ontology is described by the type of the relationship (axiom type) and a related term that already exists in the ontology. +

+ +

+ Possible axiom types for techniques and specifiers +

+

+

+ Check if more general (parent class) or more specific (child class) techniques already exist, e.g. "diffraction" is a more general term for "powder diffraction". Add those with the strongest relations as super- and subclasses. Please give their PaNET IDs. +

+ +

+ Check if the use specifiers is beneficial, e.g. "scanning probe" as an additional descriptor to "transmission x-ray microscopy". These terms are usually (direct) subclasses of +

+ Please give their PaNET IDs. +

+ +

+ + For Maintainers: Possible axiom types for relationships (object properties) +

+ +

+ +

What if a required specifier or superclass does not exist?

+ +

+ Please create a sub-issue to add the missing specifier or term, using the same template to make a "New term request". +

+

+ Example: +

    +
  1. + New term is "x-ray absorption spectroscopy in transmission mode" and "x-ray absorption spectroscopy" exists in PaNET, but "transmission mode" (or something equivalent) does not. +
    2. +
  2. + Add "transmission mode (to be done)" iIn the hierarchy section. +
    3. +
  3. + After publishing this issue, you find a box in your post "Create sub-issue", use it to create a new term request on "transmission mode". +
    4. +
+

+ +

Synonyms

+ +

+ Synonyms can be abbreviations. +

+ +

Cross-References

+ +

+ Add a cross-reference to a reliable (as persistent as possible) source, e.g. link to Wikidata. +

+

+ Add DOIs of 1 or 2 peer-reviewed journal articles using the technique. +

+ +

Motviation

+ +

+ Add a brief motivation on why this technique should be added, e.g. technique used at your facility, with a link to a website that proves this. +

+
+ +
+ Pull Request for New Term + + +

How to choose the ID for the New Term?

+ +

+ The ID for a new term depends on its type: technique, specifier, or relationship. +

+ +
Generally intended ID ranges
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeMin. IDMax. ID
Techniques0999999
"defined by ..." terms299
"defined by experimental probe" terms100199
"defined by experimental physical process" termss200299
"defined by functional dependence" terms300399
"defined by purpose" terms400499
Other, more specific terms1000999999
Relationships10000001999999
Specifier2000000
+ +
New "defined by ..." term
+

+ When a new "defined by..." term is created, it will receive an ID i in the range 2 to 99. Its subclasses will cover the ID range (i-1)*100 to i*100-1. +

+

+ Example: "defined by functional dependence" (PaNET00004) with subclasses in PaNET00300 to PaNET00399. +

+ +

Check consistency of the ontology

+ + + For Maintainers: Please check the changes in axioms caused by adding the new term and the relationships. This will guarantee that no unexpected subclass relationships have been added or correct subclass relationships have been removed. +
    +
  1. + Download the latest PaNET.csv file from the GitHub Repository, and the modified CSV file that you want to add to the pull request. The former acts as the "reference" file with which the latter will be compared. +
    2. +
  2. + Use the ROBOT template command to build an OWL file for each of the two CSV files. Here is a template for the code: + 
    
+dcterms_prefix=${DCTERMS_PREFIX:-terms}
+robot \                                                                        
+    template \
+        --template "PaNET.csv" \
+        --prefix "PaNET: http://purl.org/pan-science/PaNET/" \
+    reason --reasoner hermit \
+        --remove-redundant-subclass-axioms false \
+        --include-indirect false \
+        --exclude-tautologies all \
+        --axiom-generators "$generated_axioms" \
+    annotate \
+        --ontology-iri "http://purl.org/pan-science/PaNET/PaNET.owl" \
+        --add-prefix "sdo: http://schema.org/" \
+        --add-prefix "${dcterms_prefix}: http://purl.org/dc/terms/" \
+        --output "PaNET.owl" \
+    reason \
+        --reasoner hermit \
+        --remove-redundant-subclass-axioms false \
+        --include-indirect true \
+        --exclude-tautologies all \
+        --axiom-generators "$generated_axioms" \
+        --output "PaNET with inferred axioms.owl"
+
    +
    3. +
  3. + Use the ROBOT diff command to compare the two OWL files. This will produce an output text file that lists the differences between the two OWL files. Here is a template for the code: + 
    
+robot diff --left "PaNET_reference.owl" --right "PaNET_new.owl" --output compare.txt
+
    +
    4. +
  4. + Check the text file to make sure that there are no unexpected changes in the taxonomic structure of PaNET. +
    5. +
+ +
From 647558d9a59da4211109fa1272ef7de8cccee849 Mon Sep 17 00:00:00 2001 From: kara-mela Date: Fri, 19 Jun 2026 11:26:43 +0200 Subject: [PATCH 2/2] Improve design of headings Motivation While working on the Best Practice document, I realized that some commands in the css file were wrong and therefore effectless. By activating them, I also realized that the headings were often too big and pompous. Modification Changed ".content-section h{1,2,3}" to "#scope-sidebar h{1,2,3}" to activate the design. Updated the layout. Result More balanced design. --- docs/assets/css/custom.css | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/assets/css/custom.css b/docs/assets/css/custom.css index eb62cfe..ab2784a 100644 --- a/docs/assets/css/custom.css +++ b/docs/assets/css/custom.css @@ -270,33 +270,29 @@ mark { display: inline; } -.content-section h1, summary.h1 { +#scope-sidebar h1, summary.h1 { color: var(--panet-purple); font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; - font-size: 2rem; /* Reduced from 2.2rem to 2rem */ - margin: 35px 0 20px 0; /* Reduced margins from 40px 0 25px 0 */ + font-size: 2.5rem; + margin: 35px 0 20px 0; font-weight: 600; - border-left: 5px solid var(--panet-pink); - padding-left: 20px; } -.content-section h2, summary.h2 { +#scope-sidebar h2, summary.h2 { color: var(--panet-dark-blue); font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; - font-size: 2.8rem; /* Reduced from 3.2rem to 2.8rem */ - margin-bottom: 25px; /* Reduced from 30px to 25px */ - border-bottom: 4px solid var(--panet-pink); - padding-bottom: 15px; /* Reduced from 20px to 15px */ + font-size: 2rem; + margin: 25px 0 15px 0; font-weight: 700; line-height: 1.1; text-shadow: 0 1px 2px rgba(17, 33, 62, 0.1); } -.content-section h3, summary.h3 { +#scope-sidebar h3, summary.h3 { color: var(--panet-dark-blue); - font-size: 1.4rem; /* Reduced from 1.6rem to 1.4rem */ + font-size: 1.4rem; font-weight: 600; - margin: 25px 0 15px 0; /* Reduced margins from 30px 0 20px 0 */ + margin: 25px 0 15px 0; font-family: "Inter", "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; }