Package bar :: Module atlas_indexer :: Class barIndexer

Class barIndexer

Class of objects representing whole CAF dataset index.

The class provides also methods to create CAF dataset index de novo.

It is assumed that structure names are unique and it is not necessary to introduce another uniqe ID. However, a kind of UID (unique ID) is introduced inside the index. The UID is used to create complex structure hierarchy.

Please note that this class operates in two ways when creating CAF dataset index:

First stage is collecting information about slides and structures. When slide is parsed, module extracts all information about slide number, spatial coordinates etc.
Second stage is generating XML representation of stored data. XML file is generated and saved.

Note: Be advised that hierarchy and mappings should be assigned in defined order:

Indexing all slides
Defining hierarchy (using createFlatHierarchy or setParentsFromFile),
Then assigning full name mapping using e.g. using self.fullNameMapping or setNameMappingFromFile,
Assigning color mapping using self.colorMapping or setColorMappingFromFile.

To Do: Handle utf-8 structure names somehow...

Nested Classes

[hide private]

class _groupElement
class of objects representing 'group' elements

class _indexerElement
parental class for classes of objects representing encapsulated elements

class _propertyElement
class of objects representing 'property' elements

class _slideElement
class of objects representing 'slide' elements

class _structureElement
class of objects representing 'structure' elements

Inherited from base.barObject (private): _clsBoundingBox, _clsBregmaMetadataElement, _clsCommentLabel, _clsGenericStructure, _clsMetadataElement, _clsPath, _clsRegularLabel, _clsSpotLabel, _clsStructureLabel, _clsTransfMatrixMetadataElement

Instance Methods

[hide private]

__addGroup(self, group, parent=None)
Parse the hierarchy group (sub)tree and update self._hierarchyGroups according to information in the tree nodes; update information about parental nodes in the nodes of the tree.

__fromXML(cls, sourceXMLElement)

int

__getGID(self)
Returns: value of the next element of the GID sequence

{str : barIndexerPropertyElement}

__getProperty(self)
Returns: CAF dataset index property name to 'property' element representation mapping

{int : barIndexerSlideElement}

__getSlides(self)
Returns: slidenumber to 'slide' element representation mapping

{str : barIndexerStructureElement}

__getStructures(self)
Returns: name to 'structure' element representation mapping

int

__getUID(self)
Returns: value of the next element of the UID sequence

{str : [int, ...]}

__getUidList(self)
For each of hierarchy groups find UIDs of structures assigned to it.

__indexStructures(self, structure, slide)
Index provided structure with slide.

__init__(self, hierarchyRootElementName='Brain')
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

__normaliseIDs(self)
Normalise ID and UID of groups and structures.

__setGID(self, val)
Increase the value of the current element of the GID sequence.

__setProperty(self, newValue)
Raise ValueError.

__setSlides(self, newValue)
Raise ValueError.

__setStructures(self, newValue)
Raise ValueError.

__setUID(self, val)
Increase the value of the current element of the UID sequence.

__setUidList(self, newList)
Raise ValueError.

_validateInternalData(self)
Perform internal indexed properties validation.

clearProperties(self)
Remove all CAF dataset index properties.

fixOrphanStructures(self, parentGrpName=None)
Search for structures not covered by hierarchy, then bind them to the requested hierarchy group.

xml.dom.Document

getXMLelement(self)
Returns: XML representation of represented CAF dataset index

indexSingleSlide(self, tracedSlide, slideNumber)
Register given CAF slide to the CAF dataset index.

normaliseIDs(self)
An alias for self.__normaliseIDs().

setParentsFromFile(self, hierarchyFilename, childCol=0, parentCol=1)
Create structure hierarchy according to relation provided in the file.

set([str, ...])

unfoldSubtrees(self, rootStructures, defaultDepth=0, leavesOnly=False)
Returns: names of hierarchy subtree tree nodes related to any structure present in CAF slides

updateProperties(self, propsDict)
Updates properties of the indexer with the data from provided dictionary.

visibleGroups(self, depth=999, leavesOnly=False)
An alias for self.groups[self.hierarchyRootElementName].getVisibleGroupIterator().

Inherited from base.barObject: __str__, getElementById, writeXMLtoFile

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __subclasshook__

color_mappings

{str : str}

__getColorMapping(self)
Returns: hierarchy group name to colour mapping

__setColorMapping(self, sourceDictionary=None, dummyElementColor='#777777')
Assign colours to the hierarchy groups.

setColorMappingFromFile(self, colorFilename, nameCol=0, colourCol=1)
Assign colours to the hierarchy groups.

fullname_mappings

{str : str}

__getFullNameMapping(self)
Returns: hierarchy group name to full name mapping

__setFullNameMapping(self, sourceDictionary=None, dummyNameElement='------')
Assign full names to the hierarchy groups.

setNameMappingFromFile(self, filename, nameCol=0, fullNameCol=1)
Assign full names to the hierarchy groups.

hierarchy

tuple

__getHierarchy(self)
Returns: tuple-based hierarchy tree

{str : barIndexerGroupElement}

__getHierarchyGroups(self)
Returns: name to 'group' element representation mapping

str

__getHierarchyRoot(self)
Returns: name of the superior group of the CAF dataset structures hierarhy

__setHierarchy(self, sourceDictionary)
Create structure hierarchy according to provided relation.

__setHierarchyGroups(self, newValue)
Raise ValueError.

__setHierarchyRoot(self, hierarchyRootElementName)
Define the name of the superior group of the CAF dataset structures hierarhy.

__validateHierarchy(self, sourceDictionary)
Just a stub.

_setHierarchyRelation(self, child, parent)
Create parent - child relation between two hierarchy groups.

createFlatHierarchy(self)
Create flat hierary: gather all component structures under common superior hierarchyRootElementName hierarchy group element.

Class Methods

[hide private]

fromXML(cls, sourceXMLElement)
__fromXML method bound to the class as its classmethod.

Static Methods

[hide private]

_fromXML(cls, sourceXMLElement)
__fromXML method not bound to the class nor to the class instance.

Inherited from base.barObject (private): _getAttributesDict

Class Variables

[hide private]

[str, ...] _elementsList = ['slideindex', 'atlasproperties', 'slidedetail...
names of XML elements partitioning CAF dataset index file

{str: int} _initialIDs = {'gid': 200000, 'uid': 100000}
initial values of UID/GID sequences

[str, ...] _requiredInternalData = ['ReferenceWidth', 'ReferenceHeight', ...
names of required CAF dataset properties

Instance Variables

[hide private]

{str : str}

_colorMapping
cached hierarchy group name to colour mapping dictionary

int

_gid
current value of GID sequence

{str : _groupElement, ...}

_hierarchyGroups
hierarchy group name to object representing related 'group' element mapping

str

_hierarchyRootElementName
name of the superior group of the hierarhy gathering all structures

{str : _propertyElement, ...}

_properties
CAF dataset property name to object representing related 'property' element mapping

{int : _slideElement, ...}

_slides
CAF slide number to object representing related 'slide' element mapping

{str : _structureElement, ...}

_structures
structure name to object representing related 'structure' element mapping

int

_uid
current value of UID sequence

str

cafDirectory
path to the directory where the CAF dataset index file is located

fullname_mappings

{str : str}

_fullNameMapping
cached hierarchy group name to full name mapping

Properties

[hide private]

{str : str} colorMapping
Hierarchy group name to colour mapping.

int gid
If read - the value of the next element of the GID sequence.

{str : barIndexerGroupElement} groups
Name to 'group' element representation mapping.

non consistent hierarchy
Hierarchy of the CAF dataset structures.

str hierarchyRootElementName
Name of the superior group of the CAF dataset structures hierarhy.

{str : barIndexerPropertyElement} properties
Name to 'property' element representation mapping.

{str : barIndexerSlideElement} slides
Slide number to 'slide' element representation mapping.

{str : barIndexerGroupElement} structures
Name to 'structure' element representation mapping.

int uid
If read - he value of the next element of the UID sequence.

{str : [int, ...]} uidList
Hierarchy group name to UIDs of assigned structures mapping.

Inherited from object: __class__

fullname_mappings

{str : str} fullNameMapping
Hierarchy group name to fullname mapping.

Method Details

[hide private]

__addGroup(self, group, parent=None)

Parse the hierarchy group (sub)tree and update self._hierarchyGroups according to information in the tree nodes; update information about parental nodes in the nodes of the tree.

Parameters:

group (barIndexerGroupElement) - hierarchy group (sub)tree to be parsed
parent (barIndexerGroupElement) - parental node for the group subtree

__getColorMapping(self)

Returns: {str : str}: hierarchy group name to colour mapping

Note: Result of the method is cached in _colorMapping.

__getFullNameMapping(self)

Returns: {str : str}: hierarchy group name to full name mapping

Note: Result of the method is cached in _fullNameMapping.

__getGID(self)

Returns: int: value of the next element of the GID sequence

__getHierarchy(self)

Returns: tuple: tuple-based hierarchy tree

__getHierarchyGroups(self)

Returns: {str : barIndexerGroupElement}: name to 'group' element representation mapping

__getHierarchyRoot(self)

Returns: str: name of the superior group of the CAF dataset structures hierarhy

__getProperty(self)

Returns: {str : barIndexerPropertyElement}: CAF dataset index property name to 'property' element representation mapping

__getSlides(self)

Returns: {int : barIndexerSlideElement}: slidenumber to 'slide' element representation mapping

Note: be aware that it is not a copy, but the original dictionary!

__getStructures(self)

Returns: {str : barIndexerStructureElement}: name to 'structure' element representation mapping

Note: be aware that it is not a copy, but the original dictionary!

__getUID(self)

Returns: int: value of the next element of the UID sequence

__getUidList(self)

For each of hierarchy groups find UIDs of structures assigned to it.

Example usage:

Filter out elements which may be reconstructed: [name for (name, uid) in self.uidList.iteritems() if uid]
Filter out elements that cannot be reconstructed as they don't have children with paths assigned and they do not have uid assigned itself: [name for (name, uid) in self.uidList.iteritems() if not uid]

Returns: {str : [int, ...]}: hierarchy group name to UIDs of assigned structures mapping

__indexStructures(self, structure, slide)

Index provided structure with slide. If structure already exists in index only new path are appended to it, otherwise new index entry for this structure is created.

Parameters:

structure (barGenericStructure) - structure to index
slide (_slideElement) - slide to be indexed with the structure

init(self, hierarchyRootElementName=`'Brain'`)
(Constructor)

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Parameters:

hierarchyRootElementName (str) - Name of the root element of the hierarchy. The root element is the superior group of the hierarhy gathering all structures. CONF_HIERARCHY_ROOT_NAME by default.

Overrides: object.__init__

__setColorMapping(self, sourceDictionary=None, dummyElementColor=`'#777777'`)

Assign colours to the hierarchy groups. Update cached hierarchy group name to colour mapping.

Parameters:

sourceDictionary ({str : str}) - hierarchy group name to colour assignment
dummyElementColor (str) - colour assigned to groups not included in sourceDictionary

Note: Color mapping has to be assigned after creating strucutre hierarchy - either flat or structured.

__setFullNameMapping(self, sourceDictionary=None, dummyNameElement=`'------'`)

Assign full names to the hierarchy groups. Update cached hierarchy group name to full name mapping.

Parameters:

sourceDictionary ({str : str}) - hierarchy group name to full name assignment
dummyNameElement (str) - full name assigned to groups not included in sourceDictionary

Note: Full name mapping has to be assigned after creating strucutre hierarchy - either flat or structured.

__setGID(self, val)

Increase the value of the current element of the GID sequence.

Parameters:

val (int) - a new value of the current element of the GID sequence

Note: val must be greater than the value of the current element of the GID sequence.

__setHierarchy(self, sourceDictionary)

Create structure hierarchy according to provided relation.

Parameters:

sourceDictionary ({str : str}) - children to parent mapping

To Do: Implement hierarchy validation.

Attention: the method destroys all existing elements attributes!

__setHierarchyRoot(self, hierarchyRootElementName)

Define the name of the superior group of the CAF dataset structures hierarhy.

Parameters:

hierarchyRootElementName (str) - name of the superior group of the CAF dataset structures hierarhy

__setUID(self, val)

Increase the value of the current element of the UID sequence.

Parameters:

val (int) - a new value of the current element of the UID sequence.

Note: val must be greater than the value of the current element of the UID sequence.

__validateHierarchy(self, sourceDictionary)

Just a stub.

To Do: Implementation.

_setHierarchyRelation(self, child, parent)

Create parent - child relation between two hierarchy groups.

Parameters:

child (str) - Name of the child element
parent (str) - Name of the parent element

_validateInternalData(self)

Perform internal indexed properties validation. If invalid - raise ValueError.

createFlatHierarchy(self)

Create flat hierary: gather all component structures under common superior hierarchyRootElementName hierarchy group element.

No external ontology tree is required.

Note: This method has to be inveoked AFTER indexing all slides.

fixOrphanStructures(self, parentGrpName=None)

Search for structures not covered by hierarchy, then bind them to the requested hierarchy group.

Parameters:

parentGrpName (str) - name of group element which orphan structures are binded to; if None - orphan structures are binded directly to hierarchy root element

Note: If hierarchy group of name parentGrpName does not exist it is created and binded directly to hierarchy root element.

fromXML(cls, sourceXMLElement)
Class Method

__fromXML method bound to the class as its classmethod.

Overrides: barIndexerObject.fromXML: (inherited documentation)

getXMLelement(self)

A stub of method. Raise NotImplementedError.

Returns: xml.dom.Document: XML representation of represented CAF dataset index
Overrides: base.barObject.getXMLelement

indexSingleSlide(self, tracedSlide, slideNumber)

Parameters:

slideNumber (int) - slide number
tracedSlide (base.barTracedSlide) - CAF slide representation

setColorMappingFromFile(self, colorFilename, nameCol=0, colourCol=1)

Assign colours to the hierarchy groups. Update cached hierarchy group name to colour mapping.

Parameters:

colorFilename (str) - path to the file containing name to colour assignment
nameCol (int) - column containing names
colourCol (int) - column containing colour

setNameMappingFromFile(self, filename, nameCol=0, fullNameCol=1)

Assign full names to the hierarchy groups. Update cached hierarchy group name to full name mapping.

Parameters:

filename (str) - path to the file containing name to full name assignment
nameCol (int) - column containing names
fullNameCol (int) - column containing full names

setParentsFromFile(self, hierarchyFilename, childCol=0, parentCol=1)

Create structure hierarchy according to relation provided in the file.

Parameters:

hierarchyFilename (str) - path to the child name to parent name mapping file
childCol (int) - column containing child names
parentCol (int) - column containing parent names

unfoldSubtrees(self, rootStructures, defaultDepth=0, leavesOnly=False)

Parameters:

rootStructures (iterable([str | (str, int), ...])) - names of root elements of hierarchy subtrees or pairs of root element name and depth of the subtree
defaultDepth (int) - the default depth of hierarchy subtrees
leavesOnly (bool) - indicates if only the leaf nodes has to be returned

Returns: set([str, ...])

names of hierarchy subtree tree nodes related to any structure present in CAF slides

updateProperties(self, propsDict)

Updates properties of the indexer with the data from provided dictionary.

Parameters:

propsDict (dict) - dictionary holding indexer's properties in which keys are names of the properties.

Returns:

None

Class Variable Details

[hide private]

_elementsList

names of XML elements partitioning CAF dataset index file

Type:: [str, ...]

Value:

['slideindex',
 'atlasproperties',
 'slidedetails',
 'structureslist',
 'hierarchy']

_requiredInternalData

names of required CAF dataset properties

Type:: [str, ...]

Value:

['ReferenceWidth',
 'ReferenceHeight',
 'FilenameTemplate',
 'RefCords',
 'CAFName',
 'CAFComment',
 'CAFCreator',
 'CAFCreatorEmail',
...

Property Details

[hide private]

colorMapping

Hierarchy group name to colour mapping.

Get Method:: __getColorMapping(self) - Returns: hierarchy group name to colour mapping
Set Method:: __setColorMapping(self, sourceDictionary=None, dummyElementColor='#777777') - Assign colours to the hierarchy groups.
Type:: {str : str}

Note: Result of the method is cached in _colorMapping.

fullNameMapping

Hierarchy group name to fullname mapping.

Get Method:: __getFullNameMapping(self) - Returns: hierarchy group name to full name mapping
Set Method:: __setFullNameMapping(self, sourceDictionary=None, dummyNameElement='------') - Assign full names to the hierarchy groups.
Type:: {str : str}

Note: Result of the method is cached in _fullNameMapping.

gid

If read - the value of the next element of the GID sequence.

If write - the value of the current element of the sequence. The value of the current element of the sequence can be only increased.

Get Method:: __getGID(self) - Returns: value of the next element of the GID sequence
Set Method:: __setGID(self, val) - Increase the value of the current element of the GID sequence.
Type:: int

groups

Name to 'group' element representation mapping.

Read-only property.

Get Method:: __getHierarchyGroups(self) - Returns: name to 'group' element representation mapping
Set Method:: __setHierarchyGroups(self, newValue) - Raise ValueError.
Type:: {str : barIndexerGroupElement}

hierarchy

Hierarchy of the CAF dataset structures.

Get Method:: __getHierarchy(self) - Returns: tuple-based hierarchy tree
Set Method:: __setHierarchy(self, sourceDictionary) - Create structure hierarchy according to provided relation.
Type:: non consistent

hierarchyRootElementName

Name of the superior group of the CAF dataset structures hierarhy.

Get Method:: __getHierarchyRoot(self) - Returns: name of the superior group of the CAF dataset structures hierarhy
Set Method:: __setHierarchyRoot(self, hierarchyRootElementName) - Define the name of the superior group of the CAF dataset structures hierarhy.
Type:: str

properties

Name to 'property' element representation mapping.

Read-only property.

Get Method:: __getProperty(self) - Returns: CAF dataset index property name to 'property' element representation mapping
Set Method:: __setProperty(self, newValue) - Raise ValueError.
Type:: {str : barIndexerPropertyElement}

slides

Slide number to 'slide' element representation mapping.

Read-only property.

Get Method:: __getSlides(self) - Returns: slidenumber to 'slide' element representation mapping
Set Method:: __setSlides(self, newValue) - Raise ValueError.
Type:: {str : barIndexerSlideElement}

Note: be aware that it is not a copy, but the original dictionary!

structures

Name to 'structure' element representation mapping.

Read-only property.

Get Method:: __getStructures(self) - Returns: name to 'structure' element representation mapping
Set Method:: __setStructures(self, newValue) - Raise ValueError.
Type:: {str : barIndexerGroupElement}

Note: be aware that it is not a copy, but the original dictionary!

uid

If read - he value of the next element of the UID sequence.

If write - the value of the current element of the sequence. The value of the current element of the sequence can be only increased.

Get Method:: __getUID(self) - Returns: value of the next element of the UID sequence
Set Method:: __setUID(self, val) - Increase the value of the current element of the UID sequence.
Type:: int

uidList

Hierarchy group name to UIDs of assigned structures mapping.

Read-only property.

Get Method:: __getUidList(self) - For each of hierarchy groups find UIDs of structures assigned to it.
Set Method:: __setUidList(self, newList) - Raise ValueError.
Type:: {str : [int, ...]}

Class barIndexer

__addGroup(self, group, parent=None)

__getColorMapping(self)

__getFullNameMapping(self)

__getGID(self)

__getHierarchy(self)

__getHierarchyGroups(self)

__getHierarchyRoot(self)

__getProperty(self)

__getSlides(self)

__getStructures(self)

__getUID(self)

__getUidList(self)

__indexStructures(self, structure, slide)

__init__(self, hierarchyRootElementName='Brain') (Constructor)

__setColorMapping(self, sourceDictionary=None, dummyElementColor='#777777')

__setFullNameMapping(self, sourceDictionary=None, dummyNameElement='------')

__setGID(self, val)

__setHierarchy(self, sourceDictionary)

__setHierarchyRoot(self, hierarchyRootElementName)

__setUID(self, val)

__validateHierarchy(self, sourceDictionary)

_setHierarchyRelation(self, child, parent)

_validateInternalData(self)

createFlatHierarchy(self)

fixOrphanStructures(self, parentGrpName=None)

fromXML(cls, sourceXMLElement) Class Method

getXMLelement(self)

indexSingleSlide(self, tracedSlide, slideNumber)

setColorMappingFromFile(self, colorFilename, nameCol=0, colourCol=1)

setNameMappingFromFile(self, filename, nameCol=0, fullNameCol=1)

setParentsFromFile(self, hierarchyFilename, childCol=0, parentCol=1)

unfoldSubtrees(self, rootStructures, defaultDepth=0, leavesOnly=False)

updateProperties(self, propsDict)

_elementsList

_requiredInternalData

colorMapping

fullNameMapping

gid

groups

hierarchy

hierarchyRootElementName

properties

slides

structures

uid

uidList

init(self, hierarchyRootElementName=`'Brain'`)
(Constructor)

__setColorMapping(self, sourceDictionary=None, dummyElementColor=`'#777777'`)

__setFullNameMapping(self, sourceDictionary=None, dummyNameElement=`'------'`)

fromXML(cls, sourceXMLElement)
Class Method