pyImagingMSpec

https://pyimagingmspec.readthedocs.io/en/latest/
Admin
pyImagingMSpec is a Python library designed for processing imaging mass spectrometry data, offering...
Tokens:24,662
Snippets:131
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install pyImagingMSpec with pip

Source: https://pyimagingmspec.readthedocs.io/en/latest/README.html

Install the pyImagingMSpec library from the current branch using pip. Ensure you have the listed dependencies installed first.

```bash
sudo pip install pyImagingMSpec

```

--------------------------------

### Initialize and Load SL File

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Instantiates the slFile class and loads data from an HDF5 SL file. Requires the input filename and optionally a region name. Ensure the HDF5 LZ4 plugin is installed and the HDF5_PLUGIN_PATH environment variable is set if using LZ4 compressed files.

```python
import h5py
import sys
import numpy as np

class slFile():
    def __init__(self, input_filename, region_name=""):
        self.region_name = region_name
        self.load_file(input_filename)

    def _check_file_version(self):
        self.file_version = self.sl['Version'][0]
        print 'sl file version: {}'.format(self.file_version)
        if not self.file_version in range(16, 23):
            raise ValueError('File version {} out of range.'.format(self.file_version))

    def _get_spotlist(self):
        ### get root groups from input data
        if self.region_name == "":
            self.spotlist = range(self.sl['SpectraGroups']['InitialMeasurement']['images'].shape[1])
        else:
            print self.region_name
            region_name = self.sl['Regions'].visit(self.find_name)
            if region_name == None:
                raise ValueError("Requested region {} not found".format(self.region_name))
            self.spotlist = self.sl['Regions'][region_name]['SpotList']
        self.spotlist = np.asarray(self.spotlist)

    def _get_spectragroup(self):
        self.initialMeasurement = self.sl['SpectraGroups']['InitialMeasurement']
        self.Mzs = np.asarray(self.initialMeasurement['SamplePositions'][
                              'SamplePositions'])  # we don't write this but will use it for peak detection
        self.spectra = self.initialMeasurement['spectra']

    def _get_coordinates(self):
        ### Get Coordinates for spotlist
        self.coords = np.asarray(self.sl['Registrations']['0']['Coordinates'])
        if np.shape(self.coords)[0] != 3:
            self.coords = self.coords.T
        if np.shape(self.coords)[0] != 3:
            raise ValueError('coords second dimension should be 3 {}'.format(np.shape(self.coords)))


    def load_file(self, input_filename):
        # get a handle on the file
        self.sl = h5py.File(input_filename, 'r')  # Readonly, file must exist
        self._check_file_version()
        self._get_spotlist()
        self._get_spectragroup()
        self._get_coordinates()

```

--------------------------------

### Get Spectrum Data

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Retrieves intensity data for a specific spectrum from the loaded SL file. Returns the m/z values and corresponding intensities.

```python
def get_spectrum(self, index):
    intensities = np.asarray(self.spectra[index, :])
    return self.Mzs, intensities
```

--------------------------------

### SL File: Get Spectrum

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Retrieves a spectrum from an SL file object by its index.

```python
get_spectrum(index)
```

--------------------------------

### Get Peak Indices in Bin

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Identifies the indices of m/z values that fall within a specified lower and upper bound. Useful for selecting relevant peaks for further processing.

```python
import numpy as np
from pyImagingMSpec.utils import find_nearest


[docs]def get_peak_in_bin_idx(mzs, edge_lower, edge_upper):
    mz_count = np.arange(np.searchsorted(mzs, edge_lower), np.searchsorted(mzs, edge_upper, side='right'), dtype=int)
    return mz_count
```

--------------------------------

### Initialize ion_datacube

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Initializes an ion_datacube object. It sets up attributes for storing XICs, coordinates, and metadata. The step_size parameter can be provided or will be estimated.

```python
import numpy as np



[docs]class ion_datacube():
    # a class for holding a datacube from an MSI dataset and producing ion images
    def __init__(self, step_size=[]):
        # define mandatory parameters (todo- validator to check all present)
        self.xic = []  # 'xtracted ion chromatogram (2d array of intensities(vector of time by mzs))
        self.bounding_box = []  # tuple (x,y,w,h) in co-ordinate space
        self.coords = []  # co-ordiantes of every pixel
        self.mzs = []  # centroids of each xic vector
        self.tol = []  # tolerance window around centroids in m/z
        if step_size == []:
            self.step_size = []
        else:
            self.step_size = step_size
        self.n_im = 0
```

--------------------------------

### Command-line Interface for Centroid ImzML Conversion

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Provides a basic command-line interface to run the `centroid_imzml` function, taking an input SL file and generating an output imzML file.

```python
import sys

if __name__ == '__main__':
    centroid_imzml(sys.argv[1], sys.argv[1][:-3] + ".imzML")
```

--------------------------------

### pyImagingMSpec.convert.sl.slFile

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Represents an SL file for reading IMS data.

```APIDOC
## slFile

### Description
Class to represent and read data from an SL file.

### Methods
- **find_name(name)**: Finds an item by name within the SL file.
- **get_spectrum(index)**: Retrieves a spectrum by its index.
- **load_file(input_filename)**: Loads the specified SL file.
```

--------------------------------

### Convert XIC to Image and Process

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Converts an XIC to an image, crops it, and applies padding. This is useful for preparing image data for further processing.

```python
img = self.xic_to_image(xic_index)
img=np.asarray(img)
img = img[crop_total_pixels[0][0]:crop_total_pixels[0][1], crop_total_pixels[1][0]:crop_total_pixels[1][1]]
img = np.pad(img, ((pad_total_pixels[0][0], pad_total_pixels[0][1]), (pad_total_pixels[1][0], pad_total_pixels[1][1])), 'constant', constant_values=-1)
return img
```

--------------------------------

### Write Spectra to imzML with PyMSpec

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Writes spectra from an SL file to an imzML file. Supports apodization and gradient processing of spectra. Requires `ImzMLWriter` from `pyimagingmspec.writer` and `smoothing.apodization` from `pyMSpec`.

```python
from pyimagingmspec.writer import ImzMLWriter
from pyMSpec import smoothing

# ... (previous code for slFile, coords, gradient, etc.)

with ImzMLWriter(output_filename, mz_dtype=mz_dtype, intensity_dtype=int_dtype) as imzml:
    done = 0
    for key in sl.spotlist:
        if all((prevent_duplicate_pixels, key not in coord_idx)):# skip duplicate pixels
            #print 'skip {}'.format(key)
            continue
        mzs, intensities = sl.get_spectrum(key)
        if apodization:
            # todo - add to processing list in imzml
            mzs, intensities = smoothing.apodization(mzs, intensities)
        mzs_c, intensities_c, _ = gradient(mzs, intensities, weighted_bins=5, min_intensity=min_intensity)
        pos = coords[key]
        pos = (pos[0], nrow - 1 - pos[1], pos[2])
        imzml.addSpectrum(mzs_c, intensities_c, pos)
        done += 1
        if done % 1000 == 0:
            print "[%s] progress: %.1f%%" % (input_filename, float(done) * 100.0 / n_total)
    print "finished!"
```

--------------------------------

### SL File Class Initialization

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Initializes an slFile object to read and process data from a SL file. Can specify a region name for targeted processing.

```python
slFile(input_filename, region_name='')
```

--------------------------------

### get_edges

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Generates m/z bin edges based on spectral data, considering maximum width and peak counts.

```APIDOC
## get_edges

### Description
Generates m/z bin edges based on spectral data, considering maximum width and peak counts. It identifies potential bin boundaries and refines them to ensure no bin exceeds a maximum width and to manage the number of peaks within bins.

### Parameters
- **mzs** (array-like) - An array of mass-to-charge ratios.
- **specix** (array-like) - An array of spectrum indices corresponding to each m/z value.
- **max_width** (float, optional) - The maximum allowed width for any m/z bin. Defaults to 0.1.
- **max_ups** (int, optional) - The maximum number of peaks allowed within a bin. Defaults to 1.

### Returns
- **edges** (numpy.ndarray) - A sorted array of unique m/z bin edges.
```

--------------------------------

### Generate Mz Axis from ImzML Data

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Creates a representative m/z axis from an imzML file. It extracts spectra, determines bin edges, and calculates the average m/z and ppm for each bin.

```python
[docs]def generate_mz_axis_from_imzml(imzml, step_size=100):
    spec = get_some_real_spectra(imzml, step_size)
    edges = get_edges(spec[0], spec[2])
    mz_axis = []
    for ii in range(1, len(edges)):
        mz = np.mean(spec[0][get_peak_in_bin_idx(spec[0], edges[ii-1], edges[ii])])
        if np.isnan(mz):
            mz =  np.mean([edges[ii-1], edges[ii]])
        ppm = 0.5 * 1e6 * (edges[ii] - edges[ii-1]) / mz
        mz_axis.append((float(mz), float(ppm)))
    return mz_axis
```

--------------------------------

### slFile Class

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Handles the loading and parsing of SL files, providing access to spectral data and metadata.

```APIDOC
## Class: slFile

### Description
This class is designed to read and process data from SL files, which are HDF5-based files commonly used in mass spectrometry imaging. It handles file loading, version checking, and extraction of spectral data, coordinates, and spot lists.

### Methods

#### `__init__(self, input_filename, region_name="")`
Initializes the `slFile` object by loading the specified SL file and processing its contents.

- **input_filename** (str) - The path to the SL file to be loaded.
- **region_name** (str, optional) - The name of the region to process within the file. Defaults to "" (all regions).

#### `load_file(self, input_filename)`
Loads the SL file specified by `input_filename` and performs initial data processing.

- **input_filename** (str) - The path to the SL file.

#### `get_spectrum(self, index)`
Retrieves a single spectrum from the loaded SL file.

- **index** (int) - The index of the spectrum to retrieve.

**Returns:**
- **Mzs** (numpy.ndarray) - An array of mass-to-charge ratios for the spectrum.
- **intensities** (numpy.ndarray) - An array of intensity values for the spectrum.
```

--------------------------------

### ion_datacube Class Methods

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.html

Documentation for the methods available in the ion_datacube class, used for handling ion image data.

```APIDOC
## Class: ion_datacube

### Description
Represents an ion datacube, a data structure for storing and processing ion image data.

### Methods

#### `add_coords(coords)`

Adds coordinates to the ion datacube.

#### `add_xic(xic, mz, tol)`

Adds a cross-section (XIC) to the ion datacube.

- **xic** (numpy array) - The XIC data.
- **mz** (float) - The m/z value.
- **tol** (float) - The tolerance for the m/z value.

#### `apply_image_processing(smooth_method, **smooth_params)`

Applies pre-defined image processing methods to the ion datacube.

- **smooth_method** (string) - The image processing method to apply.
- **smooth_params** (dict) - Parameters for the smoothing method.

Returns: The ion datacube is updated in place. None returned.

#### `calculate_bounding_box()`

Calculates the bounding box of the ion datacube.

#### `coord_to_index(transform_type='reg_grid', params=())`

Converts coordinates to indices.

- **transform_type** (string) - The type of transformation ('reg_grid' by default).
- **params** (tuple) - Parameters for the transformation.

#### `image_to_xic(im)`

Converts an image to a vector suitable for insertion into the datacube.

- **im** (numpy 2d array) - The input image.

Returns: A numpy vector.

#### `remove_xic(mz)`

Removes a cross-section (XIC) from the ion datacube.

- **mz** (float) - The m/z value of the XIC to remove.

#### `xic_to_image(xic_index, padval=-1)`

Converts a cross-section (XIC) to an image.

- **xic_index** (int) - The index of the XIC to convert.
- **padval** (int) - The padding value (-1 by default).

#### `xic_to_image_fixed_size(xic_index, out_im_size)`

Returns an XIC formatted as an image of a pre-specified size, cropping or padding equally around the image as required.

- **xic_index** (int) - Index of the XIC to turn into an image.
- **out_im_size** (tuple) - Desired image size.

Returns: An image (numpy array).
```

--------------------------------

### Convert XIC to Image

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Converts a specified XIC into a 2D image. It initializes an image with a padding value and then populates it with XIC intensities at the calculated pixel indices.

```python
[docs]
    def xic_to_image(self, xic_index, padval=-1):
        xic = self.xic[xic_index].copy()
        # turn xic into an image
        img = padval + np.zeros(self.nRows * self.nColumns)
        img[self.pixel_indices] = xic
        img = np.reshape(img, (self.nRows, self.nColumns))
        return img
```

--------------------------------

### pyImagingMSpec.rebinning Module Functions

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.html

Documentation for functions within the pyImagingMSpec.rebinning module, used for data rebinning and peak detection.

```APIDOC
## Module: pyImagingMSpec.rebinning

### Functions

#### `assign_edges(core_value, core_class, edge, eps, inst)`

Assigns edges based on core values and classes.

#### `db_scan_1d_centroids(x, y, min_samples, eps, inst)`

Performs 1D DBSCAN on centroids.

#### `findNearestPeakIndex(mzs, mz)`

Finds the index of the nearest peak in a list of m/z values.

- **mzs** (list) - List of m/z values.
- **mz** (float) - The target m/z value.

Returns: Index of the nearest peak.

#### `generate_mz_axis_from_imzml(imzml, step_size=100)`

Generates an m/z axis from an imzML file.

- **imzml** (object) - The imzML object.
- **step_size** (int) - The step size for the m/z axis (100 by default).

#### `generate_mz_bin_edges(imsDataset, n_spectra=100, max_width=0.1, max_ups=1, max_spec=1)`

Generates m/z bin edges from an IMS dataset.

#### `get_core(x, min_samples, eps, inst)`

Gets the core of a dataset based on m/z values.

- **x** (list) - List of m/z values (sorted).
- **min_samples** (int) - Minimum number of samples.
- **eps** (float) - The epsilon value for clustering.
- **inst** (object) - An instance object.

#### `get_core_centroids(x, y, min_samples, eps, inst)`

Gets the core centroids from m/z and intensity data.

- **x** (list) - List of m/z values (sorted).
- **y** (list) - List of intensity values.
- **min_samples** (int) - Minimum number of samples.
- **eps** (float) - The epsilon value for clustering.
- **inst** (object) - An instance object.

#### `get_edges(mzs, specix, max_width=0.1, max_ups=1)`

Gets bin edges from m/z values and spectrum indices.

#### `get_edges_rl(mzs, specix, max_width=0.1, max_ups=1, max_spec=1)`

Gets bin edges using a specific method (likely related to real spectra).

#### `get_peak_in_bin_idx(mzs, edge_lower, edge_upper)`

Gets the index of a peak within specified bin edges.

#### `get_some_real_spectra(imsDataset, n)`

Retrieves a specified number of real spectra from an IMS dataset.

#### `nn_aggreagation(mzs, specix, max_width)`

Performs nearest neighbor aggregation on m/z values and spectrum indices.

#### `peaks_from_spectra(mzs, specix, edge_lower, edge_upper)`

Extracts peaks from spectra within specified bin edges.

#### `scaled_dist(inst, mzs, mz)`

Calculates a scaled distance.

- **inst** (object) - An instance object.
- **mzs** (list) - List of m/z values.
- **mz** (float) - The target m/z value.
```

--------------------------------

### Command-line Interface for Centroid Conversion

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/imzml.html

Parses command-line arguments for input and output filenames to run the `centroid_imzml` function. Use this script to convert imzML files from the terminal.

```python
if __name__ == '__main__':
    parser = argparse.ArgumentParser(description="convert centroids from profile imzml to centroided imzML")
    parser.add_argument('input', type=str, help="input imzml file")
    parser.add_argument('output', type=str, help="output filename (centroided imzml)")
    args = parser.parse_args()
    centroid_imzml(args.input, args.output)
```

--------------------------------

### Convert XIC to Fixed Size Image

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Converts an XIC into an image of a specified output size. This method calculates necessary padding or cropping to achieve the desired dimensions, ensuring the image is centered.

```python
[docs]
    def xic_to_image_fixed_size(self, xic_index, out_im_size):
        """
        returns an xic formatted as an image. This function returns an image of a pre-specfied size, cropping or padding equally around the image as required.
        :param xic_index: index of the xic to turn into an image
        :param out_im_size: desired image size
        :return:
        """
        def calc_pad(px1, px2):
            delta = px1-px2
            if delta < 0:
                return 0, 0
            return delta/2, delta/2+delta%2

        def calc_crop(px1, px2):
            delta = px1 - px2
            if delta > 0:
                return 0, -1
            delta = abs(delta)
            return delta/2, -1*delta/2+delta%2

        pad_total_pixels = map(calc_pad, out_im_size, (self.nRows, self.nColumns))
        crop_total_pixels = map(calc_crop, out_im_size, (self.nRows, self.nColumns))
```

--------------------------------

### log

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/smoothing.html

Applies a natural logarithm transformation to the image data.

```APIDOC
## log(im)

### Description
Applies a natural logarithm transformation to the input image data.

### Parameters
- **im** (array-like) - The input image data.
```

--------------------------------

### SL File: Load File

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Loads an SL file into the slFile object for processing.

```python
load_file(input_filename)
```

--------------------------------

### get_edges_rl

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Generates m/z bin edges based on spectral data, considering maximum width, peak counts, and spectrum limits.

```APIDOC
## get_edges_rl

### Description
Generates m/z bin edges based on spectral data, considering maximum width, peak counts, and spectrum limits. This function is similar to `get_edges` but includes an additional parameter `max_spec` to limit the number of spectra contributing to peak counts.

### Parameters
- **mzs** (array-like) - An array of mass-to-charge ratios.
- **specix** (array-like) - An array of spectrum indices corresponding to each m/z value.
- **max_width** (float, optional) - The maximum allowed width for any m/z bin. Defaults to 0.1.
- **max_ups** (int, optional) - The maximum number of peaks allowed within a bin. Defaults to 1.
- **max_spec** (int, optional) - The maximum number of spectra to consider for peak counting. Defaults to 1.

### Returns
- **edges** (numpy.ndarray) - A sorted array of unique m/z bin edges.
```

--------------------------------

### Generate Mz Bin Edges from Dataset

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Generates m/z bin edges for an imsDataset by first extracting a subset of spectra and then applying the `get_edges_rl` function.

```python
[docs]def generate_mz_bin_edges(imsDataset, n_spectra=100, max_width = 0.1, max_ups=1, max_spec=1):
    spec = get_some_real_spectra(imsDataset, n_spectra)
    edges = get_edges_rl(spec[0], spec[2], max_width=max_width, max_ups=max_ups, max_spec=max_spec)
    return edges
```

--------------------------------

### generate_mz_bin_edges

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Generates m/z bin edges from an imsDataset object by sampling spectra and applying rebinning logic.

```APIDOC
## generate_mz_bin_edges

### Description
Generates m/z bin edges from an imsDataset object by sampling a specified number of spectra and then using the `get_edges_rl` function to determine the bin boundaries.

### Parameters
- **imsDataset** (object) - An object of type `imsDataset` or any class with a `get_spectrum` method.
- **n_spectra** (int, optional) - The number of spectra to sample for generating bin edges. Defaults to 100.
- **max_width** (float, optional) - The maximum allowed width for any m/z bin. Defaults to 0.1.
- **max_ups** (int, optional) - The maximum number of peaks allowed within a bin. Defaults to 1.
- **max_spec** (int, optional) - The maximum number of spectra to consider for peak counting. Defaults to 1.

### Returns
- **edges** (numpy.ndarray) - A sorted array of unique m/z bin edges.
```

--------------------------------

### generate_mz_axis_from_imzml

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Creates an m/z axis with associated mass accuracy (PPM) from an imzML file.

```APIDOC
## generate_mz_axis_from_imzml

### Description
Creates an m/z axis with associated mass accuracy (PPM) from an imzML file. It samples spectra, determines bin edges using `get_edges`, and then calculates the mean m/z and PPM for each bin.

### Parameters
- **imzml** (object) - An imzML object (or compatible object with `get_spectrum` method).
- **step_size** (int, optional) - The number of spectra to sample for analysis. Defaults to 100.

### Returns
- **mz_axis** (list) - A list of tuples, where each tuple contains the mean m/z and its corresponding PPM value for a bin.
```

--------------------------------

### Generate Bin Edges with Real Limits

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Generates bin edges for mass spectrometry data, considering real limits and constraints on peak counts and spectrum size. This function is useful for creating bins that accurately represent spectral features.

```python
[docs]def get_edges_rl(mzs, specix, max_width=0.1, max_ups=1, max_spec=1):
    bin_edges_rl = [mzs[0],mzs[1]]
    this_bin_mzs = []
    for mz in mzs[1:]:
        ups = peaks_from_spectra(mzs, specix, bin_edges_rl[-1], mz)
        n_exceed = np.sum(ups>max_ups)
        if n_exceed > max_spec:
            bin_edges_rl.append(this_bin_mzs[0])
            bin_edges_rl.append(this_bin_mzs[-1])
            this_bin_mzs = []
        this_bin_mzs.append(mz)
    edges = np.unique(bin_edges_rl)
    delta_edges = np.diff(edges)
    extra_edges = []
    for ii, delta in enumerate(delta_edges):
        if delta >= max_width:
            extra_edges.extend(np.linspace(edges[ii], edges[ii+1], int(delta/max_width))[1:-1])
    edges = np.unique(np.concatenate([edges, np.asarray(extra_edges)]))
    return edges
```

--------------------------------

### Convert HDF5 to IMS format

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Converts data from an HDF5 file to an Imaging Mass Spectrometry (IMS) format. Requires specifying input and output filenames.

```python
pyImagingMSpec.convert.hdf5.hdf5_centroids_IMS(input_filename, output_filename)
```

--------------------------------

### Smooth Spectrum using pyMS

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/hdf5.html

Applies smoothing to a spectrum using either Savitzky-Golay filter ('sg_smooth') or apodization ('apodization') via the pyMS library. Raises ValueError for unknown methods.

```python
import pyMS

[docs]def smooth_spectrum(mzs,intensities,smoothMethod):
    
    if smoothMethod=='sg_smooth':
        intensities =  pyMS.sg_smooth(mzs,intensities,n_smooth=1)
    elif smoothMethod=='apodization':
        intensities = pyMS.apodization(mzs,intensities,w_size=10)
    else:
        raise ValueError("method {} not known".format(smoothMethod))
    return intensities

```

--------------------------------

### Generate Bin Edges from Spectra

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Calculates bin edges for mass spectrometry data based on spectral intensity and m/z values. It considers positive and negative ion modes and adjusts for maximum width and peak counts.

```python
[docs]def get_edges(mzs, specix, max_width=0.1, max_ups=1):
    bin_edges_pos = [mzs[0],mzs[1]]
    for mz in mzs[1:]:
        ups = peaks_from_spectra(mzs, specix, bin_edges_pos[-1], bin_edges_pos[-2])
        if ups > max_ups:
            bin_edges_pos.append(mz)
        bin_edges_pos[-1] = mz

    bin_edges_neg = [mzs[-1],mzs[-2]]
    for mz in mzs[::-1]:
        ups = peaks_from_spectra(mzs, specix, bin_edges_neg[-1], bin_edges_neg[-2])
        ups_max = np.max(ups)
        n_exceed = np.sum(ups>max_ups)
        if n_exceed> max_ups:
            bin_edges_neg.append(mz)
        bin_edges_neg[-1] = mz
    edges = np.unique(np.round(np.concatenate((bin_edges_pos, bin_edges_neg)), decimals=5))
    delta_edges = np.diff(edges)
    extra_edges = []
    for ii, delta in enumerate(delta_edges):
        if delta >= max_width:
            extra_edges.extend(np.linspace(edges[ii], edges[ii+1], int(delta/max_width))[1:-1])
    edges = np.unique(np.concatenate([edges, np.asarray(extra_edges)]))
    return edges
```

--------------------------------

### Logarithmic Transformation

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/smoothing.html

Applies a natural logarithm transformation to the image pixel values. Useful for compressing dynamic range.

```Python
import numpy as np

def log(im):
    return np.log(im)
```

--------------------------------

### SL File: Find Name

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Searches within an SL file object for an entry by its name.

```python
find_name(name)
```

--------------------------------

### Centroid IMS Data to HDF5

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Converts SL file data into a centroided HDF5 file. It processes spectra, detects centroids using `pyMS.centroid_detection.gradient`, and organizes data into spectral, spatial, and shared groups. Requires `h5py` and `pyMS.centroid_detection.gradient`.

```python
import h5py
import numpy as np
from pyMS.centroid_detection import gradient

# ... (previous code for slFile, instrumentInfo, sharedDataInfo)

with h5py.File(output_filename, 'w') as f_out:
    ### make root groups for output data
    spectral_data = f_out.create_group('spectral_data')
    spatial_data = f_out.create_group('spatial_data')
    shared_data = f_out.create_group('shared_data')

    ### populate common variables - can hardcode as I know what these are for h5 data
    # parameters
    instrument_parameters_1 = shared_data.create_group('instrument_parameters/001')
    if instrumentInfo != {}:
        for tag in instrumentInfo:
            instrument_parameters_1.attrs[tag] = instrumentInfo[tag]
            # ROIs
            # todo - determine and propagate all ROIs
    roi_1 = shared_data.create_group('regions_of_interest/001')
    roi_1.attrs['name'] = 'root region'
    roi_1.attrs['parent'] = ''
    # Sample
    sample_1 = shared_data.create_group('samples/001')
    if sharedDataInfo != {}:
        for tag in sharedDataInfo:
            sample_1.attrs[tag] = sharedDataInfo[tag]

    done = 0
    for key in range(0, n_total):
        mzs, intensities = sl.get_spectrum(key)
        mzs_c, intensities_c, _ = gradient(mzs, intensities)
        this_spectrum = spectral_data.create_group(str(key))
        _ = this_spectrum.create_dataset('centroid_mzs', data=np.float32(mzs_c), compression="gzip",
                                         compression_opts=9)
        # intensities
        _ = this_spectrum.create_dataset('centroid_intensities', data=np.float32(intensities_c), compression="gzip",
                                         compression_opts=9)
        # coordinates
        _ = this_spectrum.create_dataset('coordinates',
                                         data=(sl.coords[0, key], sl.coords[1, key], sl.coords[2, key]))
        ## link to shared parameters
        # ROI
        this_spectrum['ROIs/001'] = h5py.SoftLink('/shared_data/regions_of_interest/001')
        # Sample
        this_spectrum['samples/001'] = h5py.SoftLink('/shared_data/samples/001')
        # Instrument config
        this_spectrum['instrument_parameters'] = h5py.SoftLink('/shared_data/instrument_parameters/001')
        done += 1
        if done % 1000 == 0:
            print "[%s] progress: %.1f%%" % (input_filename, float(done) * 100.0 / n_total)
    print "finished!"
```

--------------------------------

### Remove XIC (Not Implemented)

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Placeholder for a method to remove an XIC based on its m/z value. This functionality is not yet implemented.

```python
[docs]
    def remove_xic(self, mz):
        # remove an xic and related info
        raise NotImplementedError
        index_to_remove = self.mz.index(mz)
        self.n_im -= 1
```

--------------------------------

### pyImagingMSpec.convert.hdf5.smooth_spectrum

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Applies smoothing to a spectrum.

```APIDOC
## smooth_spectrum

### Description
Applies smoothing to a spectrum using a specified method.

### Parameters
- **mzs** (list) - List of m/z values.
- **intensities** (list) - List of corresponding intensities.
- **smoothMethod** (string) - The smoothing method to apply.
```

--------------------------------

### Extract Spectra from Dataset

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Retrieves a specified number of spectra from an imsDataset object. It returns sorted m/z values, intensities, and pixel indices for the extracted spectra.

```python
[docs]def get_some_real_spectra(imsDataset, n):
    #get n spectra from an object of type imsDataset (or any class that has a get_spectrum method)
    # returns a sorted list of mzs, intensities, pixel_index
    all_mzs = []
    all_intensities = []
    all_ix = []
    if n > len(imsDataset.coordinates):
        n = len(imsDataset.coordinates)
    for ii in np.linspace(0, len(imsDataset.coordinates)-1, n, dtype=int):
        real_mzs, real_intensities = map(np.asarray, imsDataset.get_spectrum(ii))
        all_mzs.extend([mz for mz in real_mzs])
        all_intensities.extend([ri for ri in real_intensities])
        all_ix.extend([ii for mz in real_mzs])
    mzs = np.asarray(all_mzs).flatten()
    ints = np.asarray(all_intensities).flatten()
    specix = np.asarray(all_ix).flatten()
    six = np.argsort(mzs)
    mzs = mzs[six]
    specix = specix[six]
    return mzs, ints, specix
```

--------------------------------

### Apply Image Smoothing to Datacube

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Applies a specified smoothing method to each image within the ion datacube. The datacube is updated in place. Requires the 'smoothing' module from pyImagingMSpec.

```python
from pyImagingMSpec import smoothing
for ii in range(self.n_im):
    im = self.xic_to_image(ii)
    # todo: for method in smoothing_methods:
    methodToCall = getattr(smoothing, smooth_method)
    im_s = methodToCall(im, **smooth_params)
    self.xic[ii] = self.image_to_xic(im_s)
```

--------------------------------

### Apply quantile thresholding to an image array

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/imutils.html

Flattens values exceeding a specified percentile to that percentile value. Only non-zero pixels are considered for percentile calculation. Returns the calculated percentile.

```python
def quantile_threshold(im, q_val, notnull_mask=None):
    """
    Set all values greater than the :code:`q_val`-th percentile to the :code:`q_val`-th percentile (i.e. flatten out
    everything greater than the :code:`q_val`-th percentile). For determining the percentile, only nonzero pixels are
    taken into account, that is :code:`im[notnull_mask]`.

    :param im: the array to remove the hotspots from
    :param q_val: percentile to use
    :param notnull_mask: index array for the values greater than zero. If None, no mask is used
    :return: The :code:`q_val`-th percentile
    """
    notnull_mask = np.ones(np.shape(im)) if notnull_mask is None else notnull_mask
    im_q = np.percentile(im[notnull_mask], q_val)
    im_rep = im > im_q
    im[im_rep] = im_q
    return im_q

```

--------------------------------

### 1D DBSCAN Core Sample Identification

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/rebinning.html

Identifies core samples in a 1D dataset (m/z values) based on density. Requires sorted m/z values.

```python
def get_core(x, min_samples, eps, inst):
    """
    param x: list of m/z values (sorted)
    """
    cix = 1
    mz_class = np.zeros(x.shape, dtype=int)
    for ii, mz in enumerate(x):
        ix_l = np.max([0, ii - min_samples])
        ix_u = np.min([x.shape[0]-1, ii + min_samples])
        if np.sum(scaled_dist(inst, x[ix_l:ix_u], mz) < eps) > min_samples:  # is core sample
            mz_class[ii] = cix
        elif (ii > 0) & (mz_class[ii - 1] > 0):
            cix += 1
    return mz_class
```

--------------------------------

### image_to_xic

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Converts a 2D image array into a 1D vector suitable for insertion into the datacube. This is useful for reversing the `xic_to_image` operation.

```APIDOC
## image_to_xic

### Description
Takes a 2D image array and reshapes it into a 1D vector using pre-defined pixel indices. This is the inverse operation of `xic_to_image`.

### Method
`image_to_xic(self, im)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **im** (numpy 2d array) - The input image to be converted.

### Response
#### Success Response
* **numpy vector**: A 1D numpy array representing the image data.

### Request Example
```python
# Assuming 'ion_datacube_instance' is an instance of IonDatacube
# and 'image_data' is a 2D numpy array
vector_data = ion_datacube_instance.image_to_xic(image_data)
```

### Response Example
```python
# Example of a returned numpy vector
# [value1, value2, value3, ...]
```
```

--------------------------------

### pyImagingMSpec.smoothing.log

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.html

Applies a logarithmic transformation to an image.

```APIDOC
## log

### Description
Applies a logarithmic transformation to the input image.

### Parameters
- **im** (image) - The input image.
```

--------------------------------

### Convert SL to imzML (Centroided)

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Converts an SL file to the imzML format, applying centroid detection. This function estimates pixel size, calculates new image dimensions, and handles potential duplicate pixels.

```python
def centroid_imzml(input_filename, output_filename, step=[], apodization=False, w_size=10, min_intensity=1e-5,
                   region_name="", prevent_duplicate_pixels=False):
    # write a file to imzml format (centroided)
    """
    :type min_intensity: float
    """
    from pyimzml.ImzMLWriter import ImzMLWriter
    from pyMSpec.centroid_detection import gradient
    sl = slFile(input_filename, region_name=region_name)
    mz_dtype = sl.Mzs.dtype
    int_dtype = sl.get_spectrum(0)[1].dtype
    # Convert coords to index -> kinda hacky
    coords = np.asarray(sl.coords.copy()).T.round(5)
    coords -= np.amin(coords, axis=0)
    if step == []:  # have a guesss
        step = np.array([np.median(np.diff(np.unique(coords[sl.spotlist, i]))) for i in range(3)])
        step[np.isnan(step)] = 1
    print 'estimated pixel size: {} x {}'.format(step[0], step[1])
    coords = coords / np.reshape(step, (3,)).T
    coords = coords.round().astype(int)
    ncol, nrow, _ = np.amax(coords, axis=0) + 1
    print 'new image size: {} x {}'.format(nrow, ncol)
    if prevent_duplicate_pixels:
        b = np.ascontiguousarray(coords).view(np.dtype((np.void, coords.dtype.itemsize * coords.shape[1])))
        _, coord_idx = np.unique(b, return_index=True)
        print np.shape(sl.spotlist), np.shape(coord_idx)

```

--------------------------------

### pyImagingMSpec.segmentation.dbscan

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.html

Performs DBSCAN clustering on the input data matrix to generate a segmentation map.

```APIDOC
## dbscan

### Description
Performs DBSCAN clustering on the input data matrix.

### Parameters
- **X** (data matrix) - The input data matrix for clustering.
- **eps** (float, optional) - The maximum distance between two samples for one to be considered as in the neighborhood of the other. Defaults to 0.3.
- **return_coefficients** (bool, optional) - Whether to return clustering coefficients. Defaults to False.

### Returns
- **Y** (segmentation map) - The resulting segmentation map.
- **c** (coefficients) - Coefficients, if `return_coefficients` is True.
```

--------------------------------

### quantile_threshold

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/imutils.html

Applies a quantile threshold to an image array, setting values above the specified percentile to that percentile's value.

```APIDOC
## quantile_threshold(im, q_val, notnull_mask=None)

### Description
Set all values greater than the :code:`q_val`-th percentile to the :code:`q_val`-th percentile (i.e. flatten out everything greater than the :code:`q_val`-th percentile). For determining the percentile, only nonzero pixels are taken into account.

### Parameters
#### Path Parameters
- **im** (array) - Required - The array to remove the hotspots from.
- **q_val** (float) - Required - Percentile to use.
- **notnull_mask** (array) - Optional - Index array for the values greater than zero. If None, no mask is used.

### Returns
- **float** - The :code:`q_val`-th percentile.
```

--------------------------------

### Convert HDF5 to imzML

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/hdf5.html

Converts HDF5 centroid data to imzML format. It processes coordinates, determines step sizes, and writes spectra to an imzML file. Progress is printed during conversion.

```python
import numpy as np
from pyImagingMSpec.classes import inMemoryIMS
from pyImagingMSpec.writer import ImzMLWriter

__author__ = 'palmer'



[docs]def hdf5_centroids_IMS(input_filename, output_filename):
    # Convert hdf5 to imzML
    imsDataset = inMemoryIMS(input_filename,cache_spectra=False,do_summary=False)
    coords = imsDataset.coords
    coords -= np.amin(coords, axis=0)
    step = []
    for i in range(3):
        u = list(np.diff(np.unique(coords[:, i])))
        if u == []:
            step.append(1)
        else:
            step.append(np.median(u))
    step = np.asarray(step)
    coords /= np.reshape(step, (3,)) 
    coords = coords.round().astype(int)
    ncol, nrow, _ = np.amax(coords, axis=0) + 1
    print 'dim: {} x {}'.format(nrow,ncol)
    mz_dtype = imsDataset.get_spectrum(0).get_spectrum(source="centroids")[0].dtype
    int_dtype = imsDataset.get_spectrum(0).get_spectrum(source="centroids")[1].dtype
    n_total = len(imsDataset.index_list)
    with ImzMLWriter(output_filename, mz_dtype=mz_dtype, intensity_dtype=int_dtype) as imzml:
        done = 0
        for index in imsDataset.index_list:
            this_spectrum = imsDataset.get_spectrum(index)
            mzs,intensities = this_spectrum.get_spectrum(source='centroids')
            pos = coords[index]
            pos = (nrow - 1 - pos[0], pos[1], pos[2])
            imzml.addSpectrum(mzs, intensities, pos)
            done += 1
            if done % 1000 == 0:
                print "[%s] progress: %.1f%%" % (input_filename, float(done) * 100.0 / n_total)
        print "finished!"

```

--------------------------------

### Add Extracted Ion Chromatogram (XIC)

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/ion_datacube.html

Adds an XIC to the datacube. It validates that the number of coordinates matches the XIC length and appends the XIC, its m/z, and tolerance values to the respective lists.

```python
[docs]
    def add_xic(self, xic, mz, tol):
        # add an eXtracted Ion Chromatogram to the datacube 
        if len(self.coords) != len(xic):
            raise ValueError(
                'size of co-ordinates to not match xic (coords:{} xic:{})'.format(len(self.coords), len(xic)))
        self.xic.append(xic)  # = np.concatenate((self.xic,xic),axis=1)
        self.mzs = np.concatenate((self.mzs, mz))
        self.tol = np.concatenate((self.tol, tol))
        self.n_im += 1
```

--------------------------------

### Find Region Name in SL File

Source: https://pyimagingmspec.readthedocs.io/en/latest/_modules/pyImagingMSpec/convert/sl.html

Helper method to find a region by its name attribute within the SL file's 'Regions' group. Used internally by `_get_spotlist`.

```python
def find_name(self, name):
    if 'name' in self.sl['Regions'][name].attrs.keys():
        if self.sl['Regions'][name].attrs['name'] == self.region_name:
            assert isinstance(name, object)
            return name
```

--------------------------------

### pyImagingMSpec.convert.sl.centroid_IMS

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Centroids IMS data from an SL file.

```APIDOC
## centroid_IMS

### Description
Centroids IMS data from a specified SL file.

### Parameters
- **input_filename** (string) - Path to the input SL file.
- **output_filename** (string) - Path for the output file.
- **instrumentInfo** (dict) - Information about the instrument.
- **sharedDataInfo** (dict) - Information about shared data.
```

--------------------------------

### pyImagingMSpec.convert.sl.centroid_imzml

Source: https://pyimagingmspec.readthedocs.io/en/latest/pyImagingMSpec.convert.html

Centroids data from an SL file and converts it to imzML format.

```APIDOC
## centroid_imzml

### Description
Centroids data from an SL file and converts it to imzML format, with options for apodization and intensity filtering.

### Parameters
- **input_filename** (string) - Path to the input SL file.
- **output_filename** (string) - Path for the output imzML file.
- **step** (list) - Grid spacing of pixels. If empty, the script attempts to guess it.
- **apodization** (boolean) - Whether to attempt to remove FT wiglet artifacts.
- **w_size** (int) - Window size (m/z bins) for apodization.
- **min_intensity** (float) - Minimum intensity for peaks to be returned during centroiding.
- **region_name** (string) - The name of the region to process.
- **prevent_duplicate_pixels** (bool) - If True, only the first spectrum for pixels with the same coordinates is returned.
```
Tokens:
Raw