@biolibs/uniprot 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 +21 -0
- package/README.md +116 -2
- package/dist/ask.d.ts +87 -0
- package/dist/ask.d.ts.map +1 -0
- package/dist/ask.js +104 -0
- package/dist/ask.js.map +1 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +27 -0
- package/dist/index.js.map +1 -0
- package/dist/protein.d.ts +126 -0
- package/dist/protein.d.ts.map +1 -0
- package/dist/protein.js +156 -0
- package/dist/protein.js.map +1 -0
- package/dist/search.d.ts +99 -0
- package/dist/search.d.ts.map +1 -0
- package/dist/search.js +98 -0
- package/dist/search.js.map +1 -0
- package/package.json +46 -4
- package/src/ask.ts +135 -0
- package/src/index.ts +27 -0
- package/src/protein.ts +258 -0
- package/src/search.ts +133 -0
package/dist/protein.js
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What UniProt knows about a protein, read into positions people count.
|
|
3
|
+
*
|
|
4
|
+
* `@biolibs/seqio` already reads UniProt's XML, faithfully, into Biopython's shapes: a `SeqRecord`
|
|
5
|
+
* with features whose locations are half-open and counted from zero. That is the right thing for a
|
|
6
|
+
* port to do and the wrong thing to hand a lab, so this turns it into the few facts somebody at a
|
|
7
|
+
* bench actually asks for, counted the way the rest of these packages count.
|
|
8
|
+
*
|
|
9
|
+
* The one that matters most is the **chain**. A UniProt entry's sequence is usually the precursor —
|
|
10
|
+
* the protein as it comes off the ribosome, signal peptide and all — and the thing a lab collects
|
|
11
|
+
* is the chain that is left after the cell has cut that off. They are different lengths and so
|
|
12
|
+
* different masses on a gel, and a tool that quietly used the precursor would send somebody looking
|
|
13
|
+
* for a band two kilodaltons too high. So the mature chain is worked out, given as its own
|
|
14
|
+
* sequence, and said to be what it is.
|
|
15
|
+
*
|
|
16
|
+
* The second is **what is modified**. For a protein like casein the phosphoserines are the whole
|
|
17
|
+
* point: they are what lets it build a micelle, and a host that does not put them on makes a
|
|
18
|
+
* protein that is the right mass and the wrong thing. UniProt records them one residue at a time,
|
|
19
|
+
* with evidence, and that is worth far more than anything a sequence alone can be asked.
|
|
20
|
+
*/
|
|
21
|
+
import { UniprotIterator } from "@biolibs/seqio";
|
|
22
|
+
import { UniProtError } from "./ask.js";
|
|
23
|
+
const words = (value) => (typeof value === "string" && value.trim() !== "" ? value.trim() : null);
|
|
24
|
+
const list = (value) => (Array.isArray(value) ? value.filter((one) => typeof one === "string") : []);
|
|
25
|
+
/** A position out of a Biopython location, or `null` where it is not an exact number. */
|
|
26
|
+
const exact = (value) => {
|
|
27
|
+
const at = Number(value);
|
|
28
|
+
return Number.isSafeInteger(at) ? at : null;
|
|
29
|
+
};
|
|
30
|
+
/** A feature's stretch, turned from half-open and counted from zero into how people count. */
|
|
31
|
+
function stretchOf(feature) {
|
|
32
|
+
const [start, end] = [exact(feature.location.start), exact(feature.location.end)];
|
|
33
|
+
if (start === null || end === null || end <= start)
|
|
34
|
+
return null;
|
|
35
|
+
return { from: start + 1, to: end };
|
|
36
|
+
}
|
|
37
|
+
const said = (feature, field) => words(feature.qualifiers.get(field)) ?? "";
|
|
38
|
+
/**
|
|
39
|
+
* Read a protein out of a UniProt XML entry.
|
|
40
|
+
*
|
|
41
|
+
* @param xml - The entry, as UniProt sends it.
|
|
42
|
+
* @returns What is known about it.
|
|
43
|
+
* @throws {@link UniProtError} if that is not a UniProt entry.
|
|
44
|
+
*
|
|
45
|
+
* @example
|
|
46
|
+
* ```ts
|
|
47
|
+
* import { lookUpProtein, readProtein } from "@biolibs/uniprot";
|
|
48
|
+
*
|
|
49
|
+
* const casein = readProtein(await lookUpProtein("P02666"));
|
|
50
|
+
* casein.chain?.length; // 209, not the precursor's 224
|
|
51
|
+
* casein.modifications.map((one) => one.at); // [30, 32, 33, 34, 50]
|
|
52
|
+
* ```
|
|
53
|
+
*/
|
|
54
|
+
export function readProtein(xml) {
|
|
55
|
+
const bytes = typeof xml === "string" ? new TextEncoder().encode(xml) : xml;
|
|
56
|
+
let record;
|
|
57
|
+
try {
|
|
58
|
+
const [first] = [...new UniprotIterator(bytes)];
|
|
59
|
+
if (first === undefined)
|
|
60
|
+
throw new Error("the entry is empty");
|
|
61
|
+
record = first;
|
|
62
|
+
}
|
|
63
|
+
catch (cause) {
|
|
64
|
+
throw new UniProtError(`That is not a UniProt entry: ${cause instanceof Error ? cause.message : String(cause)}`, "uniprotkb");
|
|
65
|
+
}
|
|
66
|
+
const sequence = String(record.seq).toUpperCase();
|
|
67
|
+
const accession = list(record.annotations.get("accessions"))[0] ?? record.id;
|
|
68
|
+
const signal = record.features.filter((one) => one.type === "signal peptide").map(stretchOf).find((one) => one !== null) ?? null;
|
|
69
|
+
const chainFeature = record.features.find((one) => one.type === "chain");
|
|
70
|
+
const chainAt = chainFeature === undefined ? null : stretchOf(chainFeature);
|
|
71
|
+
const chain = chainFeature === null || chainFeature === undefined || chainAt === null ? null : {
|
|
72
|
+
...chainAt,
|
|
73
|
+
name: said(chainFeature, "description") || (words(record.description) ?? "the mature chain"),
|
|
74
|
+
sequence: sequence.slice(chainAt.from - 1, chainAt.to),
|
|
75
|
+
length: chainAt.to - chainAt.from + 1,
|
|
76
|
+
};
|
|
77
|
+
const modifications = [];
|
|
78
|
+
for (const feature of record.features) {
|
|
79
|
+
if (feature.type !== "modified residue" && feature.type !== "glycosylation site" && feature.type !== "lipid moiety-binding region")
|
|
80
|
+
continue;
|
|
81
|
+
const at = stretchOf(feature);
|
|
82
|
+
if (at === null)
|
|
83
|
+
continue;
|
|
84
|
+
modifications.push({
|
|
85
|
+
at: at.from, residue: sequence[at.from - 1] ?? "",
|
|
86
|
+
what: said(feature, "description") || feature.type,
|
|
87
|
+
evidenced: said(feature, "evidence") !== "",
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
const variants = [];
|
|
91
|
+
for (const feature of record.features) {
|
|
92
|
+
if (feature.type !== "sequence variant")
|
|
93
|
+
continue;
|
|
94
|
+
const at = stretchOf(feature);
|
|
95
|
+
if (at === null)
|
|
96
|
+
continue;
|
|
97
|
+
variants.push({ ...at, was: said(feature, "original"), now: said(feature, "variation"), note: said(feature, "description") });
|
|
98
|
+
}
|
|
99
|
+
const regions = [];
|
|
100
|
+
for (const feature of record.features) {
|
|
101
|
+
if (!["domain", "region of interest", "repeat", "motif", "zinc finger region", "binding site", "active site"].includes(feature.type))
|
|
102
|
+
continue;
|
|
103
|
+
const at = stretchOf(feature);
|
|
104
|
+
if (at === null)
|
|
105
|
+
continue;
|
|
106
|
+
regions.push({ ...at, kind: feature.type, name: said(feature, "description") || said(feature, "note") || feature.type });
|
|
107
|
+
}
|
|
108
|
+
const dataset = words(record.annotations.get("dataset"));
|
|
109
|
+
const mass = Number(record.annotations.get("sequence_mass"));
|
|
110
|
+
return {
|
|
111
|
+
accession, alsoKnownAs: list(record.annotations.get("accessions")).slice(1),
|
|
112
|
+
entryName: record.name, name: words(record.description) ?? record.name,
|
|
113
|
+
gene: words(record.annotations.get("gene_name_primary")),
|
|
114
|
+
organism: words(record.annotations.get("organism")),
|
|
115
|
+
lineage: list(record.annotations.get("taxonomy")),
|
|
116
|
+
// UniProt says "Swiss-Prot" for an entry a curator has been over and "TrEMBL" for one made by
|
|
117
|
+
// machine. Anything that is not plainly the first is treated as the second.
|
|
118
|
+
reviewed: dataset !== null && /swiss-?prot/i.test(dataset),
|
|
119
|
+
sequence, length: sequence.length,
|
|
120
|
+
mass: Number.isFinite(mass) && mass > 0 ? mass : null,
|
|
121
|
+
signal, chain,
|
|
122
|
+
modifications: modifications.sort((a, b) => a.at - b.at),
|
|
123
|
+
variants: variants.sort((a, b) => a.from - b.from),
|
|
124
|
+
regions: regions.sort((a, b) => a.from - b.from),
|
|
125
|
+
keywords: list(record.annotations.get("keywords")),
|
|
126
|
+
lookAt: `https://www.uniprot.org/uniprotkb/${accession}`,
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Where a modification falls on the mature chain, rather than on the precursor.
|
|
131
|
+
*
|
|
132
|
+
* UniProt counts every position on the whole entry, signal peptide included. A lab holding the
|
|
133
|
+
* mature protein counts from the first residue it actually has, and the two differ by the length
|
|
134
|
+
* of what was cut off. Getting this wrong by fifteen residues is the easiest mistake here to make
|
|
135
|
+
* and the hardest to notice, because both numbers look perfectly reasonable.
|
|
136
|
+
*
|
|
137
|
+
* @param protein - The protein.
|
|
138
|
+
* @param at - A position on the entry's sequence, counting from 1.
|
|
139
|
+
* @returns The same residue counted from the start of the mature chain, or `null` if it is not on
|
|
140
|
+
* the chain at all — a residue inside the signal peptide is on nothing the lab holds.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```ts
|
|
144
|
+
* import { onTheChain } from "@biolibs/uniprot";
|
|
145
|
+
*
|
|
146
|
+
* onTheChain(casein, 30); // 15 — the first phosphoserine, counted on what a lab collects
|
|
147
|
+
* onTheChain(casein, 5); // null — that residue is in the signal peptide and is cut off
|
|
148
|
+
* ```
|
|
149
|
+
*/
|
|
150
|
+
export function onTheChain(protein, at) {
|
|
151
|
+
const chain = protein.chain;
|
|
152
|
+
if (chain === null || at < chain.from || at > chain.to)
|
|
153
|
+
return null;
|
|
154
|
+
return at - chain.from + 1;
|
|
155
|
+
}
|
|
156
|
+
//# sourceMappingURL=protein.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"protein.js","sourceRoot":"","sources":["../src/protein.ts"],"names":[],"mappings":"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"}
|
package/dist/search.d.ts
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/** The most results one search gives back. */
|
|
2
|
+
export declare const MOST_FOUND = 50;
|
|
3
|
+
/** One result: enough to choose by. */
|
|
4
|
+
export interface Hit {
|
|
5
|
+
/** Its accession, to fetch it by. */
|
|
6
|
+
accession: string;
|
|
7
|
+
/** The entry's name, such as `CASB_BOVIN`. */
|
|
8
|
+
entryName: string;
|
|
9
|
+
/** What the protein is called. */
|
|
10
|
+
name: string;
|
|
11
|
+
/** The gene, where the entry names one. */
|
|
12
|
+
gene: string | null;
|
|
13
|
+
/** What it is from. */
|
|
14
|
+
organism: string | null;
|
|
15
|
+
/** How many residues the entry's own sequence has, precursor and all. */
|
|
16
|
+
length: number | null;
|
|
17
|
+
/** Whether a curator has been over it. */
|
|
18
|
+
reviewed: boolean;
|
|
19
|
+
/** Where a person would read it. */
|
|
20
|
+
lookAt: string;
|
|
21
|
+
}
|
|
22
|
+
/** What a search found. */
|
|
23
|
+
export interface Search {
|
|
24
|
+
/** What was asked. */
|
|
25
|
+
query: string;
|
|
26
|
+
/** The results. */
|
|
27
|
+
results: Hit[];
|
|
28
|
+
}
|
|
29
|
+
/** What the service sends back, in as much shape as is read. */
|
|
30
|
+
interface RawHit {
|
|
31
|
+
entryType?: string;
|
|
32
|
+
primaryAccession?: string;
|
|
33
|
+
uniProtkbId?: string;
|
|
34
|
+
organism?: {
|
|
35
|
+
scientificName?: string;
|
|
36
|
+
commonName?: string;
|
|
37
|
+
};
|
|
38
|
+
proteinDescription?: {
|
|
39
|
+
recommendedName?: {
|
|
40
|
+
fullName?: {
|
|
41
|
+
value?: string;
|
|
42
|
+
};
|
|
43
|
+
};
|
|
44
|
+
submissionNames?: {
|
|
45
|
+
fullName?: {
|
|
46
|
+
value?: string;
|
|
47
|
+
};
|
|
48
|
+
}[];
|
|
49
|
+
};
|
|
50
|
+
genes?: {
|
|
51
|
+
geneName?: {
|
|
52
|
+
value?: string;
|
|
53
|
+
};
|
|
54
|
+
}[];
|
|
55
|
+
sequence?: {
|
|
56
|
+
length?: number;
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
/** One result, read into something steady. */
|
|
60
|
+
export declare function oneHit(raw: RawHit): Hit;
|
|
61
|
+
/**
|
|
62
|
+
* Search for a protein.
|
|
63
|
+
*
|
|
64
|
+
* @param query - What to look for, in UniProt's own syntax: plain words, and fields such as
|
|
65
|
+
* `gene:CSN2`, `organism_id:9913`, `taxonomy_name:"Bos taurus"`, `reviewed:true`, `length:[200 TO 300]`.
|
|
66
|
+
* @param options - `limit` is how many to bring back; `reviewedOnly` adds the filter for entries a
|
|
67
|
+
* curator has been over, which is usually what somebody means.
|
|
68
|
+
* @returns What matched.
|
|
69
|
+
* @throws {@link UniProtError} if the service could not be reached or did not answer with results.
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* ```ts
|
|
73
|
+
* import { searchProteins } from "@biolibs/uniprot";
|
|
74
|
+
*
|
|
75
|
+
* const found = await searchProteins("casein AND organism_id:9913", { reviewedOnly: true });
|
|
76
|
+
* found.results.map((one) => [one.accession, one.gene, one.name]);
|
|
77
|
+
* ```
|
|
78
|
+
*/
|
|
79
|
+
export declare function searchProteins(query: string, options?: {
|
|
80
|
+
limit?: number;
|
|
81
|
+
reviewedOnly?: boolean;
|
|
82
|
+
}): Promise<Search>;
|
|
83
|
+
/**
|
|
84
|
+
* Fetch one entry.
|
|
85
|
+
*
|
|
86
|
+
* @param accession - The accession, such as `P02666`.
|
|
87
|
+
* @returns The entry's XML, to be read with `readProtein`.
|
|
88
|
+
* @throws {@link UniProtError} if there is no such entry, or it could not be fetched.
|
|
89
|
+
*
|
|
90
|
+
* @example
|
|
91
|
+
* ```ts
|
|
92
|
+
* import { lookUpProtein, readProtein } from "@biolibs/uniprot";
|
|
93
|
+
*
|
|
94
|
+
* const casein = readProtein(await lookUpProtein("P02666"));
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
97
|
+
export declare function lookUpProtein(accession: string): Promise<Uint8Array>;
|
|
98
|
+
export {};
|
|
99
|
+
//# sourceMappingURL=search.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAYA,8CAA8C;AAC9C,eAAO,MAAM,UAAU,KAAK,CAAC;AAE7B,uCAAuC;AACvC,MAAM,WAAW,GAAG;IAClB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uBAAuB;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2BAA2B;AAC3B,MAAM,WAAW,MAAM;IACrB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,OAAO,EAAE,GAAG,EAAE,CAAC;CAChB;AAED,gEAAgE;AAChE,UAAU,MAAM;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,kBAAkB,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE;gBAAE,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAC;QAAC,eAAe,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE;gBAAE,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IACpI,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAAE,CAAC;IAC5C,QAAQ,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAID,8CAA8C;AAC9C,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAgBvC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAY7H;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAW1E"}
|
package/dist/search.js
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Finding a protein, and fetching the entry for one.
|
|
3
|
+
*
|
|
4
|
+
* A search gives little — enough to choose between entries and no more — because the whole entry
|
|
5
|
+
* is large and most of a search's results are not the one wanted. The one thing it does give that
|
|
6
|
+
* matters before anything else is whether each entry has been **reviewed**: Swiss-Prot entries have
|
|
7
|
+
* been read out of papers by a curator, TrEMBL entries were made by machine from similarity, and
|
|
8
|
+
* treating a machine's guess as a curator's reading is the easiest way to be confidently wrong
|
|
9
|
+
* about a protein.
|
|
10
|
+
*/
|
|
11
|
+
import { ask, looksLikeAccession, UniProtError } from "./ask.js";
|
|
12
|
+
/** The most results one search gives back. */
|
|
13
|
+
export const MOST_FOUND = 50;
|
|
14
|
+
const words = (value) => (typeof value === "string" && value.trim() !== "" ? value.trim() : null);
|
|
15
|
+
/** One result, read into something steady. */
|
|
16
|
+
export function oneHit(raw) {
|
|
17
|
+
const accession = words(raw.primaryAccession) ?? "";
|
|
18
|
+
const organism = words(raw.organism?.scientificName);
|
|
19
|
+
const common = words(raw.organism?.commonName);
|
|
20
|
+
return {
|
|
21
|
+
accession,
|
|
22
|
+
entryName: words(raw.uniProtkbId) ?? "",
|
|
23
|
+
name: words(raw.proteinDescription?.recommendedName?.fullName?.value)
|
|
24
|
+
?? words(raw.proteinDescription?.submissionNames?.[0]?.fullName?.value) ?? "Unnamed",
|
|
25
|
+
gene: words(raw.genes?.[0]?.geneName?.value),
|
|
26
|
+
organism: organism === null ? null : common === null ? organism : `${organism} (${common})`,
|
|
27
|
+
length: typeof raw.sequence?.length === "number" ? raw.sequence.length : null,
|
|
28
|
+
// "UniProtKB reviewed (Swiss-Prot)" against "UniProtKB unreviewed (TrEMBL)".
|
|
29
|
+
reviewed: /reviewed/i.test(raw.entryType ?? "") && !/unreviewed/i.test(raw.entryType ?? ""),
|
|
30
|
+
lookAt: `https://www.uniprot.org/uniprotkb/${accession}`,
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Search for a protein.
|
|
35
|
+
*
|
|
36
|
+
* @param query - What to look for, in UniProt's own syntax: plain words, and fields such as
|
|
37
|
+
* `gene:CSN2`, `organism_id:9913`, `taxonomy_name:"Bos taurus"`, `reviewed:true`, `length:[200 TO 300]`.
|
|
38
|
+
* @param options - `limit` is how many to bring back; `reviewedOnly` adds the filter for entries a
|
|
39
|
+
* curator has been over, which is usually what somebody means.
|
|
40
|
+
* @returns What matched.
|
|
41
|
+
* @throws {@link UniProtError} if the service could not be reached or did not answer with results.
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```ts
|
|
45
|
+
* import { searchProteins } from "@biolibs/uniprot";
|
|
46
|
+
*
|
|
47
|
+
* const found = await searchProteins("casein AND organism_id:9913", { reviewedOnly: true });
|
|
48
|
+
* found.results.map((one) => [one.accession, one.gene, one.name]);
|
|
49
|
+
* ```
|
|
50
|
+
*/
|
|
51
|
+
export async function searchProteins(query, options = {}) {
|
|
52
|
+
const asked = query.trim();
|
|
53
|
+
if (asked === "")
|
|
54
|
+
throw new UniProtError("There is nothing to search for.", "", null);
|
|
55
|
+
const whole = options.reviewedOnly === true ? `(${asked}) AND reviewed:true` : asked;
|
|
56
|
+
const body = await ask("uniprotkb/search", {
|
|
57
|
+
query: whole, format: "json",
|
|
58
|
+
size: Math.max(1, Math.min(MOST_FOUND, options.limit ?? 10)),
|
|
59
|
+
fields: "accession,id,protein_name,gene_names,organism_name,length,reviewed",
|
|
60
|
+
});
|
|
61
|
+
let answer;
|
|
62
|
+
try {
|
|
63
|
+
answer = JSON.parse(new TextDecoder().decode(body));
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
throw new UniProtError("UniProt sent back something that is not the answer to a search.", "uniprotkb/search");
|
|
67
|
+
}
|
|
68
|
+
return { query: whole, results: (answer.results ?? []).map(oneHit) };
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Fetch one entry.
|
|
72
|
+
*
|
|
73
|
+
* @param accession - The accession, such as `P02666`.
|
|
74
|
+
* @returns The entry's XML, to be read with `readProtein`.
|
|
75
|
+
* @throws {@link UniProtError} if there is no such entry, or it could not be fetched.
|
|
76
|
+
*
|
|
77
|
+
* @example
|
|
78
|
+
* ```ts
|
|
79
|
+
* import { lookUpProtein, readProtein } from "@biolibs/uniprot";
|
|
80
|
+
*
|
|
81
|
+
* const casein = readProtein(await lookUpProtein("P02666"));
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
export async function lookUpProtein(accession) {
|
|
85
|
+
const id = accession.trim().toUpperCase();
|
|
86
|
+
if (!looksLikeAccession(id))
|
|
87
|
+
throw new UniProtError(`${JSON.stringify(accession)} is not a UniProt accession. One looks like P02666 or A0A0B4J2F0.`, "uniprotkb");
|
|
88
|
+
try {
|
|
89
|
+
return await ask(`uniprotkb/${id}.xml`);
|
|
90
|
+
}
|
|
91
|
+
catch (cause) {
|
|
92
|
+
if (cause instanceof UniProtError && cause.status === 404) {
|
|
93
|
+
throw new UniProtError(`UniProt has no entry ${id}. It may have been merged into another; searchProteins finds the one that stands.`, cause.url, 404);
|
|
94
|
+
}
|
|
95
|
+
throw cause;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
//# sourceMappingURL=search.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,48 @@
|
|
|
1
1
|
{
|
|
2
|
+
"bugs": {
|
|
3
|
+
"url": "https://github.com/matthewlovestocode/biolibs/issues"
|
|
4
|
+
},
|
|
5
|
+
"dependencies": {
|
|
6
|
+
"@biolibs/core": "^1.0.0",
|
|
7
|
+
"@biolibs/seqio": "^1.0.0"
|
|
8
|
+
},
|
|
9
|
+
"description": "UniProt client: what is known about a protein — its mature chain, its modified residues, its variants and its domains — read into positions people count",
|
|
10
|
+
"engines": {
|
|
11
|
+
"node": ">=20"
|
|
12
|
+
},
|
|
13
|
+
"exports": {
|
|
14
|
+
".": {
|
|
15
|
+
"types": "./dist/index.d.ts",
|
|
16
|
+
"default": "./dist/index.js"
|
|
17
|
+
}
|
|
18
|
+
},
|
|
19
|
+
"files": [
|
|
20
|
+
"dist",
|
|
21
|
+
"src"
|
|
22
|
+
],
|
|
23
|
+
"homepage": "https://github.com/matthewlovestocode/biolibs/tree/main/packages/uniprot#readme",
|
|
24
|
+
"keywords": [
|
|
25
|
+
"bioinformatics",
|
|
26
|
+
"biology",
|
|
27
|
+
"typescript",
|
|
28
|
+
"uniprot",
|
|
29
|
+
"swiss-prot",
|
|
30
|
+
"protein",
|
|
31
|
+
"annotation",
|
|
32
|
+
"post-translational-modification"
|
|
33
|
+
],
|
|
34
|
+
"license": "MIT",
|
|
35
|
+
"main": "dist/index.js",
|
|
2
36
|
"name": "@biolibs/uniprot",
|
|
3
|
-
"
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
37
|
+
"publishConfig": {
|
|
38
|
+
"access": "public"
|
|
39
|
+
},
|
|
40
|
+
"repository": {
|
|
41
|
+
"type": "git",
|
|
42
|
+
"url": "git+https://github.com/matthewlovestocode/biolibs.git",
|
|
43
|
+
"directory": "packages/uniprot"
|
|
44
|
+
},
|
|
45
|
+
"type": "module",
|
|
46
|
+
"types": "dist/index.d.ts",
|
|
47
|
+
"version": "0.1.0"
|
|
48
|
+
}
|
package/src/ask.ts
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Asking UniProt something: the one part of this package that touches the network.
|
|
3
|
+
*
|
|
4
|
+
* Everything else is given a {@link Transport}, so the rest can be run, and tested, without one.
|
|
5
|
+
*
|
|
6
|
+
* UniProt's REST service needs no key and no account. It asks of a client only that it name itself,
|
|
7
|
+
* so that heavy use can be traced to a piece of software rather than to nobody. It is told the
|
|
8
|
+
* software's name and nothing else: never a person, never an address, unless somebody sets one on
|
|
9
|
+
* purpose.
|
|
10
|
+
*/
|
|
11
|
+
import { BioError } from "@biolibs/core";
|
|
12
|
+
|
|
13
|
+
/** Where the service lives. */
|
|
14
|
+
export const SERVICE = "https://rest.uniprot.org";
|
|
15
|
+
|
|
16
|
+
/** Something went wrong asking UniProt. */
|
|
17
|
+
export class UniProtError extends BioError {
|
|
18
|
+
/** The HTTP status, or `null` if there was no answer at all. */
|
|
19
|
+
readonly status: number | null;
|
|
20
|
+
/** The address that was asked for. */
|
|
21
|
+
readonly url: string;
|
|
22
|
+
/**
|
|
23
|
+
* Whether the service could not be reached at all.
|
|
24
|
+
*
|
|
25
|
+
* It is a field of its own because a missing status does not mean what it looks like it means:
|
|
26
|
+
* an accession of the wrong shape is refused before anything is sent, and so has no status
|
|
27
|
+
* either. Telling somebody their device is offline when what is wrong is their typing sends them
|
|
28
|
+
* to check the wrong thing.
|
|
29
|
+
*/
|
|
30
|
+
readonly offline: boolean;
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @param message - What went wrong, in words.
|
|
34
|
+
* @param url - What was asked for.
|
|
35
|
+
* @param status - The HTTP status, if there was one.
|
|
36
|
+
* @param offline - Whether the service could not be reached at all.
|
|
37
|
+
*/
|
|
38
|
+
constructor(message: string, url: string, status: number | null = null, offline = false) {
|
|
39
|
+
super(message);
|
|
40
|
+
this.name = "UniProtError";
|
|
41
|
+
this.url = url;
|
|
42
|
+
this.status = status;
|
|
43
|
+
this.offline = offline;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** A successful reply, before anything is done with it. */
|
|
48
|
+
export interface Reply {
|
|
49
|
+
/** The `Content-Type` header, or `null` if there was none. */
|
|
50
|
+
contentType: string | null;
|
|
51
|
+
/** The body. */
|
|
52
|
+
body: Uint8Array;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Sends a request.
|
|
57
|
+
*
|
|
58
|
+
* @param url - The whole address, query string and all.
|
|
59
|
+
* @param headers - What to send with it.
|
|
60
|
+
* @returns The reply, if the service answered with success.
|
|
61
|
+
* @throws {@link UniProtError} otherwise.
|
|
62
|
+
*/
|
|
63
|
+
export type Transport = (url: string, headers: Readonly<Record<string, string>>) => Promise<Reply>;
|
|
64
|
+
|
|
65
|
+
/** The default {@link Transport}: the platform's `fetch`. */
|
|
66
|
+
export const fetchTransport: Transport = async (url, headers) => {
|
|
67
|
+
let response: Response;
|
|
68
|
+
try {
|
|
69
|
+
response = await fetch(url, { headers: { ...headers } });
|
|
70
|
+
} catch (cause) {
|
|
71
|
+
throw new UniProtError(`UniProt could not be reached: ${cause instanceof Error ? cause.message : String(cause)}`, url, null, true);
|
|
72
|
+
}
|
|
73
|
+
if (!response.ok) throw new UniProtError(`UniProt answered ${response.status} ${response.statusText}.`, url, response.status);
|
|
74
|
+
return { contentType: response.headers.get("content-type"), body: new Uint8Array(await response.arrayBuffer()) };
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
/** The settings every request shares. */
|
|
78
|
+
export interface Settings {
|
|
79
|
+
/** What to call this software when asking. Never a person's name. */
|
|
80
|
+
tool: string;
|
|
81
|
+
/** An address UniProt could use to get in touch about heavy use, if somebody has set one on purpose. */
|
|
82
|
+
email: string | null;
|
|
83
|
+
/** The most bytes of any reply that will be read. A UniProt entry is large; a proteome is larger. */
|
|
84
|
+
mostBytes: number;
|
|
85
|
+
/** Sends a request. Replace it to use something else, or to test without a network. */
|
|
86
|
+
transport: Transport;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** Shared settings. */
|
|
90
|
+
export const settings: Settings = {
|
|
91
|
+
tool: "biolibs-uniprot",
|
|
92
|
+
email: null,
|
|
93
|
+
mostBytes: 8_000_000,
|
|
94
|
+
transport: fetchTransport,
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Ask the service for something.
|
|
99
|
+
*
|
|
100
|
+
* @param path - The path under the service, such as `uniprotkb/P02666.xml`.
|
|
101
|
+
* @param query - The query string, as pairs. Anything `undefined` is left out.
|
|
102
|
+
* @returns The body, as bytes, since what comes back is XML to be parsed.
|
|
103
|
+
* @throws {@link UniProtError} if it could not be reached, answered with a failure, or sent back
|
|
104
|
+
* more than {@link Settings.mostBytes}.
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```ts
|
|
108
|
+
* import { ask } from "@biolibs/uniprot";
|
|
109
|
+
*
|
|
110
|
+
* const xml = await ask("uniprotkb/P02666.xml");
|
|
111
|
+
* ```
|
|
112
|
+
*/
|
|
113
|
+
export async function ask(path: string, query: Readonly<Record<string, string | number | undefined>> = {}): Promise<Uint8Array> {
|
|
114
|
+
const search = new URLSearchParams();
|
|
115
|
+
for (const [name, value] of Object.entries(query)) if (value !== undefined) search.set(name, String(value));
|
|
116
|
+
const url = `${SERVICE}/${path}${search.size === 0 ? "" : `?${search.toString()}`}`;
|
|
117
|
+
const agent = settings.email !== null && settings.email.trim() !== "" ? `${settings.tool} (${settings.email.trim()})` : settings.tool;
|
|
118
|
+
let reply: Reply;
|
|
119
|
+
try {
|
|
120
|
+
reply = await settings.transport(url, { "User-Agent": agent, Accept: "application/xml, application/json;q=0.9, */*;q=0.8" });
|
|
121
|
+
} catch (cause) {
|
|
122
|
+
// The transport is replaceable, and this says it throws one kind of error. One that threw
|
|
123
|
+
// something else still failed to deliver a request, which is what being offline is.
|
|
124
|
+
if (cause instanceof UniProtError) throw cause;
|
|
125
|
+
throw new UniProtError(`UniProt could not be reached: ${cause instanceof Error ? cause.message : String(cause)}`, url, null, true);
|
|
126
|
+
}
|
|
127
|
+
if (reply.body.length > settings.mostBytes) {
|
|
128
|
+
throw new UniProtError(`That reply is ${reply.body.length.toLocaleString("en-US")} bytes, which is more than one ask reads.`, url);
|
|
129
|
+
}
|
|
130
|
+
return reply.body;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** Whether something is shaped like a UniProt accession, such as `P02666` or `A0A0B4J2F0`. */
|
|
134
|
+
export const looksLikeAccession = (value: string): boolean =>
|
|
135
|
+
/^[OPQ][0-9][A-Z0-9]{3}[0-9]$/i.test(value.trim()) || /^[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2}$/i.test(value.trim());
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @packageDocumentation
|
|
3
|
+
* `@biolibs/uniprot`: what is known about a protein, read into positions people count.
|
|
4
|
+
*
|
|
5
|
+
* `@biolibs/seqio` already reads UniProt's XML, faithfully, into Biopython's shapes. That is the
|
|
6
|
+
* right thing for a port to do and the wrong thing to hand a lab: half-open locations counted from
|
|
7
|
+
* zero, and a sequence that is the precursor rather than the thing anybody holds. This turns an
|
|
8
|
+
* entry into the few facts somebody at a bench asks for — the mature chain, what is modified on it,
|
|
9
|
+
* where it varies — and counts them from 1 with both ends included, as everything else here does.
|
|
10
|
+
*
|
|
11
|
+
* - `ask.ts`: `settings`, `ask`, `UniProtError` — one place that touches the network
|
|
12
|
+
* - `search.ts`: `searchProteins`, `lookUpProtein` — finding an entry, and fetching one
|
|
13
|
+
* - `protein.ts`: `readProtein`, `onTheChain` — an entry, read
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```ts
|
|
17
|
+
* import { lookUpProtein, onTheChain, readProtein } from "@biolibs/uniprot";
|
|
18
|
+
*
|
|
19
|
+
* const casein = readProtein(await lookUpProtein("P02666"));
|
|
20
|
+
* casein.chain?.length; // what a lab collects, not the precursor
|
|
21
|
+
* casein.modifications.map((one) => onTheChain(casein, one.at)); // the phosphoserines, on the chain
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
export * from "./ask.js";
|
|
26
|
+
export * from "./search.js";
|
|
27
|
+
export * from "./protein.js";
|