From 0e92d79eb813939fc0af67d0492dae70676a0b1d Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Tue, 18 Aug 2026 11:35:02 +0100 Subject: [PATCH] docs: update documentation for SIST 1.0.0 --- docs/source/citation.rst | 57 +++++++++ docs/source/development.rst | 143 +++++++++++++++++++++++ docs/source/index.rst | 50 ++++++-- docs/source/installation.rst | 75 ++++++++++++ docs/source/source-usage.rst | 157 +++++++++++++++++++++++++ docs/source/user-guide.rst | 217 +++++++++++++++++++++++------------ 6 files changed, 614 insertions(+), 85 deletions(-) create mode 100644 docs/source/citation.rst create mode 100644 docs/source/development.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/source-usage.rst diff --git a/docs/source/citation.rst b/docs/source/citation.rst new file mode 100644 index 0000000..d3d390e --- /dev/null +++ b/docs/source/citation.rst @@ -0,0 +1,57 @@ +Citing SIST +=========== + +Software citation +----------------- + +SIST is currently maintained and developed by CCPBioSim. + +The repository provides a ``CITATION.cff`` file containing software citation +metadata for the current SIST release. + +When using SIST in published work, cite the SIST software and the relevant +scientific methods for the analyses performed. + +Scientific references +--------------------- + +When using the SIST algorithms, cite the following publication: + +Zhabinskaya, D., Madden, S., & Benham, C. J. (2015). +"SIST: stress-induced structural transitions in superhelical DNA." +*Bioinformatics*, 31(3), 421-422. + +The following publications describe the statistical-mechanical methods and +algorithms used for the different structural transitions and should be cited +as appropriate for the analyses performed. + +Fye, R. M. and Benham, C. J. (1999). +"Exact method for numerically analyzing a model of local denaturation in +superhelically stressed DNA." +*Physical Review E*, 59, 3408-3426. + +Zhabinskaya, D. and Benham, C. J. (2011). +"Theoretical Analysis of the Stress Induced BZ Transition in Superhelical DNA." +*PLoS Computational Biology*, 7, 1-14. + +Zhabinskaya, D. and Benham, C. J. (2013). +"Competitive superhelical transitions involving cruciform extrusion." +*Nucleic Acids Research*, 41(21), 9610-9621. + +Contact +------- + +SIST is currently maintained and developed by CCPBioSim. + +For questions, bug reports, or contributions relating to the maintained +software, please use the `CCPBioSim SIST GitHub repository +`_. + +Original contacts +----------------- + +The original SIST documentation listed the following contacts: + +* Dina Zhabinskaya - dzhabinskaya@ucdavis.edu +* Craig Benham - cjbenham@ucdavis.edu +* Sally Madden - sallymadden@gmail.com \ No newline at end of file diff --git a/docs/source/development.rst b/docs/source/development.rst new file mode 100644 index 0000000..0b69db9 --- /dev/null +++ b/docs/source/development.rst @@ -0,0 +1,143 @@ +Development and Testing +======================= + +The maintained development workflow validates both the source tree and the +installed Conda package. + +Source build +------------ + +Build the C++ components from the repository root: + +.. code-block:: bash + + make -C trans_three clean + make -C trans_three + make -C trans_compete clean + make -C trans_compete + +The Makefiles are also used by the Conda build and accept the compiler and +linker settings supplied by the Conda toolchain. + +Source tests +------------ + +The pytest suite validates command-line behaviour and the maintained scientific +reference outputs. + +Python 3.12 or later is supported for source testing. A direct source test run +also requires: + +* GNU Make +* a C++ compiler +* Perl +* IRF 3.08 on ``PATH`` + +Install the Python testing dependencies: + +.. code-block:: bash + + python -m pip install -e '.[testing]' + +Run the test suite: + +.. code-block:: bash + + python -m pytest tests -vv + +During a normal source test run, the test fixtures create a temporary copy of +the repository, build the C++ executables, and run the supported calculations +from that working copy. + +Scientific regression baselines +-------------------------------- + +The maintained reference outputs for SIST 1.0.0 are stored under: + +.. code-block:: text + + tests/reference/v1.0.0/ + +The regression suite covers: + +* melting +* Z-DNA +* cruciform +* competition + +The tests compare deterministic calculation metadata and profile values at the +precision printed by SIST. Runtime is excluded from the scientific comparison. + +Reference outputs should only be changed as part of a reviewed scientific +change. A failing regression test should not be resolved by replacing the +reference output without establishing the reason for the difference. + +Conda package +------------- + +The Conda recipe defines the package build, runtime, and test requirements. + +Build requirements +~~~~~~~~~~~~~~~~~~ + +* Conda C++ compiler +* GNU Make + +Runtime requirements +~~~~~~~~~~~~~~~~~~~~ + +* Perl +* IRF ``>=3.08,<3.09`` +* compiler runtime libraries resolved by Conda + +Package-test requirements +~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Python +* pytest + +Python and pytest are package-test dependencies only; they are not required for +normal use of the installed SIST package. + +Build and test the Conda package +-------------------------------- + +Build and test the package with: + +.. code-block:: bash + + conda build conda-recipe \ + --override-channels \ + -c conda-forge \ + -c bioconda \ + --no-anaconda-upload + +``conda-build`` creates isolated build and test environments automatically. + +The package test verifies the installed ``sist`` command and its declared +runtime dependencies before running the regression suite. + +The two validation paths therefore serve different purposes: + +``python -m pytest`` + Builds and tests the maintained source tree. + +``conda build`` + Builds the package and tests the installed ``sist`` command using the + dependencies declared by the Conda recipe. + +Release workflow +---------------- + +The release workflow prepares and publishes a SIST release by: + +1. validating the requested version +2. updating the Conda recipe version +3. updating ``CITATION.cff`` +4. creating the release tag +5. creating the GitHub release +6. building and testing the Conda package +7. publishing the validated package to the CCPBioSim Anaconda channel + +The package published for a release is therefore built and tested from the same +Conda recipe used during development and continuous integration. diff --git a/docs/source/index.rst b/docs/source/index.rst index f290fb8..cb3047d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,19 +1,47 @@ -.. SIST documentation master file, created by - sphinx-quickstart on Thu Jan 22 14:14:31 2026. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +SIST +==== -SIST documentation -================== +SIST (Stress-Induced Structural Transitions) is a program for analysing +stress-induced structural transitions in superhelical DNA with a specified +base sequence. -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. +SIST supports calculations for: +* strand separation (melting/SIDD) +* Z-DNA formation +* cruciform extrusion +* competition between melting, Z-DNA, and cruciform transitions + +SIST 1.0.0 provides a maintained Conda distribution, an installed ``sist`` +command, and regression testing against reference scientific outputs. + +Quick start +----------- + +Install SIST with Conda: + +.. code-block:: bash + + conda install -c ccpbiosim -c conda-forge -c bioconda sist + +Run a melting calculation: + +.. code-block:: bash + + sist -a M -f sequence.fa + +Run a competition calculation and write the result to a file: + +.. code-block:: bash + + sist -a A -f sequence.fa -o results.txt .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Contents user-guide - + installation + source-usage + development + citation diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..4992ebc --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,75 @@ +Installation +============ + +Conda +----- + +The recommended way to install SIST is with Conda: + +.. code-block:: bash + + conda install -c ccpbiosim -c conda-forge -c bioconda sist + +The package installs the ``sist`` command together with the runtime +dependencies required by SIST, including: + +* Perl +* Inverted Repeats Finder (IRF) +* the required C++ runtime libraries + +SIST 1.0.0 is validated with IRF 3.08, and the Conda package constrains the +runtime dependency to ``>=3.08,<3.09``. + +Python and pytest are used for testing and are not required in a normal SIST +runtime environment. + +Verify the installation +----------------------- + +Confirm that the installed command and runtime dependencies are available: + +.. code-block:: bash + + command -v sist + command -v perl + command -v irf + +The commands should resolve inside the active Conda environment. + +Running ``sist`` without the required arguments displays the command-line +usage: + +.. code-block:: bash + + sist + +Building from source +-------------------- + +SIST can also be built directly from the source repository. + +A source build requires: + +* a C++ compiler +* GNU Make +* Perl +* IRF 3.08 available as ``irf`` on ``PATH`` + +Build both C++ components from the repository root: + +.. code-block:: bash + + make -C trans_three + make -C trans_compete + +The source-tree pipeline can then be run with: + +.. code-block:: bash + + perl master.pl -a M -f sequence.fa + +For cruciform and competition calculations, IRF must be available on ``PATH``. + +The source build uses the same calculation modes and command-line parameters as +the installed ``sist`` command. The Source Usage page describes the individual +source components and direct component workflow in more detail. diff --git a/docs/source/source-usage.rst b/docs/source/source-usage.rst new file mode 100644 index 0000000..9c92ac5 --- /dev/null +++ b/docs/source/source-usage.rst @@ -0,0 +1,157 @@ +Source Usage +============ + +SIST consists of a Perl pipeline, an IRF integration script, and two C++ +implementations of the transition calculations. + +Normal installed use should go through the ``sist`` command. The interfaces +described on this page are useful when building, inspecting, or running the +source tree directly. + +Source components +----------------- + +``master.pl`` + Pipeline used to run the supported SIST calculations. + +``IR_finder.pl`` + Processes Inverted Repeats Finder (IRF) output and produces the inverted + repeat information required for cruciform calculations, including start + positions, possible extrusion lengths, and cruciform formation energies. + +``trans_three/`` + C++ implementation for analysing strand separation, Z-DNA, and cruciform + extrusion independently. + +``trans_compete/`` + C++ implementation for analysing competition between strand separation, + Z-DNA, and cruciform extrusion. + +Running ``master.pl`` +--------------------- + +After building both C++ components, run the source-tree pipeline with Perl: + +.. code-block:: bash + + perl master.pl -f -a [options] + +For example: + +.. code-block:: bash + + perl master.pl -a M -f sequence.fa + +The available algorithm types are: + +* ``-a M``: melting transition only (SIDD) +* ``-a Z``: Z-DNA transition only +* ``-a C``: cruciform transition only +* ``-a A``: competition between melting, Z-DNA, and cruciform transitions + +Running ``perl master.pl`` without the required arguments displays the +available command-line options. + +IRF +--- + +Cruciform and competition calculations require Inverted Repeats Finder. + +``IR_finder.pl`` invokes ``irf`` from ``PATH``. For source builds, install a +compatible IRF 3.08 executable and ensure that: + +.. code-block:: bash + + command -v irf + +returns the expected executable. + +The maintained Conda package provides this dependency automatically. + +Direct C++ usage +---------------- + +Compile the C++ implementations with: + +.. code-block:: bash + + make -C trans_three + make -C trans_compete + +After compilation, each directory contains a ``qsidd`` executable. + +Running ``qsidd`` without the required arguments displays its detailed usage +information. For example, from ``trans_three``: + +.. code-block:: bash + + ./qsidd -f sequence_file + +Cruciform and competition component workflow +-------------------------------------------- + +When running the components directly, cruciform and competition calculations +require the output produced by ``IR_finder.pl``. + +Run ``IR_finder.pl`` first: + +.. code-block:: bash + + perl IR_finder.pl temperature shape sequence_file + +For a cruciform calculation using ``trans_three``: + +.. code-block:: bash + + ./qsidd -C -X "string" -f sequence_file + +For a competition calculation using ``trans_compete``: + +.. code-block:: bash + + ./qsidd -X "string" -f sequence_file + +Here, ``string`` is the output produced by ``IR_finder.pl``. + +``master.pl`` coordinates this workflow automatically and is normally the +preferred source-tree entry point. + +Working directory +----------------- + +For cruciform and competition calculations, ``IR_finder.pl`` uses the basename +of the input sequence. The sequence file should therefore be present in the +current working directory when these calculations are run. + +Example calculation +------------------- + +The repository contains an example competition calculation based on +``pbr322.toy.fa``. + +The source-tree command is: + +.. code-block:: bash + + perl master.pl \ + -f pbr322.toy.fa \ + -a A \ + -o pbr322.toy.compete.txt \ + -b \ + -p \ + -r + +The equivalent installed command is: + +.. code-block:: bash + + sist \ + -f pbr322.toy.fa \ + -a A \ + -o pbr322.toy.compete.txt \ + -b \ + -p \ + -r + +The example directory also contains IRF intermediate output and an EPS +representation of the competition result. diff --git a/docs/source/user-guide.rst b/docs/source/user-guide.rst index e5dcb88..210c30a 100644 --- a/docs/source/user-guide.rst +++ b/docs/source/user-guide.rst @@ -1,127 +1,196 @@ -=============================================================== -SIST: Stress-Induced Structural Transitions in superhelical DNA -=============================================================== +User Guide +========== Purpose of SIST -=============== +--------------- -The codes in this repository are for analyzing three types of structural transitions in superhelical DNA molecules of specified base sequences and kilobase lengths. These are strand separation, BZ transitions and cruciform extrusion. More types of transitions may be added as their energetics become known. The statistical mechanical methods and algorithms used in these analyses are described in the papers cited below. +SIST analyses three types of structural transition in superhelical DNA +molecules of specified base sequence and length: -Codes -===== +* strand separation +* B-Z transitions +* cruciform extrusion -1. *master.pl*: This is a pipeline to run all algorithms. +The statistical-mechanical methods and algorithms used in these analyses are +described in the publications listed on the Citing SIST page. -2. *IR_finder.pl*: analyzes the output of Inverted Repeat Finder (see below), and outputs a list of inverted repeats and their start positions, all their possible extrusion lengths, and cruciform formation energies for each such length. +Running SIST +------------ -3. *trans_three*: C++ code containing the algorithms for analyzing strand separation, Z-DNA, and cruciform extrusion independently. +When installed through Conda, SIST is run with the ``sist`` command. -4. *trans_compete*: C++ code containing the algorithm for analyzing the competition between strand separation, Z-DNA, and cruciform extrusion. +The general form is: -Instructions for running *master.pl* ------------------------------------- +.. code-block:: bash -The code *master.pl* contains a pipeline that allows the user to run either trans_three or trans_compete with various parameters provided in the menu of the code. Run “perl master.pl” for more detailed instructions and to see all available parameters. Sequence file fasta format is recommended. If another format is provided, the sequence is converted into an appropriate format. Multiple sequences in one file are not permitted. + sist -f -a [options] -Algorithm types: ----------------- +Input sequences +--------------- -1. -a M: melting transition only (SIDD). +A sequence file is supplied with the ``-f`` option. FASTA format is +recommended. -2. -a Z: Z-DNA transition only. +A single input file must contain only one sequence. SIST converts the supplied +sequence into the format required by the selected calculation. -3. -a C: cruciform transition only. +For cruciform and competition calculations, the input sequence should be in +the current working directory and supplied by file name rather than by a path. +This is required by the IRF integration used by SIST 1.0.0. -4. -a A: competition between melting, Z-DNA, and cruciform transitions. +Calculation modes +----------------- +``-a M`` + Melting transition only (SIDD). -To compile and run follow these steps: --------------------------------------- +``-a Z`` + Z-DNA transition only. -1. Download *master.pl*, *IR_finder.pl*, trans_three/ and trans_compete/ folders into a working directory. +``-a C`` + Cruciform transition only. -2. Compile the C++ codes: go to both trans_three/ and trans_compete/ directories, and type **make** on the command line. +``-a A`` + Competition between melting, Z-DNA, and cruciform transitions. -3. Download Inverted Repeats Finder (IRF) that suits your operating system and move it to your working directory. This code can be downloaded here: https://github.com/Benson-Genomics-Lab/IRF/releases/tag/IRFv3.09. +Cruciform and competition calculations use Inverted Repeats Finder (IRF). +When SIST is installed through Conda, IRF is installed automatically as a +runtime dependency. -4. Ignore this step if you are a Linux user. Otherwise, replace the name of IRF executable in the line “my $code = "irf308.linux.exe;" in IR_finder.pl with the executable appropriate for your operating system. +Examples +-------- -5. Move a sequence file you want to analyze into the working directory. +Melting +~~~~~~~ -6. To execute the melting transition (SIDD) with default parameters, type: perl master.pl -a M -f sequence_file. +Run a melting calculation using the default parameters: -**More examples of step 6 above:** +.. code-block:: bash -Competition with default parameters and a specified output file: + sist -a M -f sequence.fa +Z-DNA +~~~~~ -```ruby -perl master.pl -a A -f sequence_file -o output_file -``` +Run a Z-DNA calculation: -Competition code at superhelix density of σ = -0.07 for a circular plasmid, displaying all available output: +.. code-block:: bash -```ruby -perl master.pl -a A -s 0.07 -c -b -p -r -f sequence_file -``` + sist -a Z -f sequence.fa -Usage of C++ codes -================== +Cruciform +~~~~~~~~~ -Type make on command line to compile. Once this is done, qsidd is the executable. -Run “./qsidd” for more detailed instructions and to see all available parameters. To run with default parameters: ./qsidd -f sequence_file. +Run a cruciform calculation: -The following steps are to run cruciform analysis with trans_three and the competition analysis with trans_compete: +.. code-block:: bash -1. First run *IR_finder.pl*: -```ruby -perl IR_finder.pl temperature shape sequence_file -``` + sist -a C -f sequence.fa -2. For cruciforms using trans_three run: -```ruby -./qsidd -C -X “string” -f sequence_file -``` +Competition +~~~~~~~~~~~ -3. For competition using trans_compete run: -```ruby -./qsidd -X “string” -f sequence_file -``` +Run a competition calculation using the default parameters: -Here “string” is the output from *IR_finder.pl*. Run “ perl IR_finder.pl” for a more detailed explanation of step 1. Note: *master.pl* can do the above workflow automatically. +.. code-block:: bash -Algorithm limitations and recommended parameter ranges -====================================================== + sist -a A -f sequence.fa + +Write the output to a file: + +.. code-block:: bash + + sist -a A -f sequence.fa -o output.txt + +Run the competition calculation for a circular plasmid at a superhelical +density corresponding to -0.07 and include the additional base, parameter, and +ensemble-average output: + +.. code-block:: bash + + sist -a A -s 0.07 -c -b -p -r -f sequence.fa -If the codes are executed outside of the ranges listed below, a warning will be printed in the output. We advise that you do not perform the analysis outside the recommended guidelines. Master.pl options corresponding to each parameter are listed below. +Command-line options +-------------------- +.. list-table:: + :header-rows: 1 + :widths: 18 82 -> [!WARNING] -> Algorithm warnings + * - Option + - Description + * - ``-f FILE`` + - Required. Specify the input sequence file. + * - ``-a MODE`` + - Required. Select ``M``, ``Z``, ``C``, or ``A``. + * - ``-T VALUE`` + - Set the temperature in kelvin. The default is 310 K. + * - ``-s VALUE`` + - Set the superhelical density. The default calculation corresponds to + -0.06. The command-line convention uses a value such as ``0.07`` for a + reported stress level of -0.07. + * - ``-i VALUE`` + - Set the ionic strength. The default is 0.01 M. + * - ``-th VALUE`` + - Set the energy threshold. The default is 12 kcal/mol. + * - ``-c`` + - Treat the molecule as circular. The default is linear. + * - ``-n`` + - Use nearest-neighbour melting energetics. The default is copolymeric + melting energetics. + * - ``-b`` + - Include the base at each sequence position in the output. + * - ``-p`` + - Include calculation parameters in the output. + * - ``-r`` + - Include ensemble-average results in the output. + * - ``-o FILE`` + - Write the selected SIST output to ``FILE``. -1. Sequence length in input sequence file should be greater than 1,500 and less than 10,000. +.. note:: -2. Energy Threshold (-th) below 9 many yield inaccurate results, and -th above 15 many results in very long execution times. + The SIST 1.0.0 parser accepts uppercase ``-T`` for temperature. -3. Absolute value of superhelical density (-s) greater than 0.15 may be outside of physiological range. +Output +------ -4. Temperatures (-t) less than 220 K and greater than 320 K may be outside physiological range. +Without ``-o``, the selected SIST output is written to standard output. -5. Salt concentration less than 0.0001 M may be outside physiological range. +With ``-o FILE``, the selected output is written to the specified file: + +.. code-block:: bash + + sist -a M -f sequence.fa -o melting.txt + +The exact output sections depend on the calculation mode and selected options. +The ``-b``, ``-p``, and ``-r`` options add base-pair, parameter, and +ensemble-average information respectively. + +IRF may print progress information while cruciform or competition calculations +are running. + +Algorithm limitations and recommended parameter ranges +------------------------------------------------------ -Citations -========= +SIST reports warnings when calculations are performed outside the recommended +parameter ranges. -When using these algorithms you must cite the first paper below, and some or all of the others, depending on which types of analyses you perform: +.. warning:: -Zhabinskaya, D., Madden, S., & Benham, C. J. (2015). SIST: stress-induced structural transitions in superhelical DNA. Bioinformatics, 31(3), 421-422. + Calculations outside these ranges may be inaccurate, may fall outside + physiological conditions, or may require substantially longer execution + times. -Fye, R. M. and Benham, C. J. (1999), “Exact method for numerically analyzing a model of local denaturation in superhelically stressed DNA”, Phys Rev E, 59, 3408-3426. +1. The input sequence length should be greater than 1,500 base pairs and less + than 10,000 base pairs. -Zhabinskaya, D. and Benham, C. J. (2011), “Theoretical Analysis of the Stress Induced BZ Transition in Superhelical DNA”, PLoS Comput Biol, 7, 1-14. +2. Energy thresholds (``-th``) below 9 may yield inaccurate results, while + thresholds above 15 may result in very long execution times. -Zhabinskaya, D. and Benham, C. J. (2013), “Competitive superhelical transitions involving cruciform extrusion”, Nucleic Acids Res, 41(21), 9610-9621. +3. An absolute superhelical density greater than 0.15 may be outside the + physiological range. -## Contact Information +4. Temperatures below 220 K or above 320 K may be outside the physiological + range. -For questions or problems, please contact either Dina Zhabinskaya (dzhabinskaya@ucdavis.edu), Craig Benham (cjbenham@ucdavis.edu), or Sally Madden (sallymadden@gmail.com). +5. Salt concentrations below 0.0001 M may be outside the physiological range.