Choose or make a lens

A lens says what is pulled out of each passage and what gets compared.

The built-in lenses#

A collection names its lens in its note, in the reader property.

The notes lens#

The notes lens reads your own notes as notes. A long note is read a section at a time, and the prompt names the note and the section.

It pulls out four kinds of card:

• idea: something worth trying or developing.
• claim: a position the note takes, with what supports it.
• decision: what was chosen, why, and what was ruled out.
• question: something still open, and why it is open.

Each card carries a basis that says where the point comes from, not what it is about: own for your own thinking, source for something you read or watched, experience for something you lived or did, and discussion for a conversation or meeting. Search can narrow by it, so you can tell your own thinking from what you copied in.

The lens also reads three of each note’s properties into every prompt: tags, status and created. A note without one is read as unknown for it. To read more properties, such as project, list them in the collection note’s fields (see Make a collection), or tick them in a survey.

A new collection made from a folder, a tag or a Base starts on the notes lens. A collection you made earlier keeps its lens.

Switch an older collection to notes#

A collection of notes or Base rows that is read by the nonfiction or fiction lens shows a Read as notes row in its dialog (Settings → Topic Map → Collections, then select the collection). The row gives the cost of switching, worked out without calling a model. Select Switch to notes to change the note’s reader to notes.

• Switching starts a new index, so every section is read again. The old index stays where it is until you remove it.
• The switch is logged like any other run. Undo a run (or the panel’s Runs tab) puts the lens back.

Make your own#

1. Open Settings → Topic Map → Lenses and select Customize… beside a built-in lens. Or run Customize this lens… (the panel’s Setup menu).
2. Topic Map shows what it will write, then makes a folder in Model Hub's skills folder.
3. Add your changes to its reader.yml.
4. In Model Hub, reload the skills. Your lens then shows under Yours on the Lenses tab.
5. Name it in a collection note's reader property.

Your lens extends the built-in one: it holds only what you change, so you keep the built-in's later improvements.

A facet can set group_by to the name of one of its fields. That field names a card, and cards of that facet with the same name and meaning are shown as one. The built-in lenses group concepts by term, ideas by idea and motifs by motif. A lens that extends a built-in one keeps this; set group_by: null on a facet to turn it off.

A lens is a Model Hub skill: a folder with SKILL.md, reader.yml and a prompts folder. Model Hub needs a skills folder set in its settings.

Domain libraries#

A domain library defines kinds of card once, so several lenses can share them. It is a Model Hub skill with a domains.yml, which holds:

• domains: kinds of card read together with the passage.
• addons: kinds of card read in a later pass.
• unit_fields: passage fields that a lens using its domains also gets.

Each domain has a two-letter key, a count, an about and its fields.

A lens uses a library with these keys in its reader.yml:

A lens with addons needs an add-on prompt: prompts/extract-addon.md in the lens, or extract-addon.md in the library.

Add-on passes#

An index run reads each passage once for the lens's own facets and its domains (pass 0). Then it runs each add-on pass, in order, on the passages pass 0 let through the lens's gate. A passage pass 0 gated out never reaches an add-on. A passage whose pass 0 failed, or isn't read yet, waits for it.

Each add-on pass is one more call per passage, and asks only for that pass's domains. Write a pass as a list of domains, or as a mapping with select:

addons:
  - {domains: [craft], select: craft}   # pass 1: only the passages the craft screen picks
  - [voice]                             # pass 2: every passage pass 0 let through

select: craft reads the passage field craft_notable, a whole number from 0 to 3 that pass 0 gives each passage. Put it in the lens's unit_fields or in the library's. In each book the pass takes:

• every passage scored 3;
• passages scored 2, spread evenly through the book, up to 5% of the book's passages;
• the book's first and last passage that pass 0 let through.

The pick is the same every time for the same scores.

What an add-on reads is kept under its own key, which includes the pass, its domains and the add-on prompt. So:

• adding an add-on pass, or changing one, never reads pass 0 again;
• rewording extract-addon.md reads that pass again, but not pass 0;
• a run stopped part way through a pass carries on from what it kept, and nothing kept is paid for twice.

The dry run counts each pass's reads in its passages to read, and prices them. It also says how many passages each pass is waiting on: those need pass 0 first, so a new collection's add-on reads are known only once pass 0 has run. Undo a run takes back what the run's add-on passes read, with their cards.

Topic Map refuses a lens that names a domain its library lacks, lists a domain in two passes, or rewords a field the domain doesn't have. Each refusal names the line at fault. A worked example, a library and a lens that uses it, is in the repository's docs/examples/lens-domains.

Check your lenses#

Run Check my lenses (the panel’s Setup menu), or use the check button on the Lenses tab. It lists any problem in plain words, with the line at fault. Topic Map also checks on its own after an update.

A lens in an older format still works, and the check offers to rewrite it in the current one. The rewrite happens only when you select Rewrite, and it has no undo.

What a lens changes later#

Changing a lens changes what is sent for each passage, so the next index run reads the affected passages again. The dry run shows how many.

Related#

• Make a collection
• Survey a collection