Metadata-Version: 2.4
Name: pycantus
Version: 1.1.0
Summary: PyCantus: A Python library designed to enhance accessibility of Gregorian chants for both coders and non-coders.
Project-URL: Homepage, https://github.com/dact-chant/PyCantus
Project-URL: Documentation, https://github.com/dact-chant/PyCantus/tree/main/docs
Project-URL: Repository, https://github.com/dact-chant/PyCantus.git
Author-email: Anna Dvorakova <anna.dvorakova332@student.cuni.cz>, Tim Eipert <tim.eipert@uni-wuerzburg.de>, "Jan Hajic jr." <hajicj@ufal.mff.cuni.cz>, Vojtech Lanz <lanz@ufal.mff.cuni.cz>
Maintainer-email: Tim Eipert <tim.eipert@uni-wuerzburg.de>, "Jan Hajic jr." <hajicj@ufal.mff.cuni.cz>, Vojtech Lanz <lanz@ufal.mff.cuni.cz>, Anna Dvorakova <anna.dvorakova332@student.cuni.cz>
License: Copyright (c) 2022-2024 Jan Hajic and others
        
        Permission is hereby granted, free of charge, to any person obtaining
        a copy of this software and associated documentation files (the
        "Software"), to deal in the Software without restriction, including
        without limitation the rights to use, copy, modify, merge, publish,
        distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to
        the following conditions:
        
        The above copyright notice and this permission notice shall be
        included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
        LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
        OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
        WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: Cantus,Gregorian Chant
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: pandas==2.2.2
Requires-Dist: pyyaml==6.0.2
Requires-Dist: requests==2.31.0
Provides-Extra: examples
Provides-Extra: tests
Description-Content-Type: text/markdown

# PyCantus
`PyCantus` is envisioned as a Python API to the Cantus family of databases that makes it easy to use this data for computational processing. Primarily we intend this to be used for research in digital chant scholarship, but of course it can be used to build chant-centric apps, new websites, extract data for comparative studies across different repertoires, study liturgy, etc.  
  
The [CantusCorpus v1.0](https://github.com/DvorakovaA/CantusCorpus) dataset, containing data from the [Cantus Index](https://cantusindex.org/), can be used with the PyCantus library easily.

Finally, Django template of web API providing easier creation of YAML filtration setups called [Filter for PyCantus](https://github.com/DvorakovaA/filterforpycantus) was implemented  while also being deployed at [https://filterforpycantus.owx.cz](https://filterforpycantus.owx.cz).

## Data model

At the heart of the library is the Cantus Database and Cantus Index data model. The two elementary objects in this model are a `Chant`, and a `Source`.

* A `Chant` is one instance of a chant in a source. Typically it has a text, a melody (which is not necessarily transcribed), and a Cantus ID assigned, and it should link to a source in which it is found. In principle it uses fields from the [API defined by Cantus Index](https://github.com/dact-chant/cantus-index/blob/main/README.md); the exact data model is documented in the module.
* A `Source` is a physical manuscript or print that contains Gregorian chant. Primarily, this will be a liturgical book such as an antiphonary, gradual, or other types of books. Fragments are also sources. Provenance (geographical and institutional) and century of origin metadata are carried by source records.

There are two further important classes in the data model: `Melody`, and `Corpus`.

* A `Melody` contains the chant's melody at various levels of representation.
* A `Corpus` contains a dataset composed of sources and chants (that may have melodies). Filtering is done on `Corpus` objects.

Here we have full UML schema of the data model:  

![Full UML PyCantus data model schema.](tutorials/img/data_model_pycantus_full_uml.png).

## User documentation

We realize that two types of users come together at a library of this type – a group of programmers who are getting into Gregorian chant, and then (hopefully) a group of chant experts who are getting into its computer processing. Therefore, be warned that, quite inevitably, when examining the user documentation, each group will encounter things that are obvious to them, but that is fine, as these parts are there precisely for "the others."

### Introduction for Computer Science people
In the documentation (`docs\source` folder) we attempted to compile some basic overview information about Gregorian chant (`intro_to chant.md`), that is a 'nice to have' before getting into work with the material. It should also serve as a cheat sheet for basic terms and concepts.  
(Rendered 'easy to read' version can be reached from `docs\build\html\index.html` entry point when opened in any web browser.)

### Tutorials

For an introduction to using `PyCantus`, run the `tutorials\01_intro_to_pycantus.ipynb` Jupyter notebook.  
  
For more advanced and specific tasks there are four other tutorials in the `tutorials` folder, one describing some basics about the data (especially how to work with melodies) for Gregorian chant beginners (`02_intro_to_chant_data.ipynb`), two working with repertoire (`03_repertoire_traditions.ipynb` and `04_unseen_species.ipynb`) and one showing research on melodies (`05_melody_classification.ipynb`).  
They would show you more possibilities in using `PyCantus` and hopefully also possibilities in Gregorian chant research in general.  
  
All these tutorials expect basic Python knowledge, if you feel weak about your Python programming skills, please, go through some of the many online tutorials available for Python.. 

## Development documentation

Development documentation can be found in `docs\source` folder under `development_docs.md`.  

Standard generated docstrings documentation can be found from `docs\build\html\index.html` entry point when opened in any web browser.


### Installing PyCantus library locally

1. Clone the repository:
    
    ```git clone https://github.com/dact-chant/PyCantus```
   
2. Go to the root directory of the project (the one where `pyproject.toml` is)
3. Run the following command:

    ```pip install .```
   
4. Import the pycantus library and verify it works:

    ```python
    from pycantus import hello_pycantus
    hello_pycantus()
    ```

## About project

PyCantus is being developed under the Digital Analysis of Chant Transmission ([DACT](https://dact-chant.ca/)). This project, funded by the Social Sciences and Humanities Research Council of Canada, aims to advance the study of chant dissemination using computational tools.

Explore more about the project, its goals and contacts on our [homepage](https://ufal.mff.cuni.cz/grants/dact).
