Classes

Classes and Class Hierarchy

Classes are words or small phrases that are used to describe an image, that includes species names but also additional attributes regarding the animals (eg. age, group size, etc), the environment or the camera trap. All classes used in tags are referenced in the Classes table.

Classes can have complex relationships, that are described in the Class Hierarchy table. Classes may belong to different class groups or describe several different attributes at the same time. Two different classes may also describe the same attribute. These relationships are therefore documented in this table, describing a hierarchical, top-down graph.

• Table Set Up

  • Classes
  • Class Hierarchy
  • Class Status
  • Class Groups

• Class Table Functions

  • add
  • delete
  • update
  • plotHierarchy
  • get
  • getAll
  • getRootClasses
  • getChildren

• Class Hierarchy Table Functions

  • add
  • delete
  • addIntermediate

Table Set Up

Classes

Column Name	Content	Type	Unique	Nullable	Custom Constraints	Linked Table
ID	ID for Entry	Integer	True	False
Class	word or phrase used to describe an image	String(100)	True	False
Status	class type	String(50)	False	False	one of : "active", "retired", "group"

Class Hierarchy

Column Name	Content	Type	Unique	Nullable	Custom Constraints	Linked Table
ID	ID for Entry	Integer	True	False
ParentNode	class thats directly above the child node in class hierarchy	Integer	False	False		Classes ("ID")
ChildNode	class thats directly below the parent node in class hierarchy	Integer	False	False		Classes ("ID")

Class Hierarchy

Classes are organized into a top down hierarchy that describes the relationships between classes. The logic is, that classes higher in the hierarchy are more general than classes lower in the hierarchy. E.G. We Order species classes from class -> order -> family -> genus -> species -> individual.

In the Class Hierarchy Table, only direct relationships are documented. The higher class is the "parent" class or node and the lower class the "child" class or node. Each class can have an unlimited number of parents and children. However, a descendant of a class can not simultaneoulsy be an ancestor of the same class.

Class Status

A class may have one of three statuses: active, retired or group.

active and retired

This status describes a class that is the currently used class. E.g. The name that has been used to tag a species has been changed over the years from "papa" to "pantpard" to "african leopard". All these tag describe the same species so when extracting the tags. All tags these tags can be merged and be exported with the same name - in this case the "african leopard". This is communicated by "african leopard" having an active status and the other two have a retired status and are children classes of the active class. The retired classes should also not be used when adding new tags to images.

group

A group status describes a class, that is not used to tag an image directly but to describe its assigned children classes. E.g. All active species classes are children of the class "species" that has the status group. This makes processing easier, as you can extract only the children of a given group class. This is the case if you would only want classes that describe a species.

Class Groups

Several class groups have been already added:

• class: group for classes of taxonimic species classes
• order: group for classes of taxonimic species orders
• family: group for classes of taxonimic species families
• genus: group for classes of taxonimic species genuses.
• species: group for all animal species classes
• individuals: group for classes for an individual of a species
• environment attribute: group for classes describing the location / environmnt
• technical attribute: group for classes that describes technical issues
• age: group for classes of species age descriptions
• animal attribute: group for classes of specific identifiers of an animal
• behavior: group for classes of animal behavior
• gender: group for classes of animal age
• group size: group for classes of animal group size
• human related: group for classes that indicate human presence (human, car, cattle ...)

this list is subject to change

Class Table Functions

Test code for each function of the Classes and Class Hierarchy table is shown in Functions_Classes.ipynb

In order to use the class functions, an instance of the class needs to be created

import T_Tables as tableClasses

#create class instance
Classes = tableClasses.T_Classes()
ClassHierarchy = tableClasses.T_ClassHierarchy()

add

This function adds a class to the database.

Classes.add(newClass: str, status: str, parents: list = None, children: list = None)

Parameters

• newClass: name of the class you wish to add
• status: status of class ("active", "retired" "group")
• parents: parent class(es) of new class
• children children class(es) of new class

Returns

The function returns nothing.

delete

This function deletes a class from the database. Note, that a calss cannot be deleted if it has been used for tagging. Any references need to be deleted first.

Classes.delete(className: str, deleteChildren: bool = False)

Parameters

• className: name of the class you wish to delete
• deleteChildren: if all children of the class should be deleted, regardless of if they have other parents or not.

In order to keep a clean hierarchy structure when deleting classes, the following logic has been implemented whithin the delete function:

1. if a class has no parents and no children, the class will be deleted with no additional steps
2. if a class has only parents, the relationships to its parent classes and the class itself are deleted
3. if a class has only children:
4. if deleteChildren = True, all its children are deleted
5. if deleteChildren = False, only children with no other parent classes are deleted
6. if a class has children and parents,
7. relationships to its parent classes are deleted and if deleteChildren = True, all its children are deleted
8. if deleteChildren = False, all children are directly linked to all its parents and the wanted class including all its relationship deleted.

Returns

The function returns nothing.

update

This function allows you to update information of a given column for one entry

Classes.update(name, colName: str, value)

Parameters

• name: name of the class you wish to update
• colName: name of the column where you wish to update the value
• value: new value of given column. Make sure that the value matched the data type of the column

Returns

The function returns nothing.

plotHierarchy

This funciton allows you to vizualize relationships between classes.

Classes.plotHierarchy(name, rootClassName = None)

Parameters

• rootClassName: name of class, which you wish to plot and all its children. None of its parents or unrelated classes are plotted.

Returns

This function generates a plot. Curretnly it works in a jupyter notebook.

Note

As there are curentlly over 1000 classes in the class hierarchy, not giving a rootClassName will result in an unreadable plot. I suggest choosing a rootClassName that has relatively few children, so it is possible to read. If you simply wish to know which classes are all children of a specific class, the getChildren function may be more usefull.

get

This function gets all information for one class.

Classes.get(name: str)

Parameters

• name: name of the class you wish to get information for

Returns

This function returns a pd.dataframe with one row.

getAll

This function gets all information for a all classes.

Classes.getAll()

Parameters

This Function has no parameters.

Returns

This function returns a pd.dataframe with one row for each documented class.

getRootClasses

This function gets all classes, that have no parents.

Classes.getRootClasses()

Parameters

This Function has no parameters.

Returns

This function returns a pd.dataframe with one row for each class without a parent class.

getChildren

This function gets all children of a given classes.

Classes.getChildren(parent: str, status: list = None, recursive: bool = False)

Parameters

• parent: class you wish to get all children for
• status: filters, that only children with wanted statuses extracted. If None is given, then all statuses are accepted.
• recursive: if False only children are extracted. If True all descendants are extracted.

Returns

This function returns a pd.dataframe with one row for each class.

Class Hierarchy Table Functions

add

This function adds a relationship between two classes.

ClassHierarchy.add(parent: str, child: str)

Parameters

• parent: class that will be higher / more general in the hierarchy
• child: class that will be lower / more specific in the hierarchy

Returns

The function returns nothing.

delete

This function deletes a relationship between two classes.

ClassHierarchy.add(parent: str, child: str)

Parameters

• parent: class that is higher / more general in the hierarchy
• child: class that is lower / more specific in the hierarchy

Returns

The function returns nothing.

addIntermediate

This function adds an intermediate class between two already linked classes. This is done by deleting the direct existing link and adding new links like: parent -> new class -> child.

ClassHierarchy.add(parent: str, child: str, newIntermediate: str)

Parameters

• parent: class that is higher / more general in the hierarchy
• child: class that is lower / more specific in the hierarchy
• newIntermediate: class that becomes the child of the parent class and parent of the child class.

Returns

The function returns nothing.