Mainchain angle
===============

The ``angle`` program computes **backbone angle profiles** along the amino acid
sequence of a coarse-grained protein.  
It can generate:

- time-resolved angle evolution  
- residue-resolved average angles  
- chain-resolved angle profiles  
- angle statistics (mean ± std) across chains and time  
- fully verbose angle output for every chain and every residue  

This program is part of the DROPPS analysis suite and is defined in
``angle.py``.


Overview
--------

The program:

1. Loads a MD trajectory (TPR + XTC ± NDX) using the DROPPS trajectory API.  
2. Selects a reference atom group (either automatically or interactively).  
3. Splits this group into chains and removes terminal residues.  
4. For each non-terminal residue \(i\), computes the angle formed by  
   the triplet \((i-1, i, i+1)\).  
5. Processes all selected frames.  
6. Writes one or more XVG files depending on output options.

The computation uses MDAnalysis for coordinate handling and supports optional
periodic boundary condition (PBC) unwrapping.


Usage
-----

.. code-block:: bash

   dps angle -s run.tpr -f run.xtc [-n run.ndx] [options]


Required Arguments
------------------

.. option:: -s, --run-input TPR

   TPR file containing the full simulation input information  
   (topology, coordinates, box, mapping).

.. option:: -f, --input XTC

   Trajectory (XTC) file to analyze.


Optional Arguments
------------------

Selection
~~~~~~~~~

.. option:: -n, --index NDX

   Optional index file containing predefined groups.

.. option:: -sel, --selection INT

   Select a group by index instead of interactive selection.  
   The group must contain **the angle-center atoms** (the central atom of each
   triplet). Chains will be automatically split and terminal residues removed.


Time Control
~~~~~~~~~~~~

.. option:: -b, --start-time INT

   Starting time (ns) for analysis.

.. option:: -e, --end-time INT

   Ending time (ns).

.. option:: -dt, --delta-time INT

   Time interval (ns) between analyzed frames.

Frame indices are computed internally via ``time2frame``.


Periodic Boundary Conditions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. option:: -pbc, --treat-pbc

   Apply MDAnalysis ``unwrap`` transformation to remove PBC discontinuities.


Output Options
--------------

One or multiple XVG files may be generated.

.. option:: -ot, --output-time FILE

   Output angles **averaged over all chains**, as a function of **time**.

.. option:: -or, --output-residue FILE

   Output angles **averaged over all time points**, for each **chain**,  
   as a function of **residue index**.

.. option:: -ors, --output-residue-statistic FILE

   Mean and standard deviation across all angles,  
   for each residue index.

.. option:: -ov, --output-verbose FILE

   Output verbose per-chain, per-residue, per-frame angle values.


Algorithm
---------

1. **Trajectory Loading**

   .. code-block:: python

      trajectory = trajectory_class(args.run_input, args.index, args.input)

2. **PBC Handling (optional)**

   .. code-block:: python

      unwrap(trajectory.Universe.atoms)

3. **Frame Index Construction**

   .. code-block:: python

      start, end, step = trajectory.time2frame(b, e, dt)

4. **Selection**

   - If ``--selection`` is used: direct selection  
   - Otherwise: interactive ``trajectory.index.print_all()`` prompt  
   - Groups are split by chain: ``splitch_indices``  
   - Terminal residues removed using ``trajectory.is_terminal(atom)``

5. **Angle Triplet Construction**

   For each internal residue with index *i*:

   ::

      angle(i) = angle( (i-1), i, (i+1) )

6. **Angle Calculation**

   For each frame:

   .. code-block:: python

      v1 = pos[i-1] - pos[i]
      v2 = pos[i+1] - pos[i]
      cosθ = dot(normalize(v1), normalize(v2))
      θ = arccos(cosθ) in degrees

7. **Statistics & Output**

   - verbose output  
   - time-averaged angles  
   - residue-averaged angles  
   - mean ± std per residue  


Output Files (XVG)
------------------

All outputs are written via ``write_xvg`` with proper legends and axes labels.

1. **Verbose angle file** (``--output-verbose``)
Angle vs Time for every chain and every residue.

legend example:

.. code-block:: text

    Chain A Residue 32
    Chain A Residue 33
    ...


2. **Time-resolved averages** (``--output-time``)
For each residue: angle averaged over all chains.


3. **Residue-resolved averages** (``--output-residue``)
For each chain: angle averaged over time.

4. **Statistics** (``--output-residue-statistic``)
Mean angle and standard deviation across all chains and frames.



Example
-------

.. code-block:: bash

   dps angle \
       -s run.tpr \
       -f run.xtc \
       -n run.ndx \
       --selection 3 \
       --start-time 0 \
       --end-time 200 \
       --delta-time 1 \
       --output-time angle_time.xvg \
       --output-residue angle_res.xvg \
       --output-residue-statistic angle_stat.xvg


Error Messages
--------------

**“Exception occurred when trying to open trajectory file”**  
Trajectory could not be loaded → check TPR, XTC, NDX paths.

**“Chains in selection groups are not same in length.”**  
Your selection must contain identical chain lengths.

**“The chains … don't possess same residue IDs.”**  
Your chosen index group mixes chains with different residue numbering.

**“Distance will be calculated without PBC.”**  
Displayed when ``--treat-pbc`` is omitted.  
May be acceptable for folded proteins, but not for long disordered chains.


Summary
-------

``dps angle`` provides a flexible and powerful tool for computing backbone angle
profiles across chains, time, and residue index.  
It supports both per-chain and averaged analyses, and produces high-quality XVG
files suitable for plotting with:

- Xmgrace  
- Matplotlib  
- DROPPS visualization scripts