Query documentation

check_images.py

@@ -15,6 +15,24 @@
 DEFAULT_EXTENSIONS = ['.md', '.html', '.yml', '.yaml', '.toml', '.json', '.js', '.ts', '.scss', '.css']
 
 
+def is_templated(url: str) -> bool:
+    """True for URLs that are template strings, not real links.
+
+    Hugo/Go templates build image URLs with a placeholder filled in at render
+    time, e.g. `printf "https://i.ytimg.com/vi/%s/hqdefault.jpg" $id` or a
+    `{{ ... }}` expression. Fetching the literal template string 404s, so skip
+    it. A printf verb is a `%` followed by a letter that cannot begin a valid
+    `%HH` percent-encoding (i.e. not a-f), which distinguishes `%s`/`%v` from
+    genuinely encoded characters like `%2F` or `%FF`.
+    """
+    if '{{' in url or '}}' in url:
+        return True
+    return any(
+        m.group(1).isalpha() and m.group(1).lower() not in 'abcdef'
+        for m in re.finditer(r'%(.)', url)
+    )
+
+
 def collect_image_urls(base_dir: pathlib.Path, ext_filter=None):
     ext_filter = ext_filter or DEFAULT_EXTENSIONS
     matches = []
@@ -23,7 +41,10 @@ def collect_image_urls(base_dir: pathlib.Path, ext_filter=None):
             continue
         text = path.read_text(encoding='utf-8', errors='ignore')
         for m in IMAGE_PATTERN.finditer(text):
-            matches.append((str(path), m.group(0)))
+            url = m.group(0)
+            if is_templated(url):
+                continue
+            matches.append((str(path), url))
     return matches
 
 

content/en/docs/APIs/PDB.md

@@ -26,7 +26,7 @@ The PDB contains over 1.1 million nodes and 43 million relationships, representi
 The PDB uses hierarchical node labels to classify different types of entities:
 
 **Core Ontology Nodes:**
-- `Class`, `Individual` - OWL ontology elements
+- `Class`, `Individual` - OWL ontology elements (see [Classes and individuals](/docs/concepts/classes-and-individuals/) for what the distinction means in VFB)
 - `Property` - Relationships and attributes
 
 **Anatomical Classifications:**

content/en/docs/Concepts/cell_types.md

@@ -10,6 +10,8 @@ description: >
 
 Neurons on VFB are annotated with cell types from the Drosophila Anatomy Ontology (FBbt).
 
+A cell type is a [class](/docs/concepts/classes-and-individuals/) — an ontology term for a *type* of neuron — as opposed to an individual reconstructed or imaged neuron, which is an instance of one.
+
 <img src="/images/cell_types/FW_MBON01-terminfo.png" max-width="50%" alt="A FlyWire MBON01 neuron">
 
 ## Why do we use ontology terms?

content/en/docs/Concepts/classes-and-individuals.md

@@ -0,0 +1,62 @@
+---
+title: "Classes and Individuals"
+linkTitle: "Classes & Individuals"
+weight: 301
+categories: ["overview","help"]
+tags: ["class","individual","instance","ontology","FBbt","term info"]
+description: >
+  The difference between a class (a type of thing) and an individual (a specific
+  instance) in VFB.
+---
+
+VFB describes two kinds of thing, and it helps to know which you are looking at:
+**classes** and **individuals**.
+
+## Classes
+
+A **class** is an ontology term — a general *type* of thing rather than any one
+example of it. "Kenyon cell", "medulla" and "GABAergic neuron" are classes. Each
+class:
+
+- represents a concept, with a definition based on referenced publications;
+- has a label and a set of synonyms;
+- sits in a hierarchy — a specific class such as "MBON01" is a subclass of the
+  more general "mushroom body output neuron", and so on up to "adult neuron";
+- has a persistent, resolvable identifier (for example
+  [FBbt_00100234](https://virtualflybrain.org/reports/FBbt_00100234)).
+
+Most classes in VFB come from the Drosophila Anatomy Ontology (FBbt) for anatomy
+and cell types; genes, developmental stages and biological processes are also
+represented as classes. See [Cell Types](/docs/concepts/cell_types/) for how
+neurons are classified.
+
+## Individuals
+
+An **individual** is a specific *instance* — one concrete example of one or more
+classes. Individuals include:
+
+- a single neuron reconstructed from an EM volume, or one confocal image of an
+  expression pattern;
+- a template brain;
+- a dataset;
+- an scRNAseq cluster;
+- a publication.
+
+An individual is an **instance of** one or more classes: a particular
+reconstructed neuron is an instance of a neuron-type class, which is what tells
+you what type of cell it is. A single individual can be an instance of several
+classes at once.
+
+## Telling them apart on VFB
+
+Both classes and individuals have their own
+[Term Info](/docs/website-features/terminfo/) pages. The `Name` field's tags,
+together with the `Classification` and `Relationships` fields, show how an entity
+is typed and how it relates to the classes above it. As a rough guide, anatomy
+and cell-type **classes** carry ontology identifiers such as `FBbt_…`, while
+**individuals** (images, templates, datasets) usually carry `VFB_…` identifiers.
+
+The distinction matters when [querying](/docs/website-features/queries/): queries
+are specialised by type, so some run on classes (for example *Subclasses of…* or
+*Neurons with some part in…*) and others run on individuals (for example the
+connectivity and similarity queries for a single reconstructed neuron).