kalasiris 1.8.0

A Python library to wrap functions and functionality for the Integrated Software for Imagers and Spectrometers (ISIS).

kalasiris

Calling ISIS programs from Python

---

The kalasiris library is a Python library to wrap functions and functionality for the Integrated Software for Imagers and Spectrometers (ISIS).

• 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

Quickstart

Are you new to Python? Or you just don’t want to mess with sophisticated Python installation procedures? Or you don’t want to commit to installing something when you don’t know if it will be worth it? Or you just want to write something ‘real quick’ in Python and need to call some ISIS programs now?

We’ve got you covered.

Just go into the kalasiris directory, and copy the kalasiris.py file into the same directory where your program is. It doesn’t depend on anything that isn’t already part of Python, so you can just use it like so:

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.

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 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 you now have access to 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:

$ pip install kalasiris

Installing kalasiris from the conda-forge channel can be achieved by adding conda-forge to your channels with:

conda config --add channels conda-forge

Once the conda-forge channel has been enabled, kalasiris can be installed with:

conda install kalasiris

It is possible to list all of the versions of kalasiris available on your platform with:

conda search kalasiris --channel conda-forge

---

This repository layout was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

History

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, such that released kalasiris version numbers follow this pattern: {major}.{minor}.{patch}.