Metadata-Version: 1.1
Name: kalasiris
Version: 1.9.1
Summary: A Python library to wrap functions and functionality for the Integrated Software for Imagers and Spectrometers (ISIS).
Home-page: https://github.com/rbeyer/kalasiris
Author: Ross A. Beyer
Author-email: rbeyer@seti.org
License: BSD-3-Clause License
Description: =========
        kalasiris
        =========
        
        *Calling ISIS programs from Python*
        
        ---------------------------------
        
        .. image:: https://img.shields.io/pypi/v/kalasiris.svg
                :target: https://pypi.python.org/pypi/kalasiris
        
        .. image:: https://img.shields.io/conda/vn/conda-forge/kalasiris.svg
                :target: https://anaconda.org/conda-forge/kalasiris
        
        .. image:: https://github.com/rbeyer/kalasiris/workflows/Python%20Testing/badge.svg
                :target: https://github.com/rbeyer/kalasiris/actions
        
        .. image:: https://img.shields.io/circleci/project/github/conda-forge/kalasiris-feedstock/master.svg?label=noarch
                :target: https://circleci.com/gh/conda-forge/kalasiris-feedstock
        
        .. image:: https://readthedocs.org/projects/kalasiris/badge/?version=latest
                :target: https://kalasiris.readthedocs.io/en/latest/?badge=latest
                :alt: Documentation Status
        
        
        .. image:: https://codecov.io/gh/rbeyer/kalasiris/branch/main/graph/badge.svg?token=TL5UZUQHRC
                :target: https://codecov.io/gh/rbeyer/kalasiris
                :alt: Codecov Status
        
        
        
        The *kalasiris* library is a Python library to wrap functions and
        functionality for the `Integrated Software for Imagers and Spectrometers
        (ISIS) <https://isis.astrogeology.usgs.gov>`_.
        
        
        * Free software: BSD-3-Clause License
        * Documentation: https://kalasiris.readthedocs.io.
        
        
        Features
        --------
        
        * Primarily a very lightweight wrapper around Python's subprocess
          module to allow easy calling of ISIS programs in the shell from
          within Python.
        * Calling compatibility with pysis_ (and emulation of return types)
        * Guaranteed to work with ISIS 3.6.0+, probably works with ISIS 3+
        * Only guaranteed to work with Python 3.6.0+
        
        
        ISIS
        ----
        
        This library really only works if you already have ISIS_ installed and
        working properly.  Quirks of working with where and how ISIS is loaded
        in your environment and how to use kalasiris with it, can be found
        in the documentation.
        
        
        Citing in your work
        -------------------
        
        Beyer, R. A. 2020. Kalasiris, a Python Library for Calling ISIS
        Programs. 51st Lunar and Planetary Science Conference, not held due
        to COVID-19, Abstract #2441. `ADS URL
        <https://ui.adsabs.harvard.edu/abs/2020LPI....51.2441B>`_
        
        
        Quickstart
        ----------
        
        Are you new to Python? Do you just want to write something 'real quick'
        in Python and need to call some ISIS programs **now**?
        
        We've got you covered.
        
        Need to run an ISIS program like ``cam2map``::
        
            from kalasiris import cam2map
        
            fromcube = 'something.cub'
            tocube = 'something_mapped.cub'
            cam2map(fromcube, to=mapfile)
        
        Easy! Assuming you have a ``something.cub`` file that can be
        map-projected.  The first positional argument will be assumed to be
        the "from" parameter, but you could also explicitly use ``from=fromcube``
        here.
        
        In addition to just calling *all* ISIS programs this way, you can do
        other fun things like this::
        
            import kalasiris as isis
        
            img      = 'PSP_010502_2090_RED5_0.IMG'
            hicube   = 'PSP_010502_2090_RED5_0.cub'
            histfile = 'PSP_010502_2090_RED5_0.hist'
        
            isis.hi2isis(img, to=hicube)
        
            InsID = isis.getkey_k(hicub, 'Instrument', 'InstrumentId')
            print(InsID)
            # prints HIRISE
        
            isis.hist(hicube, to=histfile)
        
            h = isis.Histogram(histfile)
        
            print(h)
            # prints the hist file header info
        
            print(h['Std Deviation'])
            # prints 166.739
        
            print(h[1])
            # prints the second row of the histogram:
            # HistRow(DN=3924.0, Pixels=1.0, CumulativePixels=2.0, Percent=4.88281e-05, CumulativePercent=9.76563e-05)
        
            print(h[1][3])
            print(h[1].Percent)
            # both of the above print 4.88281e-05
        
        
        You can see that there are things like the Histogram class,
        the ``getkey_k()`` *_k function*, and much more.
        
        Read the documentation for more: https://kalasiris.readthedocs.io
        
        
        Installation
        ------------
        
        You can install ``kalasiris`` via ``pip`` or ``conda-forge``:
        
        To install ``kalasiris`` via ``pip``, run this command in your terminal:
        
        .. code-block:: console
        
            $ pip install kalasiris
        
        Installing ``kalasiris`` from the ``conda-forge`` channel can be
        achieved by adding ``conda-forge`` to your channels with:
        
        .. code-block:: console
        
            conda config --add channels conda-forge
        
        Once the ``conda-forge`` channel has been enabled, ``kalasiris`` can be installed with:
        
        .. code-block:: console
        
            conda install kalasiris
        
        It is possible to list all of the versions of ``kalasiris`` available on your platform with:
        
        .. code-block:: console
        
            conda search kalasiris --channel conda-forge
        
        
        If for some reason you don't want to use conda or pip, you could do one of these
        two things (but really, just use conda or pip):
        
        The core functionality is contained in a single file.  Just go into the
        ``kalasiris`` directory, and copy the ``kalasiris.py``
        file into the same directory where your own program is.  It doesn't
        depend on anything that isn't already part of Python, so you can
        just use it.
        
        Just grabbing this one file gets you the ability to call ISIS
        programs from your Python programs.  There are other parts of this
        package that provide helper functions (like ``cubenormfile.writer``),
        classes (like ``Histogram``), and syntactic sugar (the *_k functions*).
        You don't get them by just grabbing ``kalasiris.py`` as described
        above.
        
        If you want *all* of the kalasiris library, but still don't want to
        go through some formal installation process, you can clone this repo,
        and then move (or copy) the whole ``kalasiris/`` directory (instead
        of just the ``kalasiris.py`` file inside of it) to your project, and
        then do the same thing as above, but now you can do more fun things.
        
        However, installation via pip or conda is so easy, and you're installing
        ISIS via conda already.
        
        -------
        
        This repository layout was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
        
        .. _ISIS: https://isis.astrogeology.usgs.gov
        .. _pysis: https://github.com/wtolson/pysis
        .. _Cookiecutter: https://github.com/audreyr/cookiecutter
        .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
        
        
        =======
        History
        =======
        
        All notable changes to this project will be documented in this file.
        
        The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
        and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
        
        When updating this file, please add an entry for your change under
        Unreleased_ and one of the following headings:
        
        - Added - for new features.
        - Changed - for changes in existing functionality.
        - Deprecated - for soon-to-be removed features.
        - Removed - for now removed features.
        - Fixed - for any bug fixes.
        - Security - in case of vulnerabilities.
        
        If the heading does not yet exist under Unreleased_, then add it
        as a 3rd level heading, underlined with pluses (see examples below).
        
        When preparing for a public release add a new 2nd level heading,
        underlined with dashes under Unreleased_ with the version number
        and the release date, in year-month-day format (see examples below).
        
        Unreleased
        ----------
        
        
        1.9.1 (2021-07-04)
        ------------------
        
        Changed
        +++++++
        * Testing now defaults to only running on mocks.
        * Consolidated boolean that controls testing on "real files" to single place.
        * Enabled GitHub Workflows for testing.
        
        Fixed
        +++++
        * Bug in reserved parameter handling, such that only some reserved parameters
          that were given with two trailing underbars (_) would be converted to their
          appropriate "-key=value" form for ISIS.  This was true for "restore" for example,
          which was embarrassingly given in the documentation, but not tested!
        * PathSet module documentation was missing the first letters of several words.
        
        
        1.9.0 (2020-10-13)
        ------------------
        
        Added
        +++++
        * Now supports the new ISISDATA environment variable, in addition to ISIS3DATA.
        
        1.8.0 (2020-06-01)
        ------------------
        * Added the ability to pass arguments to ``subprocess.run()`` for each ISIS program.
        * The ISIS functions now automatically log with a level of INFO.
        * Adopted Conventional Commits pattern (https://www.conventionalcommits.org/en/v1.0.0) for commit messages.
        * Adopted Black formatting.
        * Minor spelling and formatting improvements.
        
        1.7.1 (2020-05-05)
        ------------------
        * Corrected a readthedocs failure.
        
        1.7.0 (2020-05-05)
        ------------------
        * Added some functions to read table data from cube files.
        * Added special pixel values via specialpixels.py (implemented
          as namedtuples instead of as dictionaries, as in pysis).
        * Enabled Python 3.7 and 3.8 tests for tox.
        
        1.6.0 (2020-04-12)
        ------------------
        * Provided pysis return type and exception emulation.
        * Switched from Apache 2 to the BSD-3-Clause license.
        
        
        1.5.0 (2019-11-16)
        ------------------
        * Did some documentation formatting.
        * Streamlined the fromlist module.
        * Put in a protection from accidentally adding a Path to a PathSet twice.
        
        
        1.4.0 (2019-10-08)
        ------------------
        * Added the fromlist module.
        
        
        1.3.0 (2019-10-06)
        ------------------
        * Added the cubeit_k() k_function.
        * Added TravisCI tests for ISIS 3.8.1 and 3.9.0
        * Separated tests into those that can run in-memory with mocking, and those that
          need the filesystem, and ISIS, etc.
        
        
        1.2.0 (2019-10-04)
        ------------------
        * Added a documentation section to help guide a user to choose between pysis and kalasiris.
        * Improved the documentation for the version module a little.
        * Added the stats_k() k_function.
        
        
        1.1.0 (2019-06-19)
        ------------------
        
        * Added the version module in order to query and retrieve ISIS version
          information from the ISIS system.
        * Added TravisCI tests for ISIS 3.7.1
        
        
        1.0.0 (2019-04-24)
        ------------------
        
        * Removed cubenormDialect, and moved it to cubenormfile.Dialect
        * Implemented cubenormfile.writer and cubenormfile.DictWriter, to
          write the fixed-width file format that ISIS cubenorm will actually read.
        
        0.2.0 (2019-03-23)
        ------------------
        
        * Implemented a new feature: the PathSet Class.
        * Enabled installation via ``conda-forge``
        * Updated some documentation.
        * Fixed it so that the module documentation appears in readthedocs
        
        0.1.2 (2019-03-04)
        ------------------
        
        * Discovered a bug that made us platform-dependent.  Fixed.
        * Made a variety of documentation improvements.
        * Enabled and tested install via ``pip install``
        * Enabled testing via tox
        * Enabled testing via Travis CI
        
        0.1.1 (2019-02-22)
        ------------------
        
        * Jesse discovered that the code was incorrectly testing for
          executability of the ``$ISISROOT/bin/xml/*xml`` files instead of
          the ``$ISISROOT/bin/*`` program files, and issued a PR that
          fixed it.
        
        
        0.1.0 (2019-02-20)
        ------------------
        
        * Initial creation finished. Time to share.
        
        0.0.0 (2019-02-12)
        ------------------
        
        * Started project.
        
        
        Version Numbering
        -----------------
        
        The kalasiris library follows the `Semantic Versioning 2.0.0
        specification <https://semver.org>`_, such that released kalasiris
        version numbers follow this pattern: ``{major}.{minor}.{patch}``.
        
Keywords: kalasiris
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
