108 lines
5.6 KiB
Markdown
108 lines
5.6 KiB
Markdown
# Research types and custom annotations
|
|
|
|
Research type describes a claimed characteristic of the work (for example a survey,
|
|
benchmark, empirical study or replication). It is independent of topic, paper length,
|
|
conference track, presentation format and acceptance status. No type is inferred from
|
|
those fields. Multiple source-specific or human classifications may coexist; no
|
|
cross-platform vocabulary mapping or automatic classifier is provided.
|
|
|
|
`annotation_events` stores both kinds with an explicit `kind` discriminator:
|
|
`research_type` and `tag` are separate domains, even when namespace/value strings
|
|
happen to coincide. Existing platform labels remain in `tags` / `paper_tags`.
|
|
Each assertion carries namespace, value, actor, reason, evidence key, optional source
|
|
record and evidence URL, and the time it was recorded. This is observation time, not
|
|
paper publication time or a conference decision date.
|
|
|
|
Values are not forced into a global taxonomy: `custom:method=empirical` and
|
|
`platform:declared_type=empirical` retain separate provenance. An explicit platform
|
|
assertion API requires a source record belonging to that paper and matching the
|
|
namespace prefix. The manual CLI only accepts `custom:*`, and cannot retract platform
|
|
assertions. No source type has been automatically assigned to existing papers.
|
|
|
|
## Initialize explicitly
|
|
|
|
On the published PostgreSQL dataset, using its protected service file:
|
|
|
|
```sh
|
|
PGSERVICEFILE=/etc/paper-atlas/pg_service.conf paper-atlas annotate init \
|
|
--pg-service foundry-research --pg-schema research
|
|
```
|
|
|
|
This creates one optional table, its indexes, and an upgrade marker in one transaction,
|
|
using the existing dataset writer lock. It does not copy data, change existing papers
|
|
or decisions, or create a PostgreSQL instance. Repeating it is safe; an unexplained
|
|
pre-existing table/marker mismatch fails closed. Readers and ordinary imports do not
|
|
install the extension. Legacy datasets remain readable. A SQLite **sample** uses
|
|
`--db sample.sqlite`; the cutover SQLite backup remains protected against writes.
|
|
|
|
## Add and retract evidence
|
|
|
|
Use the canonical paper ID returned by `query`. For a reviewed classification:
|
|
|
|
```sh
|
|
paper-atlas annotate assert --pg-service foundry-research --pg-schema research \
|
|
--paper "$PAPER_ID" --kind research_type --namespace custom:method \
|
|
--value empirical --evidence-key manual:abstract-review \
|
|
--actor reviewer --reason 'Classified from the explicitly described study design' \
|
|
--request-id "$REQUEST_ID"
|
|
```
|
|
|
|
`$REQUEST_ID` must be a new, stable identifier for this action (for example a UUID).
|
|
Retry with the same request ID and identical content after an interrupted response;
|
|
it returns the original event ID. Reusing that ID with changed content is rejected.
|
|
A topic annotation uses `--kind tag --namespace custom:topic --value robotics` instead.
|
|
Optional `--source-record` and `--evidence-url` attach additional evidence; the source
|
|
record must belong to this paper. URLs are retained as evidence and are not fetched.
|
|
|
|
To withdraw one particular assertion, use its returned event ID:
|
|
|
|
```sh
|
|
paper-atlas annotate retract --pg-service foundry-research --pg-schema research \
|
|
--event "$EVENT_ID" --actor reviewer --reason 'Classification corrected after review' \
|
|
--request-id "$RETRACTION_REQUEST_ID"
|
|
```
|
|
|
|
Retraction adds an event referencing that assertion, preserving its original content.
|
|
It does not remove another contributor's assertion of the same label, platform tags,
|
|
source metadata or submission/decision history. A retracted assertion can be asserted
|
|
again with a new request ID and evidence; it is a new observation. The API does not
|
|
update or delete past annotation events. Database administrators still control direct
|
|
SQL access. Work reviewed as the same paper may subsequently be merged by the existing
|
|
identity workflow: annotation IDs, original paper IDs, evidence and retraction links
|
|
are retained while the canonical paper reference follows the surviving entity.
|
|
|
|
## Query and analyze
|
|
|
|
```sh
|
|
paper-atlas query --pg-service foundry-research --pg-schema research \
|
|
--research-type custom:method=empirical
|
|
paper-atlas query --pg-service foundry-research --pg-schema research \
|
|
--tag custom:topic=robotics
|
|
paper-atlas query --pg-service foundry-research --pg-schema research \
|
|
--paper "$PAPER_ID" --annotation-history
|
|
paper-atlas annotate list --pg-service foundry-research --pg-schema research \
|
|
--paper "$PAPER_ID" --history
|
|
```
|
|
|
|
`--tag` includes original platform labels and active annotation tags. It never matches
|
|
research types. `--research-type` matches active type assertions only. Paper details
|
|
return separate `tags` (existing provenance), `annotation_tags`, and `research_types`;
|
|
`--annotation-history` additionally includes retractions. A missing extension yields
|
|
empty annotation results rather than changing the database.
|
|
|
|
For direct SQL analysis, active research-type evidence is:
|
|
|
|
```sql
|
|
SELECT a.* FROM research.annotation_events a
|
|
WHERE a.kind = 'research_type' AND a.retracts_id IS NULL
|
|
AND NOT EXISTS (SELECT 1 FROM research.annotation_events r WHERE r.retracts_id = a.id);
|
|
```
|
|
|
|
Several independent assertions can support one label; count distinct papers/labels
|
|
when appropriate rather than counting evidence rows as papers. Namespaces stay
|
|
separate. Standard paper queries decode the PostgreSQL text codec; direct SQL consumers
|
|
must honor the dataset's documented codec, including NUL/SOH values. SQLite-to-PostgreSQL
|
|
migration recognizes an installed annotation extension and verifies its full row hashes,
|
|
constraints and identity sequence along with the original business tables. An old
|
|
21-table snapshot stays a 21-table migration; no synthetic annotations are generated.
|