Compact Manual


CATMA is a web application for text annotation, analysis and visualization. It is specifically designed to emulate the flexible workflows of hermeneutic text interpretation. Version 6 comes with a bunch of new features:

  • CATMA’s architecture is now centered around projects. Projects can contain Documents, Annotations, Tagsets and Members. The new roles-and-rights management options for project members make collaborative annotation easier to structure and organize.
  • Analysis options via queries and visualizations have been improved and are now closely integrated. A set of pre-selected standard queries  as well as several new visualization options are available.
  • The user interface has been given a complete makeover. With its new and clear look, CATMA is now even more intuitive to use.

This Compact Manual will guide you through CATMA 6 to show you its basic functions. Let’s get started!

Start Screen

CATMA Start Screen

Sign up

Sign up if you have never worked with CATMA 6 before and would like to set up a CATMA account – this only takes a minute! (If you have already worked with CATMA 5 and want to have your research data migrated to the new version, just let us know via – we’ll handle it for you! If you don’t want to take your CATMA 5 data along, simply start from scratch in CATMA 6.)


If you already have a CATMA 6 account or want to log in with your Google account, hit “Sign in”.


Want to be the first to get notified about new CATMA features, workshops, and other CATMA news? Subscribe to our Newsletter by hitting the button!

Additional Information

Additional information about CATMA can be found in the top right corner of CATMA’s user interface.


CATMA Home Screen

Create Project

Once logged in, you see your CATMA home screen with a tile overview of all the Projects you’re a member of. If you’re new to CATMA 6, there will be no project tiles yet. So let’s get started:
Create your first CATMA project by selecting the tile “Create Project”. Just type in a name and, if you like, a description of your project, confirm and you’re done: you are now the proud owner of a CATMA project, which is shown as a tile on your home screen. If you want to delete a project, click the bin icon on the tile – if you want to edit name or description, click the pencil icon. Deleting and editing a project is only possible if your role allows it.

Join Project

If you would like to join an existing CATMA Project that was created by a different CATMA user, you can select the “Join Project” tile. The owner of the project has to supply you with an invitation code for the Project, which you then type in. Once confirmed, you’re a member of the project you joined. Please note: the project owner and you, the new member, both have to be logged in at once as the project code is valid only for a short period of time.

Modules and Side Menu

On the left side of your home screen, you find the menu listing the CATMA modules Project, Tags, Annotate and Analyze. When on the home screen, these menu items are not clickable yet. To be able to navigate through CATMA via the menu, you have to open one of your projects first – just click the relevant project tile.

Project Module

CATMA Project Module

Enter the Project Module

On entering the Project module via selecting a project on your home screen, the menu on the left side has become active and highlights the Project module button. All other CATMA modules will now be  automatically headlined with the title of the project that you’ve chosen to work on. If you want to return to your home screen and select a different project, just click on the “CATMA 6.0.0” sign or on the home icon in the top left corner.
If you want to re-enter the Project module after having worked in one of the other modules, click “Project” in the left-side menu.
The project screen shows all the components of your project and allows you to manage them. Each component class is displayed in a tile: there is a tile for your Documents and Annotations, one for the Tagsets belonging to the project, and one for Project Members. 

Documents and Annotation Collections

Add Documents

When you get started with CATMA 6 for the first time, there won’t be any resources – i.e., documents, annotations or tagsets – to show yet. If you want to add a document, just hit the plus icon in the “Documents & Annotations” tile and select “Add Document”. You will now be guided by a wizard: type in a URL or upload a document in step 1, get a preview of how the document will be displayed in step 2, define the document language in step 3, and add information (like author and description) in step 4. Once confirmed, the document will be displayed in the “Documents & Annotations” tile.
Please note that you can only add documents if your project role allows it.

Edit and Delete Documents

If you want to edit or delete a document, select a document from the list and hit the three dot menu in the “Documents & Annotations” tile. Here, you can select “Edit documents / collections” or “Delete documents”. (Please note that the editing options for documents are confined to editing their names.) If you want to select more than one document, you can switch on tickable boxes using the list icon in the top left corner of the tile.
Please note that you can only edit or delete documents if your project role allows it.

Add Annotation Collections

In CATMA, annotations are stored separately from source documents: so in order to annotate a document, you will first have to create an Annotation Collection . To do so, simply select one document (or several documents via the list button on the top left), hit the plus icon and select “Add Annotation Collection”. Enter your collection’s name, confirm, and the annotation collection will be displayed beneath the associated document.
Please note that you can only add annotation collections if your project role allows it.

Edit or Delete Annotation Collections

To edit or delete annotation collections, select them from the list, hit the three dot menu and choose the relevant option. The editing options for annotation collections in the project module are confined to editing their names. Annotations can be edited in the Annotate module. To do that, double-click the relevant annotation collection or select it and click “Annotate” in the left-side menu. The collection will now open in the Annotate module.
Please note that you can only edit or delete annotation collections if your project role allows it.


Add Tagsets

The next tile shows the Tagsets associated with your current project. Tagsets are needed if you want to annotate documents in CATMA.
If you want to add a tagset, hit the plus icon in the tile, type in a name and confirm.

Edit or Delete Tagsets

To edit or delete a tagset, select a tagset from the list, hit the three dot menu and choose the relevant option. Please note that it is not possible to view or edit tagsets beyond their names in the Project module. If you want to add, view, or edit Tags, Properties and Values in your tagset, double-click it or select it and choose “Tags” in the left-side menu. The tagset will now open in the Tags module. It is also possible to import tagsets as xml-files. To do so, select “Import Tagsets” from the three dot menu.
Please note that you can only add, edit or delete tagsets if your project role allows it.


Add Members

The third tile in the Project view shows the Project Members. It will at least display the project owner’s name, plus your own name (unless of course you’re the owner yourself) as well as your role in this project.

If your role allows it, you can add new members to the project by clicking the plus icon and selecting “Add Member”. Type in the name of a CATMA user you want to add, select their role from the drop-down menu and confirm. The new member will now be displayed in the list.
Another way to add Members is via invitation in ‘real time’. Click the three dot menu in the top right corner of the “Member” tile and select “Invite someone to the Project”. In the pop-up dialog, you now have the option to automatically create annotation collections for every new member – just tick the box and select the documents for which you want to create the collections. Select a role for the new member(s) from the drop-down menu in the pop-up dialog and click invite. An invitation code will now be displayed in the pop-up dialog. Supply the intended new members with this code. Once they type it in and thereby accept your invitation, they’ll be displayed in your open invitation window. Once every intended new member appears in your window, click “Invite”. The new members and their roles will be listed on the “Members” tile.

Edit or Delete Members

To edit the role of a member or delete a member, please use the three dot menu in the tile.
Please note that you can only edit or delete members if your project role allows it.


There are five available roles in CATMA 6: The Owner has every possible right in a project; a Partner can do everything except delete a project. Assistants don’t have any project administration rights and cannot create or delete resources (except their own annotations), but can edit any resource; an Observer can see everything in a project, but can only edit resources if specifically allowed to do so; a Student will have to be granted permission to access specific resources and edit annotations by the project owner or a partner before seeing anything. (For a more detailed description of the roles and the associated rights, please view here.)


To understand how synchronization works in CATMA, it’s necessary to know a little bit about its infrastructure. CATMA uses a GitLab server as its backend, and CATMA projects are essentially just Git repositories.

Every user has their own copy of the project on the CATMA server. With Git, this copy is known as the Working Tree. The working tree, or working directory, is the umbrella term for all of the directories and files in the project. It is a copy of a particular version of the project that you are busy working on. If you are familiar with Git, you’ll know that this usually resides on your local computer, but since CATMA is a web application, we keep it on the server for you. (Of course you can also work with it locally, but that is an advanced topic – see Git Access if you’re interested.) Instead of forcing you to work with Git directly, the CATMA UI offers an easier and more user-friendly built in synchronization mechanism that tries to perform all of the necessary Git operations for you (fetching and merging, committing and pushing). 

When changes are made to the project, CATMA does not automatically synchronize them. However, whenever you’ve made changes that can be synchronized, CATMA will notify you by displaying a yellow bell icon, found in the top right corner of the Project module. 

When you want other project members to see your changes, you need to synchronize. The same is true if you want to see the changes that other project members have made.

Note that, currently, CATMA does not automatically tell you when other people have made changes that you could synchronize. 

When the bell icon is clicked, a dialog will appear. Here you can review the changes that are waiting to be synchronized. Clicking the Synchronize with the team now button will start the synchronization process (you may need to scroll down first if the list of changes is long).

So what is a commit?

Commits are snapshots of your entire [CATMA project] at specific times. […] Over time, commits should tell a story of the history of your [project] and how it came to be the way that it currently is.

GitHub Git Guides: “Git Commit”. GitHub. URL: [Last accessed: 19.05.2021].

You can use commits to document units of work, or “logical units of change”. For example, imagine a commit with the message: “Added character annotations for chapter 1”.

CATMA commits most things automatically – for example when you add documents, or when you create/modify resources like Tagsets, Tags and Annotation Collections. A commit will also be created automatically if you close the project or log out (if there are uncommitted changes). This is a small safety net that prevents you from ending up with a huge number of uncommitted changes. Annotations are not committed automatically (unless you close the project or log out). This allows you to manually create commits for units of annotation work, as described above, if you want to. If you would like to make a manual commit of your changes, navigate to the three-dot menu in the top-right corner of the Project module. Then, select the first option Commit all changes. 

You will be prompted to enter a description for the commit – your unit of work – also known as a commit message

Why doesn’t CATMA just automatically synchronize everything?

You might not want to share your changes with other project members yet, or you might still be working on a specific task that you have not yet completed. In other words, you can choose when you want to share your work, and when you want to fetch the work of others and integrate it with your own. In addition, it isn’t always possible to integrate everyone’s work completely automatically.

There may be so-called merge conflicts, and you may be asked to make a choice between conflicting alterations. CATMA tries to resolve most conflicts automatically, but that doesn’t always work and can lead to an error. If you are experiencing a problem while synchronizing, please contact the CATMA support team.

Tags Module

CATMA 6 Tags Modul

Enter the Tags Module

If you want to annotate Documents in CATMA, you need at least one Tagset. A tagset can either be imported as an xml-file (via the three dot menu on the tagsets tile in Project view) or created directly in CATMA. While the tagset itself (i.e., the ‘container’ for your Tags) can be created in the Project screen, the tags themselves can only be added via the Tags module. To enter the Tags module, either select “Tags” in the left-side menu (this option is available from every view except for the home screen) or double-click a tagset from the tile in the Project module.

Set Filters

The Tags module displays the tagsets selected for your project. You can see which of these tagsets are currently selected as well as the inactive ones by extending the gray Latch on the left side of the Tags screen. Throughout CATMA 6, this latch is used to set your filters, i.e., to select the resources that are displayed in the modules. Extend the latch by clicking on it and you’ll find a list of all tagsets of your project, with the boxes of the currently active tagsets ticked. Adjust your filters by ticking or unticking boxes and collapse the latch by clicking on it.
Note that if you enter the Tags module via the side menu the first time after a new login, your filters will be set to display all tagsets that were used in the current project. If, however, you enter the module by double-clicking a tagset from the tile in the Project module, only the selected, active tagset will be displayed.
If your tagsets already contain Tags, these can be displayed by ‘unfolding’ the tagset via the little arrow behind the tagset in the “Tags” column. The same applies to the Properties and their Values, if available.

Add Tags, Properties and Values

If you want to add a new tag to a tagset, select a tagset (or several tagsets via the list icon top left), hit the plus icon top right and select “Add Tag”. In the pop-up dialog, enter a tag name and, if you want, edit the suggested tag color. You have the possibility to also add properties for the tag you’re creating. Properties are means to further qualify an annotation made with a tag. To add a property, type in a name and click “Add Property”. If you want to, you can then add proposed values for the added property. To do this, type in the values in the “Proposed Values” box. You may type in several values separated by commas. When done, hit “Add Tag”. The new tag is now displayed in the tagset list. To display properties and values you might have added, further unfold the tagset via the arrows in the relevant columns.
To add a subtag – i.e., a tag that is subordinated to another tag in the tag hierarchy, select a tag from the list, hit the plus icon, select “Add Subtag” and proceed in the same way as for adding tags. Once done, the subtag will be displayed in the list as subordinated to the tag you selected earlier.
You can also use the plus icon to add new tagsets or to add the same properties to a number of tags. (For the latter option, first select a tag or several tags for which you would like to create the relevant property.)

Edit or Delete Tagsets, Tags or Properties

To edit or delete tagsets, tags or properties, make a selection in the list, click the three dot menu and choose the relevant option. Deletions can also be executed via the bin symbols.

Annotate Module

CATMA 6 Annotate Module

Enter the Annotate Module

Once your project contains at least one Document, Annotation Collection and Tagset, you can start to annotate a document in CATMA’s Annotate module. To enter the Annotate module, either navigate there via the left-side menu (from any view except the home screen) or double-click a document or an annotation collection in the Project module.
If you enter the Annotation module using the left-side menu for the first time after a new login, you will find the filter latch extended with no document selected yet and all available tagsets pre-selected. Once you choose a document from the list, the latch will automatically collapse and the selected text is displayed in the Annotate module.
If you enter the Annotate module via double click on a document or annotation collection from the project module, you’ll find the filter latch collapsed and the selected/associated text displayed.

Set Filters

Extend the left-side latch by clicking on it anytime to adjust your filters, i.e., to switch to a different document or to adjust the selection of tagsets. Please note that only one document at a time can be displayed in the Annotation module, but you can open a new tab with a different document by clicking the plus icon in the top right corner.
If the document you selected already has at least one annotation collection, one collection is pre-selected to store your annotations. This collection is displayed on the top right. If you want to change the collection, please use the drop-down menu. If you do not have a collection for the selected document yet, you will need to create one. You can use the latch to do so: Extend it via click, hit the plus icon, type in a name and confirm.


With exactly one document and collection selected, and at least one tagset selected, you can now start annotating your text. Use the cursor to select a passage from the text on the left side. One way to annotate the selected text is via right click. The right-click menu displays the filtered tagsets. By hovering over a tagset, it will be expanded to show the available tags, which can then be further expanded. Select a tag via right click. If the selected tag does not have any properties, the selected text passage is underlined in the tag color and your annotation is stored in the selected annotation collection. If the tag does have properties, you will get a pop-up dialog after selecting a tag. You now have the option to add pre-defined or new custom values to your annotation. Once done, hit OK and your annotation is stored.
Another way to annotate is to select a passage of the text with the cursor and then use the tagsets panel on the right. Unfold a tagset until you can see the tag you want to use, then click the line of the tag. Just as described for the other annotation routine, depending on whether the tag you use has properties, you may encounter a pop-up dialog where you can then set property values before the annotation is stored.
To apply a discontinuous annotation, select the pages-with-annotations icon below the text in the middle. You can now select multiple passages from the text and then conduct one of the annotation routines described above. If you’re done annotating discontinuously, just deselect the icon.

View Information about Annotations

If you want to see more information about your annotations, hover over the tag-colored underline beneath an annotated text passage. In a pop-up window you’ll now see the tag path (i.e., where in which tagset the used tag is located), the collection that contains the annotation, and the CATMA user who created it.

Edit or Delete Annotations

If you want to edit or delete an annotation, click on the tag-colored underline. The annotation will now appear in the “Selected Annotations” list in the bottom right area of the Annotate module. You can click on more underlines and they’ll all be added to this list. To clear the list, use the eraser icon above it.

To edit the property values of annotations, just use the pencil and paper icon. To delete annotations, click the bin icon behind a listed annotation.

Analyze Module

CATMA 6 Analyze Modul

Enter the Analyze Module

In the Analyze module, you can explore texts and annotations with search Queries and Visualizations. To enter the Analyze module, you can either use the left-side menu or click the “Analyze” button below the text in the Annotate module.

If you use the former option first time after a new login, you’ll find the filter latch extended and no document or collection selected yet. Select as many documents and/or collections as you like by ticking the boxes. Please note that collections can only be selected if their associated documents have already been selected. Collapse the latch by clicking on its handle on the right side.
If you enter the Analyze module via the “Analyze” button in the Annotate module, the latch is collapsed and the document/collection(s) you’re currently working with in the Annotate module are selected.

Set Filters

Adjust your filters (i.e., select different documents or collections) anytime by clicking on the latch on the left and tick/untick the relevant boxes.

You can open a new tab by clicking the plus icon in the top right corner of the Analyze module.


Execute Queries

Queries allow you to analyze, explore or evaluate text or annotation data. To execute a query on documents or annotation collections, you have three options: select a pre-defined query, use the Query Builder or type in a query directly.

Pre-defined Queries

You can either select one of the four available queries from the drop-down list by clicking the arrow next to the query field. The “Wordlist” query will list all of the words of the analyzed document(s), the “Wildcard ‘a’” query displays all the words starting with the letter “a”. The “Taglist” query lists all the tags used for annotations in the analyzed collections and the “Taglist with Properties” query shows all the tags having properties that were used for annotations.

Query Builder

Another way to execute a query is by using the Query Builder. Just click on the “Build Query” button in the top left corner of the Analyze module. A wizard will now help you to build your query. 

The five basic options available here are to search by word or phrase, by grade of similarity (i.e., find all the words/phrases that are similar to a chosen word to a specified degree), by tag, by collocation (i.e., find all the passages where a chosen word appears within a specified word span near another specified word), or by frequency. Make your choice between the five query options and the follow the wizard’s instructions.

For every basic query you have the option to add to, exclude from, or refine the findings. Refining a query means to restrict the results to those that match the additional criteria you have stipulated. 

If you ask for two criteria to be met, then you can furthermore specify whether these two criteria must both apply to exactly the same section of text (exact match), whether one must contain the other in its entirety (boundary match) or whether a partial overlap of positive search results for criterion 1 and 2 in your text segment suffices. When done, hit “Finish”. You will be taken back to the Analyze module where you can now execute the query by clicking on “Search”.

Direct Query

The third option for queries is to type your query directly in the query field and then execute the query by clicking on “Search”. A summary of the CATMA query language can be found here.

Explore Query Results

Once a query is executed, you can explore your results. The query results are displayed in a box beneath the query field, headlined with the query itself, a time stamp and the total number of results. (You can edit the headline/name by clicking on it.)

If you execute several queries, new boxes with results lists will be added. The boxes can be collapsed by clicking the larger arrow in the top right corner of a box. To erase boxes, use the eraser icon in the box.

You can also re-arrange your results lists. The order in which the results are displayed is by descending frequency by default. Click on the frequency column heading to switch the order to ascending frequency.

The results lists are grouped according to phrase by default, meaning there is one list entry per phrase. Further information can be found if you click the little arrows in front of an entry. You can now see the document(s) in which the result occurs.

To adjust the grouping of the results list (for example by tag), use the three dot menu.


Generate Visualizations

Visualizing text and/or annotations may help you to present your analysis results or to explore them further. Query results can be fed into four different types Visualizations: The Kwic (Key Word in Context) visualization, the Distribution graph, the Wordcloud and the Network.

To generate a visualization, just click one of the icons on the top right of the Analyze module. The view of the Analyze module will change and show the query results list(s) in the top left area, selected results on the bottom left and your visualization on the right.

You can now decide which of your query results should be fed into the visualization. Execute your choice by clicking the circled arrow icon next to a query result or select all by using the three dot menu in the top right tile.
Once selected, a result will be displayed in the selected results tile below and integrated into you visualization. To remove it from both, click the eraser icon behind the result in the bottom left area of the Analyze module.

You can switch between your available results lists by using the drop-down-menu right to the query line on the top left.

KWIC Visualization

The KWIC (Keyword in Context) visualization shows you results in their textual contexts. You can use the KWIC visualization to make annotations. Just select rows, click “Annotate selected rows” from the three dot menu in the KWIC area and follow the instructions.

By double-clicking a line from the KWIC view, you can also jump to the relevant text passage in the document in the Annotate module.

Distribution Visualization

The Distribution graph displays the distribution of query results across texts – the results are accumulated per 10 percent of the document length and summarized in a data dot. If you click on one data dot in the distribution graph, you will see a KWIC view for this data below the distribution graph. From there, you can again make annotations via the three dot menu in the KWIC area or jump into the text via double click.

You can save the distribution graph visualization as SVG or PNG via the horizontal three dot menu. You can also use the menu to view the source code for your visualization.

If you want to tweak your visualization in Vega Online Editor, click the code icon on the right and tick the box “Expose the selected data for access in the Vega Online Editor”. Collapse the side bar via click on the double arrow and select “Open in Vega Editor” from the three dot menu.

Wordcloud Visualization

The Wordcloud shows you an overview over the frequency of your query results. The higher the frequency of a word in your document, the larger it appears in the cloud.  If you click on a word in the wordcloud, you will see a KWIC view for this data below the cloud(s). From there, you can again make annotations via the three dot menu in the KWIC area or jump into the text via double click.

You can save the wordcloud visualization as SVG or PNG via the horizontal three dot menu. You can also use the menu to view the source code for your visualization.

If you want to tweak your visualization in Vega Online Editor, click the code icon on the right and tick the box “Expose the selected data for access in the Vega Online Editor”. Collapse the side bar via click on the double arrow and select “Open in Vega Editor” from the three dot menu.

Network Visualization

The Network visualization will be available in CATMA shortly.

Switch back to Query View

If you want to return from a visualization back to the query view of the Analyze module, click the minimize icon in the top right corner of the visualization. Your visualization is now collapsed on the right side and can be re-entered by clicking the maximize icon.