Read and write GFF3 data performantly. This module aims to be a complete implementation of the GFF3 specification.
- 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
ParentandDerives_fromrelationships - parses FASTA sections
- does no validation except for referential integrity of
ParentandDerives_fromrelationships (can disable Derives_from reference checking withdisableDerivesFromReferences) - only compatible with GFF3
$ npm install --save @gmod/gff
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' }),
)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:
[
{
"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:
[
{
"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": []
}
]parseDirective("##gff-version 3\n")
// returns
{
"directive": "gff-version",
"value": "3"
}parseDirective('##sequence-region ctg123 1 1497228\n')
// returns
{
"directive": "sequence-region",
"value": "ctg123 1 1497228",
"seq_id": "ctg123",
"start": "1",
"end": "1497228"
}parseComment('# hi this is a comment\n')
// returns
{
"comment": "hi this is a comment"
}These come from any embedded ##FASTA section in the GFF3 file.
parseSequences(`##FASTA
>ctgA test contig
ACTGACTAGCTAGCATCAGCGTCGTAGCTATTATATTACGGTAGCCA`)[
// returns
{
id: 'ctgA',
description: 'test contig',
sequence: 'ACTGACTAGCTAGCATCAGCGTCGTAGCTATTATATTACGGTAGCCA',
}
]Parser options
Whether to resolve references to derives from features
Type: boolean
Text encoding of the input GFF3. default 'utf8'
Type: BufferEncoding
Whether to parse features, default true
Type: boolean
Whether to parse directives, default false
Type: boolean
Whether to parse comments, default false
Type: boolean
Whether to parse sequences, default true
Type: boolean
Parse all features, directives, comments, and sequences. Overrides other parsing options. Default false.
Type: boolean
Maximum number of GFF3 lines to buffer, default 1000
Type: number
Parse a stream of text data into a stream of feature, directive, comment, an sequence objects.
optionsParseOptions Parsing options (optional, default{})
Returns GFFTransform stream (in objectMode) of parsed items
Synchronously parse a string containing GFF3 and return an array of the parsed items.
strstring GFF3 stringinputOptions({disableDerivesFromReferences: boolean?, encoding: BufferEncoding?, bufferSize: number?} | undefined)? Parsing options
Returns Array<(GFF3Feature | GFF3Sequence)> array of parsed features, directives, comments and/or sequences
Format an array of GFF3 items (features,directives,comments) into string of GFF3. Does not insert synchronization (###) marks.
itemsArray<GFF3Item> Array of features, directives, comments and/or sequences
Returns string the formatted GFF3
Format a stream of features, directives, comments and/or sequences into a stream of GFF3 text.
Inserts synchronization (###) marks automatically.
optionsFormatOptions parser options (optional, default{})
Returns FormattingTransform
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).
streamReadable the stream to write to the filewriteStreamWritableoptionsFormatOptions parser options (optional, default{})filenamethe file path to write to
Returns Promise<null> promise for null that resolves when the stream has been written
There is also a util module that contains super-low-level functions for dealing with lines and parts of lines.
// 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',
...
}))- unescape
- escape
- escapeColumn
- parseAttributes
- parseFeature
- parseDirective
- formatAttributes
- formatFeature
- formatDirective
- formatComment
- formatSequence
- formatItem
- GFF3Attributes
- GFF3FeatureLine
- GFF3FeatureLineWithRefs
- GFF3Feature
- GFF3Directive
- GFF3SequenceRegionDirective
- GFF3GenomeBuildDirective
- GFF3Comment
- GFF3Sequence
Unescape a string value used in a GFF3 attribute.
stringValstring Escaped GFF3 string value
Returns string An unescaped string value
Escape a value for use in a GFF3 attribute value.
Returns string An escaped string value
Escape a value for use in a GFF3 column value.
Returns string An escaped column value
Parse the 9th column (attributes) of a GFF3 feature line.
attrStringstring String of GFF3 9th column
Returns GFF3Attributes Parsed attributes
Parse a GFF3 feature line
linestring GFF3 feature line
Returns GFF3FeatureLine The parsed feature
Parse a GFF3 directive line.
linestring GFF3 directive line
Returns (GFF3Directive | GFF3SequenceRegionDirective | GFF3GenomeBuildDirective | null) The parsed directive
Format an attributes object into a string suitable for the 9th column of GFF3.
attrsGFF3Attributes Attributes
Returns string GFF3 9th column string
Format a feature object or array of feature objects into one or more lines of GFF3.
featureOrFeatures(GFF3FeatureLine | GFF3FeatureLineWithRefs | Array<(GFF3FeatureLine | GFF3FeatureLineWithRefs)>) A feature object or array of feature objects
Returns string A string of one or more GFF3 lines
Format a directive into a line of GFF3.
directiveGFF3Directive A directive object
Returns string A directive line string
Format a comment into a GFF3 comment. Yes I know this is just adding a # and a newline.
commentGFF3Comment A comment object
Returns string A comment line string
Format a sequence object as FASTA
seqGFF3Sequence A sequence object
Returns string Formatted single FASTA sequence string
Format a directive, comment, sequence, or feature, or array of such items, into one or more lines of GFF3.
itemOrItems(GFF3FeatureLineWithRefs | GFF3Directive | GFF3Comment | GFF3Sequence | Array<(GFF3FeatureLineWithRefs | GFF3Directive | GFF3Comment | GFF3Sequence)>) A comment, sequence, or feature, or array of such items
Returns (string | Array<string>) A formatted string or array of strings
A record of GFF3 attribute identifiers and the values of those identifiers
Type: Record<string, (Array<string> | undefined)>
A representation of a single line of a GFF3 file
The ID of the landmark used to establish the coordinate system for the current feature
Type: (string | null)
A free text qualifier intended to describe the algorithm or operating procedure that generated this feature
Type: (string | null)
The type of the feature
Type: (string | null)
The start coordinates of the feature
Type: (number | null)
The end coordinates of the feature
Type: (number | null)
The score of the feature
Type: (number | null)
The strand of the feature
Type: (string | null)
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 | null)
Feature attributes
Type: (GFF3Attributes | null)
Extends GFF3FeatureLine
A GFF3 Feature line that includes references to other features defined in their "Parent" or "Derives_from" attributes
An array of child features
Type: Array<GFF3Feature>
An array of features derived from this feature
Type: Array<GFF3Feature>
A GFF3 feature, which may include multiple individual feature lines
Type: Array<GFF3FeatureLineWithRefs>
A GFF3 directive
The name of the directive
Type: string
The string value of the directive
Type: string
Extends GFF3Directive
A GFF3 sequence-region directive
The string value of the directive
Type: string
The sequence ID parsed from the directive
Type: string
The sequence start parsed from the directive
Type: string
The sequence end parsed from the directive
Type: string
Extends GFF3Directive
A GFF3 genome-build directive
The string value of the directive
Type: string
The genome build source parsed from the directive
Type: string
The genome build name parsed from the directive
Type: string
A GFF3 comment
The text of the comment
Type: string
A GFF3 FASTA single sequence
The ID of the sequence
Type: string
The description of the sequence
Type: string
The sequence
Type: string
MIT © Robert Buels