Content¶
Introduction¶
Concept¶
What is a Tree?¶
A “tree” is a data structure, much like a table or a list. A tree sorts information hierarchically into boxes and sub-boxes and sub-sub-boxes.
If you want to organise your work tasks you could sort them into work packages, that are part of projects, that are part of products. If you plan a larger project, you can sort all tasks by responsible persons, who are part of teams, that are part of departments, that are part of branches. You can also make a time plan, where a year consists of quarters, that consist of weeks, that contain a number of tasks. You can have an address book where you have a hierarchy of friends / colleagues / aquaintances, or you can sort knowledge about animals into kingdom / class / family / species.
The nice thing about trees is that you can define mathematical functions on them. Planned hours can be summed up per work package and project, or per person and team, or per week and month. A mean priority can be shown per work package and project.
The concept of hierarchical categorisation can be applied to all sorts of data and will feel a lot more natural and easier to use than organising the same data in spread sheets.
What are linked Trees?¶
The core concept of TreeTime are linked trees. Linked trees are separate trees that share the same data. One piece of information (a node) can be in several trees at the same time, but in different place of the tree. As a single tree is a way of sorting information, different linked trees sort the same data in different ways.
In Tree 1, Node E is right at the bottom, as a child of B and a grandchild of A. In Tree 2 it is a child of D.
In TreeTime, a node or item can hold different information like text, numbers, dates, internet links. These are saved in the item’s fields.
Here we have a field we call “value”. Each node in all trees has a value field that can hold a number (like a cell in a spread sheet). The node A has the value=1, B=2, etc. In addition we have a field we call “Sum”. Its content is calculated automatically, summing up the item’s own value plus the values of all children. In TreeTime, looking at item E and Tree 1 this looks like this:
Clicking on the other tab shows the second tree while the same items stays selected:
Note how the values are summed up the branches. Apart from sums, TreeTime also offers means, ratios, or differences, using different combinations of parent, child, or sibling fields.
Linked trees are a natural and powerful way to structure data. If you, for instance, organise information about animals, you might want to see the animal’s taxonomy (kingdom/class/family/species), but also their habitat (continent/country/area), and switch between both views. If you organise tasks, you could switch between a year/quarter/week/day breakdown, a company/department/team/person tree, and a product/project/package/task overview.
In TreeTime, the structure of your data (whether you store priority, hours, and a description for a task, or expected life span, habitat and number of legs for an animal), the trees themselves, and the calculated values within the trees are completely user defined. Data is stored in text files, changes are saved on the fly, and when opening TreeTime, the software is automatically connected to the last used file.
Basic Use¶
Start the software (see ‘Execute’ from the section [Installation](#id-installation)). In the main dialog, go to “File” / “New from Template”, select “Simple-Task-List.trt” and in the next dialog give a file name for the new file. An example file with a simple project task list structure will open.
The GUI consists of three parts: - A button box on the left. Execute tree structure operations from here. - An editing grid in the middle, showing the contents of the selected data item. Edit single data items here. - A tab view with tress spanning the center-right. View and analyse your data here.
Access each single tree by clicking a tab on the main tree-view widget (the picture above shows the tree Time Plan, the picture below the tree Projects).
Branches and children can be sorted, branches can be folded and unfolded. Data content is shown via analytic fields that are defined per tree. In the example project you will see a sum, a percentage, and text display.
Add, move and remove single nodes and complete branches by using the buttons on the left. Change the name of a node by selecting the node and editing the name in the top of the edit grid in the middle. Change all other values (numbers or text) by clicking into the field and start typing.
The parents of an item are listed underneath the item name. Each tree has a separate line. Change the position of a node within a tree by clicking on any of the parent buttons.
In this example a new node in the tree Time Plan has just been created, and is now added to the tree Projects.
TreeTime lets you select different themes and will try to use the default colours that are defined with your operating system.
Data Files¶
The data in TreeTime is stored in a plain text file, marked with a ‘trt’ file ending (‘trt’ for ‘TreeTime’).
The button ‘Load File’ will open an existing ‘trt’ file. After this, all changes are written to that file. There is no ‘Save’ button, changes are written to the file immediately.
The button ‘New From Template’ opens an existing data file, creates a copy, and saves this copy. A data file can be created by copying the currently open file. All write operations will be performed on that copy. This is to create a new file from a basically empty ‘trt’ file that has a pre-defined data structure.
A data file can be created by saving the currently open file to a copy. The button ‘Save As’ saves the current state. All write operations will be on the new file.
Installation¶
Using pre-compiled Binaries¶
Windows, Linux: Go to [github.com/jkanev/treetime/releases/tag/2023.1](https://github.com/jkanev/treetime/releases/tag/2023.1) and download a zipped package for Windows 10, 64 bit, or for Linux 64 bit from there. Unzip it into your program directory and run TreeTime or TreeTime.exe from the new folder. Unzip the data package too. Add the program folder to your path.
Executable bundles have been created with pyinstaller ([www.pyinstaller.org](http://www.pyinstaller.org)).
Mac: Mac users please use the Python code (see below). There is no executable for Mac. (If anybody can help building an executable for other platforms I’d be delighted.)
Using a PyPi package in Python¶
If you don’t have it yet, install python3
- Install PyQt5 – on an elevated command prompt (Windows), or on the standard command line (Mac, Linux), type:
pip install pyqt5
- Install TreeTime – on an elevated command prompt (Windows), or on the standard command line (Mac, Linux), type:
pip install treetime
Using script code with Python¶
If you don’t have it yet, install python3
Install PyQt5 – on an elevated command prompt (Windows), or on the standard command line (Mac, Linux), type: pip install pyqt5
Download this project from GitHub as a zip file (https://github.com/jkanev/treetime/archive/master.zip) and unzip
- Install TreeTime: in the command line, cd into the main directory, then type:
- Linux:
python3 setup.py build
sudo python3 setup.py install
- Windows:
py setup.py build
py setup.py install
Execute¶
Windows: Hit the Windows key and type “TreeTime”, then click the “run command treetime” that comes up.
Linux, Mac: On the command line, type “TreeTime”. You can also start this any other way your operating system supports. Plus, there’s a .desktop file (for KDE and Gnome) in the data directory to create desktop or menu link.
Data Format¶
Global Structure¶
TreeTime data files are plain text (Unicode/UTF8) and can be edited with any text editor. The global structure consists of three parts: The tree definition, the item definition, and the item pool.
The tree definition is preceded with the marker
--trees--followed by a newline. This defines the number and data structure of the trees in the file.The data item definition is preceded by the marker
--item-types--followed by a newline. This defines the data fields of each data item.The item pool is preceded by the marker
--item-pool--followed by a newline. This section contains the actual data.
The file content of the simple example file in the Introduction chapter looks like this:
--trees--
tree "Tree 1"
field "Value"
field-type "sum"
own-fields ["value"]
child-fields []
sibling-fields []
parent-fields []
field "Sum"
field-type "sum"
own-fields ["value"]
child-fields ["Sum"]
sibling-fields []
parent-fields []
tree "Tree 2"
field "Value"
field-type "sum"
own-fields ["value"]
child-fields []
sibling-fields []
parent-fields []
field "Sum"
field-type "sum"
own-fields ["value"]
child-fields ["Sum"]
sibling-fields []
parent-fields []
--item-types--
item Node
fields {"value": {"content": 0, "type": "integer"}}
trees [[], []]
--item-pool--
item A
fields {"value": {"content": 1, "type": "integer"}}
trees [[0], [0, 0, 0]]
item B
fields {"value": {"content": 2, "type": "integer"}}
trees [[0, 0], [0, 0]]
item C
fields {"value": {"content": 3, "type": "integer"}}
trees [[0, 1], [0, 0, 1]]
item D
fields {"value": {"content": 4, "type": "integer"}}
trees [[0, 0, 0], [0]]
item E
fields {"value": {"content": 5, "type": "integer"}}
trees [[0, 0, 1], [0, 1]]
Tree Definition¶
A single tree is defined by the name of the tree and a list of tree fields. A node’s tree field values are calculated from data fields or tree fields of the node itself, its siblings, parent and children. Each of these are mentioned in the field definition. There are various different field types, some use values in the current tree, some use values from other trees. You can for example display the name of a node’s parent in a different tree. Trees are numbered starting with 0. Look at the first tree in the example:
tree "Tree 1"
field "Value"
field-type "sum"
own-fields ["value"]
child-fields []
sibling-fields []
parent-fields []
field "Sum"
field-type "sum"
own-fields ["value"]
child-fields ["Sum"]
sibling-fields []
parent-fields []
The tree itself is called “Tree 1”. It has two tree fields, “Value” and “Sum”. The tree field “Value” is of type “sum”, and it displays anything that is found in the data item field “value”. The tree field “Sum” is also of type “Sum” and for each node it adds everything in the node’s item field “value”, plus all values in the tree field “Sum” of its children.
More about how to define tree fields in the next chapter.
Data Item Definition¶
Documentation still in progress.
More about how to define data fields in the next chapter.
The Data Pool¶
Documentation still in progress.
Data Fields¶
Documentation still in progress.
Tree Fields¶
General Syntax¶
Each tree field is a function with a list of input fields. These fields can be either tree fields or data fields. To avoid ambiguities it is good practice to name tree fields starting with a capital letter and data fields with a lower case letter. A tree field is always defined as part of a tree (see previous chapter). The definition states the name, the field type, and the input parameters:
field "Name"
field-type "type"
own-fields [...]
child-fields [...]
sibling-fields [...]
parent-fields [...]
The field is started by the line field "Name" where “Name” is the name of the field. This will appear as the column heading in the tree list.
After this, indented with four spaces, is the field type: field-type "type", where “type” is the type (see next for an overview).
After this, the lines own-fields [...], child-fields [...], sibling-fields [...], and parent-fields [...] each define a list of field names. These are the input parameters for the function. They are evaluated in the order they are mentioned. A real-world example:
field "Progress"
field-type "ratio-percent"
own-fields ["Spent Hours", "Planned Hours"]
child-fields []
sibling-fields []
parent-fields []
The tree field “Progress” is a ratio, defined as parameter1 / (parameter2 + parameter3 + …). In the tree view it will be displayed as a percentage. It shows the ratio of the tree fields “Spent Hours” / “Planned Hours”.
concatenation¶
Concatenates strings. Syntax:
field "Name"
field-type "concatenation"
own-fields ["field1", "field2", ...]
child-fields ["field3", ...]
sibling-fields [...]
parent-fields [...]
were “field1”, “field2”, “field3”, …, are the names of data or tree fields.
Result: The strings found in field1, field2, field3, …, put together, in the order they are mentioned.
difference¶
Difference of numbers. Syntax:
field "Name"
field-type "difference"
own-fields ["field1", "field2", ...]
child-fields ["field3", ...]
sibling-fields [...]
parent-fields [...]
were “field1”, “field2”, “field3”, …, are the names of data or tree fields.
Result: The value field1 - (field2 + field3 + …), in the order they are mentioned.
difference-time¶
Same as “difference”, but will show the result as hour format, e.g. the value 1.5 will be displayed and exported as 1:30:00.
mean¶
The statistical mean of all input fields. Syntax:
field "Name"
field-type "mean"
own-fields ["field1", "field2", ...]
child-fields ["field3", ...]
sibling-fields [...]
parent-fields [...]
were “field1”, “field2”, “field3”, …, are the names of data or tree fields.
Result: The value (field1 + field2 + field3 + …) / N, where N is the number of fields.
mean-percent¶
Same as “mean”, but will show the result as a percentage, e.g. the value 0.75 will show as 75 %.
node-name¶
The name of the node’s parent in another tree. Syntax:
field "Name"
field-type "node-name"
own-fields []
child-fields []
sibling-fields []
parent-fields [N]
were N is an integer number.
Result: Displays the name of the node’s parent in tree N. Trees are counted starting with 0.
Example: This field is called “Project” and is defined in a tree “Time”, which is the first tree (i.e. Tree 0). There is another tree called “Projects”, which is the third tree (i.e. Tree 2):
tree "Time"
field "Project"
field-type "node-name"
own-fields []
child-fields []
sibling-fields []
parent-fields [2]
tree "Tasks"
...
tree "Projects"
...
This would create the column “Project” in the tree view of the “Time” tree. The line parent-fields[2] means each entry shows the respective node’s parent in the “Project” tree (e.g. “TreeTime”).
node-path¶
Same as “node-name”, but instead of the paren’t name, the entire path is shown, using “|” as delimiter (e.g. “Coding | Open Source | TreeTime”).
ratio¶
The ratio between the first and the sum of all following input fields. Syntax:
field "Name"
field-type "ratio"
own-fields ["field1", "field2", ...]
child-fields ["field3", ...]
sibling-fields [...]
parent-fields [...]
were “field1”, “field2”, “field3”, …, are the names of data or tree fields.
Result: The value field1 / (field2 + field3 + …), where N is the number of fields.
ratio-percent¶
Same as “ratio”, but displayed as percentage (e.g., 0.75 is displayed as 75 %).
set¶
A list of unique occurrences of values of all input fields. Syntax:
field "Name"
field-type "set"
own-fields ["field1", "field2", ...]
child-fields ["field3", ...]
sibling-fields [...]
parent-fields [...]
were “field1”, “field2”, “field3”, …, are the names of data or tree fields.
Result: A list like value1, value2, value3, value4, where each value is the value of at least on input field and each value is listed only once.
string¶
The simple display of the content of a data field or another tree field. Syntax:
field "Name"
field-type "string"
own-fields ["field1"]
child-fields []
sibling-fields []
parent-fields []
were “field1” is the name of a current data or tree field. The “string” function only takes one parameter.
Result: The value of field1.
sum¶
The sum of all input fields. Syntax:
field "Name"
field-type "sum"
own-fields ["field1", "field2", ...]
child-fields ["field3", ...]
sibling-fields [...]
parent-fields [...]
were “field1”, “field2”, “field3”, …, are the names of data or tree fields. Fields must be integer fields, the result for string fields is not defined.
Result: The value field1 + field2 + field3 + ….
sum-time¶
Same as “sum”, but will show the result as hour format, e.g. the value 1.5 will be displayed and exported as 1:30:00.
text¶
Same as “string”, but the exported field has a larger width and can span several lines.
url¶
Same as “string”, but in an html export the field is formated as url link (clickable).
History and Road Map¶
Past¶
2015¶
November: First implementation, simple data types, simple GUI
2016¶
February: Implemented selection (the same item gets selected in all trees, changing a tab shows the same item)
March: Implemented remaining local functionality (Copy Branch as Sibling, Copy Children to Siblings, Remove from this Tree, Delete Item)
August: Created installable python package
2017¶
May: Implemented new field type text
June: Create deployable packages for Linux and Windows
June: Made pre-release v0.0 available
October: Implemented new field type node-path, re-wrote the way nodes move to new parents
November: Uploaded package to pypi.python.org, TreeTime can now be installed using pip
2018¶
October: Re-implemented the parent selection mechanism. The old cascaded menus have been replaced with single drop down lists.
October: Re-furbished the GUI and removed a couple of bugs. Slighty changed the data file format. Implemented theme selection. Tested pyqtdeploy for deployment instead of pyinstaller. Updated the description.
November: Released version 2018-10
2019¶
January: Implemented new field type “URL”
2020¶
June: Fixed problem with protected cells (typing into a cell without data could cause a crash), and fixed file selection dialog (now only offers .trt files).
July: Implemented text export - single branches or complete trees can now be exported to txt files.
August: Implemented time counters - nodes can record the time using a special field of type “timer” (experimental). GUI buttons can start and stop the stopwatch function.
September: Added move-to-top-level option for first level nodes
October: Added a dark and a light palette for GUI colours, selectable in addition to the theme selection.
November: Fixed too slow editing in text fields when tree files are big (>1.5 MB).
2021¶
January: Released version 2021.01.
January: Bugfixing (timer crash)
February: Released version 2021.2.
March: New functions “Delete node” and “Remove node from tree” now move descendants one level up. “Remove branch” removes the respective branch in all trees, “Delete branch” deletes a branch, all child branches and inter-connections in all trees.
March: If a file with running timers is saved, those timers will be running when the file is loaded.
March: Added tooltips for main buttons
March: Implemented HTML export of branches and complete trees
March: Added auto-delete for orphans
March: Released version 2021.3
April: Added file option
April: Implemented four-column layout and rainbow colours for html export
April: Released version 2021.4
May: Improvement to html and txt export (changed colours, headings have no different sizes)
May: On export of both html and txt, user can now decide how many tree levels (depth) should be exported.
May: Released version 2021.5
July: Fixed broken application logo
July: Implemented CSV export
August: Released version 2021.8
September: Added new export option “Text to Clipboard”
November: Added new export option “Html (List) to File”
December: Added two primitive template files (a text-only single tree and dual tree mindmap)
December: Released version 2021.9
2022¶
March: Fixed crash bug on non-export
March 2022: Improved sorting and grouping in html export, changed to five columns
June 2022: Added a tutorial file
June 2022: Added first-use dialog when no file is loaded, instead of the file-open dialog
June 2022: Released version 2022.1
2023¶
February 2023: Added new tree field types “concatenation” and “set”.
February 2023: Implemented adjustable width for the data item and the tree table main view.
February 2023: Release version 2023.1
Present¶
Bugfixing
Extend documentation on readthedocs.io
Add more fields
Add more examples and more template data files
Future¶
Near Future¶
Implement search function
Mid Future¶
Implement global functions (Linearise Tree, Level-Swap, Merge identical Siblings, Merge Identical Parents/Children, Remove all Orphans, Insert all Orphans as Children)
Implement more tree field types (standard deviation, min, max, string concatenation),
Far Future¶
Implement tree field editing with graphical dialog (add, remove, change tree fields)
Implement data item field editing with graphical dialog (add, remove, change data item fields)
Implement safe usage by multiple simultaneous users
Implement a database backend instead of text file storage
Implement a web server
A whole lot of other fancy things that will probably never get done