Alhambra File Format
====================


Introduction
------------

Alhambra uses a unified, `YAML-based <yaml.org>`__ file format for both
its input and output, and for describing tile systems from an abstract
level to an experiment-ready sequence level.

This format can be written and modified by hand, and can also be
generated and modified through Alhambra or other programmatic methods.
Alhambra uses `ruamel.yaml <https://bitbucket.org/ruamel/yaml>`__ for
loading and saving YAML files, which should result in comments being
preserved.

Alhambra’s file format is currently designed to store the following
information:

-  Tile descriptions (name, structure, labels, sticky ends, sequences,
   etc)
-  End descriptions (name, type, orientation, sequence)
-  Origami seed descriptions (type, adapters)
-  Xgrow parameters
-  Generation information (sequence design parameters for ends, tiles,
   etc - a log of what Alhambra has done)

Other information can easily be added by adding extra key/value pairs.

The top level of the YAML file should be a mapping. Alhambra recognizes
the following key/value pairs:

-  tiles: a list of tiles
-  ends: a list of sticky ends
-  seed: a mapping describing the seed
-  info: a mapping of system information
-  guards: a list of guard strands and sequences
-  xgrow_params: (or xgrow_options) a mapping of xgrow options
   
tiles
-----

The value attached to the tile key should be a YAML sequence. Each
sequence item should be a mapping, with the following keys recognized by
Alhambra:

-  name: (required, or one will be generated by Alhambra) the name of
   the tile. This should be a name that is compatible with
   peppercompiler’s component naming restrictions.
-  structure: (required) a name of a TileStructure class describing the
   tile's structure.  Eg 'tile_daoe_3up'.
-  ends: a YAML sequence of end names. Complements should be indicated
   with / at the end of the name.
-  label: a label option for the TileStructure, describing what label
   should be used, if any.  At the moment, the only option most
   structures recognize is 'both', which puts two biotinylated Ts in
   the middle of the tile.
-  color: a color for Xgrow and diagrams FIXME.
-  strands (or fullseqs): a YAML sequence of strand sequence strings.  Usually
   generated by Alhambra.

ends
----

The value attached to the ends jey should be a YAML sequence.  Each
sequence item should be mapping, with the following keys recognized by
Alhambra:

- name: (required) the name of the end.
- type: the end type, as in Stickydesign, usually TD (5' is terminal,
  3' attaches to tile), DT (5' continues to tile, 3' is terminal).
- fseq: The full (end plus adjacent base and complement of the complement's adjacent base)
  sequence of the end, usually generated by Alhambra.

seed
----

- type
- adapters
- use_adapters

guards
------

info
----

- reorder
- core
- end_design
