Homework 03
===========

**Due Date: Tuesday, February 3 by 11:00am CST**

Life in Many Formats
---------------------

Our in-class examples so far have used a simplified Uniprot protein dataset in multiple formats. 
Your task for the third homework is to work with a more realistic protein dataset from Uniprot.
You will read data from a Uniprot JSON file and perform a few exploratory analyses on the data. 
You will also convert this JSON to CSV, XML, and YAML formats.

This assignment will help you practice working with 
different data formats commonly used in bioinformatics.

**Input File:** `This JSON file <https://raw.githubusercontent.com/kbeavers/mbs-337-sp26/refs/heads/main/docs/unit02/sample-data/uniprot_protein_list.json>`_
will be your input for each exercise below. 

Exercise 1: Reading and Analyzing JSON Data
--------------------------------------------

Create a Python script called ``exercise1.py`` that:

1. Defines a ProteinEntry model with Pydantic
2. Reads in the input JSON file as a Python Dictionary
3. Converts the Python Dictionary into a list of ProteinEntry objects

Then,

1. Write a function called ``find_total_mass()`` that prints the total combined mass of all proteins in the dataset. 
2. Write a function called ``find_large_proteins()`` that prints a list of protein names of any proteins with a sequence length greater than or equal to 1000.
3. Write a function called ``find_non_eukaryotes()`` that prints a list of protein names of any non-eukaryotic proteins in the dataset. (Hint: A protein is considered non-eukaryotic if "Eukaryota" does not appear in ``protein.organism['lineage']``)

After defining your functions, call each one so the results are printed to the terminal when the script runs. 

**Requirements:**

* Use the ``json`` module from Python's standard library
* Use the ``BaseModel`` class from the ``pydantic`` Python library to define a ``ProteinEntry`` model
* Use **type hints** when defining your functions. 

Exercise 2: Converting JSON to CSV
-----------------------------------

Create a Python script called ``exercise2.py`` that:

1. Reads the input JSON file into a Python dictionary
2. Converts the data to CSV format with the following columns:
   
   * ``primaryAccession``
   * ``proteinName``
   * ``geneName``
   * ``organism_scientificName`` (extract from nested ``organism`` object)
   * ``sequence_length`` (extract from nested ``sequence`` object)
   * ``sequence_mass`` (extract from nested ``sequence`` object)
   * ``function``
3. Writes the output to a file called ``proteins.csv``

**Requirements:**

* Use the ``csv`` module from Python's standard library
* Include a header row with flattened field names (using underscores to indicate nesting)
* Iterate through entries and extract nested values to create each row
* Write each flattened row to the CSV file


Exercise 3: Converting JSON to XML
-----------------------------------

Create a Python script called ``exercise3.py`` that:

1. Reads the input JSON file
2. Converts the data to XML format
3. Writes the output to a file called ``proteins.xml``

**Requirements:**

* Import the ``xmltodict`` module
* Remember that XML requires exactly one root element
* Use the ``pretty=True`` option when writing XML for readability

Exercise 4: Converting JSON to YAML
------------------------------------

Create a Python script called ``exercise4.py`` that:

1. Reads the ``uniprot_protein_list.json`` file
2. Converts the data to YAML format
3. Writes the output to a file called ``proteins.yaml``

**Requirements:**

* Import the ``yaml`` module
* The YAML file should maintain the original order within the JSON file
* The YAML file should start with ``---`` and end with ``...``

What to Turn In
---------------

1. Create a ``homework03`` directory in your Git repository (on your VM)
2. Add all four Python scripts (``exercise1.py`` through ``exercise4.py``) to this directory
3. Add a ``README.md`` file in the ``homework03`` directory that:

   * Describes what each script does
   * Includes a section on AI usage (if applicable - see note below)
4. Commit and push your work to GitHub

**Expected Output Files:**

.. code-block:: text

   my-mbs337-repo/
   ├── homework03/
   │   ├── exercise1.py 
   │   ├── exercise2.py
   │   ├── exercise3.py
   │   ├── exercise4.py
   |   |── proteins.csv
   |   |── proteins.xml
   |   |── proteins.yaml
   │   └── README.md          # specifically describes the contents of the homework03 directory


Note on Using AI
----------------

The use of AI to complete this assignment is not recommended, but it is permitted
with the following restrictions:

The use of LLMs (like ChatGPT, Copilot, etc) or any other AI must be rigorously
cited. Any code blocks or text that are generated by an AI model should be
clearly marked as such with in-code comments describing what was generated, how
it was generated, and why you chose to use AI in that instance. The homework
README must also contain a section that summarizes where AI was used in the assignment.

Additional Resources
--------------------

* `JSON Module Documentation <https://docs.python.org/3/library/json.html>`_
* `CSV Module Documentation <https://docs.python.org/3/library/csv.html>`_
* `xmltodict Library <https://github.com/martinblech/xmltodict>`_
* `PyYAML Documentation <https://pyyaml.org/wiki/PyYAMLDocumentation>`_
* `UniProt <https://www.uniprot.org/>`_ — protein sequence and functional annotation database
* Please find us in the class Slack channel if you have any questions!