filterCSV

iThoughts is a third-party application for creating and managing mind maps. It runs on iOS, iPad OS, Mac OS and Windows.

You can create a mind map either in the application itself or by importing files in a number of other formats. The most complete format is Comma-Separated Value (CSV). Being a text format, CSV can be programmatically created in a number of programming languages, such as Python.

The CSV format that iThoughts understands has a tree-like structure. A tree consists of nodes, which contain data as well as potentially child nodes. A node with no parent is called a root node. A node with no children is called a leaf node.

There can be multiple root nodes - and hence multiple trees - in an iThoughts CSV file. In which case it's better to call the ensemble a forest of trees.

As well as the nodes' tree structure, an iThoughts' CSV file can store for each node its colour, its position, its shape and other attributes. To a very limited extent the format is documented here. A better way to understand the format is to export a mind map from iThoughts as CSV and look at the resulting file.

An Introduction To The iThoughts CSV File Format
About filterCSV
Using filterCSV

An Introduction To The iThoughts CSV File Format

Here is a sample CSV file in the format required by iThoughts:

"colour","shape","level","level0","level1","level2"
00FFFF,,0,"A"
,triangle,1,,A1
,square,1,,A2
FF0000,square,2,,,A2A

and here is how it looks when imported into iThoughts:

This is obviously a very simple example, but it illustrates some features of the file format:

Each line is a node, apart from the first one.
All lines have a cell in the "level" column, with the level number filled in.
Some nodes have colours, in RGB format. (Nodes "A2" and "A1" inherit the turquoise colour from node "A".)
Some nodes have shapes associated with them.

A more detailed description of the file format is given in iThoughts CSV File Format but this brief description should be enough to get you started.

In more complex cases other columns come into play.

About filterCSV

filterCSV is a set of tools to automatically edit a CSV file in the form used in iThoughts. filterCSV is written in Python 3.6+. It has been tested on a Raspberry Pi and a machine running macOS.

Based on matching regular expressions, plus a few other criteria, you can do things for matching nodes such as:

Set colours for nodes
Change their shape
Delete them
Set their positions
Set icons for nodes

You can check the structure of the input CSV file is good for importing into iThoughts.

You can export the CSV file as a Markdown file consisting of headings and bulleted lists, and in a number of other formats.

NOTE: In this document we will use terms such as "mind map" and "tree". Structurally the data represents a tree.
It might or might not be used for mapping your mind.

Using filterCSV

filterCSV reads from stdin and writes to stdout, with messages (including error messages) written to stderr. For example:

filterCSV '^A1$' 'triangle' < input.csv > output.csv

It's designed for use in a pipeline, where the input of one program can be the output of another.

Do not specify the input and output files as command parameters. Instead

Code the input file as an input stream using <.
Code the output file as an output stream using >.
You can code stderr as an output stream using 2> or let it default to the terminal session.

Command line parameters instruct filterCSV on how to process the parsed input file to create the output file. The parameters are specified in pairs. Each pair consists of:

A specifier. This is a regular expression to match. (A special value all matches any value.)
An action or sequence of actions.

In the case where no action is expected you can code anything you like for the second parameter. A useful suggestion would be to code . for it.

Instead of using command line parameters you can code the commands in a file read in from Stream 3. See Command Files for more information on this, potentially more flexible, way of controlling filterCSV.

You can get some basic help by invoking filterCSV with no parameters. That help points to this README and the project on GitHub.

Specifiers

Specifiers are used to specify which nodes to operate on and can be in one of the following forms.

Regular expressions in a format the Python re module understands.
A special value of all, matching all nodes.
A special value of none, matching no nodes.
A level specifier of the form @level:n - where n is an integer, referring to the level number.
A priority specifier of the form @priority:n - where n is an integer between 1 and 5. You can use @prio:n for short. You can use @nopriority or @noprio to match nodes where the priority has not been set.
A progress specifier of the form @progress:n - where n is an integer between 0 and 100, representing percent complete. You can use @prog:n for short. You can use @noprogress or @noprog to match nodes where the progress has not been set.
A shape specifier of the form @shape:myshape - where myshape is one of the shapes described in iThoughts Shape Names. You can use @noshape to specify nodes where the shape hasn't been set.
an icon specifier of the form @icon:icon - where icon is the name of the icon. It is one of the icons described in iThoughts Icon Names. If the node's icon set contains this icon then the node matches. @noicon matches if the node has no icons.

Notes:

If you want to match a cell's text exactly you can code something like ^A1$ where ^ means 'the start of the text' and $ means 'the end of the text'.
In the level:n form of the specifier the level of a node is taken from how it was read in - though that could be modified by check repairsubtree. \
For @priority:n, @progress:n, @shape:s, @icon:i an empty value in the node's attribute means it's not been set.
You can use values for shape, icon, etc, that iThoughts doesn't support, perhaps to tag a node. It is unpredictable what iThoughts will do if it encounters them.
If you're not sure the levels are properly numbered you should run check repairsubtree first. For example

filterCSV < input_file.csv > output_file.csv \
    check repairsubtree \
    @level:1 'triangle note'

Actions

Actions you can take include:

Specify a colour number
Specify a colour RGB value
Automate colouring nodes based on a regular expression's capturing group
delete
keep
Specify a shape
Specify a position
Specify an icon
Removing colour, shape, and icon specifications
Promote all subtrees at a certain level by 1 level
Computing basic statistics about the mind map

In the following action specifications are case-insensitive; If you specify, for example, an action in upper case it will be converted to lower case before being applied to matching nodes.

You can, in most cases, specify a sequence of actions. You can separate them by spaces or commas. If you specify multiple actions you probably need to surround them with a pair of single quotes.

Colour Numbers

A colour number is a 1- or 2-digit number. It is specified relative to the top left of iThoughts' colour palette. (1 is the first colour in the palette.)

You can also specify nextcolour, nextcolor or even nc and filterCSV will select the next colour in iThoughts' colour palette. samecolour, samecolor or sc can be used to specify the same colour again.

Colour RGB Values

This is a hexadecimal 6-character representation of the colour, in Red-Green-Blue (RGB) format. For example FFAAFF.

Automatic Colouring

Rather than either using

FilterCSV

Install / Use

README