sfftkrw¶
This module defines a user-friendly adapter API (compared to the one generated by generateDS). It is designed to fulfill several requirements:
- allow multiple versions of
generateDS
APIs to exist for the same adapter; - implement more convenient ways of working with the classes of the API;
- easily integrate new EMDB-SFF entities into the API;
- decouple the file format from the data model: most classes in this adapter implement methods to handle conversion to non-XML formats (XML is the only format that generateDS writes to)
Here is an example of how the SFFSegmentation
class is defined using these classes (details omitted for brevity):
from .base import SFFType, SFFAttribute
class SFFSegmentation(SFFType):
"""Adapter class to make using the output of ``generateDS`` easier to use"""
gds_type = sff.segmentation
gds_tag_name = "segmentation"
repr_string = "SFFSegmentation(...)"
# attributes
name = SFFAttribute('name', required=True)
version = SFFAttribute('version')
software_list = SFFAttribute('software_list', sff_type=SFFSoftwareList)
primary_descriptor = SFFAttribute('primary_descriptor')
transform_list = SFFAttribute('transform_list', sff_type=SFFTransformList)
bounding_box = SFFAttribute('bounding_box', sff_type=SFFBoundingBox)
global_external_references = SFFAttribute('global_external_references', sff_type=SFFGlobalExternalReferences)
segment_list = SFFAttribute('segment_list', sff_type=SFFSegmentList)
lattice_list = SFFAttribute('lattice_list', sff_type=SFFLatticeList)
details = SFFAttribute('details')
In the above example, the SFFSegmentation
class inherits from SFFType
; SFFType
uses the first three attributes (gds_type
, gds_tag_name
and repr_string
) to configure the user class
SFFSegmentation
. The API user can now exploit SFFSegmentation
without any need to know the
underlying implementation while benefiting from the aforementioned facilities:
from sfftkrw import SFFSegmentation
# to create a new empty EMDB-SFF segmentation object
# provide the only required attribute
seg = SFFSegmentation(name='my name')
seg.to_file('file.sff') # export
# to read an XML-, HDF5- or JSON-formatted file, respectively
seg = SFFSegmentation('file.sff')
seg = SFFSegmentation('file.hff')
seg = SFFSegmentation('file.json')
The attributes (name
, version
, etc.) are all instances of SFFAttribute
, which takes the name (first
positional argument) and an optional keyword argument sff_type
denoting the class of the attribute. In the above
example, the software_list
attribute will be of type SFFSoftwareList
.
To learn more about the core classes please refer to sfftkrw.schema.base.