Update README.md

README.md

@@ -1,40 +1,147 @@
 ---
 license: apache-2.0
 tags:
-- generated_from_trainer
+- digital humanities
 metrics:
 - bleu
+- cer
 datasets:
 - versae/modernisa
 model-index:
-- name: byt5-base-finetuned-modernisa
+- name: modernisa-byt5-base
   results: []
+language:
+- es
+pipeline_tag: text2text-generation
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
 
-# byt5-base-finetuned-modernisa
 
-This model is a fine-tuned version of [google/byt5-base](https://huggingface.co/google/byt5-base) on an unknown dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.1176
-- Bleu: 44.888
-- Gen Len: 18.4465
 
-## Model description
 
-More information needed
 
-## Intended uses & limitations
+# Model Card for  modernisa-byt5-base
 
-More information needed
+<!-- Provide a quick summary of what the model is/does. [Optional] -->
+This model translates from historical, non-normalized Spanish with historical orthography to modern normalized Spanish. It is a fine-tuned version of the multilingual version of the text-totext transformer ByT5 (Xue et al, 2021, 2022) fro translation from 17th century Spanish to modern Spanish.
 
-## Training and evaluation data
 
-More information needed
 
-## Training procedure
+
+#  Table of Contents
+
+- [Model Card for  modernisa-byt5-base](#model-card-for--model_id-)
+- [Table of Contents](#table-of-contents)
+- [Table of Contents](#table-of-contents-1)
+- [Model Details](#model-details)
+  - [Model Description](#model-description)
+- [Uses](#uses)
+  - [Direct Use](#direct-use)
+  - [Downstream Use [Optional]](#downstream-use-optional)
+  - [Out-of-Scope Use](#out-of-scope-use)
+- [Bias, Risks, and Limitations](#bias-risks-and-limitations)
+  - [Recommendations](#recommendations)
+- [Training Details](#training-details)
+  - [Training Data](#training-data)
+  - [Training Procedure](#training-procedure)
+    - [Preprocessing](#preprocessing)
+    - [Speeds, Sizes, Times](#speeds-sizes-times)
+- [Evaluation](#evaluation)
+  - [Testing Data, Factors & Metrics](#testing-data-factors--metrics)
+    - [Testing Data](#testing-data)
+    - [Factors](#factors)
+    - [Metrics](#metrics)
+  - [Results](#results)
+- [Model Examination](#model-examination)
+- [Environmental Impact](#environmental-impact)
+- [Technical Specifications [optional]](#technical-specifications-optional)
+  - [Model Architecture and Objective](#model-architecture-and-objective)
+  - [Compute Infrastructure](#compute-infrastructure)
+    - [Hardware](#hardware)
+    - [Software](#software)
+- [Citation](#citation)
+- [Glossary [optional]](#glossary-optional)
+- [More Information [optional]](#more-information-optional)
+- [Model Card Authors [optional]](#model-card-authors-optional)
+- [Model Card Contact](#model-card-contact)
+- [How to Get Started with the Model](#how-to-get-started-with-the-model)
+
+
+# Model Details
+
+## Model Description
+
+<!-- Provide a longer summary of what this model is/does. -->
+This model translates from historical, non-normalized Spanish with historical orthography to modern normalized Spanish. It is a fine-tuned version of the multilingual version of the text-to-text transformer ByT5 (Xue et al, 2021, 2022) for translation from 17th century Spanish to modern Spanish. A fine-tuned version of [google/byt5-base](https://huggingface.co/google/byt5-base) trained on a parallel corpus of 44 Spanish-language Golden Age dramas.
+
+- **Developed by:** [Javier de la Rosa](https://huggingface.co/versae)
+- **Shared by [Optional]:** More information needed
+- **Model type:** Transformer
+- **Language(s) (NLP):** es
+- **License:** apache-2.0
+- **Parent Model:** [Byt5-Base](https://huggingface.co/google/byt5-base)
+- **Resources for more information:** More information needed
+    - [GitHub Repo](https://github.com/versae/modernisa)
+    - [Associated Paper](https://dh2022.dhii.asia/abstracts/files/DE_LA_ROSA_Javier_The_Moderni_a_Project__Orthographic_Modern.html)
+    - [Demo](https://huggingface.co/spaces/versae/modernisa)
+	
+# Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+The motivation to develop the model was to provide a tool producing normalized text which enables computational analyses (such as distances between texts, clustering, topic modeling, sentiment analysis, stylometry etc.), to facilitate modern editions of historical texts and thus alleviate a job which been done manually so far and to provide a resource which may be used by historians and editors who manually transcribe texts produced in the 17th century which were not yet digitized, which are available in cultural heritage institutions, especially libraries and archives. While all the dramas used are written in verses, the model was not tested on texts in prose; the quality of the translation of prose texts into modern normalized Spanish might therefore differ significantly from the satisfying results achieved with dramas in verses.
+
+## Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
+
+This resource may be used by historians and editors who manually transcribe texts produced in the 17th century which were not yet digitized and which are typically available in cultural heritage institutions, especially libraries and archives. 
+
+
+## Downstream Use [Optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
+ 
+This model is already fine-tuned.
+
+
+## Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
+
+
+
+
+# Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+It has to be underlined that the parallel corpus was created solely from text written by four men who lived in counter-reformatory Spain during the rule of inquisition. The view of the world of these dramatists is from our contemporary point of view outdated, strongly patriarchal, misogynist and discriminatory with respect to non-catholic human beings.
+
+
+## Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+
+The intended users of this model are researchers and editors of historical texts. We cannot imagine any harm done by the modernization of those texts as a technical process; however, the reading of such texts may be harmful for persons who are not acquainted with the worldview produced in 17th century Spain. Moreover, linguistic change provides a strong challenge to Natural Language Processing (NLP) applications. Vis-à-vis other languages, linguistic change within the Spanish language was not very pronounced. Further research on the modernization of historical languages is therefore strongly recommended.
+
+
+# Training Details
+
+## Training Data
+
+<!-- This should link to a Data Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+We built a parallel corpus of Spanish Golden Age theater texts with pairs of 44 Golden Age dramas in historical orthography and current orthography. Both corpora were aligned line by line to establish a ground truth for the translation between the different historical varieties of Spanish. The 44 dramas have been written by Juan Ruiz de Alarcón (5), Pedro Calderón de la Barca (28), Félix Lope de Vega Carpio (6), and Juan Pérez de Montalbán (5). The dataset is available on [Huggingface](https://huggingface.co/datasets/versae/modernisa).
+
+
+## Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
 
 ### Training hyperparameters
 
@@ -61,9 +168,140 @@ The following hyperparameters were used during training:
 | 0.0907        | 2.84  | 80000 | 0.1176          | 44.888  | 18.4465 |
 
 
+
 ### Framework versions
 
 - Transformers 4.13.0.dev0
 - Pytorch 1.10.0+cu111
 - Datasets 1.15.2.dev0
 - Tokenizers 0.10.3
+
+
+### Preprocessing
+
+
+
+
+### Speeds, Sizes, Times
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+After randomizing all 141,023 lines in the corpus, we split it into training (80%), validation (10%) and test (10%) sets stratifying by play. We then fine-tuned T5 and ByT5 base models on sequence lengths of 256 doing a grid search for 3 and 5 epochs, weight decay 0 and 0.01, learning rates of 0.001 and 0.0001, and with and without a “translate” prompt.
+ 
+# Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+## Testing Data, Factors & Metrics
+
+### Testing Data
+
+<!-- This should link to a Data Card if possible. -->
+
+A single drama by Lope de Vega (Castelvines y Monteses, 1647).
+
+
+### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+More information needed
+
+### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+More information needed
+
+## Results 
+
+BLEU: 80.66
+CER: 4.20%
+
+# Model Examination
+
+More information needed
+
+# Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type:** More information needed
+- **Hours used:** More information needed
+- **Cloud Provider:** More information needed
+- **Compute Region:** More information needed
+- **Carbon Emitted:** More information needed
+
+# Technical Specifications [optional]
+
+## Model Architecture and Objective
+
+More information needed
+
+## Compute Infrastructure
+
+More information needed
+
+### Hardware
+
+More information needed
+
+### Software
+
+More information needed
+
+# Citation
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+**BibTeX:**
+
+@inproceedings{de_la_rosa_modernilproject_2022,
+	address = {Tokyo},
+	title = {The {Moderniſa} {Project}: {Orthographic} {Modernization} of {Spanish} {Golden} {Age} {Dramas} with {Language} {Models}},
+	shorttitle = {The {Moderniſa} {Project}},
+	url = {https://dh2022.dhii.asia/abstracts/files/DE_LA_ROSA_Javier_The_Moderni_a_Project__Orthographic_Modern.html},
+	language = {en},
+	publisher = {Alliance of Digital Humanities Organizations ADHO / The University of Tokyo, Japan},
+	author = {de la Rosa, Javier and Cuéllar, Álvaro and Lehmann, Jörg},
+	month = jul,
+	year = {2022},
+}
+
+
+**APA:**
+
+
+
+# Glossary [optional]
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+More information needed
+
+# More Information [optional]
+
+More information needed
+
+# Model Card Authors [optional]
+
+<!-- This section provides another layer of transparency and accountability. Whose views is this model card representing? How many voices were included in its construction? Etc. -->
+
+[Javier de la Rosa](https://huggingface.co/versae), [Jörg Lehmann](https://huggingface.co/Jrglmn), questions and comments about the model card can be directed to Jörg Lehmann at joerg.lehmann@sbb.spk-berlin.de
+
+# Model Card Contact
+
+[Jörg Lehmann](joerg.lehmann@sbb.spk-berlin.de)
+
+# How to Get Started with the Model
+
+Use the code below to get started with the model.
+
+<details>
+<summary> Click to expand </summary>
+
+More information needed
+
+</details>