Skip to content

Commit

Permalink
update documetation
Browse files Browse the repository at this point in the history
  • Loading branch information
@joshduran
joshduran committed Jun 5, 2024
1 parent fd301d5 commit 69c3051
Show file tree
Hide file tree
Showing 15 changed files with 5,551 additions and 3,421 deletions.
3 changes: 2 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@ __pycache__/

dist/
*.egg-info/
test/files/
test/files/
test/temp.py
9 changes: 6 additions & 3 deletions brukeropus/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,21 @@
### Namespace
`brukeropus` provides direct imports to the following:
```python
from brukeropus import find_opus_files, read_opus, OPUSFile, Opus
from brukeropus import find_opus_files, read_opus, OPUSFile, Opus, parse_file_and_print
```
All other file functions or classes can be directly imported from the `brukeropus.file` or `brukeropus.control`
submodules, e.g.:
```python
from brukeropus.file import parse_file_and_print
from brukeropus.file import parse_header
```
It is recommended that you do **not** import from the fully qualified namespace, e.g.:
```python
from brukeropus.file.utils import parse_file_and_print
from brukeropus.file.parse import parse_header
```
as that namespace is subject to change. Instead import directly from `brukeropus` or its first level submodules.
### Reading OPUS Files (Basic Usage)
`brukeropus` can read the proprietary binary files saved by Bruker's OPUS software.
```python
from brukeropus import read_opus
from matplotlib import pyplot as plt
Expand All @@ -42,6 +43,8 @@
More detailed documentation on the file submodule can be found in `brukeropus.file`
### Controlling OPUS Software (Basic Usage)
`brukeropus` can also control/communicate directly with OPUS over the DDE communication protocol. For this to work,
you must be on Windows and OPUS must be open and logged in.
```python
from brukeropus import opus, read_opus
from matplotlib import pyplot as plt
Expand Down
106 changes: 61 additions & 45 deletions brukeropus/file/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
In the above code, `data` and `same_data` are both `OPUSFile` objects with identical data.
## Using the `OPUSFile` Class
OPUS files all start with the same first four *magic bytes*. If the file does not start with these bytes (i.e. is not
a valid OPUS file), the OPUSFile class will logically evaluate to `false`:
a valid OPUS file), the `OPUSFile` class will logically evaluate to `false`:
```python
data = read_opus('file.pdf')
if data:
Expand All @@ -51,6 +51,9 @@
<p>
```console
====================================================================================================
Sample/Result Parameters (params)
....................................................................................................
Optical Parameters
Key Label Value
ACC Accessory TRANS *010A984F
Expand All @@ -70,7 +73,7 @@
ADC External Analog Signals 0
SON External Sync Off
====================================================================================================
....................................................................................................
Fourier Transform Parameters
Key Label Value
APF Apodization Function B3
Expand All @@ -82,7 +85,7 @@
SPZ Stored Phase Mode NO
ZFF Zero Filling Factor 2
====================================================================================================
....................................................................................................
Acquisition Parameters
Key Label Value
ADT Additional Data Treatment 0
Expand All @@ -101,7 +104,7 @@
TDL To Do List 16777271
SGN Sample Signal Gain 1
====================================================================================================
....................................................................................................
Sample Origin Parameters
Key Label Value
BLD Building
Expand All @@ -117,7 +120,7 @@
CPG Character Encoding Code Page 1252
UID Universally Unique Identifier 0d1348c2-3a2c-41c9-b521-bdaf0a23710c
====================================================================================================
....................................................................................................
Instrument Status Parameters
Key Label Value
HFL High Folding Limit 15795.820598
Expand Down Expand Up @@ -161,6 +164,9 @@
RDY Ready Check 1
====================================================================================================
Reference Parameters (rf_params)
....................................................................................................
Reference Instrument Status Parameters
Key Label Value
HFL High Folding Limit 15795.820598
Expand Down Expand Up @@ -204,7 +210,7 @@
RDY Ready Check 1
ARS Number of Reference Scans 1
====================================================================================================
....................................................................................................
Reference Optical Parameters
Key Label Value
ACC Accessory TRANS *010A984F
Expand All @@ -224,7 +230,7 @@
ADC External Analog Signals 0
SON External Sync Off
====================================================================================================
....................................................................................................
Reference Acquisition Parameters
Key Label Value
ADT Additional Data Treatment 0
Expand All @@ -243,7 +249,7 @@
TCL Command Line for Additional Data Tr...
TDL To Do List 16777271
====================================================================================================
....................................................................................................
Reference Fourier Transform Parameters
Key Label Value
APF Apodization Function B3
Expand All @@ -257,34 +263,38 @@
```
</p>
</details>
You can access a specific parameter simply by calling the key as a direct attribute of the class (case insensitive). You
can also get the human-readable label using the `get_param_label` function:
You can access the sample parameters through the `OPUSFile.params` attribute, or as a direct attribute for shorthand
(e.g. `OPUSFile.params.apt` or `OPUSFile.apt`). The parameter keys are also case insensitive (e.g. `OPUSFile.bms` or
`OPUSFile.BMS`).
OPUS files can also contain parameter information about the associated reference (aka background) measurement. These
parameters are only accessible through the `OPUSFile.rf_params` attribute to avoid namespace collisions (e.g.
`OPUSFile.rf_params.apt`).
```python
from brukeropus.file import get_param_label
data = read_opus('file.0')
print(get_param_label('bms') + ':', data.bms)
print(get_param_label('src') + ':', data.src)
print('Sample ZFF:', data.zff, 'Reference ZFF:', data.rf_params.zff)
```
```console
Beamsplitter: KBr-Broadband
Source: MIR
Sample ZFF: 2 Reference ZFF: 2
```
You will notice in the example output that some keys (e.g. zero filling factor `zff`) may have two entries: one for the
sample measurement and another for the reference. By default, the sample parameters are accessible directly from the
`OPUSFile` class, while the reference parameters can be accessed through the `rf_params` attribute.
You can also get the human-readable label for a parameter key using the `get_param_label` function:
```python
from brukeropus.file import get_param_label
data = read_opus('file.0')
print('Sample ZFF:', data.zff, 'Reference ZFF:', data.rf_params.zff)
print(get_param_label('bms') + ':', data.bms)
print(get_param_label('src') + ':', data.src)
```
```console
Sample ZFF: 2 Reference ZFF: 2
Beamsplitter: KBr-Broadband
Source: MIR
```
You can also iterate over the parameters using the familiar `keys()`, `values()`, and `items()` functions using the
`params` or `rf_params` attributes:
`params` or `rf_params` attributes (just like a dictionary):
```python
data = read_opus('file.0')
Expand All @@ -307,36 +317,22 @@
```
Depending on the settings used to save the OPUS file, different data blocks can be stored. To retrieve a list of data
blocks stored in the OPUS File, use the `data_keys` attribute:
blocks stored in the OPUS File, you can use the `all_data_keys` attribute:
```python
data = read_opus('file.0')
print(data.data_keys)
print(data.all_data_keys)
```
```console
['igsm', 'phsm', 'sm', 'a', 'igrf', 'rf']
```
Each key is also an attribute of the `OPUSFile` instance that returns either a `Data` or `Data3D` class. You can get
the `x` and `y` array values (in the units they were saved in) as direct attributes to the `Data` class:
Each key is also an attribute of the `OPUSFile` instance that returns either a `Data` (single spectra) or `DataSeries`
(series of spectra) class. You can use the `data_keys` attribute to retrieve a list of only the single-spectra `Data`
keys in the class, or the `series_keys` attribute to retrieve a list of only the `DataSeries` keys.
```python
data = read_opus('file.0')
plt.plot(data.a.x, data.a.y)
plt.ylim((0, 1))
plt.show()
```
For spectra with wavenumber as valid unit (e.g. single-channel or ratioed spectra), the `x` array can be given in `cm⁻¹`
or `µm` units by using the attributes `wn` or `wl` respectively:
```python
data = read_opus('file.0')
plt.plot(data.sm.wl, data.sm.y)
plt.show()
```
You can also iterate over all data spectra in the file using the `iter_data()` method:
You can also iterate over these data keys using the `iter_all_data()`, `iter_data()` and `iter_series()` class
methods:
```python
data = read_opus('file.0')
Expand All @@ -352,9 +348,28 @@
Reference Spectrum (2019-05-03 13:31:22.358000)
```
You can access the `x` and `y` arrays of a `Data` or `DataSeries` class:
```python
data = read_opus('file.0')
plt.plot(data.a.x, data.a.y) # Plot absorbance
plt.ylim((0, 1))
plt.show()
```
For spectra with wavenumber as valid unit (e.g. single-channel or ratioed spectra), the `x` array can be given in
wavenumber [`cm⁻¹`] or wavelength [`µm`] or modulation frequency [`Hz`] units by using the attributes `wn`, `wl`, or `f`
respectively:
```python
data = read_opus('file.0')
plt.plot(data.sm.wl, data.sm.y)
plt.show()
```
Each data block in an OPUS file also contains a small parameter block with information such as the min/max y-value
(mny, mxy), x-units (dxu), number of data points (npt), etc. These can be accessed as direct attributes to the `Data`
class, or through the `params` attribute:
class, or through the `Data.params` attribute:
```python
data = read_opus('file.0')
Expand All @@ -366,10 +381,11 @@
For full API documentation, see:
`OPUSFile`: `brukeropus.file.file.OPUSFile`
`Data`: `brukeropus.file.file.Data`
`Data3D`: `brukeropus.file.file.Data3D`
`DataSeries`: `brukeropus.file.file.DataSeries`
'''
from brukeropus.file.file import *
from brukeropus.file.block import *
from brukeropus.file.parse import *
from brukeropus.file.labels import *
from brukeropus.file.utils import *
from brukeropus.file.constants import *
12 changes: 10 additions & 2 deletions brukeropus/file/file.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@
'''
The `OPUSFile` class attempts to abstract away some of the complexity and rigid organization structure of Bruker's OPUS
files while providing full access to the data contained in them. This way, the user does not have to memorize the
organization structure of an OPUS file to access the information.
organization structure of an OPUS file (e.g. which parameter block contains the beamsplitter parameter) to access the
information.
'''

class OPUSFile:
Expand All @@ -22,7 +23,8 @@ class OPUSFile:
an `OPUSFile` object.
Attributes:
is_opus: True if filepath points to an OPUS file, False otherwise. Also returned for dunder `__bool__()`
is_opus: True if filepath points to an OPUS file, False otherwise. Also returned for dunder `__bool__()`
filepath: full path pointing to the OPUS file
params: class containing all general parameter metadata for the OPUS file. To save typing, the
three char parameters from params also become attributes of the `OPUSFile` class (e.g. bms, apt, src)
rf_params: class containing all reference parameter metadata for the OPUS file
Expand All @@ -34,6 +36,8 @@ class OPUSFile:
datetime: Returns the most recent datetime of all the data blocks stored in the file (typically result spectra)
directory: `FileDirectory` class containing information about all the various data blocks in the file.
history: History (file-log) containing text about how the file was generated/edited (not always saved)
unmatched_data_blocks: list of data `FileBlock` that were not uniquely matched to a data status block
unmatched_data_status_blocks: list of data status `FileBlock` that were not uniquely matched to a data block
unknown_blocks: list of `FileBlock` that were not parsed and/or assigned to attributes into the class
Data Attributes:
Expand Down Expand Up @@ -73,6 +77,10 @@ def __getattr__(self, name):
return self.directory.blocks

def __init__(self, filepath):
'''Note: a list of `FileBlock` is initially loaded and parsed using the `FileDirectory` class. This list is
located in `OPUSFile.directory.blocks`. After parsing all the file blocks (performed by the `FileBlock` class),
data from those blocks are saved to various attributes within the `OPUSFile` class. Subsequently, the block is
removed from `OPUSFile.directory.blocks` to eliminate redundant data and reduce memory footprint.'''
self.filepath = filepath
self.is_opus = False
self.data_keys = []
Expand Down
Loading

0 comments on commit 69c3051

Please sign in to comment.