Help page for ChantMapper
Here you can find pieces of advice for smooth usage of ChantMaper app - web application for those interested in
computational research on Gregorian chant and map visualizations of sources of chant.
Sections
1. Pages
2. How can I ...?
2.1 Compute results for ...
3. Problems report contact
2.1.1 One feast
2.1.2 More feasts
2.1.3 All feasts
2.1.4 Only Matins
2.1.5 All offices
2.1.6 Data from my dataset
2.2 Choose proper community search principle
2.3 Interpret the results
2.4 Get user account
2.5 Log into my existing user account
2.6 Upload my dataset
2.6 Add geography info
1. Pages
1.1 Home page
Home page provides redirect to Search tool page as well as users authentication options.
It also let you have a look on what provenances of sources are known to the tool and so what you can and cannot expect in the results of provided search.
It also let you have a look on what provenances of sources are known to the tool and so what you can and cannot expect in the results of provided search.
1.2 Tool page
Web page referred as tool is main research playground.
Given schemata (and also tutorial bellow) should show you, how to make desired search.
1.2.1 Tradition search request
Form fill consists of these five steps:
List of abbreviations:
- V, M, L, V2
- - standard Cantus Index abbreviations for services: First Vespers, Matins, Lauds, Second Vespers
- Basic CI dataset
- - it is dataset consisting of antiphons and responsories that were reachable in Cantus Index database in February 2024
1.2.2 Results of tradition search
Results of search for potential traditions in repertoire can be examine in three different ways:
Table
Community map
Century map
Another part of the result is significance level.
This is kind of "algorithm confidence indicator" - once using Louvain algorithm we run the search ten times and compute how "stable" retrieved results are via Jaccard index. (All retrieved varinats were same => 1.0.)
For Complete agreemnt priciple as a deterministic principle this would be always equal to 1.0.
For approach using Topic modeling running the search more then once also does not make sence since we use pretrainded models and so the answer would again be the same for all such runs.
This is kind of "algorithm confidence indicator" - once using Louvain algorithm we run the search ten times and compute how "stable" retrieved results are via Jaccard index. (All retrieved varinats were same => 1.0.)
For Complete agreemnt priciple as a deterministic principle this would be always equal to 1.0.
For approach using Topic modeling running the search more then once also does not make sence since we use pretrainded models and so the answer would again be the same for all such runs.
1.3 Dataset page
To authenticated users (those registered and logged in) we offer possibility to work with their own selected data.
Named datasets are then shown to its owner user in search form.
There is also possibility of public datasets that allows users to make their datasets accessible for all other users. Every app visitor can see and use public datasets of others.
To find this page please log in and then on Tool page click on Maintain your datasets button on right.
To start with this option please follow instructions in section about upload of custom datasets.
Named datasets are then shown to its owner user in search form.
There is also possibility of public datasets that allows users to make their datasets accessible for all other users. Every app visitor can see and use public datasets of others.
To find this page please log in and then on Tool page click on Maintain your datasets button on right.
1.4 Geography page
Big feature of this app is map visualisation that is driven by geography data (what is where).
To provide this we tried our best to find all provenances for our sources. But we did not manage to find them all
as well as we cannot have all possible places listed somewhere so if you upload new source from new provenance
app would be clueless about where to draw it.
For such situation there is geography page (reachable for example from home page), where you can help us
(as a logged in user) to identify unknown places.
I section [1] there is space to identify same places written in different way (this can happened when someone indexing used different translation or add some punctuation etc.).
If there is no identity in provenance in bold on top and suggestions in section [1], then
you can enter geographical coordinates in section [2]. Use decimal format of coordinates (e. g. [51.507222, -0.1275] is London).
To provide this we tried our best to find all provenances for our sources. But we did not manage to find them all as well as we cannot have all possible places listed somewhere so if you upload new source from new provenance app would be clueless about where to draw it.
For such situation there is geography page (reachable for example from home page), where you can help us (as a logged in user) to identify unknown places.
If there is no identity in provenance in bold on top and suggestions in section [1], then you can enter geographical coordinates in section [2]. Use decimal format of coordinates (e. g. [51.507222, -0.1275] is London).
2. How can I ... ?
2.1 Compute results for ...
2.1.1 Results for one particular feast
To get result for only one feast search for it in section [1] filed and once it pops
out from suggestions click on it.
2.1.2 Results for more particular feasts
To get result for more than one feast search one by one for all of them in filed in section [1].
Just after each selection click again into the filed and type another search and click on right suggestion.
Just after each selection click again into the filed and type another search and click on right suggestion.
2.1.3 Results for all available feasts
2.1.4 Results for chants only from Matins
To use only data of particular office in your search use fileds in section [2].
From second part of section click on grey square beside M (Matins):
But you can also select more offices from given options:
2.1.5 Results for all available offices
To use all available data (from all parts of day) you simply click
on filed All in first part of section [2].
2.1.6 Results using data from particular datasets
To choose sources (datasets) of data that would be use in your search
use filed in section [5].
You can pick not only your uploaded datasets (that would be listed under Basic CI dataset) but also from datasets uploaded by other users as public. You can list these by clicking on button Show other public datasets.
You can pick not only your uploaded datasets (that would be listed under Basic CI dataset) but also from datasets uploaded by other users as public. You can list these by clicking on button Show other public datasets.
2.2 Choose proper community search principle
That is difficult question.
ChantMapper app offer one deterministic (Complete agreement principle), one nondeterministic (Louvain algorithm) and one very experimental method (Topic models).
ChantMapper app offer one deterministic (Complete agreement principle), one nondeterministic (Louvain algorithm) and one very experimental method (Topic models).
Complete agreement principle works on unification of same sets of chants - one way is treating all office as one big bag of chnats, other is
comparing chants in sets of office where two sources are considered being in same community while having all office sets same.
Louvain algorithm is method for community detection in networks and is used e. g. for social networks. It optimizes the modularity of the network when merging its vertices in sequence. Paper is here.
It was used for purposes of chant by Eipert and Moss (link to their poster here).
Topic modeling is method borrowed from computer linguistic and NLP. We used LDA model (paper here).
LDA is a hierarchical generative model of a text-like corpus, in which
every document (here: document = liturgical book) is represented as a distribution over a number of topics, and every topic
is represented as a distribution over all possible words (here: Cantus IDs).
So I would suggest to think about what you are searching for...
Is it overview of material grouped by same chants? Or are you user used to synoptic tables from Cantus Analysis Tool?
Go for Complete agreement principle.
Go for Complete agreement principle.
Is it possibility of new unseen connections with the risk of uncertainty?
Go for Louvain.
Go for Louvain.
Is it interest in something completely new although it can lead to misleading results?
Go and try Louvain and also Topic model.
Go and try Louvain and also Topic model.
2.3 Interpret the results
As in section 2.2 about picking clustering principle, here is also not clear and one simple correct answer and it is dependenig on your usecase.
In general ChantMapper is helper in exploration, it suggests possibilities and if any of them catches your attention than it is probably good plan to go deeper, but even with deterministic clear Complete agreement principle at the end one has to dive into manual work with sources to be sure.
Of course "soft" methods for traditions building such as Louvain and Topic models bring even more uncertainity into the game and not even measured significance level (described in section 1.2.2) is 100 % certificate for anything.
So... How to interpret?
Carefully and with mind scientifically open to doubts.
(Being sorted into one community can mean also just not having much of an repertoire and just by some coincidence having one of the few pieces in common. Is this a sign of tradition match?)
In general ChantMapper is helper in exploration, it suggests possibilities and if any of them catches your attention than it is probably good plan to go deeper, but even with deterministic clear Complete agreement principle at the end one has to dive into manual work with sources to be sure.
Of course "soft" methods for traditions building such as Louvain and Topic models bring even more uncertainity into the game and not even measured significance level (described in section 1.2.2) is 100 % certificate for anything.
So... How to interpret?
Carefully and with mind scientifically open to doubts.
(Being sorted into one community can mean also just not having much of an repertoire and just by some coincidence having one of the few pieces in common. Is this a sign of tradition match?)
2.4 Get user account
To create your user account you have to go to home page (click on the Chantmapper sign in the top grey bar)
and then click on right on the button Create account:
That would take you to Registration page:
Your username can be almost anything, with password we require a certain "strength",
for that follow please instructions in red that would appear in case of some problems.
2.5 Log into my existing user account
You have already created your user account in ChantMapper app and now you want to log yourself in.
To do so you have to go to home page (click on the ChantMapper sign in the top grey bar) and the click on right on the button Login:
That would take you to Login page:
If you forget your password or username to existing account, then we are truly sorry for your lose and so please feel free to create new account.
To do so you have to go to home page (click on the ChantMapper sign in the top grey bar) and the click on right on the button Login:
2.6 Upload my dataset
For uploading your datasets you need to have own or two files in CSV format.
If your file does not contain any data from sources (liturgical books) unknown to this app, then uploading file containing chants would be enough, otherwise the app would ask you to provide also basic info about your new (to app unknown) sources.
Next two sections destribe what such files should look like.
If your file does not contain any data from sources (liturgical books) unknown to this app, then uploading file containing chants would be enough, otherwise the app would ask you to provide also basic info about your new (to app unknown) sources.
Next two sections destribe what such files should look like.
2.6.1 Chants
For usage by app we need you to upload file
where each chant is on one row and where you insert info about chants into these 5 columns:
Here is a sample CSV file you can compare your file to.
incipit, cantus_id, feast_code, office_id, source_id
(Be careful for example with editors like Excel or LibreOffice Calc that allow you to view and edit CSV files but can damage fields like Cantus ID by deleting leading zeros, e. g. Cantus ID 005482 -> 5482.)
- incipit
- - incipit of the chant (to be listed in the table with result)
- cantus_id
- - Cantus ID of the chant (for more info refer to Cantus Index)
- feast_code
- - for what feast the chant was prescribed (e. g. for Adalberti)
- - to pass this info in a unified way use please codes used by Cantus Index (list can be found here)
- office_id
- - info about office for which the chant was prescribed (e. g. V for (first) Vespers)
- - you can find list of all possible IDs with description on Cantus Database webpage
- source_id
- - by ID of liturgical book is meant URL of a webpage where info about source, that this chant record is from, can be found
- - e. g. https://cantusdatabase.org/source/123614
Here is a sample CSV file you can compare your file to.
2.6.2 Sources
For usage by ChantMapper when you uploaded some sources that are new to the app database we need you to provide some basic info about these sources.
There is minimum requirement of two columns:
There is minimum requirement of two columns:
siglum, source_id
But you can provide more (for better users experience as well as simply for being happy that more info was collected):
- siglum
- - RISM siglum code or other similar identifier of the book (source)
- - e. g. CZ-Bu R 387 or CH-Fco Ms. 2
- source_id
- - URL of a webpage where info about the source can be found
- - e. g. https://cantusdatabase.org/source/123614
- - this URL has to be the same as used in your file with chants while identifying same book
century, provenance, cursus, title
Here is a sample CSV file you can compare your file to.
- century
- - info about time of source origin (please use particular year or "12th century" form)
- provenance
- - place of origin (e. g. Paris)
- - please have a look at the map on home page and try to use same names for same places to make geography view easier
- cursus
- - info if source has Monastic or Secular origin (if unknown just leave the field blank)
- title
- - longer description of source (e. g. Köln (Cologne), Erzbischöfliche Diözesan- und Dombibliothek, 215)
2.7 Add geography info
Once you are asked to add some geography info about provenances you just uploaded in your dataset or you simply want to help us
with identification of places then please visit geography page that can be easily reach from home page (via clicking the button under present map).
As is suggested in description of geography page there are two ways of addition:
As is suggested in description of geography page there are two ways of addition:
by matching unknown provenance with some already present in the database (preferred way)
by adding new coordinates (in decimal format, e. g. [51.507222, -0.1275] is London).
by adding new coordinates (in decimal format, e. g. [51.507222, -0.1275] is London).
3. Problems report
Something seems not working or broken?
You uploaded wrong source info?
Wrong provenances matched? Mistake in coordinates?
Results contain weird data? Anything weird anywhere in the app?
Do not worry and tell us! The easiest way is to report your problem via our email address:
This also apply to any other kind of feedback which is more than welcome.
You uploaded wrong source info?
Wrong provenances matched? Mistake in coordinates?
Results contain weird data? Anything weird anywhere in the app?
Do not worry and tell us! The easiest way is to report your problem via our email address:
This also apply to any other kind of feedback which is more than welcome.
You have not found answer to your question?
Do not worry! You can still ask the administrators :-D
Feel free to contact us the same way that is described in section about reporting problems.
Feel free to contact us the same way that is described in section about reporting problems.