README
======

Part 1: Random Embeddings
-------------------------

Description
-----------
In this part, we train a window-based tagger for POS and NER using random embeddings.  
It reads data from `<task>/train`, evaluates on `<task>/dev`, and (optionally) predicts on `<task>/test`.

Directory structure
-------------------
.
|-- tagger1.py  
|-- pos/  
|   |-- train  
|   |-- dev  
|   `-- test  
`-- ner/  
    |-- train  
    |-- dev  
    `-- test  

Arguments
---------
--task pos|ner        Task to run (“pos” or “ner”)  
--part NAME           Identifier for exercise part (part 1)  
[--output_test PATH]  Write test-set predictions to PATH (optional)  

Usage
-----
Train & evaluate on dev set:
  python tagger1.py --task pos --part 1

Generate test-set predictions:
  python tagger1.py --task pos --part 1 \
    --output_test test1.pos

Outputs
-------
Graphs for validation set accuracy and loss are created and saved in figures/ dir
Test predictions are writtten to:
  <output_test> path (if specified)  

Determinism
-----------
Fixed seed (42) for Python, NumPy, and PyTorch;  
cuDNN deterministic flags enabled.  

Part 3: Pretrained Embeddings
------------------------------

Description
-----------
In this part, we extend our tagger (tagger1.py) to support loading a pretrained vocabulary (embeddings/vocab.txt) and its corresponding embeddings (embeddings/wordVectors.txt) via command-line flags. 
Training and evaluation follow the same pattern as Part 1 but with a different number of epochs since convergence is faster.

Directory structure
-------------------
.
|-- tagger1.py  
|-- pos/  
|   |-- train  
|   |-- dev  
|   `-- test  
`-- ner/  
    |-- train  
    |-- dev  
    `-- test  
|-- embeddings/  
    |-- vocab.txt  
    `-- wordVectors.txt  

Arguments
---------
--task pos|ner        Task to run (“pos” or “ner”)  
--part NAME           Identifier for part of the assignment (e.g. “3”)  
--vec_path PATH       Pretrained vectors file (required)  
--vocab_path PATH     Vocabulary file matching vectors (required)  
[--output_test PATH]  Write test-set predictions to PATH (optional)  

Usage
-----
Train with pretrained embeddings:
  python tagger1.py --task ner --part 3 \
    --vec_path embeddings/wordVectors.txt \
    --vocab_path embeddings/vocab.txt

Generate test-set predictions:
  python tagger1.py --task ner --part 3 \
    --vec_path embeddings/wordVectors.txt \
    --vocab_path embeddings/vocab.txt \
    --output_test test3.ner

Outputs
-------
Graphs for validation set accuracy and loss are created and saved in figures/ dir
Test predictions are writtten to:
  <output_test> path (if specified)  

Determinism
-----------
Same as part 1

Part 4: Affix-Based Window Tagger (tagger4.py)
----------------------------------------------

Description
-----------
In this part, we extend the window-based tagger to incorporate prefix and suffix (affix) features. Each word in the context window is represented by its word embedding and separate embeddings for its fixed-length prefix and suffix. The embeddings for word, prefix and suffix are summed and fed into an MLP, enabling the model to capture morphological patterns. Pre-trained embeddings can also be provided thorugh appropriate command-line flags.

Directory structure
-------------------
.
|-- tagger3.py       # main script for Part 4
|-- pos/             # part-of-speech data
|   |-- train
|   |-- dev
|   `-- test
|-- ner/             # named-entity-recognition data
|   |-- train
|   |-- dev
|   `-- test
|-- embeddings/      # (optional) pretrained vectors
|   |-- vocab.txt
|   `-- wordVectors.txt

Arguments
---------
--task pos|ner         Task to run (“pos” or “ner”)
[--vec_path PATH]      Path to pretrained vectors file (optional)
[--vocab_path PATH]    Path to vocabulary file matching vectors (optional)
[--output_test PATH]   Write test-set predictions to PATH (optional)

Usage
-----
Train & evaluate on dev set (random embeddings):
  python tagger3.py --task pos

Train with pretrained embeddings:
  python tagger3.py --task pos --vec_path embeddings/wordVectors.txt --vocab_path embeddings/vocab.txt

Generate test-set predictions:
  python tagger3.py --task pos --output_test test4.pos

Hyperparameters
---------------

Outputs
-------
Graphs for validation set accuracy and loss are create and saved in figures/ dir

Test predictions are writtten to:
  <output_test> path (if specified)

Determinism
-----------
Same as part 1

Part 5: Character‐CNN Tagger (tagger4.py)
----------------------------------------------

Description
-----------

In this part, we extend our window‐based tagger to include a character‐level CNN. Each word is represented by concatenating its pretrained (or randomly initialized) word embedding with a max-pooled vector produced by applying a 1D convolution over that word’s character embeddings. This allows the model to learn subword features useful for both POS and NER.


Directory structure
-------------------
.
|-- tagger4.py      
|-- pos/            
|   |-- train
|   |-- dev
|   `-- test
|-- ner/            
|   |-- train
|   |-- dev
|   `-- test
|-- embeddings/      
|   |-- vocab.txt
|   `-- wordVectors.txt

Arguments
---------
--task pos|ner         Task to run (“pos” or “ner”)
[--vec_path PATH]      Path to pretrained vectors file (required)
[--vocab_path PATH]    Path to vocabulary file matching vectors (required)
[--output_test PATH]   Write test-set predictions to PATH (optional)

Usage
-----
Train & evaluate on dev set (random embeddings):
  python tagger4.py --task pos

Train with pretrained embeddings:
  python tagger4.py --task ner --vec_path embeddings/wordVectors.txt --vocab_path embeddings/vocab.txt

Generate test-set predictions:
  python tagger4.py --task pos --vec_path embeddings/wordVectors.txt --vocab_path embeddings/vocab.txt --output_test test5.pos

Hyperparameters
---------------

Outputs
-------
Graphs for validation set accuracy and loss are create and saved in figures/ dir

Test predictions are writtten to:
  <output_test> path (if specified)