kalasiris package

Submodules

kalasiris.Histogram module

class kalasiris.Histogram.Histogram(histinfo)

Bases: Sequence

Reads the output from ISIS hist and provides it as a sequence.

The resulting Histogram object primarily behaves like a list, where that list represents the rows of the ISIS hist output. Each of those rows is a collections.namedtuple() which contains the elements of each row, referenced by their column names.

The Histogram object also has some dictionary-like capabilities, in order to get at the values listed in the ISIS hist output in the section before the numerical output.

keys()

Gets the keys from the initial portion of the hist output file.

These will be items like ‘Cube’, ‘Band’, ‘Average’, etc.

static parse(histinfo: str) → tuple

Takes a string (expecting the output of ISIS hist), and parses the output.

A three-element namedtuple is returned: the first element is a dictionary of the name:value information at the top of the file, the second element is a list of the of the fields that decorate the top of the histogram rows, and the third element is a list of HistRow collections.namedtuple() objects that represent each row of the hist output.

The contents of the file that results from ISIS hist look like this:

Cube:           PSP_010502_2090_RED5_0.EDR_Stats.cub
Band:           1
Average:        6490.68
[... other lines like this ...]
His Pixels:      0
Hrs Pixels:      0


DN,Pixels,CumulativePixels,Percent,CumulativePercent
3889,1,1,4.88281e-05,4.88281e-05
3924,1,2,4.88281e-05,9.76563e-05
3960,2,4,9.76563e-05,0.000195313
[... more comma-separated lines like above ...]

But this function sees it like this:

k: v
k: v
k: v
[... other lines like this ...]
k: v
k: v


h,h,h,h,h
n,n,n,n,n
n,n,n,n,n
n,n,n,n,n
[... more comma-separated lines like above ...]

Where each of the letters above is a string value that the parser reads.

First, it takes all of the k and v elements and saves them as the keys and values in the returned dictionary.

Second, the h elements are returned them as the list of fieldnames.

Third, it reads the lines with n and stores them as namedtuples in the returned list.

values()

Gets the values from the initial portion of the hist output file.

kalasiris.PathSet module

This module contains the PathSet Class.

Working with ISIS can result in a lot of files to keep track of. The PathSet Class is simply a mutable set that only takes pathlib.Path objects. If you need to keep track of a bunch of files (typically to delete them after a set of processing calls), you can use a PathSet to keep track of them, and then delete them, like so:

import kalasiris as isis

to_delete = isis.PathSet()

input_p = Path('some.fits')
output_p = input_p.with_suffix('.done.cub')

isis_cub = to_delete.add(input_p.with_suffix('.cub'))
isis.lorri2isis(input_fits, to= isis_cub)

first = to_delete.add(input_p..with_suffix('.1.cub'))
isis.some_progeram(isis_cub, to=first)

second = to_delete.add(input_p..with_suffix('.2.cub'))
isis.some_program(first, to=second)

isis.final_step(second, to=output_p)

to_delete.unlink()

class kalasiris.PathSet.PathSet(iterable=None)

Bases: set

A class for containing a set of pathlib.Path objects.

add(elem) → Path

This variation on add() returns the element.

unlink()

Just runs Path.unlink() on all members.

kalasiris.cube module

These functions provide some mechanisms for dealing with ISIS cube files. These functions are not comprehensive, and only seek to provide functionality that does not exist elsewhere.

For example, there is already a GDAL driver for ISIS cubes, and access to the primary bands and such can already be accomplished via GDAL, and in order to get the image pixels as a numpy array:

import numpy as np
from osgeo import gdal_array

cube = 'some.cub'
img_arr = gdal_array.LoadFile(cube)

If you want to make sure to mask out all of the special pixels in the image you’ve read into img_arr above, you can do this:

import pvl
import kalasiris as isis

label = pvl.load(cube)
specialpix = getattr(isis.specialpixels,
                     label['IsisCube']['Core']['Pixels']['Type'])
masked_img_arr = np.ma.masked_outside(img_arr,
                                      specialpix.Min, specialpix.Max)

kalasiris.cube.encode_table(table: dict, fields: list) → bytes

Return a bytes object created from the table dict.

The table dict must contain lists of equal length as values. If they are not of equal length, an IndexError will be raised.

The fields list must be a list of dicts, each of which must contain the following keys: ‘Name’, ‘Type’, and ‘Size’. The ‘Name’ key can be any string, but must match the keys in the table dict. ‘Size’ is the size in bytes of the field, and ‘Type’ is a string that must be one of ‘Integer’, ‘Double’, ‘Real’, or ‘Text’.

If a field’s ‘Size’ value is more than 1, then the list which is the value of the table with that key name must be a list of length ‘Size’.

If you are using the pvl library, the overwrite_table() function will be easier to use.

kalasiris.cube.get_startsize_from(label=None, table_name=None, cube_path=None) → Tuple[int, int]

Returns a tuple of ints that represent the true start byte and size based on the provided label or combination of table_name and cube_path.

Either label or table_name and cube_path are needed. If neither a label nor a table_name is provided, then this function will raise a ValueError. If both are provided, label will take precedence and table_name will be ignored.

label is a dict which must contain a StartByte key and a Bytes key whose values can be converted to int (if not already). These values should be those in the cube file label for the table.

The name of the table as a string can be provided via table_name and the ISIS getkey function will be applied to the file at cube_path to extract the needed StartByte and Bytes values from the label. However, if there is more than one table in the cube, getkey can only find the first, and a ValueError might be returned.

If the pvl library is available, this function will use it to find all of the tables in the cube_path labels and will find the one named by table_name if it is present.

kalasiris.cube.get_table(cube_path: PathLike, table_name: str) → dict

Return a Python dictionary created from the named table in the ISIS cube.

This function requires the pvl Python library.

kalasiris.cube.overwrite_table(cube_path: PathLike, table_name: str, table: dict)

The file at cube_path will be modified by overwriting the data in the specfied table name with the contents of table.

The table dict must contain lists of equal length as values. If they are not of equal length, an IndexError will be raised. The table dict must also contain, as keys, all of the Field names from table_name in the cube_path.

This function requires the pvl Python library.

kalasiris.cube.overwrite_table_data(cube_path: PathLike, data: bytes, label=None, table_name=None)

The file at cube_path will be modified by overwriting the data in the specfied table name with the contents of data.

Either label or table_name is needed. If neither a label dict (which must contain a ‘Name’ key) nor a table_name is provided, then this function will raise a ValueError. If both are provided, label will take precedence and table_name will be ignored.

label is a dict which must contain Name, StartByte, and Bytes keys (StartByte and Bytes must be convertable to int if not already). These values will be used to locate where in the file to write the new data.

The name of the table as a string can be provided via table_name and the ISIS getkey function will be applied to extract the needed StartByte and Bytes values from the label. However, if there is more than one table in the cube, getkey can only find the first, and a ValueError might be returned, even thought there is a table of that name in the file.

If the pvl library is available, this function will use it to find all of the tables in the cube_path labels and will find the one named by table_name if it is present.

kalasiris.cube.parse_table(data: bytes, fields: list) → dict

Return a Python dictionary created from the bytes data of an ISIS cube table (presumably extracted via read_table_data()), and described by the fields list and records.

Please be aware that this does not perform masking of the ISIS special pixels that may be present in the table, and simply returns them as the appropriate int or float values.

The fields list must be a list of dicts, each of which must contain the following keys: ‘Name’, ‘Type’, and ‘Size’. The ‘Name’ key can be any string (and these will end up being the keys in the returned dict). ‘Size’ is the size in bytes of the field, and ‘Type’ is a string that must be one of ‘Integer’, ‘Double’, ‘Real’, or ‘Text’.

If you are using the pvl library, the get_table() function will be easier to use.

kalasiris.cube.read_table_data(cube_path: PathLike, label=None, table_name=None) → bytes

Returns a bytes object with the contents read from the file at cube_path based on the elements provided in the label or table_name.

Either label or table_name is needed. If neither a label nor a table_name is provided, then this function will raise a ValueError. If both are provided, label will take precedence and table_name will be ignored.

label is a dict which must contain a StartByte key and a Bytes key whose values can be converted to int (if not already). These values should be those in the cube file label for the table.

The name of the table as a string can be provided via table_name and the ISIS getkey function will be applied to extract the needed StartByte and Bytes values from the label. However, if there is more than one table in the cube, getkey can only find the first, and a ValueError might be returned.

If the pvl library is available, this function will use it to find all of the tables in the cube_path labels and will find the one named by table_name if it is present.

kalasiris.cubenormfile module

The ISIS cubenorm program outputs plain text table information and also reads it in, but the format is a very specific fixed-width table format. A plain csv.reader() or csv.DictReader() using the cubenormfile.Dialect object will be able to read the text output of cubenorm, but to write out a file that cubenorm will read in, you will need to use the cubenormfile.writer or cubenormfile.DictWriter classes.

class kalasiris.cubenormfile.Dialect

Bases: Dialect

A csv.Dialect for the output of the ISIS cubenorm program.

delimiter = ' '

lineterminator = '\n'

quoting = 3

skipinitialspace = True

class kalasiris.cubenormfile.DictWriter(f, restval='', extrasaction='raise', dialect=<class 'kalasiris.cubenormfile.Dialect'>, *args, **kwds)

Bases: DictWriter

A DictWriter for cubenorm files.

class kalasiris.cubenormfile.writer(f)

Bases: object

A class for writing out the fixed-width format required by cubenorm.

The interface is similar to the csv.writer class, but does not inherit from it.

writeheader()

A convenience function, since the fieldnames are pre-defined.

writerow(row)

writerows(rows)

kalasiris.fromlist module

Many ISIS programs require the creation of a fromlist file for input. These functions and classes provide convenient mechanisms for creating those files, or simply creating temporary versions.

kalasiris.fromlist.make(fromlist: list, pathlike=None) → Path

Creates a file with the fromlist elements one per line.

If pathlike is given, that will be the path used, otherwise create a temporary file and return its path.

You’re responsible for deleting it after you’re done.

You can use it like this:

fromlist_path = fromlist.make(['a.cub', 'b.cub', 'c.cub'])
isis.cubeit(fromlist=fromlist_path, to='stacked.cub')
fromlist_path.unlink()

However, using the fromlist.temp() context manager might be even more handy.

class kalasiris.fromlist.open_fl(fromlist: list, pathlike=None)

Bases: object

This is a context manager that works similarly to open(), but for creating fromlist files. Use it like this:

with fromlist.open_fl(['a.cub', 'b.cub', 'c.cub']) as f:
    isis.cubeit(fromlist=f.name, to='stacked.cub')

Its probably better to use fromlist.temp(), however.

This context manager is deprecated, and may be removed at the next major patch.

kalasiris.fromlist.print(fromlist: list, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Works like print(), but when given a list, will write out that list, one element per line.

This is the format that many ISIS programs which take a FROMLIST= parameter need.

Therefore, if you wanted to create a fromlist file, you could do:

with open('fromlist.txt', 'w') as f:
    fromlist.print(['a.cub', 'b.cub', 'c.cub'], file=f)

isis.cubeit(fromlist='fromlist.txt', to='stacked.cub')

However, it is more likely that you would use fromlist.make() or the fromlist.temp() context manager.

kalasiris.fromlist.print_fl(fromlist: list, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Synonym for fromlist.print()

This function is deprecated, and may be removed at the next major patch.

class kalasiris.fromlist.temp(fromlist: list)

Bases: object

This is a context manager that creates a temporary fromlist file and then gets rid of it for you. Use it like this:

with fromlist.temp(['a.cub', 'b.cub', 'c.cub']) as f:
    isis.cubeit(fromlist=f, to='stacked.cub')

The object that is bound to the as clause of the with statement is a pathlib.Path().

kalasiris.k_funcs module

Provides kalasiris _k functions.

The kalasiris _k functions provide some syntactic sugar to make calling the ISIS programs just that much easier. For example here are two ways to do the same thing:

import kalasiris as isis

cube_file = 'some.cub'

keyval = isis.getkey(cube_file, grpname='Instrument',
                 keyword='InstrumentId').stdout.strip()

k_keyval = isis.getkey_k(cube_file, 'Instrument', 'InstrumentId')

And the values of keyval and k_keyval are identical, its just that the _k function version is a little more compact. Each of the _k functions implements their modifications a little differently, so make sure to read their documentation.

kalasiris.k_funcs.cubeit_k(fromlist: list, **kwargs)

Takes a list of paths to cubes to operate cubeit on, rather than having the user create a text list.

kalasiris.k_funcs.getkey_k(cube: PathLike, group: str, key: str) → str

Simplified calling for getkey.

No default parameters are needed, and it directly returns a string.

kalasiris.k_funcs.hi2isis_k(*args, **kwargs)

Creates a default name for the to= cube.

If the FROM file has the name foo.img, then the output will be foo.cub.

kalasiris.k_funcs.hist_k(*args, **kwargs) → str

Returns the contents of the file created by ISIS hist as a string.

If there is a TO= parameter in the arguments, hist_k() will create the file, and return its contents as a string

kalasiris.k_funcs.stats_k(*args, **kwargs) → dict

Returns the result of running ISIS stats as a Python Dictionary.

If there are TO=, FORMAT=, or APPEND= parameters, stats_k will perform the file-based activities that stats normally would, and also return the Python Dictionary.

kalasiris.kalasiris module

Provides the ability to call ISIS functions.

kalasiris.kalasiris.param_fmt(key: str, value: str) → str

Returns a “key=value” string from the inputs.

This is the pattern that ISIS uses for arguments. If there are any trailing underbars (_) on the key, they will be stripped off. This supports the old pysis syntax to protect Python reserved words like from and min, while still allowing the user to provide ‘natural’ function calls like isis.stats(from_=cubefile).

Additionally, it also supports passing what ISIS calls reserved parameters for any ISIS program, denoted with a prefix of a single dash, like -restore=file or -verbose via keys with two trailing underbars. So to call spiceinit from= some.cub -restore=file you would do this:

cubefile = 'some.cub'
restore_file = 'some.par'
isis.spiceinit(cubefile, restore__=restore_file)

Likewise, to call getkey -help, or getkey -help=GRPNAME do this:

isis.getkey('help__')
isis.getkey(help__='GRPNAME')

Of course, you’ll probably want to do this:

help_text = isis.getkey(help__='').stdout

kalasiris.kalasiris.set_persistent_preferences(path: Path)

Sets a persistent preferences file for each ISIS command.

Using this function will cause the kalasiris library to include a “pref=path/to/pref/file” argument to each ISIS program you ask it to run. This is a convenience function such that if you always want to have ISIS programs that kalasiris runs given the same preferences file, you don’t have to manually provide it to each ISIS function that you call with kalasiris, you can just do it once for the program you are writing.

Giving None to this argument resets the library to the default of not adding a “pref=” argument.

A user can always specify a pref__=”path/to/pref/file” to any kalasiris ISIS function to manually insert a “pref=path/to/pref/file” argument for that call. If there is a persistent path set, then providing a pref__ argument will temporarily override this persistent setting for that call.

kalasiris.pysis module

Makes the ‘regular’ ISIS functions return what pysis did.

If you have old code that was built with pysis and is doing this:

from pysis import isis

value = isis.getkey(from_='W1467351325_4.map.cal.cub',
                    keyword='minimumringradius',
                    grp='mapping')

And you want to start using kalasiris, but don’t want to overhaul a bunch of code, you can just change the import line like so:

import kalasiris.pysis as isis

value = isis.getkey(from_='W1467351325_4.map.cal.cub',
                    keyword='minimumringradius',
                    grp='mapping')

And you should be good to go. Note that this works for calls to ISIS programs, but does not provide the pysis IsisPool functionality, nor any of the non-ISIS pysis functions or classes, like pysis.cubefile, pysis.specialpixels, etc.

exception kalasiris.pysis.IsisException

Bases: Exception

Base exception for pysis errors.

exception kalasiris.pysis.ProcessError(returncode, cmd, stdout, stderr)

Bases: IsisException

This exception is raised when an ISIS process returns a non-zero exit status.

kalasiris.specialpixels module

Constants for Isis Special Pixels.

The constants are provided as SpecialPixel :func:collection.namedtuple: objects, and have the following keys: Min, Null, Lrs, Lis, His, Hrs, and Max.

Null

A null pixel indicates no data was collected at the particular location.

Lis

A low instrument saturation pixel occurred meaning the instrument readout was at its lowest possible value.

His

A high instrument saturation pixel occurred meaning the instrument readout was at its highest possible value.

Lrs

A low representation saturation pixel occurred meaning a program computed a new pixel value at this location that was lower than native bit-type for the file (e.g., less than zero for an 8-bit file).

Hrs:

A high representation saturation pixel occurred meaning a program computed a new pixel value at this location that was greater than native bit-type for the file (e.g., greater than 255 for an 8-bit file).

The above definitions come from the Logical Cube Format Guide and the numerical values come from the ISIS SpecialPixel.h file.

In order to be able to know whether value should result in a Lrs or Hrs value, we must also know:

Min

The minimum valid value for a pixel.

Max

The maximum valid value for a pixel.

class kalasiris.specialpixels.SpecialPixels(Min, Null, Lrs, Lis, His, Hrs, Max)

Bases: tuple

His

Alias for field number 4

Hrs

Alias for field number 5

Lis

Alias for field number 3

Lrs

Alias for field number 2

Max

Alias for field number 6

Min

Alias for field number 0

Null

Alias for field number 1

kalasiris.sweetened module

Makes the ‘regular’ ISIS functions act like the _k functions.

If you prefer the simplified argument structure and behavior of the _k functions, but are constantly forgetting to put the _k on the end of your function names, this module is for you.

For example, here’s the ‘regular’ and _k function way of calling the ISIS getkey program:

import kalasiris as isis

cube_file = 'some.cub'

keyval = isis.getkey(cube_file, grpname='Instrument',
                     keyword='InstrumentId').stdout.strip()

k_keyval = isis.getkey_k(cube_file, 'Instrument', 'InstrumentId')

And the values of keyval and k_keyval are the same.

However, if you do this:

import kalasiris as isis

cube_file = 'some.cub'

key = isis.getkey(cube_file, 'Instrument', 'InstrumentId')

You’ll get this exception:

IndexError: only accepts 1 non-keyword argument to be from=

Because you tried to call isis.getkey() with the argument signature of isis.getkey_k() and then isis.getkey() couldn’t deal with it.

If you are always doing this, then instead of the above, do this:

import kalasiris.sweetened as isis

cube_file = 'some.cub'

key = isis.getkey(cube_file, 'Instrument', 'InstrumentId')

And now the ‘regularly’ named functions will work the way that you expect the _k function versions to act.

kalasiris.version module

These functions return information about the version of ISIS.

Most of the time, the only thing you’ll probably need is the version_info() function which returns an ISISversion tuple.

class kalasiris.version.ISISversion(major, minor, patch, releaselevel, date)

Bases: ISISversion

This is a custom collections.namedtuple() which can contain ISIS version information.

The first three elements, major, minor, and patch should be integers. The fourth element, releaselevel, should be the string ‘alpha’, ‘beta’, or ‘stable’ or None. And the fifth element, date, should be a datetime.date object or None. That’s what the functions in this module will return in an ISISversion collections.namedtuple().

kalasiris.version.get_from_file(file_path: PathLike) → ISISversion

Read an ISIS version file and parse the contents.

This should parse version files as far back as ISIS 3.5.2.0, but possibly earlier.

kalasiris.version.get_from_string(s: str) → ISISversion

Read text and parse the contents for ISIS version information.

This should parse ISIS version text as far back as ISIS 3.5.2.0, but possibly earlier. It will return None values for releaselevel and date if it cannot parse them. It will raise a ValueError if it cannot parse a version number.

kalasiris.version.version_info() → ISISversion

Returned collections.namedtuple() of ISIS version information for the ISIS system underlying kalasiris. If you want to answer, “What version of ISIS is being used?” This is the function you’re after. It is modeled after sys.version_info().

Module contents

Top-level package for kalasiris.