Introduction

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-permissions 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 tightly 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

Sign Up

Click “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 Contact us – 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.)

Login

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

Newsletter

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

Additional Information

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

CATMA Home

Create Project

Once logged in, you’ll 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 the 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 invitation code is valid only for a short period of time.
Alternatively the project owner can add you directly, without you needing to do anything (see Members below).

Modules and Side Menu

On the left side of your home screen, you’ll 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

Enter the Project Module

On entering the Project module via selecting a project on your home screen, the menu on the left side becomes 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 home icon or text 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 & 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, annotation collections or tagsets – to show yet. If you want to add a document, just click 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 click 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 icon at the top left), click 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, click the three-dot menu and choose the relevant option. (Please note that, in the Project module, the editing options for annotation collections 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.

Tagsets

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, click 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, click the three-dot menu and choose the relevant option. (Please note that, in the Project module, the editing options for tagsets are confined to editing their names.) 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.

Members

Add Members

The third tile in the Project module shows the project members. It will display at least 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 username 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 Members 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 “Stop Invititation”. The new members and their roles will be listed on the Members tile. (You can find a more detailed explanation of how this process works here.)

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.

Roles

There are five available roles in CATMA 6. The Owner has every possible right in a project. A Partner can do everything except manage members or delete a project. Assistants don’t have any project administration rights and cannot create or delete resources, but they can view resources and add tags or annotations. An Observer can view everything in a project, but can’t do anything else unless specifically allowed to do so by granting permissions at the resource level. 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 an overview of the roles and the associated rights, please see here.)

Synchronization

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. If the yellow bell icon is not present, you can still find the option to “Synchronize with the team“ in the three-dot menu.

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 to see the button, 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: https://github.com/git-guides/git-commit [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

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 the Project module) or created directly in CATMA. While the tagset (i.e., the ‘container’ for your tags) can be created in the Project module, 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 of 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. Throughout CATMA 6, this latch is used to set your filters, i.e., to select the resources that are displayed in the different 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 selected/active tagsets ticked. Adjust your filters by ticking or unticking boxes and collapse the latch again by clicking on it.
Note that when you enter the Tags module via the left-side menu for the first time after a new login, your filters will be set to display all tagsets of 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 at the top left), click the plus icon at the 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 that you’re creating. Properties are a 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 new property. To do this, type in the values in the Proposed Values box. You may type in several values separated by commas. When you’re done, click “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, click 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 performed via the bin symbols.

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.
Note that when you enter the Annotate 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 already displayed.

Set Filters

Extend the filter latch (by clicking on it) at any time 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 Annotate 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, then one is pre-selected to store any new annotations. This collection is displayed in the top right, under Collection currently being edited. If you want to change the collection that will be used to store new annotations, 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, then click the plus icon, type in a name and confirm.

Annotate

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 from the menu via left-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 selected tag does have properties, you will get a pop-up dialog. You now have the option to add pre-defined or new custom property values to your annotation. Once done, click 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 method above, depending on whether the tag you select 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 “Allow multiple discontinuous selections“ icon below the text, to the right of the slider. You can now select multiple passages from the text and then apply annotations as described above. When you’re done annotating discontinuously, simply click the icon again to turn off the option.

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. 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, all in a tooltip.

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

Enter the Analyze Module

In the Analyze module, you can explore texts and annotations with 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.

Note that if you use the former option for the first time after a new login, you’ll find the filter latch extended and no document or annotation collection selected yet. Select as many documents and/or annotation 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 will be collapsed and the document/collection(s) you’re currently working with in the Annotate module will already be selected.

Set Filters

Adjust your filters (i.e., select different documents or annotation collections) at any time 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.

Queries

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 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 then 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, click “Finish”. You will be taken back to the Analyze module where you can now execute the query by clicking on “Search”.

The Query Builder can also help you to learn the CATMA query language, so that you can construct more complex queries and enter them directly (see below). The query that results from the options you’ve selected via the wizard is shown at the bottom left of the dialog.

Direct Query

The third option for queries is to type your query directly into 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 has been 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-order individual results lists. The default order in which the results are displayed is by descending frequency. 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.

Visualize

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 of Visualization: The KWIC (Key Word in Context) visualization, the Distribution graph, the Wordcloud and the Doubletree (network) visualization.

To generate a visualization, just click one of the icons at 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 left tile.
Once selected, a result will be displayed in the selected results tile below and integrated into your visualization. To remove it from both, click the eraser icon behind the result in the bottom left tile of the Analyze module.

You can switch between your available results lists by using the drop-down menu in the top left corner of the top left tile.

KWIC Visualization

The KWIC (Keyword in Context) visualization shows you results in their textual contexts in the form of a table. You can also use the KWIC visualization to create annotations semi-automatically! Just select one or more rows from the table, and then select “Annotate selected rows” from the three-dot menu and follow the instructions.

By double-clicking a line in the KWIC table, 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 a data dot in the distribution graph, you will see a KWIC view for this data below the graph(s). From there, you can again make annotations via the three-dot menu 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 this 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 horizontal three-dot menu.

Wordcloud Visualization

The wordcloud shows you an overview of 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 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 this 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.

DoubleTree (Network) Visualization

The DoubleTree displays KWIC (Keyword in Context) results as a browsable tree, showing both the preceding and following contexts of one particular word. If you click on a word on the right hand side of the DoubleTree visualization, you will get the following contexts of this word. From there, you can again expand the single paths of the tree. Accordingly, if you click on a word on the left hand side of the DoubleTree visualization, you will see the immediate preceding contexts. 

You can save the DoubleTree visualization as SVG or PNG via the horizontal three-dot menu. You can also use this 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 horizontal three-dot menu.

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.