Creation of the zip folder of the Insights produced (and get_timesoap)

README.rst

@@ -1,22 +1,22 @@
-:maintainers:
-    `andrewtarzia <https://github.com/andrewtarzia/>`_;
-    `matteobecchi <https://github.com/matteobecchi/>`_;
-    `simonemartino <https://github.com/SimoneMartino98/>`_
-:documentation: https://dynsight.readthedocs.io
-
 Overview
 ========
 
-``dynsight`` is structured to support a wide range of tasks commonly
-encountered in the analysis of many-body dynamical systems. These tasks
-include handling trajectory data, computing single-particle descriptors,
-performing time-series clustering and conducting various auxiliary analyses.
-To achieve this, dynsight is organized into specialized modules, each
-addressing a specific aspect of this workflow.
-
-Previously in `cpctools`_.
-
-.. _`cpctools`: https://github.com/GMPavanLab/cpctools
+``dynsight`` is an open Python platform built to support a wide range of tasks commonly encountered 
+in the analysis of complex dynamical systems. The software contains and combines modules that allows
+resolving and handling trajectory data, computing single-particle descriptors obtaining time-series
+data that are easier to analyze, performing time-series data clustering, and extracting relevant information out of them. 
+``dynsight`` contains also various auxiliary tools useful to data analysis, including, e.g., modules 
+(`vision <https://dynsight.readthedocs.io/en/latest/vision.html>`_ and `track <https://dynsight.readthedocs.io/en/latest/track.html>`_)  
+for resolving individual-object trajectories for many-body systems - e.g., experimental ones - for which these are 
+not readily available, denoising algorithms, and tools for assessing maximum information extraction from data. 
+
+The documentation is available at: `dynsight.readthedocs.io <https://dynsight.readthedocs.io>`_
+
+If you use ``dynsight``, please to cite the associated scientific paper:
+
+| S. Martino, M. Becchi, A. Tarzia, D. Rapetti & G. M. Pavan
+| "dynsight: an open Python platform for simulation and experimental trajectory data analysis"  
+| arXiv (2025), DOI: `10.48550/arXiv.2510.23493 <https://doi.org/10.48550/arXiv.2510.23493>`_
 
 Installation
 ============
@@ -76,17 +76,10 @@ Examples
 There are examples throughout the documentation and available in
 the ``examples/`` directory of this repository.
 
-There are also examples available in the ``cpctools`` repository
-`here <https://github.com/GMPavanLab/cpctools/tree/main/Examples>`
-
-How To Cite
-===========
-
-If you use ``dynsight`` please cite
+Related works and packages
+==========================
 
-    https://github.com/GMPavanLab/dynsight
-
-    https://doi.org/10.48550/arXiv.2510.23493
+``dynsight`` uses many different open-source packages. Please cite them when appropriate:
 
 * Most modules also use MDAnalysis, https://www.mdanalysis.org/pages/citations/
 * If you use SOAP, please cite https://doi.org/10.1103/PhysRevB.87.184115 and DScribe https://singroup.github.io/dscribe/latest/citing.html
@@ -98,17 +91,8 @@ If you use ``dynsight`` please cite
 * If you use ``dynsight.track``, please cite Trackpy https://soft-matter.github.io/trackpy/dev/introduction.html
 * Entropy calculations are based on ``infomeasure`` https://doi.org/10.1038/s41598-025-14053-5
 
-
 Acknowledgements
 ================
 
-We developed this code when working in the Pavan group,
-https://www.gmpavanlab.polito.it/, whose members often provide very valuable
-feedback, which we gratefully acknowledge.
-
-Much of the original code in ``cpctools`` was written by Daniele Rapetti (Iximiel).
-
-The work was funded by the European Union and ERC under projects DYNAPOL and the
-NextGenerationEU project, CAGEX.
-
-.. figure:: docs/source/_static/EU_image.png
+``dynsight`` is developed and mantained by the G. M. Pavan group at Politecnico di Torino, https://www.gmpavanlab.polito.it/.
+Many group members continuously provide, with their daily work, useful feedback that we gratefully acknowledge.

docs/source/index.rst

@@ -16,6 +16,7 @@
    analysis <analysis>
    data processing <data_processing>
    HDF5er <hdf5er>
+   logs <logs>
 
 .. toctree::
   :hidden:
@@ -46,43 +47,48 @@
 Overview
 ========
 
-| GitHub: https://www.github.com/GMPavanLab/dynsight
-
-:mod:`.dynsight` is structured to support a wide range of tasks commonly
-encountered in the analysis of many-body dynamical systems. These tasks
-include handling trajectory data, computing single-particle descriptors,
-performing time-series clustering and conducting various auxiliary analyses.
-To achieve this, dynsight is organized into specialized modules, each
-addressing a specific aspect of this workflow.
-
-Previously in `cpctools`_.
-
-.. _`cpctools`: https://github.com/GMPavanLab/cpctools
-
+``dynsight`` is an open Python platform built to support a wide range of tasks commonly encountered 
+in the analysis of complex dynamical systems. The software contains and combines modules that allows
+resolving and handling trajectory data, computing single-particle descriptors obtaining time-series
+data that are easier to analyze, performing time-series data clustering, and extracting relevant information out of them. 
+``dynsight`` contains also various auxiliary tools useful to data analysis, including, e.g., modules (:doc:`vision <vision>` and :doc:`track <track>`)  
+for resolving individual-object trajectories for many-body systems - e.g., experimental ones - for which these are 
+not readily available, denoising algorithms, and tools for assessing maximum information extraction from data. 
+
+The software is available at: `www.github.com/GMPavanLab/dynsight <https://www.github.com/GMPavanLab/dynsight>`_
+
+If you use ``dynsight``, please to cite the associated scientific paper:
+
+| S. Martino, M. Becchi, A. Tarzia, D. Rapetti & G. M. Pavan
+| "dynsight: an open Python platform for simulation and experimental trajectory data analysis"  
+| arXiv (2025), DOI: `10.48550/arXiv.2510.23493 <https://doi.org/10.48550/arXiv.2510.23493>`_
 
 Installation
 ============
 
-To get :mod:`.dynsight`, you can install it with pip::
-
-  $ pip install dynsight
+To get ``dynsight``, you can install it with pip::
 
+    $ pip install dynsight
 
 Optional Dependancies
 ---------------------
 
-Old versions :mod:`dynsight` used :mod:`cpctools` for SOAP calculations, if
-you are using Python 3.10 and below, you can use :mod:`cpctools` to access
-:mod:`SOAPify` and :mod:`hd5er` using ::
+Old versions ``dynsight`` used ``cpctools`` for SOAP calculations, if
+you are using Python 3.10 and below, you can use ``cpctools`` to access
+``SOAPify`` and ``hd5er`` using ::
 
   $ pip install cpctools
 
+If you want to use the ``dynsight.vision`` and ``dynsight.track`` modules
+you will need to install a series of packages. This can be done with with pip::
+
+  $ pip install ultralytics PyYAML
 
 How to get started
 ------------------
 
 We suggest you give a read to the ``dynsight.trajectory`` module documentation,
-which offers a compact and easy way of using most of the ``dynsight`` tools.
+which offers a compact and easy way of using most of the ``dynsight`` tools. 
 Also, the documentation offers some copiable Recipes and Examples for the most
 common analyses.
 
@@ -103,33 +109,22 @@ Developer Setup
 
     $ just dev
 
-
 #. Run code checks::
 
     $ just check
 
-
 .. _`just`: https://github.com/casey/just
 
-
 Examples
 ========
 
 There are examples throughout the documentation and available in
 the ``examples/`` directory of this repository.
 
-There are also examples available in the ``cpctools`` repository here:
-https://github.com/GMPavanLab/cpctools/tree/main/Examples
-
-
-How To Cite
-===========
+Related works and packages
+==========================
 
-If you use ``dynsight`` please cite
-
-    https://github.com/GMPavanLab/dynsight
-
-    https://doi.org/10.48550/arXiv.2510.23493
+``dynsight`` uses many different open-source packages. Please cite them when appropriate:
 
 * Most modules also use MDAnalysis, https://www.mdanalysis.org/pages/citations/
 * If you use SOAP, please cite https://doi.org/10.1103/PhysRevB.87.184115 and DScribe https://singroup.github.io/dscribe/latest/citing.html
@@ -139,19 +134,15 @@ If you use ``dynsight`` please cite
 * If you use tICA, please cite ``deeptime`` https://deeptime-ml.github.io/latest/index.html
 * If you use ``dynsight.vision``, please cite Ultralytics YOLO https://docs.ultralytics.com/it/models/yolo11/#usage-examples
 * If you use ``dynsight.track``, please cite Trackpy https://soft-matter.github.io/trackpy/dev/introduction.html
+* Entropy calculations are based on ``infomeasure`` https://doi.org/10.1038/s41598-025-14053-5
 
 
 Acknowledgements
 ================
 
-We developed this code when working in the Pavan group,
-https://www.gmpavanlab.polito.it/, whose members often provide very valuable
-feedback, which we gratefully acknowledge.
-
-Much of the original code in ``cpctools`` was written by Daniele Rapetti (Iximiel).
+``dynsight`` is developed and mantained by the G. M. Pavan group at Politecnico di Torino, https://www.gmpavanlab.polito.it/.
+Many group members continuously provide, with their daily work, useful feedback that we gratefully acknowledge.
 
-The work was funded by the European Union and ERC under projects DYNAPOL and the
-NextGenerationEU project, CAGEX.
 
 Indices and tables
 ------------------

docs/source/logs.rst

@@ -0,0 +1,27 @@
+Logs
+====
+
+dynsight logging system.
+
+.. warning::
+
+   A default instance of :class:`Logger` is **automatically created** when importing the ``dynsight`` package.  
+   This instance is available as ``dynsight.logs.logger``.
+
+   You can configure it, for example to disable the automatic recording of datasets, using:
+
+   .. code-block:: python
+
+      import dynsight
+      dynsight.logs.logger.configure(auto_recording=False)
+
+   You can also access all its attributes and methods described in the Logs page below.
+
+-----
+Usage
+-----
+
+.. toctree::
+  :maxdepth: 1
+
+  Logs <_autosummary/dynsight.logs.rst>