polyjson

Documentation

Overview

Package polyjson provides utilities to read and write poly.Sequence structs as JSON.

Poly's JSON schema is still in flux so be on the lookout for breaking changes as we approach the 1.0 release.

Example

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"time"

	"github.com/bebop/poly/io/polyjson"
	"github.com/bebop/poly/seqhash"
)

func main() {
	// this example also is run by the poly's test suite so this just sets up a temporary directory for writing files
	tmpDataDir, err := os.MkdirTemp("", "data-*")
	if err != nil {
		fmt.Println(err.Error())
	}

	defer os.RemoveAll(tmpDataDir)

	// initiate a new polyjson sequence struct
	var sequence polyjson.Poly

	// define the meta section of our sequence.
	sequence.Meta.Name = "Cat DNA"
	sequence.Meta.Description = "Synthetic Cat DNA for testing purposes."
	sequence.Meta.CreatedBy = "Catz (all you basepair are belong to us)"
	sequence.Meta.CreatedOn = time.Now()
	sequence.Meta.URL = "www.allyourbasepair.com/catz"
	sequence.Meta.CreatedWith = "Poly - The world's most modern, open source software library for engineering organisms."

	// add our sequence string and its hash to use as a unique identifier.
	sequence.Sequence = "CATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCAT"
	sequence.Meta.Hash, _ = seqhash.Hash(sequence.Sequence, "DNA", false, true)

	// add our sequence features
	catFeature := polyjson.Feature{}
	catFeature.Name = "Cat coding region."
	catFeature.Description = "a cat coding region at the beginning of our sequence."
	catFeature.Type = "CDS"
	catFeature.Location.Start = 0
	catFeature.Location.End = 8
	catFeature.Tags = map[string]string{"product": "cat protein"}

	_ = sequence.AddFeature(&catFeature) // add the feature annotation to our sequence

	// write our sequence to a JSON file
	tmpJSONFilePath := filepath.Join(tmpDataDir, "sample.json")
	_ = polyjson.Write(sequence, tmpJSONFilePath)

	exportedSequence, _ := polyjson.Read(tmpJSONFilePath)

	// print our struct DNA sequence
	fmt.Println(exportedSequence.Sequence)
}

Output:

CATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCAT

Index

• func Write(sequence Poly, path string) error
• type Feature
  • func (feature Feature) GetSequence() (string, error)
• type Location
• type Meta
• type Poly
  • func Parse(file io.Reader) (Poly, error)
  • func Read(path string) (Poly, error)
  • func (sequence *Poly) AddFeature(feature *Feature) error

Examples

• Package
• Feature.GetSequence
• Parse
• Poly.AddFeature
• Read
• Write

Functions

func Write

func Write(sequence Poly, path string) error

Write writes a Poly struct out to json.

Example

package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/bebop/poly/io/polyjson"
)

func main() {
	tmpDataDir, err := os.MkdirTemp("", "data-*")
	if err != nil {
		fmt.Println(err.Error())
	}
	defer os.RemoveAll(tmpDataDir)

	sequence, _ := polyjson.Read("../../data/cat.json")

	tmpJSONFilePath := filepath.Join(tmpDataDir, "sample.json")
	_ = polyjson.Write(sequence, tmpJSONFilePath)

	testSequence, _ := polyjson.Read(tmpJSONFilePath)

	fmt.Println(testSequence.Sequence)
}

Output:

CATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCAT

Types

type Feature

type Feature struct {
	Name           string            `json:"name"`
	Hash           string            `json:"hash"`
	Type           string            `json:"type"`
	Description    string            `json:"description"`
	Location       Location          `json:"location"`
	Tags           map[string]string `json:"tags"`
	Sequence       string            `json:"sequence"`
	ParentSequence *Poly             `json:"-"`
}

Feature contains all the feature data for a poly feature struct.

func (Feature) GetSequence

func (feature Feature) GetSequence() (string, error)

GetSequence takes a feature and returns a sequence string for that feature.

Example

package main

import (
	"fmt"

	"github.com/bebop/poly/io/polyjson"
)

func main() {
	// Sequence for greenflourescent protein (GFP) that we're using as test data for this example.
	gfpSequence := "ATGGCTAGCAAAGGAGAAGAACTTTTCACTGGAGTTGTCCCAATTCTTGTTGAATTAGATGGTGATGTTAATGGGCACAAATTTTCTGTCAGTGGAGAGGGTGAAGGTGATGCTACATACGGAAAGCTTACCCTTAAATTTATTTGCACTACTGGAAAACTACCTGTTCCATGGCCAACACTTGTCACTACTTTCTCTTATGGTGTTCAATGCTTTTCCCGTTATCCGGATCATATGAAACGGCATGACTTTTTCAAGAGTGCCATGCCCGAAGGTTATGTACAGGAACGCACTATATCTTTCAAAGATGACGGGAACTACAAGACGCGTGCTGAAGTCAAGTTTGAAGGTGATACCCTTGTTAATCGTATCGAGTTAAAAGGTATTGATTTTAAAGAAGATGGAAACATTCTCGGACACAAACTCGAGTACAACTATAACTCACACAATGTATACATCACGGCAGACAAACAAAAGAATGGAATCAAAGCTAACTTCAAAATTCGCCACAACATTGAAGATGGATCCGTTCAACTAGCAGACCATTATCAACAAAATACTCCAATTGGCGATGGCCCTGTCCTTTTACCAGACAACCATTACCTGTCGACACAATCTGCCCTTTCGAAAGATCCCAACGAAAAGCGTGACCACATGGTCCTTCTTGAGTTTGTAACTGCTGCTGGGATTACACATGGCATGGATGAGCTCTACAAATAA"

	// initialize sequence and feature structs.
	var sequence polyjson.Poly
	var feature polyjson.Feature

	// set the initialized sequence struct's sequence.
	sequence.Sequence = gfpSequence

	// Set the initialized feature name and sequence location.
	feature.Description = "Green Fluorescent Protein"
	feature.Location.Start = 0
	feature.Location.End = len(sequence.Sequence)

	// Add the GFP feature to the sequence struct.
	_ = sequence.AddFeature(&feature)

	// get the GFP feature sequence string from the sequence struct.
	featureSequence, _ := feature.GetSequence()

	// check to see if the feature was inserted properly into the sequence.
	fmt.Println(gfpSequence == featureSequence)

}

Output:

true

type Location

type Location struct {
	Start             int        `json:"start"`
	End               int        `json:"end"`
	Complement        bool       `json:"complement"`
	Join              bool       `json:"join"`
	FivePrimePartial  bool       `json:"five_prime_partial"`
	ThreePrimePartial bool       `json:"three_prime_partial"`
	SubLocations      []Location `json:"sub_locations"`
}

Location contains all the location data for a poly feature's location.

type Meta

type Meta struct {
	Name        string    `json:"name"`
	Hash        string    `json:"hash"`
	Description string    `json:"description"`
	URL         string    `json:"url"`
	CreatedBy   string    `json:"created_by"`
	CreatedWith string    `json:"created_with"`
	CreatedOn   time.Time `json:"created_on"`
	Schema      string    `json:"schema"`
}

Meta contains all the metadata for a poly sequence struct.

type Poly

type Poly struct {
	Meta     Meta      `json:"meta"`
	Features []Feature `json:"features"`
	Sequence string    `json:"sequence"`
}

Poly is poly's native JSON representation of a sequence.

func Parse

func Parse(file io.Reader) (Poly, error)

Parse parses a Poly JSON file and adds appropriate pointers to struct.

Example

package main

import (
	"fmt"
	"os"

	"github.com/bebop/poly/io/polyjson"
)

func main() {
	file, _ := os.Open("../../data/cat.json")
	sequence, _ := polyjson.Parse(file)

	fmt.Println(sequence.Sequence)
}

Output:

CATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCAT

func Read

func Read(path string) (Poly, error)

Read reads a Poly JSON file.

Example

package main

import (
	"fmt"

	"github.com/bebop/poly/io/polyjson"
)

func main() {
	sequence, _ := polyjson.Read("../../data/cat.json")

	fmt.Println(sequence.Sequence)
}

Output:

CATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCATCAT

func (*Poly) AddFeature

func (sequence *Poly) AddFeature(feature *Feature) error

AddFeature adds a feature to a Poly struct. Does not add the feature's sequence

Example

package main

import (
	"fmt"

	"github.com/bebop/poly/io/polyjson"
)

func main() {
	// Sequence for greenflourescent protein (GFP) that we're using as test data for this example.
	gfpSequence := "ATGGCTAGCAAAGGAGAAGAACTTTTCACTGGAGTTGTCCCAATTCTTGTTGAATTAGATGGTGATGTTAATGGGCACAAATTTTCTGTCAGTGGAGAGGGTGAAGGTGATGCTACATACGGAAAGCTTACCCTTAAATTTATTTGCACTACTGGAAAACTACCTGTTCCATGGCCAACACTTGTCACTACTTTCTCTTATGGTGTTCAATGCTTTTCCCGTTATCCGGATCATATGAAACGGCATGACTTTTTCAAGAGTGCCATGCCCGAAGGTTATGTACAGGAACGCACTATATCTTTCAAAGATGACGGGAACTACAAGACGCGTGCTGAAGTCAAGTTTGAAGGTGATACCCTTGTTAATCGTATCGAGTTAAAAGGTATTGATTTTAAAGAAGATGGAAACATTCTCGGACACAAACTCGAGTACAACTATAACTCACACAATGTATACATCACGGCAGACAAACAAAAGAATGGAATCAAAGCTAACTTCAAAATTCGCCACAACATTGAAGATGGATCCGTTCAACTAGCAGACCATTATCAACAAAATACTCCAATTGGCGATGGCCCTGTCCTTTTACCAGACAACCATTACCTGTCGACACAATCTGCCCTTTCGAAAGATCCCAACGAAAAGCGTGACCACATGGTCCTTCTTGAGTTTGTAACTGCTGCTGGGATTACACATGGCATGGATGAGCTCTACAAATAA"

	// initialize sequence and feature structs.
	var sequence polyjson.Poly
	var feature polyjson.Feature

	// set the initialized sequence struct's sequence.
	sequence.Sequence = gfpSequence

	// Set the initialized feature name and sequence location.
	feature.Description = "Green Fluorescent Protein"
	feature.Location = polyjson.Location{}
	feature.Location.Start = 0
	feature.Location.End = len(sequence.Sequence)

	// Add the GFP feature to the sequence struct.
	_ = sequence.AddFeature(&feature)

	// get the GFP feature sequence string from the sequence struct.
	featureSequence, _ := feature.GetSequence()

	// check to see if the feature was inserted properly into the sequence.
	fmt.Println(gfpSequence == featureSequence)

}

Output:

true