..
  Copyright (C) 2025 Andrea Raffo <andrea.raffo@ibv.uio.no>
  SPDX-License-Identifier: MIT

Generating plots
================

StripePy comes with a ``plot`` subcommand that can be used to generate various kinds of plots.

`stripepy_plot_help` supports the following subcommands:

* ``contact-map`` (``cm``): plot stripes and other features over the Hi-C matrix
* ``pseudodistribution`` (``pd``): plot the pseudo-distribution over the given region of interest
* ``stripe-hist`` (``hist``): generate and plot the histograms showing the distribution of the stripe heights and widths

``stripepy cm`` takes as input a Hi-C matrix in ``.cool``, ``.mcool``, or ``.hic`` format, and optionally the ``.hdf5`` file generated by `stripepy_call_help` (this parameter is mandatory when highlighting stripes or stripe seeds).

``stripepy pd`` and ``stripepy hist`` do not require the Hi-C matrix file, and require the ``.hdf5`` file generated by `stripepy_call_help` instead.

All three subcommands support specifying a region of interest through the ``--region`` option.
When the commands are run without specifying the region of interest, ``stripepy cm`` and ``stripepy pd`` will generate plots for a random 2.5 Mbp region, while ``stripepy hist`` will generate histograms using data from the entire genome.

Example usage:

.. code-block:: bash

  # Plot the pseudo-distribution over a region of interest
  stripepy plot pd 4DNFI9GMP2J8.10000.hdf5 /tmp/pseudodistribution.png --region chr2:120100000-122100000

  # Plot the histograms using genome-wide data
  stripepy plot hist 4DNFI9GMP2J8.10000.hdf5 /tmp/stripe_hist_gw.png

  # Plot the Hi-C matrix
  stripepy plot cm 4DNFI9GMP2J8.mcool 10000 /tmp/matrix.png

  # Plot the Hi-C matrix highlighting the stripe seeds
  stripepy plot cm 4DNFI9GMP2J8.mcool 10000 /tmp/matrix_with_seeds.png --stripepy-hdf5 4DNFI9GMP2J8.10000.hdf5 --highlight-seeds

  # Plot the Hi-C matrix highlighting the architectural stripes
  stripepy plot cm 4DNFI9GMP2J8.mcool 10000 /tmp/matrix_with_stripes.png --stripepy-hdf5 4DNFI9GMP2J8.10000.hdf5 --highlight-stripes

Some example plots generated with `stripepy_plot_help` can be found in file ``stripepy-plot-test-images.tar.xz`` from `doi.org/10.5281/zenodo.14283921 <https://doi.org/10.5281/zenodo.14283921>`_.