@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/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,117 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @biolibs/uniprot
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
What is known about a protein, read into positions people count. UniProt needs no key and no account.
|
|
4
|
+
|
|
5
|
+
- **`lookUpProtein` and `readProtein`** — one entry: its mature chain, every residue modified after
|
|
6
|
+
it is made, where it varies, and its named parts
|
|
7
|
+
- **`onTheChain`** — a position on the entry turned into the same residue counted on the mature chain
|
|
8
|
+
- **`searchProteins`** — finding an entry, and whether a curator has been over it
|
|
9
|
+
- **Two dependencies**, `@biolibs/core` for the error class and `@biolibs/seqio` for the XML reader
|
|
10
|
+
|
|
11
|
+
## Why this exists when `@biolibs/seqio` already reads UniProt
|
|
12
|
+
|
|
13
|
+
It does, faithfully, into Biopython's shapes: a `SeqRecord` whose feature locations are half-open and
|
|
14
|
+
counted from zero, and whose sequence is whatever the entry holds. That is the right thing for a port
|
|
15
|
+
to do. It is the wrong thing to hand a lab, for two reasons that both cost real work to get wrong.
|
|
16
|
+
|
|
17
|
+
**An entry's sequence is usually the precursor.** It is the protein as it comes off the ribosome,
|
|
18
|
+
signal peptide and all. What a lab collects is the chain that is left after the cell has cut that off.
|
|
19
|
+
They are different lengths and so different masses, and a tool that quietly used the precursor sends
|
|
20
|
+
somebody looking for a band a kilodalton or two too high.
|
|
21
|
+
|
|
22
|
+
**Positions are counted twice.** UniProt counts every residue of the entry; a lab holding the mature
|
|
23
|
+
protein counts from the first residue it actually has. For bovine β-casein those differ by fifteen.
|
|
24
|
+
Both numbers look perfectly reasonable, which is what makes confusing them so easy.
|
|
25
|
+
|
|
26
|
+
## What is verified
|
|
27
|
+
|
|
28
|
+
There is no Biopython counterpart to this layer, so there is no parity checklist. What there is:
|
|
29
|
+
|
|
30
|
+
| | |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `test/uniprot.test.ts` | every function, against a transport that answers instead of the network |
|
|
33
|
+
| | an entry written by hand, small enough to read, with the awkward parts in it |
|
|
34
|
+
|
|
35
|
+
Nothing in the tests reaches the internet.
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @biolibs/uniprot
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Reading an entry
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import { lookUpProtein, onTheChain, readProtein } from "@biolibs/uniprot";
|
|
47
|
+
|
|
48
|
+
const casein = readProtein(await lookUpProtein("P02666"));
|
|
49
|
+
|
|
50
|
+
casein.name; // "Beta-casein"
|
|
51
|
+
casein.gene; // "CSN2"
|
|
52
|
+
casein.reviewed; // true — a curator has been over it
|
|
53
|
+
casein.length; // 224, the precursor
|
|
54
|
+
casein.chain?.length; // 209, what a lab ends up holding
|
|
55
|
+
casein.signal; // { from: 1, to: 15 }
|
|
56
|
+
|
|
57
|
+
casein.modifications.map((one) => [one.at, one.what]);
|
|
58
|
+
// [[30, "Phosphoserine"], [32, "Phosphoserine"], [33, "Phosphoserine"], [34, "Phosphoserine"], [50, "Phosphoserine; in variant A1, …"]]
|
|
59
|
+
|
|
60
|
+
casein.modifications.map((one) => onTheChain(casein, one.at));
|
|
61
|
+
// [15, 17, 18, 19, 35] — the same residues, counted on what the lab holds
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Everything is counted from 1 with both ends included, as everything else in these packages is.
|
|
65
|
+
|
|
66
|
+
## Reviewed and unreviewed are not the same thing
|
|
67
|
+
|
|
68
|
+
`reviewed` is the first field to look at and the easiest to skip past.
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
const found = await searchProteins("casein AND organism_id:9913", { reviewedOnly: true });
|
|
72
|
+
found.results.map((one) => [one.accession, one.gene, one.reviewed]);
|
|
73
|
+
// [["P02666", "CSN2", true], ["P02663", "CSN1S2", true], ["P02662", "CSN1S1", true], ["P02668", "CSN3", true]]
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A Swiss-Prot entry's modified residues were read out of papers by a person. A TrEMBL entry's were
|
|
77
|
+
inferred by machine from similarity to something else. Both arrive in the same fields and read the
|
|
78
|
+
same way, and treating the second as the first is the quietest way to be confidently wrong about a
|
|
79
|
+
protein.
|
|
80
|
+
|
|
81
|
+
## What is sent
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { settings } from "@biolibs/uniprot";
|
|
85
|
+
|
|
86
|
+
settings.tool = "my-software"; // what to call this software. Never a person's name
|
|
87
|
+
settings.email = null; // nothing goes unless somebody sets one on purpose
|
|
88
|
+
settings.transport = myTransport; // swap the network out, which is how the tests run
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The software's name is the only thing this package says about who is asking. An address is sent only
|
|
92
|
+
if somebody puts one in the settings deliberately; it is never taken from a document, a file or a
|
|
93
|
+
device.
|
|
94
|
+
|
|
95
|
+
## Testing
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
npm test # the whole workspace
|
|
99
|
+
npx vitest run packages/uniprot/test
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Things to know
|
|
103
|
+
|
|
104
|
+
- **`mass` is the precursor's**, as UniProt gives it. For the mature chain, weigh `chain.sequence`
|
|
105
|
+
with `ProteinAnalysis` in [`@biolibs/seqtools`](../seqtools).
|
|
106
|
+
- **`onTheChain` returns `null`** for a residue inside the signal peptide, because that residue is on
|
|
107
|
+
nothing the lab holds. It is not an error, and it is not position zero.
|
|
108
|
+
- **An entry with no features** is normal for an unreviewed one. Recording no modifications usually
|
|
109
|
+
means nobody has looked, not that there are none.
|
|
110
|
+
- **Accessions get merged.** A 404 may mean the entry was folded into another; the error says so, and
|
|
111
|
+
`searchProteins` finds the one that stands.
|
|
112
|
+
- **Variants matter more than they look.** For β-casein the sequence variants are the A1/A2
|
|
113
|
+
distinction, which is a real difference between milks and worth choosing deliberately.
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT — see [LICENSE](LICENSE).
|
package/dist/ask.d.ts
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
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
|
+
/** Where the service lives. */
|
|
13
|
+
export declare const SERVICE = "https://rest.uniprot.org";
|
|
14
|
+
/** Something went wrong asking UniProt. */
|
|
15
|
+
export declare class UniProtError extends BioError {
|
|
16
|
+
/** The HTTP status, or `null` if there was no answer at all. */
|
|
17
|
+
readonly status: number | null;
|
|
18
|
+
/** The address that was asked for. */
|
|
19
|
+
readonly url: string;
|
|
20
|
+
/**
|
|
21
|
+
* Whether the service could not be reached at all.
|
|
22
|
+
*
|
|
23
|
+
* It is a field of its own because a missing status does not mean what it looks like it means:
|
|
24
|
+
* an accession of the wrong shape is refused before anything is sent, and so has no status
|
|
25
|
+
* either. Telling somebody their device is offline when what is wrong is their typing sends them
|
|
26
|
+
* to check the wrong thing.
|
|
27
|
+
*/
|
|
28
|
+
readonly offline: boolean;
|
|
29
|
+
/**
|
|
30
|
+
* @param message - What went wrong, in words.
|
|
31
|
+
* @param url - What was asked for.
|
|
32
|
+
* @param status - The HTTP status, if there was one.
|
|
33
|
+
* @param offline - Whether the service could not be reached at all.
|
|
34
|
+
*/
|
|
35
|
+
constructor(message: string, url: string, status?: number | null, offline?: boolean);
|
|
36
|
+
}
|
|
37
|
+
/** A successful reply, before anything is done with it. */
|
|
38
|
+
export interface Reply {
|
|
39
|
+
/** The `Content-Type` header, or `null` if there was none. */
|
|
40
|
+
contentType: string | null;
|
|
41
|
+
/** The body. */
|
|
42
|
+
body: Uint8Array;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Sends a request.
|
|
46
|
+
*
|
|
47
|
+
* @param url - The whole address, query string and all.
|
|
48
|
+
* @param headers - What to send with it.
|
|
49
|
+
* @returns The reply, if the service answered with success.
|
|
50
|
+
* @throws {@link UniProtError} otherwise.
|
|
51
|
+
*/
|
|
52
|
+
export type Transport = (url: string, headers: Readonly<Record<string, string>>) => Promise<Reply>;
|
|
53
|
+
/** The default {@link Transport}: the platform's `fetch`. */
|
|
54
|
+
export declare const fetchTransport: Transport;
|
|
55
|
+
/** The settings every request shares. */
|
|
56
|
+
export interface Settings {
|
|
57
|
+
/** What to call this software when asking. Never a person's name. */
|
|
58
|
+
tool: string;
|
|
59
|
+
/** An address UniProt could use to get in touch about heavy use, if somebody has set one on purpose. */
|
|
60
|
+
email: string | null;
|
|
61
|
+
/** The most bytes of any reply that will be read. A UniProt entry is large; a proteome is larger. */
|
|
62
|
+
mostBytes: number;
|
|
63
|
+
/** Sends a request. Replace it to use something else, or to test without a network. */
|
|
64
|
+
transport: Transport;
|
|
65
|
+
}
|
|
66
|
+
/** Shared settings. */
|
|
67
|
+
export declare const settings: Settings;
|
|
68
|
+
/**
|
|
69
|
+
* Ask the service for something.
|
|
70
|
+
*
|
|
71
|
+
* @param path - The path under the service, such as `uniprotkb/P02666.xml`.
|
|
72
|
+
* @param query - The query string, as pairs. Anything `undefined` is left out.
|
|
73
|
+
* @returns The body, as bytes, since what comes back is XML to be parsed.
|
|
74
|
+
* @throws {@link UniProtError} if it could not be reached, answered with a failure, or sent back
|
|
75
|
+
* more than {@link Settings.mostBytes}.
|
|
76
|
+
*
|
|
77
|
+
* @example
|
|
78
|
+
* ```ts
|
|
79
|
+
* import { ask } from "@biolibs/uniprot";
|
|
80
|
+
*
|
|
81
|
+
* const xml = await ask("uniprotkb/P02666.xml");
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
export declare function ask(path: string, query?: Readonly<Record<string, string | number | undefined>>): Promise<Uint8Array>;
|
|
85
|
+
/** Whether something is shaped like a UniProt accession, such as `P02666` or `A0A0B4J2F0`. */
|
|
86
|
+
export declare const looksLikeAccession: (value: string) => boolean;
|
|
87
|
+
//# sourceMappingURL=ask.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,+BAA+B;AAC/B,eAAO,MAAM,OAAO,6BAA6B,CAAC;AAElD,2CAA2C;AAC3C,qBAAa,YAAa,SAAQ,QAAQ;IACxC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,EAAE,OAAO,UAAQ;CAOxF;AAED,2DAA2D;AAC3D,MAAM,WAAW,KAAK;IACpB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB;IAChB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;AAEnG,6DAA6D;AAC7D,eAAO,MAAM,cAAc,EAAE,SAS5B,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACvB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qGAAqG;IACrG,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,uBAAuB;AACvB,eAAO,MAAM,QAAQ,EAAE,QAKtB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkB9H;AAED,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,OACwE,CAAC"}
|
package/dist/ask.js
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
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
|
+
/** Where the service lives. */
|
|
13
|
+
export const SERVICE = "https://rest.uniprot.org";
|
|
14
|
+
/** Something went wrong asking UniProt. */
|
|
15
|
+
export class UniProtError extends BioError {
|
|
16
|
+
/** The HTTP status, or `null` if there was no answer at all. */
|
|
17
|
+
status;
|
|
18
|
+
/** The address that was asked for. */
|
|
19
|
+
url;
|
|
20
|
+
/**
|
|
21
|
+
* Whether the service could not be reached at all.
|
|
22
|
+
*
|
|
23
|
+
* It is a field of its own because a missing status does not mean what it looks like it means:
|
|
24
|
+
* an accession of the wrong shape is refused before anything is sent, and so has no status
|
|
25
|
+
* either. Telling somebody their device is offline when what is wrong is their typing sends them
|
|
26
|
+
* to check the wrong thing.
|
|
27
|
+
*/
|
|
28
|
+
offline;
|
|
29
|
+
/**
|
|
30
|
+
* @param message - What went wrong, in words.
|
|
31
|
+
* @param url - What was asked for.
|
|
32
|
+
* @param status - The HTTP status, if there was one.
|
|
33
|
+
* @param offline - Whether the service could not be reached at all.
|
|
34
|
+
*/
|
|
35
|
+
constructor(message, url, status = null, offline = false) {
|
|
36
|
+
super(message);
|
|
37
|
+
this.name = "UniProtError";
|
|
38
|
+
this.url = url;
|
|
39
|
+
this.status = status;
|
|
40
|
+
this.offline = offline;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/** The default {@link Transport}: the platform's `fetch`. */
|
|
44
|
+
export const fetchTransport = async (url, headers) => {
|
|
45
|
+
let response;
|
|
46
|
+
try {
|
|
47
|
+
response = await fetch(url, { headers: { ...headers } });
|
|
48
|
+
}
|
|
49
|
+
catch (cause) {
|
|
50
|
+
throw new UniProtError(`UniProt could not be reached: ${cause instanceof Error ? cause.message : String(cause)}`, url, null, true);
|
|
51
|
+
}
|
|
52
|
+
if (!response.ok)
|
|
53
|
+
throw new UniProtError(`UniProt answered ${response.status} ${response.statusText}.`, url, response.status);
|
|
54
|
+
return { contentType: response.headers.get("content-type"), body: new Uint8Array(await response.arrayBuffer()) };
|
|
55
|
+
};
|
|
56
|
+
/** Shared settings. */
|
|
57
|
+
export const settings = {
|
|
58
|
+
tool: "biolibs-uniprot",
|
|
59
|
+
email: null,
|
|
60
|
+
mostBytes: 8_000_000,
|
|
61
|
+
transport: fetchTransport,
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* Ask the service for something.
|
|
65
|
+
*
|
|
66
|
+
* @param path - The path under the service, such as `uniprotkb/P02666.xml`.
|
|
67
|
+
* @param query - The query string, as pairs. Anything `undefined` is left out.
|
|
68
|
+
* @returns The body, as bytes, since what comes back is XML to be parsed.
|
|
69
|
+
* @throws {@link UniProtError} if it could not be reached, answered with a failure, or sent back
|
|
70
|
+
* more than {@link Settings.mostBytes}.
|
|
71
|
+
*
|
|
72
|
+
* @example
|
|
73
|
+
* ```ts
|
|
74
|
+
* import { ask } from "@biolibs/uniprot";
|
|
75
|
+
*
|
|
76
|
+
* const xml = await ask("uniprotkb/P02666.xml");
|
|
77
|
+
* ```
|
|
78
|
+
*/
|
|
79
|
+
export async function ask(path, query = {}) {
|
|
80
|
+
const search = new URLSearchParams();
|
|
81
|
+
for (const [name, value] of Object.entries(query))
|
|
82
|
+
if (value !== undefined)
|
|
83
|
+
search.set(name, String(value));
|
|
84
|
+
const url = `${SERVICE}/${path}${search.size === 0 ? "" : `?${search.toString()}`}`;
|
|
85
|
+
const agent = settings.email !== null && settings.email.trim() !== "" ? `${settings.tool} (${settings.email.trim()})` : settings.tool;
|
|
86
|
+
let reply;
|
|
87
|
+
try {
|
|
88
|
+
reply = await settings.transport(url, { "User-Agent": agent, Accept: "application/xml, application/json;q=0.9, */*;q=0.8" });
|
|
89
|
+
}
|
|
90
|
+
catch (cause) {
|
|
91
|
+
// The transport is replaceable, and this says it throws one kind of error. One that threw
|
|
92
|
+
// something else still failed to deliver a request, which is what being offline is.
|
|
93
|
+
if (cause instanceof UniProtError)
|
|
94
|
+
throw cause;
|
|
95
|
+
throw new UniProtError(`UniProt could not be reached: ${cause instanceof Error ? cause.message : String(cause)}`, url, null, true);
|
|
96
|
+
}
|
|
97
|
+
if (reply.body.length > settings.mostBytes) {
|
|
98
|
+
throw new UniProtError(`That reply is ${reply.body.length.toLocaleString("en-US")} bytes, which is more than one ask reads.`, url);
|
|
99
|
+
}
|
|
100
|
+
return reply.body;
|
|
101
|
+
}
|
|
102
|
+
/** Whether something is shaped like a UniProt accession, such as `P02666` or `A0A0B4J2F0`. */
|
|
103
|
+
export const looksLikeAccession = (value) => /^[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());
|
|
104
|
+
//# sourceMappingURL=ask.js.map
|
package/dist/ask.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ask.js","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.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
|
+
export * from "./ask.js";
|
|
25
|
+
export * from "./search.js";
|
|
26
|
+
export * from "./protein.js";
|
|
27
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
|
package/dist/index.js
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
|
+
export * from "./ask.js";
|
|
25
|
+
export * from "./search.js";
|
|
26
|
+
export * from "./protein.js";
|
|
27
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
/** A stretch of a protein, counted as people count: from 1, both ends included. */
|
|
2
|
+
export interface Stretch {
|
|
3
|
+
/** The first residue, counting from 1. */
|
|
4
|
+
from: number;
|
|
5
|
+
/** The last residue. */
|
|
6
|
+
to: number;
|
|
7
|
+
}
|
|
8
|
+
/** The mature protein: what is left once the cell has cut off what it cuts off. */
|
|
9
|
+
export interface Chain extends Stretch {
|
|
10
|
+
/** What UniProt calls it. */
|
|
11
|
+
name: string;
|
|
12
|
+
/** Its own sequence. */
|
|
13
|
+
sequence: string;
|
|
14
|
+
/** How many residues. */
|
|
15
|
+
length: number;
|
|
16
|
+
}
|
|
17
|
+
/** One residue that carries something after it is made. */
|
|
18
|
+
export interface Modified {
|
|
19
|
+
/** Where it is, counting from 1 on the whole entry's sequence. */
|
|
20
|
+
at: number;
|
|
21
|
+
/** The residue itself, as a letter. */
|
|
22
|
+
residue: string;
|
|
23
|
+
/** What is on it: `Phosphoserine`, `N-linked (GlcNAc) asparagine`, and so on. */
|
|
24
|
+
what: string;
|
|
25
|
+
/** Whether UniProt cites evidence for it. */
|
|
26
|
+
evidenced: boolean;
|
|
27
|
+
}
|
|
28
|
+
/** One place the protein is known to differ between individuals or breeds. */
|
|
29
|
+
export interface Variant extends Stretch {
|
|
30
|
+
/** What is usually there, and what it becomes. */
|
|
31
|
+
was: string;
|
|
32
|
+
/** What it becomes, or `""` where the residues are simply gone. */
|
|
33
|
+
now: string;
|
|
34
|
+
/** What UniProt says about it, which usually names the variant. */
|
|
35
|
+
note: string;
|
|
36
|
+
}
|
|
37
|
+
/** A named part of a protein: a domain, a region, a repeat. */
|
|
38
|
+
export interface Region extends Stretch {
|
|
39
|
+
/** What kind of thing it is, as UniProt types it. */
|
|
40
|
+
kind: string;
|
|
41
|
+
/** What it is called. */
|
|
42
|
+
name: string;
|
|
43
|
+
}
|
|
44
|
+
/** What is known about one protein. */
|
|
45
|
+
export interface Protein {
|
|
46
|
+
/** Its accession, which is what to cite it by. */
|
|
47
|
+
accession: string;
|
|
48
|
+
/** Every accession that leads here, since entries get merged. */
|
|
49
|
+
alsoKnownAs: string[];
|
|
50
|
+
/** The entry's name, such as `CASB_BOVIN`. */
|
|
51
|
+
entryName: string;
|
|
52
|
+
/** What the protein is called. */
|
|
53
|
+
name: string;
|
|
54
|
+
/** The gene it comes from, where the entry names one. */
|
|
55
|
+
gene: string | null;
|
|
56
|
+
/** What it is from, and where that sits. */
|
|
57
|
+
organism: string | null;
|
|
58
|
+
lineage: string[];
|
|
59
|
+
/**
|
|
60
|
+
* Whether a curator has been over this entry (Swiss-Prot) or it was made by machine (TrEMBL).
|
|
61
|
+
*
|
|
62
|
+
* It is the first thing to look at. A reviewed entry's modified residues have been read out of
|
|
63
|
+
* papers by somebody; an unreviewed entry's have been guessed from similarity, and saying they
|
|
64
|
+
* are the same thing would be a lie by omission.
|
|
65
|
+
*/
|
|
66
|
+
reviewed: boolean;
|
|
67
|
+
/** The whole entry's sequence, which is usually the precursor. */
|
|
68
|
+
sequence: string;
|
|
69
|
+
length: number;
|
|
70
|
+
/** What UniProt says the whole entry weighs, in daltons. */
|
|
71
|
+
mass: number | null;
|
|
72
|
+
/** The signal peptide, if the entry marks one. */
|
|
73
|
+
signal: Stretch | null;
|
|
74
|
+
/** The mature chain, if the entry marks one: what a lab actually ends up holding. */
|
|
75
|
+
chain: Chain | null;
|
|
76
|
+
/** Each residue that carries something after it is made. */
|
|
77
|
+
modifications: Modified[];
|
|
78
|
+
/** Where it is known to differ between individuals or breeds. */
|
|
79
|
+
variants: Variant[];
|
|
80
|
+
/** Its named parts. */
|
|
81
|
+
regions: Region[];
|
|
82
|
+
/** The words UniProt files it under. */
|
|
83
|
+
keywords: string[];
|
|
84
|
+
/** Where a person would read it. */
|
|
85
|
+
lookAt: string;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Read a protein out of a UniProt XML entry.
|
|
89
|
+
*
|
|
90
|
+
* @param xml - The entry, as UniProt sends it.
|
|
91
|
+
* @returns What is known about it.
|
|
92
|
+
* @throws {@link UniProtError} if that is not a UniProt entry.
|
|
93
|
+
*
|
|
94
|
+
* @example
|
|
95
|
+
* ```ts
|
|
96
|
+
* import { lookUpProtein, readProtein } from "@biolibs/uniprot";
|
|
97
|
+
*
|
|
98
|
+
* const casein = readProtein(await lookUpProtein("P02666"));
|
|
99
|
+
* casein.chain?.length; // 209, not the precursor's 224
|
|
100
|
+
* casein.modifications.map((one) => one.at); // [30, 32, 33, 34, 50]
|
|
101
|
+
* ```
|
|
102
|
+
*/
|
|
103
|
+
export declare function readProtein(xml: Uint8Array | string): Protein;
|
|
104
|
+
/**
|
|
105
|
+
* Where a modification falls on the mature chain, rather than on the precursor.
|
|
106
|
+
*
|
|
107
|
+
* UniProt counts every position on the whole entry, signal peptide included. A lab holding the
|
|
108
|
+
* mature protein counts from the first residue it actually has, and the two differ by the length
|
|
109
|
+
* of what was cut off. Getting this wrong by fifteen residues is the easiest mistake here to make
|
|
110
|
+
* and the hardest to notice, because both numbers look perfectly reasonable.
|
|
111
|
+
*
|
|
112
|
+
* @param protein - The protein.
|
|
113
|
+
* @param at - A position on the entry's sequence, counting from 1.
|
|
114
|
+
* @returns The same residue counted from the start of the mature chain, or `null` if it is not on
|
|
115
|
+
* the chain at all — a residue inside the signal peptide is on nothing the lab holds.
|
|
116
|
+
*
|
|
117
|
+
* @example
|
|
118
|
+
* ```ts
|
|
119
|
+
* import { onTheChain } from "@biolibs/uniprot";
|
|
120
|
+
*
|
|
121
|
+
* onTheChain(casein, 30); // 15 — the first phosphoserine, counted on what a lab collects
|
|
122
|
+
* onTheChain(casein, 5); // null — that residue is in the signal peptide and is cut off
|
|
123
|
+
* ```
|
|
124
|
+
*/
|
|
125
|
+
export declare function onTheChain(protein: Pick<Protein, "chain">, at: number): number | null;
|
|
126
|
+
//# sourceMappingURL=protein.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"protein.d.ts","sourceRoot":"","sources":["../src/protein.ts"],"names":[],"mappings":"AAuBA,mFAAmF;AACnF,MAAM,WAAW,OAAO;IACtB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mFAAmF;AACnF,MAAM,WAAW,KAAM,SAAQ,OAAO;IACpC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,WAAW,OAAQ,SAAQ,OAAO;IACtC,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,+DAA+D;AAC/D,MAAM,WAAW,MAAO,SAAQ,OAAO;IACrC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uCAAuC;AACvC,MAAM,WAAW,OAAO;IACtB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,kDAAkD;IAClD,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,qFAAqF;IACrF,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,4DAA4D;IAC5D,aAAa,EAAE,QAAQ,EAAE,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AA8BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAuE7D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrF"}
|