Metadata-Version: 2.0
Name: spe2py
Version: 2.0.0
Summary: This module imports a Princeton Instruments LightField (SPE 3.0) file into a python environment.
Home-page: https://github.com/ashirsch/spe2py
Author: Alex Hirsch (Zia Lab)
Author-email: alexander_hirsch@brown.edu
License: MIT
Description-Content-Type: text/markdown
Keywords: spectroscopy optics imaging data analysis
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: untangle

# spe2py

spe2py is a module that imports a Princeton Instruments LightField (SPE 3.x) file into a python environment. 

### Basic Usage
##### Modules
The `spe2py` module is designed for quick data loading, viewing, and exploration. It is most effective for quick access
to .spe files via a graphical file dialog, and incorporates tooling functionality to view images and plots with as
little typing as possible.

The `spe_loader` module is responsible for the pure .spe file loading functionality, and can (and should) be imported
separately when only lightweight, programmatic loading is necessary.

##### Loading and accessing data
Use the `load()` function to load one or more SPE files at a time into a set of tools:
```python
>>> import spe2py as spe
>>> spe_tools = spe.load()
```
A file selection window will open to allow browsing for source files. The result is an individual SpeTool object, or, in the case where multiple files are loaded at once, a list of SpeTool objects.

Alternatively programmatic loading should be done with with the `spe_loader` module:
```python
>>> import spe_loader as sl
>>> spe_files = sl.load_from_files(['path/to/file1', 'path/to/file2'])
```
The result is an individual SpeFile object, or, in the case where multiple files are loaded at once, a list of SpeFile objects.

Raw data from a file is stored in NumPy arrays and can be accessed directly by
```python
>>> frame_data = spe_tool.file.data[frame][regionOfInterest]
>>> frame_data = spe_tools[n].file.data[frame][regionOfInterest]  # where multiple files are loaded
```
or when using the pure loader module:
```python
>>> frame_data = spe_file.data[frame][regionOfInterest]
>>> frame_data = spe_files[n].data[frame][regionOfInterest]  # where multiple files are loaded
```

##### Automatic imaging and plotting (spe2py tools only)
To quickly view an individual frame, region-of-interest, or spectrum, use the `image()` or `specplot()` methods. For example,
```python
>>> spe_tool.image()  # images the first frame and region of interest
>>> spe_tool.image(f, r)  # images frame 'f' and region of interest 'r'
>>> spe_tool.specplot()  # plots the loaded spectrum
```

##### Accessing metadata
Upon loading, the metadata contained in the file's XML footer is automatically parsed and stored as an `untangle` object in the `footer` variable. Elements and attributes can be accessed by calling the different elements and subelements of footer, ending with the attribute as a string:
```python
>>> sensor_height = loaded_file.footer.SpeFormat.Calibrations.SensorInformation['height']
```
One can print the full element tree by calling the `xmltree()` method.

### Dependencies
  - NumPy - data storage and file reading
  - [untangle](https://github.com/stchris/untangle) - XML parsing
  - tkinter - file selection dialog (spe2py tools only)
  - matplotlib - imaging and plotting (spe2py tools only)

### Version
2.0.0 - Separation of Tooling and Loading functionality


License
----

MIT



