# bio-parsers
> A library of parsers for interconverting between genbank, fasta, and (eventually) sbol through Teselagen's intermediary json format
Latest version **9.3.6** (published 2023-04-06) · MIT license · 0 weekly downloads
> **Deprecated.** This package is deprecated.
## Install
```sh
npm install bio-parsers
pnpm add bio-parsers
yarn add bio-parsers
bun add bio-parsers
```
## Health
**Score 10/100 (F)** — status: deprecated.
Negative: deprecated.
## Facts
| | |
|---|---|
| Version | 9.3.6 |
| Published | 2023-04-06 |
| First published | 2015-11-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 9 |
| Unpacked size | 4.8 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 34 |
| Author | teselagen |
| Maintainers | teselagen-admin, tnrich |
| Keywords | genbank, fasta, parser, dna, rna, protein, snapgene, geneious, prot, sbol, json, jbei, biojs, teselagen |
## Links
- npm: https://www.npmjs.com/package/bio-parsers
- Repository: https://github.com/TeselaGen/ve-sequence-parsers
- Homepage: https://github.com/TeselaGen/ve-sequence-parsers#readme
- Issues: https://github.com/TeselaGen/ve-sequence-parsers/issues
- npm.io page: https://npm.io/package/bio-parsers
## Dependencies (9)
- [color](https://npm.io/package/color.md) ^4.2.3
- [buffer](https://npm.io/package/buffer.md) ^6.0.3
- [fflate](https://npm.io/package/fflate.md) ^0.7.4
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [@gmod/gff](https://npm.io/package/@gmod/gff.md) ^1.2.1
- [bufferpack](https://npm.io/package/bufferpack.md) ^0.0.6
- [string_decoder](https://npm.io/package/string_decoder.md) ^1.3.0
- [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) ^4.0.9
- [validate.io-nonnegative-integer-array](https://npm.io/package/validate.io-nonnegative-integer-array.md) ^1.0.1
## Alternatives
- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads
## Recent versions
- 9.3.6 (latest) — 2023-04-06
- 9.3.5 — 2023-04-06
- 9.3.4 — 2023-04-05
- 9.3.2 — 2023-03-07
- 9.3.1 — 2023-02-24
- 9.3.0 — 2023-02-13
- 9.2.1 — 2023-01-27
- 9.2.0 — 2023-01-18
- 9.1.1 — 2023-01-12
- 9.1.0 — 2023-01-07
- 9.0.1 — 2022-11-14
- 9.0.0 — 2022-11-14
- 8.3.32 — 2022-09-27
- 8.3.31 — 2022-08-16
- 8.3.30 — 2022-08-04
- … 151 more at https://npm.io/package/bio-parsers/versions
## README
# Bio Parsers
- [Bio Parsers](#bio-parsers)
- [About this Repo](#about-this-repo)
- [[CHANGELOG](CHANGELOG.md)](#changelogchangelogmd)
- [Exported Functions](#exported-functions)
- [Format Specification](#format-specification)
- [Usage](#usage)
- [install](#install)
- [jsonToGenbank (same interface as jsonToFasta)](#jsontogenbank-same-interface-as-jsontofasta)
- [anyToJson (same interface as genbankToJson, fastaToJson, xxxxToJson) (async required)](#anytojson-same-interface-as-genbanktojson-fastatojson-xxxxtojson-async-required)
- [Options (for anyToJson or xxxxToJson)](#options-for-anytojson-or-xxxxtojson)
- [ab1ToJson](#ab1tojson)
- [snapgeneToJson (.dna files)](#snapgenetojson-dna-files)
- [genbankToJson](#genbanktojson)
- [Editing This Repo](#editing-this-repo)
- [All collaborators:](#all-collaborators)
- [Debug](#debug)
- [Updating this repo](#updating-this-repo)
- [Teselagen collaborators](#teselagen-collaborators)
- [Outside collaborators](#outside-collaborators)
- [Thanks/Collaborators](#thankscollaborators)
## About this Repo
This repo contains a set of parsers to convert between datatypes through a generalized JSON format.
## [CHANGELOG](CHANGELOG.md)
## Exported Functions
Use the following exports to convert to a generalized JSON format:
```
fastaToJson //handles fasta files (.fa, .fasta)
genbankToJson //handles genbank files (.gb, .gbk)
ab1ToJson //handles .ab1 sequencing read files
sbolXmlToJson //handles .sbol files
geneiousXmlToJson //handles .genious files
jbeiXmlToJson //handles jbei .seq or .xml files
snapgeneToJson //handles snapgene (.dna) files
anyToJson //this handles any of the above file types based on file extension
```
Use the following exports to convert from a generalized JSON format back to a specific format:
```
jsonToGenbank
jsonToFasta
jsonToBed
```
## Format Specification
The generalized JSON format looks like:
```js
const generalizedJsonFormat = {
"size": 25,
"sequence": "asaasdgasdgasdgasdgasgdasgdasdgasdgasgdagasdgasdfasdfdfasdfa",
"circular": true,
"name": "pBbS8c-RFP",
"description": "",
"parts": [
{
"name": "part 1",
"type": "CDS", //optional for parts
"id": "092j92", //Must be a unique id. If no id is provided, we'll autogenerate one for you
"start": 10, //0-based inclusive index
"end": 30, //0-based inclusive index
"strand": 1,
"notes": {},
}
],
"primers": [
{
"name": "primer 1",
"id": "092j92", //Must be a unique id. If no id is provided, we'll autogenerate one for you
"start": 10, //0-based inclusive index
"end": 30, //0-based inclusive index
"strand": 1,
"notes": {},
}
],
"features": [
{
"name": "anonymous feature",
"type": "misc_feature",
"id": "5590c1978979df000a4f02c7", //Must be a unique id. If no id is provided, we'll autogenerate one for you
"start": 1,
"end": 3,
"strand": 1,
"notes": {},
},
{
"name": "coding region 1",
"type": "CDS",
"id": "5590c1d88979df000a4f02f5",
"start": 12,
"end": 9,
"strand": -1,
"notes": {},
}
],
//only if parsing in an ab1 file
"chromatogramData": {
"aTrace": [], //same as cTrace but for a
"tTrace": [], //same as cTrace but for t
"gTrace": [], //same as cTrace but for g
"cTrace": [0,0,0,1,3,5,11,24,56,68,54,30,21,3,1,4,1,0,0, ...etc], //heights of the curve spaced 1 per x position (aka if the cTrace.length === 1000, then the max basePos can be is 1000)
"basePos": [33, 46, 55, ...etc], //x position of the bases (can be unevenly spaced)
"baseCalls": ["A", "T", ...etc],
"qualNums": [], //or undefined if no qualNums are detected on the file
},
}
```
## Usage
### install
`npm install -S bio-parsers`
or
`yarn add bio-parsers`
or
use it from a script tag:
```html
```
see the `./umd_demo.html` file for a full working example
### jsonToGenbank (same interface as jsonToFasta)
```js
//To go from json to genbank:
import { jsonToGenbank } from "bio-parsers"
//You can pass an optional options object as the second argument. Here are the defaults
const options = {
isProtein: false, //by default the sequence will be parsed and validated as type DNA (unless U's instead of T's are found). If isProtein=true the sequence will be parsed and validated as a PROTEIN type (seqData.isProtein === true)
guessIfProtein: false, //if true the parser will attempt to guess if the sequence is of type DNA or type PROTEIN (this will override the isProtein flag)
guessIfProteinOptions: {
threshold = 0.90, //percent of characters that must be DNA letters to be considered of type DNA
dnaLetters = ['G', 'A', 'T', 'C'] //customizable set of letters to use as DNA
},
inclusive1BasedStart: false //by default feature starts are parsed out as 0-based and inclusive
inclusive1BasedEnd: false //by default feature ends are parsed out as 0-based and inclusive
// Example:
// 0123456
// ATGAGAG
// --fff-- (the feature covers GAG)
// 0-based inclusive start:
// feature.start = 2
// 1-based inclusive start:
// feature.start = 3
// 0-based inclusive end:
// feature.end = 4
// 1-based inclusive end:
// feature.end = 5
}
const genbankString = jsonToGenbank(generalizedJsonFormat, options)
```
### anyToJson (same interface as genbankToJson, fastaToJson, xxxxToJson) (async required)
```js
import { anyToJson } from "bio-parsers"
//note, anyToJson should be called using an await to allow for file parsing to occur (if a file is being passed)
const results = await anyToJson(
stringOrFile, //if ab1 files are being passed in you should pass files only, otherwise strings or files are fine as inputs
options //options.fileName (eg "pBad.ab1" or "pCherry.fasta") is important to pass here in order for the parser to!
)
//we always return an array of results because some files my contain multiple sequences
results[0].success //either true or false
results[0].messages //either an array of strings giving any warnings or errors generated during the parsing process
results[0].parsedSequence //this will be the generalized json format as specified above :)
//chromatogram data will be here (ab1 only):
results[0].parsedSequence.chromatogramData
```
### Options (for anyToJson or xxxxToJson)
```js
//You can pass an optional options object as the third argument. Here are the defaults
const options = {
fileName: "example.gb", //the filename is used if none is found in the genbank
isProtein: false, //if you know that it is a protein string being parsed you can pass true here
parseFastaAsCircular: false; //by default fasta files are parsed as linear sequences. You can change this by setting parseFastaAsCircular=true
//genbankToJson options only
inclusive1BasedStart: false //by default feature starts are parsed out as 0-based and inclusive
inclusive1BasedEnd: false //by default feature ends are parsed out as 0-based and inclusive
acceptParts: true //by default features with a feature.notes.pragma[0] === "Teselagen_Part" are added to the sequenceData.parts array. Setting this to false will keep them as features instead
// fastaToJson options only
parseName: true //by default attempt to parse the name and description of sequence from the comment line. Setting this to false will keep the name unchanged with no description
}
```
### ab1ToJson
```js
import { ab1ToJson } from "bio-parsers"
const results = await ab1ToJson(
//this can be either a browser file
// or a node file ab1ToJson(fs.readFileSync(path.join(__dirname, './testData/ab1/example1.ab1')));
file,
options //options.fileName (eg "pBad.ab1" or "pCherry.fasta") is important to pass here in order for the parser to!
)
//we always return an array of results because some files my contain multiple sequences
results[0].success //either true or false
results[0].messages //either an array of strings giving any warnings or errors generated during the parsing process
results[0].parsedSequence //this will be the generalized json format as specified above :)
//chromatogram data will be here (ab1 only):
results[0].parsedSequence.chromatogramData
```
### snapgeneToJson (.dna files)
```js
import { snapgeneToJson } from "bio-parsers"
//file can be either a browser file
// or a node file snapgeneToJson(fs.readFileSync(path.join(__dirname, './testData/ab1/example1.ab1')));
const results = await snapgeneToJson(file,options)
```
### genbankToJson
```js
import { genbankToJson } from "bio-parsers"
const result = genbankToJson(string, options)
console.info(result)
// [
// {
// "messages": [
// "Import Error: Illegal character(s) detected and removed from sequence. Allowed characters are: atgcyrswkmbvdhn",
// "Invalid feature end: 1384 detected for Homo sapiens and set to 1",
// ],
// "success": true,
// "parsedSequence": {
// "features": [
// {
// "notes": {
// "organism": [
// "Homo sapiens"
// ],
// "db_xref": [
// "taxon:9606"
// ],
// "chromosome": [
// "17"
// ],
// "map": [
// "17q21"
// ]
// },
// "type": "source",
// "strand": 1,
// "name": "Homo sapiens",
// "start": 0,
// "end": 1
// }
// ],
// "name": "NP_003623",
// "sequence": "gagaggggggttatccccccttcgtcagtcgatcgtaacgtatcagcagcgcgcgagattttctggcgcagtcag",
// "circular": true,
// "extraLines": [
// "DEFINITION contactin-associated protein 1 precursor [Homo sapiens].",
// "ACCESSION NP_003623",
// "VERSION NP_003623.1 GI:4505463",
// "DBSOURCE REFSEQ: accession NM_003632.2",
// "KEYWORDS RefSeq."
// ],
// "type": "DNA",
// "size": 925
// }
// }
// ]
```
You can see more examples by looking at the tests.
## Editing This Repo
### All collaborators:
Edit/create a new file and update/add any relevant tests.
Make sure they pass by running `yarn test`
## Debug
```
yarn test-debug
```
## Updating this repo
### Teselagen collaborators
Commit and push all changes
Sign into npm using the teselagen npm account (npm whoami)
```
npm version patch|minor|major
npm publish
```
### Outside collaborators
fork and pull request please :)
## Thanks/Collaborators
- IsaacLuo - https://github.com/IsaacLuo/SnapGeneFileReader (from which the snapgene parser was adapted)
- Joshua Nixon (original collaborator)
- Thomas Rich (original collaborator)
---
_Source: https://npm.io/package/bio-parsers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._