FAQs

NB: Our documentation pages still need to be updated for CATMA 7. In the mean time, please see What’s New and Changed in CATMA 7.

Getting Started

Do I need to download CATMA?

No, you don’t. You just need a good internet connection.

Which operating systems and browsers can I use?

All common browsers (Chrome, Firefox, Safari, Edge etc.) can be used on MacOS, Windows or Linux. Note however that annotating texts with touch devices is not yet supported.

Is CATMA really free?

Yes! As a research project, the development of CATMA is funded – currently by the Stiftung Innovation in der Hochschullehre (StIL, Foundation for Innovation in University Teaching) as part of the research project forTEXT).

What if something goes wrong and I need help?

That is part of our mission. Do not hesitate to Contact us and we will get back to you as soon as possible.

Login / Password Reset

How do I know if I can log in with my Google account?

Please visit this page for more information.

If I use my Google account to log in, will Google have access to my data?

No. We only use Google as an authentication service. Your text and annotation data will remain private (as long as you don’t share them with other CATMA users). You can also create your own CATMA account. Check our Privacy Policy and Terms of Use for more details on these topics.

How do I reset my password?

Please click here to reset your password.

Common Problems

Why can't I see my annotations anymore?

You haven’t activated the eye-icon of your tagset(s) in the Annotate module. When you open a document in the Annotate module, your annotations are not visible by default. 

Steps to make the annotations visible: 

1) Log in and select the project you recently worked on.

2) Go to the Annotate module. You will see a slide-out panel on the left with a list of all Documents & Annotations of your project.

Image showing CATMA's Documents and Annotations panel (Warum kann ich bei CATMA meine Annotationen nicht mehr sehen, dokument, editor, annotator, sichtbar, auge, tagset, collection, gone)

3) Click the arrow next to the desired document to reveal the associated Annotation Collections. Note the eye-icon next to each collection – this controls the visibility of the annotations within the corresponding collection and is set to visible by default.

Select the document by clicking on the circle next to the name. 

Image showing CATMA's Documents and Annotations panel with a document selected and expanded

4) The slide-out panel will close automatically and your text will be displayed on the left, with Tagsets on the right. Note the crossed out eye-icon next to the Tagset name – this controls the visibility of the associated annotations and is set to not visible by default.

Image showing the Tagsets panel in CATMA's Annotate module, with a collapsed tagset set to not visible (hide, show)

5) Click on the eye-icon to make all annotations for that Tagset visible. 

Image showing the Tagsets panel in CATMA's Annotate module, with a collapsed tagset set to visible and annotations in the text

6) You can also control visibility at the individual tag level. Click the arrow in the Tags column to expand the Tagset and view the contained tags. Each tag has its own eye-icon.

Image showing the Tagsets panel in CATMA's Annotate module, with an expanded tagset and varying visibility

Why am I not able to see or edit any resources in a shared project?

The project Owner has not yet assigned any rights to you for the resources, or one or both of you still need to use the Synchronize with the team function. See the manual entries for roles and synchronization, as well as the next question.

Why can't I or my team members see any changes to the project?

If your team members are unable to see your project changes, either you, or they, or both probably forgot to use the Synchronize with the team function.

CATMA will automatically let you know if you have made changes that can be synchronized with the team by notifying you through the yellow bell icon, found in the top right corner of the Project module. 

Image showing CATMA's yellow synchronization bell (Warum können ich oder meine Team Mitglieder keine Änderungen bei CATMA sehen, gelbe glocke, synchronisieren)

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.

Whenever you have made changes that can be synchronized, the yellow bell icon will appear.

Click the bell icon and a dialog window will appear. Here you can review the changes that are waiting to be synchronized. Click the Synchronize with the team button (you may need to scroll down first if the list of changes is long).

Image showing CATMA's synchronization dialog (unsynchronized commits, synchronize with the team now)

After the loading bar has finished you should receive a notification confirming that your synchronization has been successful. The other team members should now synchronize as well, after which they should be able to see your changes.

To learn more about synchronization, please see this manual entry.

Your Data

Where do you save my uploaded data?

Our primary servers are located in the data centers of the University of Hamburg and the Technical University of Darmstadt. We also utilize services offered by public cloud providers, mostly for backups. All of our servers and data are located in Germany (or in the case of backups, another member state of the European Union) and are subject to stringent security and access control policies. CATMA data and Privacy Policy fall under European jurisdiction.

What happens to my data if your servers crash?

Everything is automatically backed up multiple times per day, in multiple locations. Therefore it’s unlikely that anything will be lost. However, it’s never a bad idea to create your own backups (there are a number of export options, as well as the Git Access).

Is it possible to save local copies of my data?

Yes. You can export text and annotation data to your own computer (see export options below), or you can use Git to clone your projects/repositories (see Git Access).

Exports

Which export formats are supported?

  • .txt
  • .xml (TEI – see here for detailed information on the CATMA-TEI export format)
  • .csv

How can I export resources from the Project module?

First, choose a project you are currently working on. You will automatically be directed to the Resources section of your chosen project. There, you can export from the two panels Documents & Annotations and Tagsets

Image displays view of an open project, CATMA annotation tool, FAQ
Exporting Documents & Annotations

To select one or more documents and annotation collections, switch on the checkboxes using the list icon in the top left corner of the panel (a – see screenshot below).

After you have selected your desired documents and annotation collections (b), you will be presented with the following option via the three-dot menu (c): Export Documents & Collections (d)

Image shows how to export documents and annotations using CATMA
How is the export structured?

The export files will be of the .tar.gz file type, a Unix / Linux ZIP format. After extracting these files, you will find one or more folders that are named according to the document(s), each containing the document itself (of the .txt file type) and a folder annotationcollections that contains a TEI-XML file per annotation collection (if one or more have been selected for download).

This file contains the following XML-elements/attributes:

<teiHeader>: Contains almost exactly the same information as the XML-file that you get when you 
             export a tagset (see Exporting Tagsets below)

<text>: Contains the <ptr>, <seg> and <fs>-elements:
   <ptr>-elements are always references to a section of the text. The target attribute contains         
         the document ID and the character offsets (start,end) of the section of text being 
         referenced.
   <seg>-elements contain a <ptr>-element, and together with a referenced <fs>-element they 
         denote an actual annotation. The ana attribute points to the xml:id of an <fs>- 
         element.
   <fs>-elements reference a particular tag (found in the <teiHeader>) via the type attribute, 
         and they contain metadata and property values of the annotation as <f>-elements.

In summary, a single annotation is a combination of <seg>, <ptr> and <fs>-elements. 
Note that even the non-annotated sections of the text are referenced by <ptr>-elements, but that 
these are not enclosed by <seg>-elements.
Exporting Tagsets

Tagsets are exported in a similar manner as documents and annotations. Select the desired tagset(s) and choose one of the following from the three-dot menu (a):

  • Export Tagsets > as XML (b)
  • Export Tagsets > as CSV (b)
Image shows how to export tagsets in CATMA
Which information is included in the exported XML files?

Each XML file contains a TEI-encoded tagset. The most important human-readable information is contained in the following XML-elements/properties:

˂title˃: Project title
˂author˃: Your public name, i.e. the one who downloaded this file
˂publisher˃: Your public name, i.e. the one who downloaded this file
˂fsdDecl n=”[name] [hash]”˃: Name of the tagset
˂fsDecl˃: A tag
˂fsDescr˃: Name of the tag
˂fDecl˃: Metadata elements including the display color of the tag (name="catma_displaycolor"), 
         the username of the tag author (i.e. the one who created this tag - 
         name="catma_markupauthor"), as well as user-defined properties and their proposed 
         values (name="[property name]")
Which information (i.e. column names) is included in the exported CSV files?

The exported CSV file contains the following column names:

a. Tagset
b. Tagset ID
c. Tag
d. Tag ID
e. Tag Path
f. Tag Parent ID
g. Tag Color
h. Tag Author
i. Project Name
j. Project ID
k. Tag Properties & Values & Property ID

How can I export my query results from the Analyze module?

Select one or more documents and annotation collections (from the slide-out panel on the left) and build a query. In this module, you can export from the results panel or from the KeyWord in Context table.

Exporting from the results panel

First, click on the three-dot menu in the results panel, which is located under the Search button (a). There you can choose between the following display options (b):

  • Group by Phrase
  • Group by Tag Path
  • Display Annotations as flat table
  • Display Properties as columns

Next, click on the three-dot menu again and choose between:

  • Export > Export flat as CSV (c)
  • Export > Export grouped as CSV (c)
Image shows how to export from the results panel CATMA

Hint: This download may take some time depending on the number and size of documents, as well as the number of annotations.

Which information (i.e. column names) is included in the exported CSV files?

The exact output depends on the export option chosen as well as the selected display options (Group by Phrase, Group by Tag Path, Display …).

Selected options:

  • Group by Phrase or Group by Tag Path
  • Export flat as CSV

You will get a table with the following column names (which apply to all queries) if you have built a query by word or phrase pattern:

a. Query and Timestamp
b. Document ID
c. Document Title
d. Text Length in Characters
e. Annotated Text Segment
f. Annotated Text Segment with Context (the asterisks enclose the annotated text segment)
g. Start Offset of Annotation
h. End Offset of Annotation

You will get a table with the following additional column names if you have built a query by tag:

i. Annotation Collection ID
j. Annotation Collection Title
k. Complete Tag Path
l. (empty)
m. Color of Tag as Hex Code
n. Annotation ID

Selected options:

  • Group by Phrase or Group by Tag Path
  • Export grouped as CSV

You will get a table with the following column names (which apply to all queries) if you have built a query by word or phrase pattern:

a. Group: All tokens of the query are listed below
b. Total: Sum of the token occurrences in all documents
c. Title of the document and its ID, with the number of token occurrences in the respective document below
d. Another document and its ID, etc. (optionally)

You will get a table with the following additional column names if you have built a query by tag:

d. Title of the Annotation Collection and its ID, with the number of annotation occurrences in the respective collection below 
e. Another document and its ID, etc. (optionally)
f. Another Annotation Collection and its ID, etc. (optionally)

Selected options:

  • Display Annotations as flat table or Display Properties as columns
  • Export flat as CSV

The export document will contain the following column names:

a. Query and Timestamp
b. Document ID
c. Document Title 
d. Text Length in Characters
e. Annotated Text Segment
f. Annotated Text Segment with Context (the asterisks enclose the annotated text segment)
g. Start Offset of Annotation
h. End Offset of Annotation
i. Annotation Collection ID
j. Annotation Collection Title
k. Complete Tag Path
l. (empty)
m. Color of Tag as Hex Code
n. Annotation ID

Selected options:

  • Display Annotations as flat table or Display Properties as columns
  • Export grouped as CSV 

The export document will contain the following column names:

a. Group: All annotated text segments are listed below
b. Total: Sum of the annotated text segment occurrences in all documents
c. Title of the document and its ID, with the number of annotated text segment occurrences in the respective document below
d. Title of the Annotation Collection and its ID, with the number of annotated text segment occurrences in the respective collection below 
e. Another document and its ID, etc. (optionally)
f. Another Annotation Collection and its ID, etc. (optionally)
Further information

If you select the Group by Tag Path view and export the results via Export flat as CSV, you will get almost the same result/table as if you exported via the KWIC view (see below). The only difference is in the order of the results.

Exporting from the KeyWord in Context table

Once you have some query results, switch to the KWIC view on the right (under Visualizations). 

In the results panel, a new column named Select will appear. 

Select each result you wish to be displayed in the KWIC table, by clicking on the down-arrow icons (a). You can also select all results by choosing the option Select all (b) from the three-dot menu.

Image shows how to export the keyword in context table, KWIC, double-tree

Next, choose from the three-dot menu of the KWIC table (c):

  • Export > Export as CSV (d)
Image shows how to export in CSV format CATMA, annotation tool

If you would like to export only some of the entries from the KWIC table, you can switch on the checkboxes using the list icon in the top left corner of the panel and then select the desired entries. 

Which information (i.e. column names) is included in the exported CSV files?

You will get a table with the following column names if you have built a query by word or phrase pattern:

a. Query and Timestamp
b. Document ID
c. Document Title
d. Text Length in Characters
e. Annotated Text Segment
f. Annotated Text Segment with Context (the asterisks enclose the annotated text segment)
g. Start Offset of Annotation
h. End Offset of Annotation

You will get a table with the following additional column names if you have built a query by tag:

i. Annotation Collection ID
j. Annotation Collection Title
k. Complete Tag Path
l. (empty)
m. Color of Tag as Hex Code
n. Annotation ID

How do I open exported CSV files in other programs like Microsoft Excel and OpenOffice/LibreOffice? Why can’t I see non-Latin characters in exported CSV files?

If you are working with texts in languages that use the Latin alphabet, you can usually open CSV files exported from CATMA without any problems.

However, if you are working with texts in languages that use other characters, such as Greek or Hebrew, you may need to take additional steps before the file contents are displayed properly. In our experience, especially Microsoft Excel tends to automatically choose the Windows-1252 (Latin) character set, without first giving the user a choice.

Note that CATMA CSV exports use the UTF-8 Unicode encoding / character set, and the semicolon as a separator/delimiter.

Programs like OpenOffice and LibreOffice usually give you some options as soon as you open a CSV file, as shown below. Note the choice of character set and separator.

Image showing an OpenOffice Text Import window, and which character set and separator options to select.

For Microsoft Excel, depending on the version, you may need to find the option to import a document, rather than simply opening it. You should then see a similar dialog, where you can make the appropriate choices. Note the selections under ‘File Origin’ and ‘Delimiter’ below.

Image showing a Microsoft Excel Import window, and which character set and delimiter options to select.

Collaboration & Synchronization

How do I add members to my project? What are the roles and permissions that can be assigned?

You are given two options for adding members to your project:

  • You can invite them via an invitation code (recommended for larger groups)
    •  Navigate to the three-dot menu in the top right corner of the Members panel and select Invite someone to the Project
The displayed image shows an expanded menu that allows a user to invite someone to the project
  • You can add them directly by entering your members’ usernames (recommended for individuals and small groups)
    • Navigate to the plus symbol in the top right corner of the Members panel and select Add Member
The displayed image shows an expanded menu that allows a user to add someone to the project

Note that the two methods behave differently. Please visit Roles and Permissions for details.

When should I synchronize my project?

Whenever you make changes to your documents, tagsets, or annotation collections, you have the option to synchronize. This is especially important if you are working with others in the same project. To learn more about synchronization, please see this manual entry.

Limits & Restrictions

Is the uploadable file size or the number of users that can work collaboratively limited?

Theoretically not – if a problem arises, Contact us and we will try to resolve it. Note however that CATMA is a tool that emulates traditional practices in the field of qualitative text studies (with a focus on literary studies), and thus has not been designed as a quantitative or statistical text mining environment for handling massive amounts of data.

Citation

How do I cite the CATMA tool and screenshots of annotations etc. in CATMA?

Please check the footer at the bottom of our website for the correct citation.

These questions and answers were compiled with help from: Larissa Kranewitter-Call and Kristina Becker