@teselagen/bio-parsers 0.3.8 → 0.3.9

package/README.md

@@ -0,0 +1,330 @@
+# Bio Parsers
+
+<!-- TOC -->
+
+- [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)
+  - [Updating this repo](#updating-this-repo)
+    - [Outside collaborators](#outside-collaborators)
+  - [Thanks/Collaborators](#thankscollaborators)
+
+<!-- /TOC -->
+
+## 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 @teselagen/bio-parsers`
+
+or
+
+`yarn add @teselagen/bio-parsers`
+
+or
+
+use it from a script tag:
+
+```html
+<script src="https://unpkg.com/bio-parsers/umd/bio-parsers.js"></script>
+<script>
+  async function main() {
+    var jsonOutput = await window.bioParsers.genbankToJson(
+      `LOCUS       kc2         108 bp    DNA     linear    01-NOV-2016
+COMMENT             teselagen_unique_id: 581929a7bc6d3e00ac7394e8
+FEATURES             Location/Qualifiers
+     CDS             1..108
+                     /label="GFPuv"
+     misc_feature    61..108
+                     /label="gly_ser_linker"
+     bogus_dude      4..60
+                     /label="ccmN_sig_pep"
+     misc_feature    4..60
+                     /label="ccmN_nterm_sig_pep"
+                     /pragma="Teselagen_Part"
+                     /preferred5PrimeOverhangs=""
+                     /preferred3PrimeOverhangs=""
+ORIGIN      
+        1 atgaaggtct acggcaagga acagtttttg cggatgcgcc agagcatgtt ccccgatcgc
+       61 ggtggcagtg gtagcgggag ctcgggtggc tcaggctctg ggg
+//`
+    );
+    console.log("jsonOutput:", jsonOutput);
+    var genbankString = window.bioParsers.jsonToGenbank(jsonOutput[0].parsedSequence);
+    console.log(genbankString);
+  }
+  main();
+</script>
+```
+
+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  <input type="file" id="input" multiple onchange="ab1ToJson(this.files[0])">
+  // 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  <input type="file" id="input" multiple onchange="snapgeneToJson(this.files[0])">
+// 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.
+
+## Updating this repo
+
+### 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)

package/index.js

@@ -6283,8 +6283,8 @@ function getOverlapsOfPotentiallyCircularRanges(rangeA, rangeB, maxRangeLength,
     maxRangeLength
   );
   let overlaps = [];
-  normalizedRangeA.forEach(function(nonCircularRangeA, iA) {
-    normalizedRangeB.forEach(function(nonCircularRangeB, iB) {
+  normalizedRangeA.forEach(function(nonCircularRangeA) {
+    normalizedRangeB.forEach(function(nonCircularRangeB) {
       const overlap = getOverlapOfNonCircularRanges(
         nonCircularRangeA,
         nonCircularRangeB
@@ -6296,7 +6296,7 @@ function getOverlapsOfPotentiallyCircularRanges(rangeA, rangeB, maxRangeLength,
   });
   if (joinIfPossible && normalizedRangeA.length === 2 && normalizedRangeB.length === 2 && maxRangeLength) {
     const joinedOverlap = {};
-    overlaps = lodashExports.flatMap(overlaps, (o, i) => {
+    overlaps = lodashExports.flatMap(overlaps, (o) => {
       if (o.start === 0) {
         joinedOverlap.end = o.end;
         return [];
@@ -6394,12 +6394,14 @@ function trimRangeByAnotherRange(rangeToBeTrimmed, trimmingRange, sequenceLength
     });
     splitRangesToBeTrimmed[index] = nonCircularRangeToBeTrimmed;
   });
-  const outputSplitRanges = splitRangesToBeTrimmed.filter(function(trimmedRange) {
-    if (trimmedRange) {
-      return true;
+  const outputSplitRanges = splitRangesToBeTrimmed.filter(
+    function(trimmedRange) {
+      if (trimmedRange) {
+        return true;
+      }
+      return false;
     }
-    return false;
-  });
+  );
   let outputTrimmedRange;
   if (outputSplitRanges.length < 0)
     ;
@@ -6449,8 +6451,14 @@ function normalizePositionByRangeLength(pPosition, sequenceLength, isInBetweenPo
 __name(normalizePositionByRangeLength, "normalizePositionByRangeLength");
 function translateRange(rangeToBeAdjusted, translateBy, rangeLength) {
   return lodashExports.assign({}, rangeToBeAdjusted, {
-    start: normalizePositionByRangeLength(rangeToBeAdjusted.start + translateBy, rangeLength),
-    end: normalizePositionByRangeLength(rangeToBeAdjusted.end + translateBy, rangeLength)
+    start: normalizePositionByRangeLength(
+      rangeToBeAdjusted.start + translateBy,
+      rangeLength
+    ),
+    end: normalizePositionByRangeLength(
+      rangeToBeAdjusted.end + translateBy,
+      rangeLength
+    )
   });
 }
 __name(translateRange, "translateRange");
@@ -11391,13 +11399,13 @@ function coerceLocation({
     messages.push(
       "Invalid annotation start: " + location.start + " detected for " + location.name + " and set to size: " + size
     );
-    location.start = size - (isProtein ? 3 : 1);
+    location.start = Math.max(0, size - (isProtein ? 3 : 1));
   }
   if (location.end < 0 || !(location.end <= size - 1) || location.end > size - 1) {
     messages.push(
       "Invalid annotation end:  " + location.end + " detected for " + location.name + " and set to seq size: " + size
     );
-    location.end = size - 1;
+    location.end = Math.max(0, size - 1);
   }
   if (location.start > location.end && circular === false) {
     messages.push(
@@ -11410,9 +11418,9 @@ __name(coerceLocation, "coerceLocation");
 function filterAminoAcidSequenceString(sequenceString, options) {
   options = options || {};
   if (options.includeStopCodon) {
-    return sequenceString.replace(/[^xtgalmfwkqespvicyhrndu.*]/gi, "");
+    return sequenceString == null ? void 0 : sequenceString.replace(/[^xtgalmfwkqespvicyhrndu.*]/gi, "");
   }
-  return sequenceString.replace(/[^xtgalmfwkqespvicyhrndu]/gi, "");
+  return sequenceString == null ? void 0 : sequenceString.replace(/[^xtgalmfwkqespvicyhrndu]/gi, "");
 }
 __name(filterAminoAcidSequenceString, "filterAminoAcidSequenceString");
 function getDegenerateDnaStringFromAAString(aaString) {
@@ -11610,7 +11618,7 @@ const calcTmMethods = {
   calculateTemperature: function(sequence, type, A, R, C, Na) {
     if (typeof type === "undefined") {
       type = this.TABLE_BRESLAUER;
-    } else if (type != this.TABLE_BRESLAUER && (type != this.TABLE_UNIFIED && type != this.TABLE_SUGIMOTO)) {
+    } else if (type != this.TABLE_BRESLAUER && type != this.TABLE_UNIFIED && type != this.TABLE_SUGIMOTO) {
       throw new Error("Invalid table type!");
     }
     if (!A) {
@@ -19761,18 +19769,20 @@ function genbankToJson(string, options = {}) {
       const isKeyRunon = isKeywordRunon(line);
       const isSubKey = isSubKeyword(line);
       const isKey = isKeyword(line);
-      if (key === "LOCUS") {
-        LINETYPE = key;
-      } else if (key === "REFERENCE") {
-        LINETYPE = key;
-      } else if (key === "FEATURES") {
-        LINETYPE = key;
-      } else if (key === "ORIGIN") {
-        LINETYPE = key;
-      } else if (key === "//") {
-        LINETYPE = key;
-      } else if (isKey === true) {
-        LINETYPE = key;
+      if (!isKeyRunon) {
+        if (key === "LOCUS") {
+          LINETYPE = key;
+        } else if (key === "REFERENCE") {
+          LINETYPE = key;
+        } else if (key === "FEATURES") {
+          LINETYPE = key;
+        } else if (key === "ORIGIN") {
+          LINETYPE = key;
+        } else if (key === "//") {
+          LINETYPE = key;
+        } else if (isKey === true) {
+          LINETYPE = key;
+        }
       }
       if (line.trim() === "" || key === ";") {
         return false;
@@ -19941,7 +19951,6 @@ function genbankToJson(string, options = {}) {
   __name(parseOrigin, "parseOrigin");
   function parseLocus(line) {
     result = createInitialSequence(options);
-    let locusName;
     let circular;
     let gbDivision;
     let date;
@@ -19952,7 +19961,7 @@ function genbankToJson(string, options = {}) {
       );
       addMessage("Import Warning: Locus line contains no values: " + line);
     }
-    locusName = lineArr[1];
+    const locusName = lineArr[1];
     for (let i = 1; i < lineArr.length; i++) {
       if (lineArr[i].match(/circular/gi)) {
         circular = true;
@@ -20105,10 +20114,10 @@ function genbankToJson(string, options = {}) {
   }
   __name(parseFeatureLocation, "parseFeatureLocation");
   function parseFeatureNote(line) {
-    let newLine, lineArr;
+    let newLine;
     newLine = line.trimLeft();
     newLine = newLine.replace(/^\/|"$/g, "");
-    lineArr = newLine.split(/="|=/);
+    const lineArr = newLine.split(/="|=/);
     let val2 = lineArr.slice(1).join("=");
     if (val2) {
       val2 = val2.replace(/\\/g, " ");
@@ -29914,13 +29923,10 @@ function geneiousXmlToJson(string, options) {
           });
         }
       });
-      const toRet = lodashExports.filter(
-        resultArray,
-        (r) => {
-          var _a3, _b3;
-          return (_b3 = (_a3 = r == null ? void 0 : r.parsedSequence) == null ? void 0 : _a3.sequence) == null ? void 0 : _b3.length;
-        }
-      );
+      const toRet = lodashExports.filter(resultArray, (r) => {
+        var _a3, _b3;
+        return (_b3 = (_a3 = r == null ? void 0 : r.parsedSequence) == null ? void 0 : _a3.sequence) == null ? void 0 : _b3.length;
+      });
       if (toRet.length)
         return toRet;
       return onFileParsed(resultArray);
@@ -30025,13 +30031,10 @@ function jbeiXmlToJson(string, options) {
           messages: ["Error while parsing JBEI format"]
         });
       }
-      const toRet = lodashExports.filter(
-        resultArray,
-        (r) => {
-          var _a3, _b3;
-          return (_b3 = (_a3 = r == null ? void 0 : r.parsedSequence) == null ? void 0 : _a3.sequence) == null ? void 0 : _b3.length;
-        }
-      );
+      const toRet = lodashExports.filter(resultArray, (r) => {
+        var _a3, _b3;
+        return (_b3 = (_a3 = r == null ? void 0 : r.parsedSequence) == null ? void 0 : _a3.sequence) == null ? void 0 : _b3.length;
+      });
       if (toRet.length)
         return toRet;
       return onFileParsed(resultArray);
@@ -32415,7 +32418,6 @@ function createGenbankLocus(serSeq, options) {
   if (serSeq.sequence.symbols) {
     serSeq.sequence = serSeq.sequence.symbols.split("");
   }
-  let tmp;
   let dnaType;
   if (serSeq.isProtein) {
     dnaType = "";
@@ -32432,7 +32434,7 @@ function createGenbankLocus(serSeq, options) {
   line += " ";
   line += StringUtil.lpad(String(serSeq.sequence.length), " ", 11);
   line += serSeq.isProtein ? " aa " : " bp ";
-  tmp = "";
+  const tmp = "";
   line += StringUtil.lpad(tmp, " ", 3);
   line += StringUtil.rpad(dnaType, " ", 6);
   line += "  ";