@gmod/gff

# @gmod/gff [![Build Status](https://img.shields.io/github/workflow/status/GMOD/gff-js/Push/master?logo=github&style=for-the-badge)](https://github.com/GMOD/gff-js/actions?query=branch%3Amaster+workflow%3APush+) Read and write GFF3 data performantly. This module aims to be a complete implementation of the [GFF3 specification](https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md). - streaming parsing and streaming formatting - proper escaping and unescaping of attribute and column values - supports features with multiple locations and features with multiple parents - reconstructs feature hierarchies of both `Parent` and `Derives_from` relationships - parses FASTA sections - does no validation except for referential integrity of `Parent` and `Derives_from` relationships - only compatible with GFF3 ## Install $ npm install --save @gmod/gff ## Usage ```js const gff = require('@gmod/gff').default // or in ES6 (recommended) import gff from '@gmod/gff' const fs = require('fs') // parse a file from a file name // parses only features and sequences by default, // set options to parse directives and/or comments fs.createReadStream('path/to/my/file.gff3') .pipe(gff.parseStream({ parseAll: true })) .on('data', (data) => { if (data.directive) { console.log('got a directive', data) } else if (data.comment) { console.log('got a comment', data) } else if (data.sequence) { console.log('got a sequence from a FASTA section') } else { console.log('got a feature', data) } }) // parse a string of gff3 synchronously const stringOfGFF3 = fs.readFileSync('my_annotations.gff3').toString() const arrayOfThings = gff.parseStringSync(stringOfGFF3) // format an array of items to a string const newStringOfGFF3 = gff.formatSync(arrayOfThings) // format a stream of things to a stream of text. // inserts sync marks automatically. myStreamOfGFF3Objects .pipe(gff.formatStream()) .pipe(fs.createWriteStream('my_new.gff3')) // format a stream of things and write it to // a gff3 file. inserts sync marks and a // '##gff-version 3' header if one is not // already present gff.formatFile( myStreamOfGFF3Objects, fs.createWriteStream('my_new_2.gff3', { encoding: 'utf8' }), ) ``` ## Object format ### features In GFF3, features can have more than one location. We parse features as arrayrefs of all the lines that share that feature's ID. Values that are `.` in the GFF3 are `null` in the output. A simple feature that's located in just one place: ```json [ { "seq_id": "ctg123", "source": null, "type": "gene", "start": 1000, "end": 9000, "score": null, "strand": "+", "phase": null, "attributes": { "ID": [ "gene00001" ], "Name": [ "EDEN" ] }, "child_features": [], "derived_features": [] } ] ``` A CDS called `cds00001` located in two places: ```json [ { "seq_id": "ctg123", "source": null, "type": "CDS", "start": 1201, "end": 1500, "score": null, "strand": "+", "phase": "0", "attributes": { "ID": ["cds00001"], "Parent": ["mRNA00001"] }, "child_features": [], "derived_features": [] }, { "seq_id": "ctg123", "source": null, "type": "CDS", "start": 3000, "end": 3902, "score": null, "strand": "+", "phase": "0", "attributes": { "ID": ["cds00001"], "Parent": ["mRNA00001"] }, "child_features": [], "derived_features": [] } ] ``` ### directives ```js parseDirective("##gff-version 3\n") // returns { "directive": "gff-version", "value": "3" } ``` ```js parseDirective('##sequence-region ctg123 1 1497228\n') // returns { "directive": "sequence-region", "value": "ctg123 1 1497228", "seq_id": "ctg123", "start": "1", "end": "1497228" } ``` ### comments ```js parseComment('# hi this is a comment\n') // returns { "comment": "hi this is a comment" } ``` ### sequences These come from any embedded `##FASTA` section in the GFF3 file. ```js parseSequences(`##FASTA >ctgA test contig ACTGACTAGCTAGCATCAGCGTCGTAGCTATTATATTACGGTAGCCA`) // returns [ { "id": "ctgA", "description": "test contig", "sequence": "ACTGACTAGCTAGCATCAGCGTCGTAGCTATTATATTACGGTAGCCA" } ] ``` ## API  #### Table of Contents - [ParseOptions](#parseoptions) - [encoding](#encoding) - [parseFeatures](#parsefeatures) - [parseDirectives](#parsedirectives) - [parseComments](#parsecomments) - [parseSequences](#parsesequences) - [parseAll](#parseall) - [bufferSize](#buffersize) - [parseStream](#parsestream) - [Parameters](#parameters) - [parseStringSync](#parsestringsync) - [Parameters](#parameters-1) - [formatSync](#formatsync) - [Parameters](#parameters-2) - [formatStream](#formatstream) - [Parameters](#parameters-3) - [formatFile](#formatfile) - [Parameters](#parameters-4) ### ParseOptions Parser options #### encoding Text encoding of the input GFF3. default 'utf8' Type: BufferEncoding #### parseFeatures Whether to parse features, default true Type: [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) #### parseDirectives Whether to parse directives, default false Type: [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) #### parseComments Whether to parse comments, default false Type: [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) #### parseSequences Whether to parse sequences, default true Type: [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) #### parseAll Parse all features, directives, comments, and sequences. Overrides other parsing options. Default false. Type: [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) #### bufferSize Maximum number of GFF3 lines to buffer, default 1000 Type: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) ### parseStream Parse a stream of text data into a stream of feature, directive, comment, an sequence objects. #### Parameters - `options` **[ParseOptions](#parseoptions)** Parsing options (optional, default `{}`) Returns **GFFTransform** stream (in objectMode) of parsed items ### parseStringSync Synchronously parse a string containing GFF3 and return an array of the parsed items. #### Parameters - `str` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** GFF3 string - `inputOptions` **({encoding: BufferEncoding?, bufferSize: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?} | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))?** Parsing options Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<(GFF3Feature | GFF3Sequence)>** array of parsed features, directives, comments and/or sequences ### formatSync Format an array of GFF3 items (features,directives,comments) into string of GFF3. Does not insert synchronization (###) marks. #### Parameters - `items` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\<GFF3Item>** Array of features, directives, comments and/or sequences Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the formatted GFF3 ### formatStream Format a stream of features, directives, comments and/or sequences into a stream of GFF3 text. Inserts synchronization (###) marks automatically. #### Parameters - `options` **FormatOptions** parser options (optional, default `{}`) Returns **FormattingTransform** ### formatFile Format a stream of features, directives, comments and/or sequences into a GFF3 file and write it to the filesystem. Inserts synchronization (###) marks and a ##gff-version directive automatically (if one is not already present). #### Parameters - `stream` **Readable** the stream to write to the file - `writeStream` **Writable** - `options` **FormatOptions** parser options (optional, default `{}`) - `filename` the file path to write to Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<null>** promise for null that resolves when the stream has been written ## About `util` There is also a `util` module that contains super-low-level functions for dealing with lines and parts of lines. ```js // non-ES6 const util = require('@gmod/gff').default.util // or, with ES6 import gff from '@gmod/gff' const util = gff.util const gff3Lines = util.formatItem({ seq_id: 'ctgA', ... })) ``` ## util  #### Table of Contents - [unescape](#unescape) - [Parameters](#parameters) - [escape](#escape) - [Parameters](#parameters-1) - [escapeColumn](#escapecolumn) - [Parameters](#parameters-2) - [parseAttributes](#parseattributes) - [Parameters](#parameters-3) - [parseFeature](#parsefeature) - [Parameters](#parameters-4) - [parseDirective](#parsedirective) - [Parameters](#parameters-5) - [formatAttributes](#formatattributes) - [Parameters](#parameters-6) - [formatFeature](#formatfeature) - [Parameters](#parameters-7) - [formatDirective](#formatdirective) - [Parameters](#parameters-8) - [formatComment](#formatcomment) - [Parameters](#parameters-9) - [formatSequence](#formatsequence) - [Parameters](#parameters-10) - [formatItem](#formatitem) - [Parameters](#parameters-11) - [GFF3Attributes](#gff3attributes) - [GFF3FeatureLine](#gff3featureline) - [seq_id](#seq_id) - [source](#source) - [type](#type) - [start](#start) - [end](#end) - [score](#score) - [strand](#strand) - [phase](#phase) - [attributes](#attributes) - [GFF3FeatureLineWithRefs](#gff3featurelinewithrefs) - [child_features](#child_features) - [derived_features](#derived_features) - [GFF3Feature](#gff3feature) - [GFF3Directive](#gff3directive) - [directive](#directive) - [value](#value) - [GFF3SequenceRegionDirective](#gff3sequenceregiondirective) - [value](#value-1) - [seq_id](#seq_id-1) - [start](#start-1) - [end](#end-1) - [GFF3GenomeBuildDirective](#gff3genomebuilddirective) - [value](#value-2) - [source](#source-1) - [buildName](#buildname) - [GFF3Comment](#gff3comment) - [comment](#comment) - [GFF3Sequence](#gff3sequence) - [id](#id) - [description](#description) - [sequence](#sequence) ### unescape Unescape a string value used in a GFF3 attribute. #### Parameters - `stringVal` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Escaped GFF3 string value Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** An unescaped string value ### escape Escape a value for use in a GFF3 attribute value. #### Parameters - `rawVal` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** Raw GFF3 attribute value Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** An escaped string value ### escapeColumn Escape a value for use in a GFF3 column value. #### Parameters - `rawVal` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** Raw GFF3 column value Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** An escaped column value ### parseAttributes Parse the 9th column (attributes) of a GFF3 feature line. #### Parameters - `attrString` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** String of GFF3 9th column Returns **[GFF3Attributes](#gff3attributes)** Parsed attributes ### parseFeature Parse a GFF3 feature line #### Parameters - `line` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** GFF3 feature line Returns **[GFF3FeatureLine](#gff3featureline)** The parsed feature ### parseDirective Parse a GFF3 directive line. #### Parameters - `line` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** GFF3 directive line Returns **([GFF3Directive](#gff3directive) | [GFF3SequenceRegionDirective](#gff3sequenceregiondirective) | [GFF3GenomeBuildDirective](#gff3genomebuilddirective) | null)** The parsed directive ### formatAttributes Format an attributes object into a string suitable for the 9th column of GFF3. #### Parameters - `attrs` **[GFF3Attributes](#gff3attributes)** Attributes Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** GFF3 9th column string ### formatFeature Format a feature object or array of feature objects into one or more lines of GFF3. #### Parameters - `featureOrFeatures` **([GFF3FeatureLine](#gff3featureline) | [GFF3FeatureLineWithRefs](#gff3featurelinewithrefs) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<([GFF3FeatureLine](#gff3featureline) | [GFF3FeatureLineWithRefs](#gff3featurelinewithrefs))>)** A feature object or array of feature objects Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** A string of one or more GFF3 lines ### formatDirective Format a directive into a line of GFF3. #### Parameters - `directive` **[GFF3Directive](#gff3directive)** A directive object Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** A directive line string ### formatComment Format a comment into a GFF3 comment. Yes I know this is just adding a # and a newline. #### Parameters - `comment` **[GFF3Comment](#gff3comment)** A comment object Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** A comment line string ### formatSequence Format a sequence object as FASTA #### Parameters - `seq` **[GFF3Sequence](#gff3sequence)** A sequence object Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Formatted single FASTA sequence string ### formatItem Format a directive, comment, sequence, or feature, or array of such items, into one or more lines of GFF3. #### Parameters - `itemOrItems` **([GFF3FeatureLineWithRefs](#gff3featurelinewithrefs) | [GFF3Directive](#gff3directive) | [GFF3Comment](#gff3comment) | [GFF3Sequence](#gff3sequence) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<([GFF3FeatureLineWithRefs](#gff3featurelinewithrefs) | [GFF3Directive](#gff3directive) | [GFF3Comment](#gff3comment) | [GFF3Sequence](#gff3sequence))>)** A comment, sequence, or feature, or array of such items Returns **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** A formatted string or array of strings ### GFF3Attributes A record of GFF3 attribute identifiers and the values of those identifiers Type: Record<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), ([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))> ### GFF3FeatureLine A representation of a single line of a GFF3 file #### seq_id The ID of the landmark used to establish the coordinate system for the current feature Type: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | null) #### source A free text qualifier intended to describe the algorithm or operating procedure that generated this feature Type: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | null) #### type The type of the feature Type: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | null) #### start The start coordinates of the feature Type: ([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | null) #### end The end coordinates of the feature Type: ([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | null) #### score The score of the feature Type: ([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | null) #### strand The strand of the feature Type: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | null) #### phase For features of type "CDS", the phase indicates where the next codon begins relative to the 5' end of the current CDS feature Type: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | null) #### attributes Feature attributes Type: ([GFF3Attributes](#gff3attributes) | null) ### GFF3FeatureLineWithRefs **Extends GFF3FeatureLine** A GFF3 Feature line that includes references to other features defined in their "Parent" or "Derives_from" attributes #### child_features An array of child features Type: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[GFF3Feature](#gff3feature)> #### derived_features An array of features derived from this feature Type: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[GFF3Feature](#gff3feature)> ### GFF3Feature A GFF3 feature, which may include multiple individual feature lines Type: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[GFF3FeatureLineWithRefs](#gff3featurelinewithrefs)> ### GFF3Directive A GFF3 directive #### directive The name of the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### value The string value of the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) ### GFF3SequenceRegionDirective **Extends GFF3Directive** A GFF3 sequence-region directive #### value The string value of the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### seq_id The sequence ID parsed from the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### start The sequence start parsed from the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### end The sequence end parsed from the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) ### GFF3GenomeBuildDirective **Extends GFF3Directive** A GFF3 genome-build directive #### value The string value of the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### source The genome build source parsed from the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### buildName The genome build name parsed from the directive Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) ### GFF3Comment A GFF3 comment #### comment The text of the comment Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) ### GFF3Sequence A GFF3 FASTA single sequence #### id The ID of the sequence Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### description The description of the sequence Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) #### sequence The sequence Type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) ## License MIT © [Robert Buels](https://github.com/rbuels)