@biolibs/europepmc 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matthew Stewart
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,159 @@
1
- # Temporary Holding Version
1
+ # @biolibs/europepmc
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Searching the literature, and reading an open-access paper as sections, tables and figures instead of
4
+ as JATS XML. Europe PMC indexes PubMed, PubMed Central, preprints, patents and theses together, needs
5
+ no key and no account, and will hand over the whole text of an open-access paper.
6
+
7
+ - **`searchArticles`** — the literature by keyword, saying plainly whether each result's full text can
8
+ actually be read
9
+ - **`fullTextOf` and `readArticle`** — a paper, read out of its markup into sections with their
10
+ headings, tables as rows, and figures as captions
11
+ - **`sectionsNamed`** — the methods, however this particular journal chose to name them
12
+ - **`referencesOf` and `citationsOf`** — what a paper cited, and who has cited it since
13
+ - **Two dependencies**, `@biolibs/core` for the error class and `@biolibs/seqio` for the XML parser
14
+
15
+ ## What is verified
16
+
17
+ There is no Biopython counterpart, so there is no parity checklist and no reference implementation to
18
+ compare with. What there is instead:
19
+
20
+ | | |
21
+ |---|---|
22
+ | `test/europepmc.test.ts` | every tool, against a transport that answers instead of the network |
23
+ | | the awkward shapes of JATS, written out by hand rather than captured from one publisher |
24
+
25
+ Nothing in the tests reaches the internet. The JATS fixture is written by hand on purpose: a captured
26
+ file would check one publisher's habits, and what needs checking is the shape every publisher has in
27
+ common — sections inside sections, citation markers mid-sentence, a table where a paragraph would be.
28
+
29
+ ## Install
30
+
31
+ ```bash
32
+ npm install @biolibs/europepmc
33
+ ```
34
+
35
+ ## Searching
36
+
37
+ ```ts
38
+ import { searchArticles } from "@biolibs/europepmc";
39
+
40
+ const found = await searchArticles('"kappa-casein" AND "Pichia pastoris"', { corpus: "open-access", abstracts: true });
41
+ found.matched; // how many matched in all
42
+ found.results[0].title; // the full stop journals add is taken off
43
+ found.results.filter((one) => one.fullText); // the ones there is a full text to read
44
+ ```
45
+
46
+ The query takes plain words, phrases in quotes, and Europe PMC's fields: `TITLE:`, `ABSTRACT:`,
47
+ `AUTH:`, `JOURNAL:`, `PUB_YEAR:`, and `METHODS:`, which searches the methods sections of open papers
48
+ and is the one to reach for when looking for a technique rather than a subject.
49
+
50
+ **`openAccess` and `fullText` are not the same thing**, and the difference is the one that matters
51
+ before reading. The first is a licence. The second is whether the text is here. A paper can be open
52
+ access and not be in Europe PMC, and then there is the abstract and a link and nothing else.
53
+
54
+ ## Reading a paper
55
+
56
+ This is what the package is for. Europe PMC will give you a paper's whole text, but it gives it as
57
+ JATS: a hundred and eighty kilobytes of markup in which the one paragraph anybody wants is three
58
+ levels down inside nested `<sec>` elements, wrapped in `<italic>`, and interrupted every other
59
+ sentence by an `<xref>` that renders as "[14]".
60
+
61
+ ```ts
62
+ import { fullTextOf, readArticle, sectionsNamed } from "@biolibs/europepmc";
63
+
64
+ const paper = readArticle(await fullTextOf("PMC11767299"));
65
+ paper.title; // "Recombinant Production of Bovine αS1-Casein in …"
66
+ paper.licence; // "https://creativecommons.org/licenses/by/4.0/"
67
+ paper.sections.map((one) => one.heading); // "1. Introduction", "2. Materials and Methods", "2.1. …"
68
+
69
+ for (const part of sectionsNamed(paper, "methods")) console.log(part.heading, part.text);
70
+ // 2.4. Bioproduction of Recombinant Bovine αS1-Casein
71
+ // In shake flask cultivations, the pre-culture was prepared in LB medium (10 g/L tryptone, …) …
72
+
73
+ paper.tables[0];
74
+ // { label: "Table 1", caption: "Strains and plasmids.", headings: [...], rows: [[...], ...] }
75
+ ```
76
+
77
+ Three decisions are made in the reading, rather than left to whoever reads it afterwards.
78
+
79
+ **A citation marker is not text.** An `<xref>` pointing at the reference list is dropped, along with
80
+ the brackets it leaves standing, so "as described before by Sambrook and Russell []" comes out as a
81
+ sentence. One pointing at a table or a figure is kept, because "as Table 2 shows" is part of what the
82
+ sentence says.
83
+
84
+ **A table is not a paragraph.** Tables and figures are lifted out of the running text and kept apart
85
+ with their labels and captions, since a table flattened into prose is unreadable — and a yield is as
86
+ often in a table as in a sentence.
87
+
88
+ **A section's words are its own.** The walk does not descend into the sections inside one, or every
89
+ paragraph would be counted again at every level above it. A heading with no paragraphs of its own
90
+ comes back with none.
91
+
92
+ ## Finding the section somebody wants
93
+
94
+ ```ts
95
+ sectionsNamed(paper, "methods");
96
+ // "2. Materials and Methods" and everything under it, down to the next heading at its level
97
+
98
+ sectionsNamed(paper, "yeast");
99
+ // any heading with that word in it: "4.2. Caseins Expressed in Yeast"
100
+ ```
101
+
102
+ Papers do not agree about what to call anything. The methods are under "Materials and Methods",
103
+ "Methods and Materials", "Experimental Procedures" or just "Methods", with or without a number in
104
+ front, and the one thing they have in common is that no tool can rely on which. So the matching is
105
+ loose, the numbering is ignored, a heading that *is* one of the names beats one that merely contains
106
+ it, and the sections nested inside a match come with it — a yield under "2.4. Fermentation" belongs to
107
+ the methods even though its own heading does not say so.
108
+
109
+ ## Following a paper back and forward
110
+
111
+ ```ts
112
+ import { citationsOf, referencesOf } from "@biolibs/europepmc";
113
+
114
+ const back = await referencesOf("MED", "40723902"); // what it cited
115
+ const forward = await citationsOf("MED", "40723902"); // who has cited it since
116
+ ```
117
+
118
+ A method is almost never described where you first meet it: a paper says it expressed the gene "as
119
+ described previously" and gives a number, and the number is the paper with the actual recipe. Going
120
+ the other way says whether anybody managed to repeat it.
121
+
122
+ ## What is sent
123
+
124
+ ```ts
125
+ import { settings } from "@biolibs/europepmc";
126
+
127
+ settings.tool = "my-software"; // what to call this software. Never a person's name
128
+ settings.email = null; // nothing goes unless somebody sets one on purpose
129
+ settings.transport = myTransport; // swap the network out, which is how the tests run
130
+ ```
131
+
132
+ Europe PMC asks a client to name itself so that heavy use can be traced to a program. That name is the
133
+ only thing this package says about who is asking. An address is sent only if somebody puts one in the
134
+ settings deliberately; it is never taken from a document, a file or a device.
135
+
136
+ ## Testing
137
+
138
+ ```bash
139
+ npm test # the whole workspace
140
+ npx vitest run packages/europepmc/test
141
+ ```
142
+
143
+ ## Things to know
144
+
145
+ - **Most papers are not open access.** `fullTextOf` answers 404 for those, and says so in those words
146
+ rather than as a status code. There is the abstract from a search, and a link.
147
+ - **What a paper says is what one group reported.** It is not something anybody else has checked, and
148
+ a method that worked for them may not work elsewhere.
149
+ - **A reply is capped.** `settings.mostCharacters` refuses one larger than it, so a pathological
150
+ document cannot be read into memory whole.
151
+ - **A table with no `<thead>`** has its headings taken from its first row, which is what most
152
+ publishers that omit it mean.
153
+ - **Preprints are in here too**, under `SRC:PPR`, and are often where a method appears first. They
154
+ have not been reviewed, and `source` says so.
155
+ - **`matched` is usually far larger than what comes back.** Narrow the query rather than paging.
156
+
157
+ ## License
158
+
159
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,162 @@
1
+ /**
2
+ * An open-access paper's full text, read out of JATS XML into something a person can read.
3
+ *
4
+ * This is the part of the package that earns its keep. Europe PMC will hand over a paper's whole
5
+ * text, but it hands it over as JATS: a hundred and eighty kilobytes of markup in which the one
6
+ * paragraph somebody wants — which host, which promoter, what yield — is three levels down inside
7
+ * nested `<sec>` elements, wrapped in `<italic>` and interrupted every other sentence by an
8
+ * `<xref>` that renders as "[14]". Handing that on as it stands is not giving anybody the paper.
9
+ *
10
+ * So it is read into sections with their headings, tables as rows, and figures as captions, and
11
+ * three decisions are made here rather than left to whoever reads it:
12
+ *
13
+ * - **A citation marker is not text.** An `<xref>` pointing at the reference list is dropped, so a
14
+ * sentence reads as a sentence. One pointing at a table or a figure is kept, because "as Table 2
15
+ * shows" is part of what the sentence says.
16
+ * - **A table is not a paragraph.** Tables and figures are lifted out of the running text and kept
17
+ * apart, with their labels and captions, since a table flattened into prose is unreadable and a
18
+ * yield is as often in a table as in a sentence.
19
+ * - **A heading is worth more than its words.** Section headings are kept with their depth and
20
+ * their numbering, and {@link sectionsNamed} matches the loose way people name them, so that
21
+ * asking for the methods finds "2. Materials and Methods" and "Experimental Procedures" alike.
22
+ */
23
+ import { Element } from "@biolibs/seqio";
24
+ /** One section of a paper. */
25
+ export interface Section {
26
+ /** Its heading, or `""` for text that came before any heading. */
27
+ heading: string;
28
+ /** How deeply nested it is: 0 for a top-level section, 1 for one inside that. */
29
+ depth: number;
30
+ /** Its own paragraphs, not counting those of the sections inside it. */
31
+ text: string;
32
+ }
33
+ /** One table, as rows of cells. */
34
+ export interface Table {
35
+ /** What the paper calls it, such as `Table 2`. */
36
+ label: string;
37
+ /** What it says the table shows. */
38
+ caption: string;
39
+ /** The heading row's cells, if it has one. */
40
+ headings: string[];
41
+ /** The body rows, each a list of cells. */
42
+ rows: string[][];
43
+ }
44
+ /** One figure, which is a picture and so is only its words. */
45
+ export interface Figure {
46
+ /** What the paper calls it, such as `Figure 1`. */
47
+ label: string;
48
+ /** What it says the figure shows. */
49
+ caption: string;
50
+ }
51
+ /** A paper, read. */
52
+ export interface Article {
53
+ /** Its title. */
54
+ title: string;
55
+ /** The journal it was published in, and when. */
56
+ journal: string | null;
57
+ year: number | null;
58
+ /** The authors, surname first, as the paper writes them. */
59
+ authors: string[];
60
+ /** The abstract, as one piece of text. */
61
+ abstract: string;
62
+ /** The keywords the paper gives itself. */
63
+ keywords: string[];
64
+ /** Its sections, in the order they are written, each with its own paragraphs. */
65
+ sections: Section[];
66
+ /** Its tables and figures, lifted out of the running text. */
67
+ tables: Table[];
68
+ figures: Figure[];
69
+ /** What it is licensed under, where it says. */
70
+ licence: string | null;
71
+ }
72
+ /**
73
+ * The words of an element and everything inside it, as running text.
74
+ *
75
+ * A section's own words are its own: the walk does not go down into the sections inside it, or the
76
+ * text of every paragraph would be counted again at every level above it.
77
+ *
78
+ * @param element - The element.
79
+ * @param options - `keepTitle` keeps a `<title>` child's words, which is wanted for a caption and
80
+ * not for a section, whose heading is taken separately.
81
+ * @returns The text, with the markup gone and the spacing tidied.
82
+ */
83
+ export declare function wordsOf(element: Element, options?: {
84
+ keepTitle?: boolean;
85
+ }): string;
86
+ /**
87
+ * Read a paper out of its JATS XML.
88
+ *
89
+ * @param xml - The document, as Europe PMC sends it.
90
+ * @returns The paper.
91
+ * @throws {@link EuropePmcError} if that is not a JATS article.
92
+ *
93
+ * @example
94
+ * ```ts
95
+ * import { fullTextOf, readArticle, sectionsNamed } from "@biolibs/europepmc";
96
+ *
97
+ * const paper = readArticle(await fullTextOf("PMC12292773"));
98
+ * sectionsNamed(paper, "methods").map((one) => one.heading);
99
+ * ```
100
+ */
101
+ export declare function readArticle(xml: string): Article;
102
+ /** The kinds of section that can be asked for by name. */
103
+ export declare const SECTION_KINDS: string[];
104
+ /**
105
+ * The sections of a paper written under a given kind of heading.
106
+ *
107
+ * {@link findSection} is this, and says besides whether the heading was that name outright or only
108
+ * contained it, which is worth knowing before passing an answer on.
109
+ *
110
+ * Papers do not agree about what to call anything. The methods are under "Materials and Methods",
111
+ * "Experimental Procedures", "Methods", or a number and then one of those, and the one thing they
112
+ * have in common is that nobody writing a tool can rely on which. So the matching is loose, the
113
+ * numbering is ignored, and the sections *inside* a matching one come with it — a yield in "2.4.
114
+ * Fermentation" belongs to the methods even though its own heading does not say so.
115
+ *
116
+ * @param article - The paper.
117
+ * @param kind - What is wanted: `methods`, `results`, `discussion`, `introduction`, `conclusion`,
118
+ * or any other words, which are matched against the headings as they are.
119
+ * @returns The sections, in the order they are written. Empty if the paper has no such heading.
120
+ *
121
+ * @example
122
+ * ```ts
123
+ * import { sectionsNamed } from "@biolibs/europepmc";
124
+ *
125
+ * sectionsNamed(paper, "methods"); // "2. Materials and Methods" and everything under it
126
+ * sectionsNamed(paper, "casein"); // any heading with that word in it
127
+ * ```
128
+ */
129
+ export declare const sectionsNamed: (article: Article, kind: string) => Section[];
130
+ /**
131
+ * The sections of a paper written under a given kind of heading, and how they were found.
132
+ *
133
+ * {@link sectionsNamed} is this without the second part. The second part matters when the answer is
134
+ * going to be handed to somebody: a paper with no methods section at all still has headings with
135
+ * the word "methods" in them, and "BNBMs by novel biosynthesis methods" is not the methods. Saying
136
+ * which kind of match it was lets a caller pass that doubt on instead of swallowing it.
137
+ *
138
+ * @param article - The paper.
139
+ * @param kind - What is wanted, as {@link sectionsNamed} takes it.
140
+ * @returns The sections, and whether a heading was that name outright rather than merely containing it.
141
+ */
142
+ export declare function findSection(article: Article, kind: string): {
143
+ sections: Section[];
144
+ exact: boolean;
145
+ };
146
+ /**
147
+ * Fetch one open-access paper's full text.
148
+ *
149
+ * @param pmcid - Its PubMed Central ID, such as `PMC12292773`.
150
+ * @returns The JATS XML, to be read with {@link readArticle}.
151
+ * @throws {@link EuropePmcError} if there is no full text to be had, which for a paper that is not
152
+ * open access is the usual answer.
153
+ *
154
+ * @example
155
+ * ```ts
156
+ * import { fullTextOf } from "@biolibs/europepmc";
157
+ *
158
+ * const xml = await fullTextOf("PMC12292773");
159
+ * ```
160
+ */
161
+ export declare function fullTextOf(pmcid: string): Promise<string>;
162
+ //# sourceMappingURL=article.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"article.d.ts","sourceRoot":"","sources":["../src/article.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,OAAO,EAA0B,MAAM,gBAAgB,CAAC;AAGjE,8BAA8B;AAC9B,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mCAAmC;AACnC,MAAM,WAAW,KAAK;IACpB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,MAAM;IACrB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAqB;AACrB,MAAM,WAAW,OAAO;IACtB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iFAAiF;IACjF,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,8DAA8D;IAC9D,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAkCD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAmBvF;AAkCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA4EhD;AAaD,0DAA0D;AAC1D,eAAO,MAAM,aAAa,UAAsB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,EAAE,MAAM,MAAM,KAAG,OAAO,EAAyC,CAAC;AAEhH;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAoBnG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW/D"}