casanovoutils.graphloss
=======================

.. py:module:: casanovoutils.graphloss

.. autoapi-nested-parse::

   Plot Casanovo training and validation loss.

   This script reads one or more Casanovo training logs (either a log file or a
   `metrics.csv` file) and produces a PNG plot of training and validation loss as
   a function of step/iteration.

   Output is written to `<root>.png`.



Attributes
----------

.. autoapisummary::

   casanovoutils.graphloss.LossSeries
   casanovoutils.graphloss.COMMANDS


Functions
---------

.. autoapisummary::

   casanovoutils.graphloss.read_from_logfile
   casanovoutils.graphloss.read_from_csvfile
   casanovoutils.graphloss.detect_input_format
   casanovoutils.graphloss.read_from_file
   casanovoutils.graphloss.plot_losses
   casanovoutils.graphloss.plot
   casanovoutils.graphloss.main


Module Contents
---------------

.. py:type:: LossSeries
   :canonical: list[tuple[int, float]]


.. py:function:: read_from_logfile(input_path: pathlib.Path) -> tuple[LossSeries, LossSeries]

   Read train/validation loss series from a Casanovo log file.

   :param input_path: Path to a text log file produced during Casanovo training.

   :returns: Two lists of ``(step, loss)`` tuples.
   :rtype: (train_losses, val_losses)


.. py:function:: read_from_csvfile(input_path: pathlib.Path) -> tuple[LossSeries, LossSeries]

   Read train/validation loss series from a Casanovo `metrics.csv` file.

   :param input_path: Path to a CSV file containing Casanovo metrics.

   :returns: Two lists of ``(step, loss)`` tuples.
   :rtype: (train_losses, val_losses)


.. py:function:: detect_input_format(input_path: pathlib.Path) -> str

   Determine whether the input is a log file or a metrics CSV.

   The detection is based on filename conventions and a quick header sniff.

   :param input_path: Path to an input file.

   :returns: Either ``"csv"`` or ``"log"``.
   :rtype: format


.. py:function:: read_from_file(input_path: pathlib.Path) -> tuple[LossSeries, LossSeries]

   Read losses from a Casanovo log file or metrics CSV.


.. py:function:: plot_losses(root: str, train_loss_lists: list[LossSeries], val_loss_lists: list[LossSeries], max_y: float | None) -> None

   Create and save the loss plot.

   :param root: Output file root name. Output is written to ``{root}.png``.
   :param train_loss_lists: A sequence of training loss series.
   :param val_loss_lists: A sequence of validation loss series.
   :param max_y: Optional y-axis maximum.


.. py:function:: plot(root: str, inputs: list[str], max_y: Optional[float] = None) -> None

   Read Casanovo log and/or metrics.csv files and plot training/validation loss.

   :param root: Output file root; plot will be written to ``<root>.png`` and log to
                ``<root>.log``.
   :param inputs: One or more input files (Casanovo log files or ``metrics.csv`` files).
   :param max_y: Optional y-axis maximum.


.. py:data:: COMMANDS
   :type:  casanovoutils.types.Commands

.. py:function:: main() -> None