pytxs 0.0.1__tar.gz

pytxs-0.0.1/.flake8

@@ -0,0 +1,17 @@
+[flake8]
+ignore=E203,E303,E301,F405,E221,F403,E251,E902,W503,W504,E731,W605,F401
+exclude=
+    .git,
+    __pycache__,
+    conf.py,
+    old,
+    build,
+    dist,
+    deprecated,
+    */tests/*,
+    setup.py,
+    conf.py,
+    .coveragerc,
+    __main__.py,
+    *__init__.py,
+    venv*

pytxs-0.0.1/LICENSE.rst

@@ -0,0 +1,32 @@
+License
+===============================================================================
+
+txs
+-------------------------------------------------------------------------------
+
+txs is available under the `MIT License`_::
+
+  txs: time-resolved x-ray scattering/spectroscopy data analysis tools
+
+  Copyright (C) 2021-2022 ESRF - The European Synchrotron, Grenoble, France
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+  THE SOFTWARE.
+
+.. _MIT License: http://opensource.org/licenses/MIT
+

pytxs-0.0.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include .flake8 requirements-dev.txt
+
+graft docs
+
+# Include tests except the data files
+recursive-include txs *.py

pytxs-0.0.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.1
+Name: pytxs
+Version: 0.0.1
+Summary: time-resolved x-ray scattering
+Author-email: Matteo Levantino <matteo.levantino@esrf.fr>
+License: MIT
+Project-URL: Homepage, https://gitlab.esrf.fr/levantin/txs
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/x-rst
+License-File: LICENSE.rst
+Requires-Dist: numpy>=1.10
+Requires-Dist: h5py>3.0
+Requires-Dist: tqdm
+Requires-Dist: fabio
+Requires-Dist: pyFAI
+Requires-Dist: xraydb>=4.3.4
+Requires-Dist: datastorage
+Provides-Extra: gui
+Requires-Dist: PyQt5; extra == "gui"
+Requires-Dist: matplotlib; extra == "gui"
+Requires-Dist: silx; extra == "gui"
+
+====
+txs
+====
+
+**txs** is a free and open-source python package for the analysis
+of time-resolved x-ray scattering/spectroscopy data. 
+
+
+GETTING txs
+------------
+
+You can run txs on all major platforms. For download and installation:
+
+.. code-block:: bash
+
+    pip install git+https://gitlab.esrf.fr/levantin/txs.git
+
+For installing a specific version (e.g. version 0.1.0):
+
+.. code-block:: bash
+
+    pip install git+https://gitlab.esrf.fr/levantin/txs.git@0.1.0
+
+For upgrading txs to the last version/commit:
+
+.. code-block:: bash
+
+    pip install --upgrade git+https://gitlab.esrf.fr/levantin/txs.git
+
+For forcing the reinstallation of all packages (including dependencies):
+
+.. code-block:: bash
+
+    pip install --force-reinstall git+https://gitlab.esrf.fr/levantin/txs.git
+
+
+DOCUMENTATION
+-------------
+
+* Homepage: https://levantin.gitlab-pages.esrf.fr/txs
+* Quick guide: https://confluence.esrf.fr/display/ID09KB/txs+Python+package
+
+
+SOURCE CODE
+-----------
+
+* Source code: https://gitlab.esrf.fr/levantin/txs
+
+
+LICENSE
+-------
+
+txs is available under MIT License. See LICENSE.rst for more details.
+

pytxs-0.0.1/README.rst

@@ -0,0 +1,54 @@
+====
+txs
+====
+
+**txs** is a free and open-source python package for the analysis
+of time-resolved x-ray scattering/spectroscopy data. 
+
+
+GETTING txs
+------------
+
+You can run txs on all major platforms. For download and installation:
+
+.. code-block:: bash
+
+    pip install git+https://gitlab.esrf.fr/levantin/txs.git
+
+For installing a specific version (e.g. version 0.1.0):
+
+.. code-block:: bash
+
+    pip install git+https://gitlab.esrf.fr/levantin/txs.git@0.1.0
+
+For upgrading txs to the last version/commit:
+
+.. code-block:: bash
+
+    pip install --upgrade git+https://gitlab.esrf.fr/levantin/txs.git
+
+For forcing the reinstallation of all packages (including dependencies):
+
+.. code-block:: bash
+
+    pip install --force-reinstall git+https://gitlab.esrf.fr/levantin/txs.git
+
+
+DOCUMENTATION
+-------------
+
+* Homepage: https://levantin.gitlab-pages.esrf.fr/txs
+* Quick guide: https://confluence.esrf.fr/display/ID09KB/txs+Python+package
+
+
+SOURCE CODE
+-----------
+
+* Source code: https://gitlab.esrf.fr/levantin/txs
+
+
+LICENSE
+-------
+
+txs is available under MIT License. See LICENSE.rst for more details.
+

pytxs-0.0.1/docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pytxs-0.0.1/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

pytxs-0.0.1/docs/source/analysis.rst

@@ -0,0 +1,23 @@
+Analyze the processed data
+==========================
+
+.. note::
+        
+   The following code snippets assumes that you have processed the 
+   data using the procedure described earlier in the 
+   :doc:`previous section <datared>`.
+
+Subtract the heating signal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: python
+
+    import txs
+
+    ai = txs.get_ai(
+        15e3,  # the incoming X-ray energy (in eV)
+        0.15,  # the sample-to-detector distance (in m)
+        center=(968, 969),  # the beam center on the detector (in pixels)
+        detector='rayonix',  # the detector being used
+        binning=(2, 2),  # the pixel binning being used
+    )

pytxs-0.0.1/docs/source/conf.py

@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../../txs'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'txs'
+copyright = '2023, Matteo Levantino'
+author = 'Matteo Levantino'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = '0.0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme',
+    'sphinx_copybutton',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'txsdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'txs.tex', 'txs Documentation',
+     'Matteo Levantino', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'txs', 'txs Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'txs', 'txs Documentation',
+     author, 'txs', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------

pytxs-0.0.1/docs/source/datared.rst

@@ -0,0 +1,67 @@
+Data reduction
+==============
+
+The data reduction methods in the :py:mod:`datared` allow to obtain
+X-ray scattering difference patterns based on the result of the azimuthal
+integration as obtained in the :doc:`previous section <import>`.
+
+The data reduction proceeds as follows:
+
+#. Identify each scattering pattern with its associated time delay.
+#. Normalize each pattern based on the signal in a given q region.
+#. Computes the differences by subtracting the reference signal to each pattern.
+#. Computes the average of the differences for each time delay.
+#. Optionally, apply a filter to discard outliers.
+
+
+Performing data reduction 
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Most of the work done by the :py:func:`datared.datared` function is automatic
+and the function can be used as follows:
+
+.. code:: python
+
+    import txs
+
+    # from previous section
+    dset = ...
+    azav = ...
+
+    dred = txs.datared.datared(azav, "<your reference delay, e.g. '-20us'>")
+
+
+Plot the result
+^^^^^^^^^^^^^^^
+Helper functions are available in :py:mod:`plot` to quickly plot the 
+data. For the difference patterns, :py:func:`plot.plot_diffs` may be used.
+
+.. code:: python
+
+    txs.plot_diffs(dred)
+
+Resulting in a `matplotlib <https://matplotlib.org/>`_ figure:
+
+.. image:: ../fig/fig_plot_diffs.png
+    :width: 600
+    :alt: Difference patterns at various time delays
+
+
+The resulting *dred* object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The *dred* object is a Python dictionary containing the reduced dataset as well
+the content of the *azav* object generated in the `last section <import>`_
+
+The import entries are:
+
+* *q*, the scattering angle amplitudes vector.
+* *t*, the time delays as strings.
+* | *diff_av*, the averaged - and potentially filtered - difference patterns
+  | for each time delay. The axes of the array are (q, time delays).
+* *diff_err*, the errors associated with *diff_av*.
+
+
+Additional options
+^^^^^^^^^^^^^^^^^^
+.. toctree::
+    :maxdepth: 1
+

pytxs-0.0.1/docs/source/help.rst

@@ -0,0 +1,5 @@
+Help
+====
+
+In case of bugs or request for improvements or new features,
+please open an issue on gitlab: https://gitlab.esrf.fr/levantin/txs/-/issues

pytxs-0.0.1/docs/source/import.rst

@@ -0,0 +1,140 @@
+Import and inspect data
+=======================
+
+
+Creating an azimuthal integrator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The txs software makes use of 
+`pyFAI <https://pyfai.readthedocs.io/en/v2023.1/>`_ 
+to perform the azimuthal integration on the images.
+
+Hence, the first step to process your data is to create a so-called
+`AzimuthalIntegrator <https://pyfai.readthedocs.io/en/v2023.1/api/pyFAI.html#module-pyFAI.azimuthalIntegrator>`_ 
+object.
+
+The azimuthal integrator takes information about the detector and the
+geometry of the setup to compute the position of the pixels corresponding
+to the same scattering angle.
+
+In txs, the :py:func:`utils.get_ai` helper function is provided to ease 
+the creation of this object:
+
+.. code:: python
+
+    import txs
+
+    ai = txs.get_ai(
+        15e3,  # the incoming X-ray energy (in eV)
+        0.15,  # the sample-to-detector distance (in m)
+        center=(968, 969),  # the beam center on the detector (in pixels)
+        detector='rayonix',  # the detector being used
+        binning=(2, 2),  # the pixel binning being used
+    )
+
+.. note::
+
+    The creation of the AzimuthalIntegrator object is expected to be 
+    automatized in the future on ID09 at the ESRF by using the metadata 
+    that are recorded during the experiment.
+
+
+Using .edf files (old setup)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Prior to the installation of BLISS software at the ESRF, the detector 
+images were recorded in the .edf file format.
+
+The raw images can be visualized using the 
+`FabIO viewer <https://www.silx.org/doc/fabio/latest/man/fabio_viewer.html>`_.
+
+To perform the **azimuthal integration** for these experiments,
+the :py:func:`azav.integrate1d_dataset` function is 
+to be used by providing the data folder as well as the file extension
+as such:
+
+.. code:: python
+
+    azav = txs.int1d_dset(
+        "<data_folder>",  # the scan folder containing the images
+        ai,  # the previously created AzimuthalIntegrator object
+        extension="edf",
+        method='csr_ocl',  # faster, multi-threaded integration
+        sample_thickness=1.2e-3,  # sample thickness in m (for transmission)
+        sample_material='H2O'
+    )
+
+
+Using BLISS dataset
+^^^^^^^^^^^^^^^^^^^
+The folder hierarchy in BLISS and associated HDF5 files makes possible to
+access the data in multiple ways. 
+The recommanded method is to import the 'dataset' HDF5 file using the 
+:py:class:`datasets.BlissDataset` class:
+
+.. code:: python
+
+    dset = txs.BlissDataset(
+        "path_to/<sample_name>_<dataset_number>.h5"
+    )
+
+The resulting *dset* object is an iterator over the scans and the images which
+contains also metadata related to the experiment:
+
+.. code:: python
+
+    dset.scans  # -> ['1.1', '1.2', '2.1', '3.1',...]
+    
+    # to obtain the metadata for scans '1.2'
+    dset.metdata(1, 2)
+
+Hence, for a given scan '2.1', the images can be accessed and plotted 
+as follows:
+
+.. code:: python
+
+    import matplotlib.pyplot as plt
+
+    plt.imshow(dset["2.1"][0])  # plot the first image
+    plt.imshow(dset["2.1"][4])  # plot the fifth's image
+
+The **azimuthal integration** is done similarly as above by using the 
+:py:func:`azav.integrate1d_dataset` function:
+
+.. code:: python
+
+    azav = txs.azav.integrate1d_dataset(
+        dset["2.1"].folder,  # the folder of scan 2.1 containing the images
+        extension='h5',  # default value, so it can be ommited
+        ai,  # the previously created AzimuthalIntegrator object
+        method='csr_ocl',  # faster, multi-threaded integration
+        sample_thickness=1.2e-3,  # sample thickness in m (for transmission)
+        sample_material='H2O'
+    )
+
+
+The resulting *azav* object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The *azav* object obtained above is a Python dictionary that contains
+the 1D scattering patterns with their associated errors as well as 
+other information about the data and the methods used to process them.
+
+The scattering vector magnitude q, the intensities and errors are 
+contained in the `q`, `i` and `e` keys of the *azav* dictionary, respectively.
+
+
+Plotting possibilities
+^^^^^^^^^^^^^^^^^^^^^^
+Some plotting functions are available to quickly plot useful information.
+For the azimuthal integration, the function :py:func:`plot.plot_azim_regroup`
+allows to view the projection map used by the azimuthal integrator:
+
+.. image:: ../fig/fig_txs_plot_azim_regroup.png
+    :width: 600
+    :alt: projection map of the azimuthal integrator
+
+
+Additional options
+^^^^^^^^^^^^^^^^^^
+.. toctree::
+    :maxdepth: 1
+
+    mask