.. RosettaSciIO documentation master file, created by
   sphinx-quickstart on Wed Jul 13 20:21:14 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

##########################
RosettaSciIO documentation
##########################

The **Rosetta Scientific Input Output library** aims at providing easy reading and
writing capabilities in Python for a wide range of
:ref:`scientific data formats <supported-formats>`. Thus
providing an entry point to the wide ecosystem of python packages for scientific data
analysis and computation, as well as an interoperability between different file
formats. Just as the `Rosetta stone <https://en.wikipedia.org/wiki/Rosetta_Stone>`_
provided a translation between ancient Egyptian hieroglyphs and ancient Greek.
The RosettaSciIO library originates from the `HyperSpy <https://hyperspy.org>`_
project for multi-dimensional data analysis. As HyperSpy is rooted in the electron
microscopy community, data formats used by this community are still particularly
well represented.


.. grid:: 2 3 3 3
  :gutter: 2

  .. grid-item-card::
    :link: user_guide/install
    :link-type: doc

    :octicon:`rocket;2em;sd-text-info` Getting Started
    ^^^

    New to RosettaSciIO or Python? Find information on how to
    install RosettaSciIO.

  .. grid-item-card::
    :link: supported_formats/index
    :link-type: doc

    :octicon:`checklist;2em;sd-text-info` Supported Formats
    ^^^

    Overview of the different file formats that RosettaSciIO can read
    from and write to, as well as information on specific options if applicable.

  .. grid-item-card::
    :link: user_guide/interoperability
    :link-type: doc

    :octicon:`arrow-switch;2em;sd-text-info` Interoperability
    ^^^

    Information on scripts and packages that allow opening data saved using
    RosettaSciIO with third-party programs.

  .. grid-item-card::
    :link: file_specification/index
    :link-type: doc

    :octicon:`checklist;2em;sd-text-info` File Specifications
    ^^^

    Links to or documentation of file specifications for
    some of the formats supported by RosettaSciIO.

  .. grid-item-card::
    :link: api/index
    :link-type: doc

    :octicon:`book;2em;sd-text-info` API Reference
    ^^^

    Documentation describing how to use RosettaSciIO with other
    libraries than HyperSpy or for custom implementations using the
    Application Programming Interface (API).

  .. grid-item-card::
    :link: contributing
    :link-type: doc

    :octicon:`code-square;2em;sd-text-info` Contributing
    ^^^

    Information on how to implement new file plugins or help improve existing ones.


RosettaSciIO provides the dataset, its axes and related metadata contained in a
file in a :ref:`python dictionary <interfacing-api>` that can be easily
handled by other libraries.

.. note::

   RosettaSciIO has recently been split out of the `HyperSpy repository
   <https://github.com/hyperspy/hyperspy>`_ and the new API is still under development.
   HyperSpy will use the RosettaSciIO IO-plugins from v2.0. It is already possible to import
   the readers directly from RosettaSciIO as follows:

   .. code::

      from rsciio import msa
      msa.file_reader("your_msa_file.msa")


.. _using-rsciio:

Python packages using RosettaSciIO
==================================

The following python packages available through `PyPI <https://pypi.org/>`_ and/or
`conda-forge <https://anaconda.org/conda-forge/>`_ use the RosettaSciIO plugins
for reading/writing of data files:

* `HyperSpy <https://hyperspy.org>`_: Multidimensional data analysis 

* Any `HyperSpy extension <https://github.com/hyperspy/hyperspy-extensions-list>`_
  that inherits the IO capabilities:

  * `LumiSpy <https://lumispy.org>`_: Luminescence analysis with HyperSpy
  * `Kikuchipy <https://kikuchipy.org>`_: Processing, simulating and analyzing
    electron backscatter diffraction (EBSD) patterns in Python 
  * `PyXem <https://pyxem.readthedocs.io>`_: An open-source Python library for
    multi-dimensional diffraction microscopy.
  * `exSpy <https://hyperspy.org/exspy/>`_: Analysis of X-ray Energy Dispersive
    Spectroscopy (EDS) and Electron Energy Loss Spectroscopy (EELS).
  * `holospy <https://hyperspy.org/holospy/>`_: Analysis of (off-axis) electron
    holography data.

* `quantem <https://github.com/electronmicroscopy/quantem>`_: Quantitative electron
  microscopy data analysis toolkit
* `Fitspy <https://github.com/CEA-MetroCarac/fitspy>`_: Fit spectra in python with
  GUIs
* `pynxtools-em <https://fairmat-nfdi.github.io/pynxtools-em/>`_: Parse and normalize
  electron microscopy data to the nexus metadata format

The following python packages available only via `GitHub <https://github.com>`_ use
the RosettaSciIO plugins for reading/writing of data files:

* `TemCompanion <https://github.com/matao1984/temcompanion>`_: View, edit, and convert
  TEM micrographs to common image formats

In addition, any package depending on the above may make use of the I/O capacities of RosettaSciIO.

.. note::

   If you think a certain package should be added to the above list, feel free 
   to open an `issue <https://github.com/hyperspy/rosettasciio/issues>`_ or make
   a :ref:`pull request <pull_requests>`. Packages depending on RosettaSciIO can
   be also found on the `Insights tap <https://github.com/hyperspy/rosettasciio/network/dependents?dependent_type=PACKAGE>`_
   of the RosettaSciIO repository on GitHub, or via
   `Wheelodex <https://www.wheelodex.org/projects/rosettasciio/rdepends/>`_.


Citing RosettaSciIO
===================

If RosettaSciIO has been significant to a project that leads to an academic
publication, please acknowledge that fact by citing it. The DOI in the
badge below is the `Concept DOI <https://support.zenodo.org/help/en-gb/1-upload-deposit/97-what-is-doi-versioning>`_ --
it can be used to cite the project without referring to a specific
version. If you are citing RosettaSciIO because you have used it to process data,
please use the DOI of the specific version that you have employed. You can
find it by clicking on the DOI badge:

.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.8011666.svg
   :target: https://doi.org/10.5281/zenodo.8011666


Credits
=======

RosettaSciIO is developed by `an active community of contributors
<https://github.com/hyperspy/rosettasciio/contributors>`_.


Table of contents
=================

.. toctree::
   :maxdepth: 2

   user_guide/index
   file_specification/index
   supported_formats/index
   api/index
   contributing
   changes
