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.

SFFSegmentation class

SFFSoftwareList class

SFFSoftware class

SFFTransformList class

SFFTransformationMatrix class

SFFBoundingBox class

SFFGlobalExternalReferenceList class

SFFExternalReferenceList class

SFFExternalReference class

SFFSegmentList class

SFFSegment class

SFFBiologicalAnnotation class


SFFEncodedSequence class

SFFVertices class

SFFNormals class

SFFTriangles class

SFFMeshList class

SFFMesh class

SFFThreeDVolume class

SFFLatticeList class

SFFLattice class

SFFVolumeStructure class

SFFVolumeIndex class

SFFShapePrimitiveList class

SFFShape class

SFFCone class

SFFCuboid class

SFFCylinder class

SFFEllipsoid class