Initial release of NucleoSpec

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.github/workflows/sync_hf.yml

@@ -0,0 +1,46 @@
+name: Sync to Hugging Face
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to HF Space
+        env:
+          HF_TOKEN: ${{ secrets.HF }}
+        run: |
+          git clone https://viviandlin:$HF_TOKEN@huggingface.co/spaces/copplab/NucleoSpec hf_repo || {
+            mkdir hf_repo && cd hf_repo && git init && git branch -M main
+            git remote add origin https://viviandlin:$HF_TOKEN@huggingface.co/spaces/copplab/NucleoSpec
+            cd ..
+          }
+
+          cd hf_repo
+          git config user.email "vivian891110@gmail.com"
+          git config user.name "viviandlin"
+
+          # Remove old files (except .git) and copy fresh ones
+          find . -maxdepth 1 ! -name '.git' ! -name '.' -exec rm -rf {} +
+          cp ../dna_silver_webapp.py .
+          cp ../Dockerfile .
+          cp ../environment_hf.yml .
+          # Prepend HF Space YAML frontmatter (kept out of GitHub README)
+          printf '%s\n' '---' 'title: NucleoSpec' 'emoji: 🔬' 'colorFrom: blue' 'colorTo: purple' 'sdk: docker' 'app_port: 7860' 'pinned: false' 'license: cc-by-nc-4.0' 'short_description: ESI-MS analysis of nucleic acid-silver complexes' '---' '' > README.md
+          cat ../README.md >> README.md
+          cp -r ../core/ core/
+          cp -r ../lib/ lib/
+          cp -r ../templates/ templates/
+          cp -r ../sample_data/ sample_data/
+
+          echo "${{ github.sha }}" > .last_sync
+          git add -A
+          git commit -m "Sync from GitHub: ${{ github.event.head_commit.message }}"
+          git push origin main

.gitignore

@@ -0,0 +1 @@
+core/.DS_Store

Dockerfile

@@ -0,0 +1,29 @@
+FROM continuumio/miniconda3:latest
+
+WORKDIR /app
+
+# Install g++ (needed to build IsoSpecPy C++ extension)
+RUN apt-get update && apt-get install -y g++ && rm -rf /var/lib/apt/lists/*
+
+# Install conda dependencies (including RDKit from conda-forge)
+COPY environment_hf.yml .
+RUN conda env create -f environment_hf.yml && conda clean -afy
+
+# Activate conda env for all subsequent commands
+SHELL ["conda", "run", "-n", "dna_mass_spec", "/bin/bash", "-c"]
+
+# Copy application code
+COPY dna_silver_webapp.py .
+COPY core/ core/
+COPY lib/ lib/
+COPY templates/index.html templates/
+COPY sample_data/ sample_data/
+
+# HF Spaces expects port 7860
+ENV PORT=7860
+ENV SECRET_KEY=auto
+ENV FLASK_ENV=production
+
+EXPOSE 7860
+
+CMD ["conda", "run", "--no-capture-output", "-n", "dna_mass_spec", "python", "dna_silver_webapp.py"]

README.md

@@ -0,0 +1,103 @@
+# NucleoSpec
+
+**Nucleic Acid-Silver Complex & Cluster Analyzer**
+
+A web-based application for analyzing nucleic acid (DNA/XNA)-silver complexes and nanoclusters from mass spectrometry data.
+
+## Project Structure
+
+```
+NucleoSpec/
+├── dna_silver_webapp.py    # Main Flask application
+├── core/
+│   └── analyzer.py         # DNASilverAnalyzer class (analysis logic)
+├── lib/
+│   └── pythoms/            # PythoMS library (isotope calculations)
+├── templates/              # HTML templates
+├── sample_data/            # Example spectrum files
+└── environment_hf.yml      # HuggingFace deployment environment
+```
+
+## Installation
+
+```bash
+conda env create -f environment.yml
+conda activate dna_mass_spec
+python dna_silver_webapp.py
+```
+
+Open http://localhost:8080 in browser.
+
+## Analysis Modes
+
+### DNA-Ag<sub>N</sub> Mode
+For single-stranded DNA-silver nanoclusters.
+- Enter DNA sequence using A, T, G, C bases
+- Automatically calculates molecular composition
+- Uses N₀/Qcl framework for cluster characterization
+
+### Ag(I)-DNA/XNA Complex Mode
+For double-stranded DNA or DNA/XNA hybrids.
+- **DNA Complex**: Enter two DNA sequences (Strand 1 and Strand 2)
+- **XNA Complex**: Check "Use XNA" and enter two molecular formulas
+  - Formulas are automatically combined by adding atoms
+
+### XNA-Ag<sub>N</sub> Mode
+For custom xeno nucleic acids (TNA, PNA, LNA, etc.).
+- Enter XNA name for identification
+- Enter complete molecular formula (e.g., C<sub>100</sub>H<sub>120</sub>N<sub>40</sub>O<sub>60</sub>P<sub>10</sub>)
+- Optionally use JSME structure drawer to get formula
+
+## Workflow
+
+1. **Select Mode** - Choose DNA-Ag<sub>N</sub>, Ag(I)-DNA/XNA Complex, or XNA-Ag<sub>N</sub> from the mode selector
+2. **Upload Spectrum** - Click "Choose File" and select your mass spectrum file
+3. **Enter Information** - Provide DNA sequence or XNA formula based on selected mode
+4. **Apply Settings** - Click the "Apply" button to confirm your settings
+5. **Analyze Peaks** - Click any peak in the spectrum to find matching compositions
+6. **Compare Results** - Toggle checkboxes to overlay theoretical isotope patterns on the experimental data
+
+## File Format
+
+Spectrum files should be two-column format (tab or comma separated):
+```
+m/z         intensity
+1000.123    45678.9
+1000.456    56789.0
+1001.234    67890.1
+```
+
+Supported formats: .txt, .csv
+
+## Output Fields
+
+| Field | Description |
+|-------|-------------|
+| Formula | Neutral molecular formula of the cluster |
+| Ion Formula | Charged species formula (can be copied) |
+| n<sub>Ag <sub>| Number of silver atoms in the cluster |
+| N₀ | Number of effective valence electrons|
+| Qcl | Charge of inorganic core |
+| z | Charge state of the detected ion |
+| ΔX₀ | Difference between experimental and theoretical centroid (lower = better match). Primary criterion for Best Fit selection. |
+| Pattern similarity | Mean of cosine similarity and Pearson correlation between experimental and theoretical isotope envelopes (0–1). Confidence indicator: ▲ > 0.8 high, ○ 0.5–0.8 moderate, ▽ < 0.5 low |
+
+## Features
+
+- **Charge Detection** - Automatic charge state determination from isotope spacing
+- **Isotope Pattern Matching** - Compare experimental peaks with theoretical patterns
+- **Adduct Support** - Account for common adducts (NH₄⁺, Na⁺, Cl⁻) plus user-defined custom adducts
+- **Structure Drawing** - JSME molecule editor for drawing bioconjugate structures
+- **Data Export** - Download theoretical spectra as CSV files
+
+## Technical Details
+
+- **Backend:** Python 3.12, Flask, NumPy, SciPy
+- **Frontend:** HTML5, JavaScript, Plotly.js, JSME
+- **Libraries:** PythoMS, IsoSpecPy
+
+## Support
+
+- **Developer:** I-Hsin (Vivian) Lin
+- **Email:** ihl1@uci.edu
+- **Lab:** Copp Lab, University of California, Irvine

environment_hf.yml

@@ -0,0 +1,15 @@
+name: dna_mass_spec
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.12
+  - flask=3.0.0
+  - numpy=1.26.4
+  - scipy=1.16.3
+  - sympy=1.14.0
+  - rdkit
+  - matplotlib
+  - pip
+  - pip:
+    - IsoSpecPy==2.2.1

lib/pythoms/__init__.py

@@ -0,0 +1 @@
+__version__ = '1.6.3'

lib/pythoms/colour.py

@@ -0,0 +1,240 @@
+"""
+IGNORE:
+takes an input string, tuple, or list and attempts to interpret it as a colour
+
+new:
+    several methods were rewritten to be less restrictive
+    updated docstring
+    added cmyk support (both to and from)
+    added printdetails method for easy colour conversion
+    made it so hex input does not need a '#'
+    ---2.1---
+    ---2.2
+IGNORE
+"""
+
+
+class Colour(object):
+    def __init__(self, c, rgb_scale=255, cmyk_scale=100):
+        """
+        Takes an input colour string and stores several colour properties of that colour
+
+        **Parameters**
+
+        c: *string* or *tuple*
+            Input string (predefined colour or hex code) or R,G,B tuple.
+
+        rgb_scale: *integer*
+            The maximum value of the RGB scale for this object. Default is 255, implying
+            RGB values between 0-255.
+
+        cmyk_scale: *integer*
+            The maximum value of the CMYK scale. Currently unused
+
+
+        **Examples**
+
+        ::
+
+            >>> col = Colour((89,89,89))
+            >>> col.print_details()
+            Colour (89, 89, 89)
+            RGB:        89, 89, 89
+            RGB (0-1):  0.349, 0.349, 0.349
+            CMYK:       0.0, 0.0, 0.0, 65.1
+            hex:        #595959
+
+            >>> col.mpl # matplotlib RGB format (floats between 0 and 1)
+            (0.34901960784313724, 0.34901960784313724, 0.34901960784313724)
+
+            >>> col2 = Colour('#A8E5B0')
+            >>> col2.rgb
+            (168, 229, 176)
+            >>> col2.cmyk
+            (26.637554585152838, 0.0, 23.144104803493455, 10.196078431372547)
+
+
+        **Predefined Colours**
+
+        b: blue
+        r: red
+        g: olive green
+        p: purple
+        o: orange
+        a: aqua
+        k: black
+
+        d_: dark colour (ex. 'db' = dark blue)
+        l_: light colour (ex. 'lb' = light blue)
+
+        """
+        self.c = c
+        self.rgb_scale = float(rgb_scale)
+        self.cmyk_scale = float(cmyk_scale)
+        self.ty = type(self.c)
+        if self.ty == str:  # interpret as string
+            self.interpretstring(c)
+        elif self.ty == tuple or self.ty == list:  # interpret as list or tuple
+            if len(self.c) == 3:
+                self.validatergb(self.c)
+                self.rgb = self.c
+                self.cmyk = self.rgb_to_cmyk(self.rgb)
+            elif len(self.c) == 4:
+                self.validatecmyk(self.c)
+                self.cmyk = self.c
+                self.rgb = self.cmyk_to_rgb(self.cmyk)
+            self.hex = self.rgb_to_hex(self.rgb)
+        self.mpl = self.mplcolour(self.rgb)  # generate matplotlib colour tuple
+        self.rgb_to_others()  # calculate other values
+
+    def __str__(self):
+        return 'Colour {}'.format(self.c)
+
+    def __repr__(self):
+        return '{}({})'.format(self.__class__.__name__, self.c)
+
+    def hex_to_rgb(self, string):
+        """
+        converts hex colour to tuple
+        snagged from http://stackoverflow.com/questions/214359/converting-hex-color-to-rgb-and-vice-versa
+        """
+        string = string.lstrip('#')  # remove hash if present
+        lv = len(string)
+        if lv % 3 == 0:
+            out = []
+            for i in range(0, lv, lv // 3):
+                out.append(int(string[i:i + lv // 3], 16))  # append integer in base 16
+            return tuple(out)
+            # return tuple(int(string[i:i + lv // 3], 16) for i in range(0, lv, lv // 3)) #list-comprehension version
+        else:
+            raise ValueError('The provided colour string "%s" could not be interpreted as a colour.\n%s' % (
+            string, self.__class__.__doc__))
+
+    def cmyk_to_rgb(self, tup):
+        """converts cmyk tuple to rgb"""
+        # set values and normalize
+        c, m, y, k = tup
+        c /= self.cmyk_scale
+        m /= self.cmyk_scale
+        y /= self.cmyk_scale
+        k /= self.cmyk_scale
+
+        # convert to RGB and scale
+        r = int(round(self.rgb_scale * (1.0 - c) * (1.0 - k), 0))
+        g = int(round(self.rgb_scale * (1.0 - m) * (1.0 - k), 0))
+        b = int(round(self.rgb_scale * (1.0 - y) * (1.0 - k), 0))
+        return r, g, b
+
+    def interpretstring(self, string):
+        """interprets a string as a colour"""
+        colourdict = {
+            'b': (79, 129, 189),
+            'r': (192, 80, 77),
+            'g': (155, 187, 89),
+            'p': (128, 100, 162),
+            'a': (75, 172, 198),
+            'o': (247, 150, 70),
+            'lb': (149, 179, 215),
+            'lr': (217, 150, 148),
+            'lg': (195, 214, 155),
+            'lp': (179, 162, 199),
+            'lo': (147, 205, 221),
+            'la': (250, 192, 144),
+            'db': (54, 96, 146),
+            'dr': (99, 37, 35),
+            'dg': (79, 98, 40),
+            'dp': (64, 49, 82),
+            'do': (33, 89, 104),
+            'da': (152, 72, 7),
+            'k': (0, 0, 0),
+        }
+        if string in colourdict:
+            self.hex = self.rgb_to_hex(colourdict[string])
+            self.rgb = colourdict[string]
+        else:
+            self.rgb = self.hex_to_rgb(string)
+            self.hex = string
+        self.cmyk = self.rgb_to_cmyk(self.rgb)
+
+    def mplcolour(self, c):
+        """converts 0-255 integers to 0-1 floats used by matplotlib"""
+        out = []
+        for val in c:  # normalize output to 255
+            out.append(val / self.rgb_scale)
+        return tuple(out)
+
+    def printdetails(self):
+        """prints the details of the object"""
+        import sys
+        sys.stdout.write('Colour %s\n' % str(self.c))
+        sys.stdout.write('RGB:        %d, %d, %d\n' % self.rgb)
+        sys.stdout.write('RGB (0-1):  %.3f, %.3f, %.3f\n' % self.mpl)
+        sys.stdout.write('CMYK:       %.1f, %.1f, %.1f, %.1f\n' % self.cmyk)
+        # sys.stdout.write('HLS:        %.3f, %.3f, %.3f\n' %self.hls)
+        # sys.stdout.write('HSV:        %.3f, %.3f, %.3f\n' %self.hsv)
+        # sys.stdout.write('YIQ:        %.3f, %.3f, %.3f\n' %self.yiq)
+        sys.stdout.write('hex:        %s' % self.hex)
+
+    def rgb_to_cmyk(self, tup):
+        """converts rgb tuple to cmyk"""
+        if sum(tup) == 0:  # black
+            return 0, 0, 0, self.cmyk_scale
+
+        # set values and normalize
+        r, g, b = tup
+        r /= self.rgb_scale
+        g /= self.rgb_scale
+        b /= self.rgb_scale
+
+        # extract CMYK values
+        k = 1 - max(r, g, b)
+        c = (1 - r - k) / (1 - k)
+        m = (1 - g - k) / (1 - k)
+        y = (1 - b - k) / (1 - k)
+
+        # scale and return
+        return c * self.cmyk_scale, m * self.cmyk_scale, y * self.cmyk_scale, k * self.cmyk_scale
+
+    def rgb_to_hex(self, tup):
+        """converts RGB tuple to hex code"""
+        return '#%02x%02x%02x' % tup
+
+    def rgb_to_others(self):
+        """
+        converts RGB tuple to:
+            HLS (Hue Lightness Saturation)
+            HSV (Hue Saturation Value)
+            YIQ"""
+        import colorsys
+        r, g, b = [i / self.rgb_scale for i in self.rgb]
+        self.hls = colorsys.rgb_to_hls(r, g, b)
+        self.hsv = colorsys.rgb_to_hsv(r, g, b)
+        self.yiq = colorsys.rgb_to_yiq(r, g, b)
+
+    def validatecmyk(self, tup):
+        """checks that values in a CMYK tuple are valid"""
+        for val in tup:
+            if type(val) != int and type(val) != float:
+                raise ValueError('One of the values in the CMYK colour tuple is not a number (%s).\n%s' % (
+                str(val), self.__class__.__doc__))
+            if val > self.cmyk_scale or val < 0:
+                raise ValueError(
+                    'One of the values in the CMYK colour tuple (%s) is outside of the valid range (0-%d)\n%s' % (
+                    str(val), self.cmyk_scale, self.__class__.__doc__))
+
+    def validatergb(self, tup):
+        """checks that values in an RGB tuple are valid"""
+        for val in tup:
+            if type(val) != int:
+                raise ValueError(
+                    'One of the values in the RGB colour tuple is not an integer ("%s").\nPlease correct the value.\n%s' % (
+                    str(val), self.__class__.__doc__))
+            elif val > self.rgb_scale or val < 0:
+                raise ValueError(
+                    'One of the values in the RGB colour tuple (%s) is outside of the valid RGB range of 0-%d.\n%s' % (
+                    str(val), self.rgb_scale, self.__class__.__doc__))
+
+
+if __name__ == '__main__':
+    col = Colour((89, 89, 89))
+    col.printdetails()

lib/pythoms/mass_abbreviations.py

@@ -0,0 +1,59 @@
+"""
+Dictionary of common abbreviations used in chemical formulas
+A new 'element' is triggered by an upper case letter in the MolecularFormula class
+Additional entries can be added by using a unique trigger starting with an upper case letter and followed by lower case
+letters.
+Each new entry should be a dictionary giving the molecular formula
+"""
+
+abbrvs = {
+    # common chemical abbreviations
+    'Ac': {'C': 2, 'H': 3, 'O': 1},  # acetyl
+    'Ar+': {'C': 25, 'H': 21, 'P': 1},  # phosphonium tagged aryl group
+    'Bn': {'C': 7, 'H': 7},  # benzyl
+    'Bu': {'C': 4, 'H': 8},  # butyl
+    'Cod': {'C': 8, 'H': 12},  # cyclooctadiene
+    'Cp': {'C': 5, 'H': 5},  # cyclopenadienyl
+    'Cp*': {'C': 10, 'H': 15},  # pentamethylcyclopentadienyl
+    'Cy': {'C': 6, 'H': 11},  # cyclohexyl
+    'Et': {'C': 2, 'H': 4},  # ethyl
+    'Dba': {'C': 17, 'H': 14, 'O': 1},  # dibenzylideneacetone
+    'Dbu': {'C': 9, 'H': 16, 'N': 2},  # 1,8-diazabicycloundec-7-ene
+    'Dmf': {'C': 3, 'H': 7, 'N': 1, 'O': 1},  # dimethylformamide
+    'Dppm': {'C': 25, 'H': 22, 'P': 2},  # bis(diphenylphosphino)methane
+    'Dppe': {'C': 26, 'H': 24, 'P': 2},  # bis(diphenylphosphino)ethane
+    'Dppp': {'C': 27, 'H': 26, 'P': 2},  # bis(diphenylphosphino)propane
+    'L': {'C': 18, 'H': 15, 'P': 1},  # triphenylphosphine
+    'Im+': {'C': 11, 'H': 12, 'N': 2},  # imidazolium tagged aryl group
+    'Me': {'C': 1, 'H': 3},  # methyl
+    'Mes': {'C': 9, 'H': 12},  # mesitylene
+    'Ph': {'C': 6, 'H': 5},  # phenyl
+    'Pr': {'C': 3, 'H': 6},  # propyl
+    'Py': {'C': 5, 'H': 5, 'N': 1},  # pyridine
+    'Tf': {'C': 1, 'F': 3, 'O': 2, 'S': 1},  # trifluoromethanesulfonyl
+    'Thf': {'C': 4, 'H': 8, 'O': 1},  # tetrahydrofuran
+    'Tol': {'C': 7, 'H': 7},  # tolyl
+    'Tr': {'C': 19, 'H': 15},  # triphenylmethyl
+
+    # amino acids (assumes in polypeptide form; subtracting 1 O and 2 H from each)
+    'Ala': {'C': 3, 'H': 5, 'N': 1, 'O': 1},  # alanine
+    'Arg': {'C': 6, 'H': 11, 'N': 4, 'O': 1},  # arginine
+    'Asn': {'C': 4, 'H': 6, 'N': 2, 'O': 2},  # asparagine
+    'Asp': {'C': 4, 'H': 5, 'N': 1, 'O': 3},  # aspartic acid
+    'Cys': {'C': 3, 'H': 5, 'N': 1, 'O': 1, 'S': 1},  # cysteine
+    'Gln': {'C': 5, 'H': 8, 'N': 2, 'O': 1},  # glutamine
+    'Glu': {'C': 5, 'H': 7, 'N': 1, 'O': 3},  # glutamic acid
+    'Gly': {'C': 2, 'H': 3, 'N': 1, 'O': 1},  # glycine
+    'His': {'C': 6, 'H': 7, 'N': 3, 'O': 1},  # histidine
+    'Ile': {'C': 6, 'H': 11, 'N': 1, 'O': 1},  # isoleucine
+    'Leu': {'C': 6, 'H': 11, 'N': 1, 'O': 1},  # leucine
+    'Lys': {'C': 6, 'H': 12, 'N': 2, 'O': 1},  # lysine
+    'Met': {'C': 5, 'H': 9, 'N': 1, 'O': 1, 'S': 1},  # methionine
+    'Phe': {'C': 9, 'H': 9, 'N': 1, 'O': 1},  # phenylalanine
+    'Pro': {'C': 5, 'H': 7, 'N': 1, 'O': 1},  # proline
+    'Ser': {'C': 3, 'H': 5, 'N': 1, 'O': 2},  # serine
+    'Thr': {'C': 4, 'H': 7, 'N': 1, 'O': 2},  # threonine
+    'Trp': {'C': 11, 'H': 10, 'N': 2, 'O': 1},  # tryptophan
+    'Tyr': {'C': 9, 'H': 9, 'N': 1, 'O': 2},  # tryosine
+    'Val': {'C': 5, 'H': 9, 'N': 1, 'O': 1},  # valine
+}

lib/pythoms/molecule.py

@@ -0,0 +1,2117 @@
+"""
+IGNORE:
+Molecule class (previously "isotope pattern generator" and "MolecularFormula")
+
+The output of this builder has been validated against values calculated by ChemCalc (www.chemcalc.org)
+Negligable differences are attributed to different low value discarding techniques
+(ChemCalc keeps the top 5000 peaks, this script drops values less than a threshold 5 orders of magnitude below the
+maximum value)
+
+CHANGELOG:
+- added exact mass comparison
+- separated fwhm calculation from sigma
+- fwhm calculation now uses monoisotopic mass
+- barisotope pattern now groups using the full width at half max
+- gaussian isotope pattern generation now works off of rawip by default
+- updated to use Progress class
+- updated gaussian isotope pattern generator to automatically determine the appropriate decimal places
+---2.9 INCOMPATIBLE WITH SPECTRUM v2.4 or older
+- moved charge application to raw isotope pattern function
+- fixed bug in validation function for charged molecules
+- added support for and enabled auto-saving of molecule instances (loading and saving to .mol files)
+IGNORE
+"""
+import sys
+import pickle
+import os
+import importlib.util
+import numpy as np
+from scipy import stats
+from datetime import datetime
+import sympy as sym
+import pylab as pl
+import copy
+from .scripttime import ScriptTime
+from .spectrum import Spectrum, weighted_average
+from .progress import Progress
+from . import mass_dictionaries  # import mass dictionaries
+from itertools import combinations_with_replacement as cwr
+from IsoSpecPy import IsoThreshold
+
+# flag for reminding folk to cite people
+_CITATION_REMINDER = False
+
+# attempt to load abbreviation dictionary from current working directory
+from .mass_abbreviations import abbrvs
+
+try:
+    abbrv_spec = importlib.util.spec_from_file_location(
+        'user_abbrvs',
+        os.path.join(
+            os.getcwd(),
+            'user_mass_abbreviations.py'
+        )
+    )
+    abbrv_module = importlib.util.module_from_spec(abbrv_spec)
+    abbrv_spec.loader.exec_module(abbrv_module)
+    user_abbrvs = abbrv_module.user_abbrvs
+    abbrvs.update(user_abbrvs)
+except FileNotFoundError:  # if it can't find the file, continue with default abbreviations
+    pass
+
+
+"""Mass dictionary associated with the instance"""
+MASS_KEY = 'crc_mass'
+mass_dict = getattr(
+    mass_dictionaries,
+    MASS_KEY,
+)
+
+
+st = ScriptTime(profile=True)
+
+# valid start and end brackets
+OPENING_BRACKETS = ['(', '{', '[']  # opening brackets
+CLOSING_BRACKETS = [')', '}', ']']  # closing brackets
+SIGNS = ['+', '-']  # charge signs
+VERBOSE = False  # toggle for verbose
+
+# valid grouping methods
+VALID_GROUP_METHODS = [
+    'weighted',
+    'centroid',
+]
+# valid isotope pattern generation methods
+VALID_IPMETHODS = [
+    'combinatorics',
+    'multiplicative',
+    'hybrid',
+    'isospec',  # use isospecpy package
+    # 'cuda',
+]
+
+# valid dropping methods
+VALID_DROPMETHODS = [
+    None,  # no dropping
+    'threshold',  # drop values below threshold
+    'npeaks',  # keep top n number of peaks
+    # 'consolidate',  # consolidate intensities
+]
+
+# default threshold for low-intensity peak dropping
+THRESHOLD = 0.01
+# number of peaks to keep for low-intensity peak dropping
+NPEAKS = 5000
+# consolidation threshold for low-intensity peak combination
+CONSOLIDATE = 3
+
+
+def interpret(block: str):
+    """
+    Interprets an element block, breaking it into element and number of that element.
+
+    :param block: string block describing an element
+    :return: composition dictionary
+    :rtype: dict
+    """
+    if block[0].isdigit() is True:  # if isotope number is encountered
+        return {block: 1}
+    else:
+        ele = block[0]
+        i = 0
+        num = ''
+        while i < len(block) - 1:
+            i += 1
+            if block[i].isdigit() is True:  # add digits
+                num += block[i]
+            elif block[i] == ' ':  # ignore spaces
+                continue
+            else:
+                ele += block[i]
+        if num == '':
+            num = 1
+        else:
+            num = int(num)
+        return {ele: num}
+
+
+def interpret_charge(string: str):
+    """
+    Interprets a charge string.
+
+    :param string: string describing the charge (e.g. '2+')
+    :return: charge, sign
+    :rtype: tuple
+    """
+    value = ''
+    sign = '+'  # default value for sign
+    if type(string) is int:
+        return string, sign
+    for ind, val in enumerate(string):
+        if val in SIGNS:  # if val sets mode
+            sign = val
+        else:  # number
+            value += val
+    if value == '':  # if no number was specified (e.g. "+")
+        value = 1
+    return int(value), sign
+
+
+def string_to_isotope(string: str):
+    """
+    Attempts to interpret an undefined key as an isotope/element combination (e.g. "13C" becomes 'C', 13). Raises a
+    ValueError if the string cannot be interpreted as such.
+
+    :param string: string to interpret
+    :return: element, isotope
+    :rtype: (str, int)
+    """
+    iso = string[0]
+    if iso.isdigit() is False:
+        raise TypeError(f'The isotope "{string}" is not a valid format. Use isotope/element format e.g. "12C"')
+    ele = ''
+    i = 1
+    try:
+        while i < len(string):
+            if string[i].isdigit() is True:
+                iso += string[i]
+                i += 1
+            if string[i].isalpha() is True:
+                ele += string[i]
+                i += 1
+        return ele, int(iso)
+    except ValueError:
+        raise ValueError(
+            f'The string "{string}" could not be interpreted as an element, isotope combination, please check'
+            f'your input')
+
+
+unicode_subscripts = {  # subscripts values for unit representations
+    0: f'\u2080',
+    1: f'\u2081',
+    2: f'\u2082',
+    3: f'\u2083',
+    4: f'\u2084',
+    5: f'\u2085',
+    6: f'\u2086',
+    7: f'\u2087',
+    8: f'\u2088',
+    9: f'\u2089',
+}
+unicode_superscripts = {  # superscript values for unit representations
+    0: f'\u2070',
+    1: f'\u00b9',
+    2: f'\u00b2',
+    3: f'\u00b3',
+    4: f'\u2074',
+    5: f'\u2075',
+    6: f'\u2076',
+    7: f'\u2077',
+    8: f'\u2078',
+    9: f'\u2079',
+}
+
+
+def to_subscript(number):
+    """
+    Converts the value to subscript characters.
+
+    :param int number: number to convert
+    :return: subscript
+    :rtype: str
+    """
+    return ''.join(
+        [unicode_subscripts[int(val)] for val in str(abs(number))]
+    )
+
+
+def to_superscript(val):
+    """
+    Returns the integer value represented as a superscript string.
+
+    :param int val: value to represent
+    :return: superscript string
+    :rtype: str
+    """
+    return ''.join(
+        [unicode_superscripts[int(val)] for val in str(abs(val))]
+    )
+
+
+def check_in_mass_dict(comp: dict):
+    """
+    Checks for the presence of the dictionary keys in the mass dictionary. Raises a ValueError if the key is not found.
+
+    :param comp: composition dictionary
+    """
+    for key in comp:
+        if key not in mass_dict:
+            ele, iso = string_to_isotope(key)
+            if ele not in mass_dict:
+                raise ValueError(f'The element {ele} is not defined in the mass dictionary. Please check your input.')
+            elif iso not in mass_dict[ele]:
+                raise ValueError(
+                    f'The element "{ele}" does not have a defined isotope "{iso}" in the mass dictionary. '
+                    f'Please check your input.'
+                )
+
+
+def element_intensity_list(element: str):
+    """
+    Returns the non-zero element intensity for the specified element.
+
+    :param element: element key
+    :return: mass, intensity lists
+    :rtype: list
+    """
+    if element not in mass_dict:
+        raise KeyError(f'The element {element} is not defined in the mass dictionary.')
+    ele_dict = mass_dict[element]
+    mass_out = []
+    intensity_out = []
+    for isotope in ele_dict:
+        if isotope != 0 and ele_dict[isotope][1] != 0.:
+            mass_out.append(ele_dict[isotope][0])
+            intensity_out.append(ele_dict[isotope][1])
+    return [mass_out, intensity_out]
+
+
+def chew_formula(formula: str):
+    """
+    Iterates through provided formula, extracting blocks, interpreting the blocks,
+    and returning the formula minus the blocks.
+
+    :param formula: string formula
+    :return: remaining formula, interpreted block
+    :rtype: str, dict
+    """
+    if formula[0].isupper() is True:  # element is recognized by an uppercase letter
+        block = formula[0]  # element block
+        for loc in range(len(formula)):
+            if loc == 0:
+                continue
+            if formula[loc].isupper() is True:  # if an uppercase character is encountered
+                break
+            elif formula[loc] in OPENING_BRACKETS:  # if a bracket is encountered
+                break
+            else:
+                block += formula[loc]
+        return formula[len(block):], interpret(block)  # return remaining formula and the interpreted block
+    elif formula[0] in OPENING_BRACKETS:  # if a bracket is encountered, intialize bracket interpretation
+        return bracket(formula)
+    elif formula[0].isdigit() is True:  # either isotope or charge
+        if any([sign in formula for sign in SIGNS]):  # if the block is a value-sign charge specification
+            return '', {'charge': formula}
+        for ind, val in enumerate(formula):
+            if formula[ind].isalpha() is True:  # if isotope encountered, return that isotope with n=1
+                return '', {formula: 1}
+    elif formula[0] in SIGNS:  # charge specification
+        return '', {'charge': formula}  # assign as charge for later interpretation
+    else:
+        raise ValueError(f'An uninterpretable formula chunck was encountered: {formula}')
+
+
+def bracket(form):
+    """finds the string block contained within a bracket and determines the formula within that bracket"""
+    bracktype = OPENING_BRACKETS.index(form[0])  # sets bracket type (so close bracket can be identified)
+    bnum = ''  # number of things indicated in the bracket
+    block = ''  # element block
+    nest = 1  # counter for nesting brackets
+    for loc in range(len(form)):  # look for close bracket
+        if loc == 0:
+            continue
+        elif form[loc] == OPENING_BRACKETS[bracktype]:  # if a nested bracket is encountered
+            nest += 1
+            block += form[loc]
+        elif form[loc] == CLOSING_BRACKETS[bracktype]:  # if close bracket is encountered
+            nest -= 1
+            if nest == 0:
+                i = loc + 1  # index of close bracket
+                break
+            else:
+                block += form[loc]
+        else:
+            block += form[loc]
+
+    try:  # look for digits outside of the bracket
+        while form[i].isdigit() is True:
+            bnum += form[i]
+            i += 1
+    except IndexError:  # if i extends past the length of the formula
+        pass
+    except UnboundLocalError:  # if a close bracket was not found, i will not be defined
+        raise ValueError(
+            f'A close bracket was not encountered for the "{form[0]}" bracket in the formula segment "{form}". '
+            f'Please check your input molecular formula.')
+
+    lblock = len(block) + len(
+        bnum) + 2  # length of the internal block + the length of the number + 2 for the brackets
+    if bnum == '':  # if no number is specified
+        bnum = 1
+    else:
+        bnum = int(bnum)
+    outdict = {}
+    while len(block) > 0:  # chew through bracket
+        ftemp, tempdict = chew_formula(block)
+        for key in tempdict:
+            try:
+                outdict[key] += tempdict[key] * bnum
+            except KeyError:
+                outdict[key] = tempdict[key] * bnum
+        block = ftemp
+    return form[lblock:], outdict  # returns remaining formula and composition of the block
+
+
+def abbreviations(dct: dict):
+    """
+    Searches for abbreviations predefined in mass_abbreviations.py either in the pythoms package or in the current
+    working directory. Any found abbreviations will be added to the current dictionary.
+
+    :param dct: incoming dictionary
+    :return: un-abbreviated dictionary
+    :rtype: dict
+    """
+    comptemp = {}
+    for key in dct:
+        if key in abbrvs:  # if a common abbreviation is found in formula
+            for subkey in abbrvs[key]:
+                try:
+                    comptemp[subkey] += abbrvs[key][subkey] * dct[key]
+                except KeyError:
+                    comptemp[subkey] = abbrvs[key][subkey] * dct[key]
+        else:
+            try:
+                comptemp[key] += dct[key]
+            except KeyError:
+                comptemp[key] = dct[key]
+    return comptemp
+
+
+def composition_from_formula(formula):
+    """
+    Interprets a provided string as a molecular formula.
+    Supports nested brackets, charges, and isotopes.
+
+    :param formula:  A molecular formula. Charge may be specified in the formula, but care must be taken to specify
+        the charge in sign-value format (e.g. '+2' if value-sign is specified, the script will attempt to interpret the
+        key as an isotope).
+    :return: A dictionary where each key is an element or isotope with its value
+        being the number of each of the elements or isotopes. e.g. the
+        molecule CH4 would have the composition ``comp = {'C':1, 'H':4}``
+    :rtype: dict
+    """
+    comp = {}
+    while len(formula) > 0:  # chew through formula
+        ftemp, nomdict = chew_formula(formula)  # find the next block
+        for ele in nomdict:
+            try:
+                comp[ele] += nomdict[ele]
+            except KeyError:
+                comp[ele] = nomdict[ele]
+        formula = ftemp
+    comp = abbreviations(comp)  # look for common abbreviations
+    return comp
+
+
+def standard_deviation(fwhm):
+    """determines the standard deviation for a normal distribution with the full width at half max specified"""
+    return fwhm / (2 * np.sqrt(2 * np.log(2)))  # based on the equation FWHM = 2*sqrt(2ln2)*sigma
+
+
+def group_masses(ip, dm: float = 0.25):
+    """
+    Groups masses in an isotope pattern looking for differences in m/z greater than the specified delta.
+    expects
+
+    :param ip: a paired list of [[mz values],[intensity values]]
+    :param dm: Delta for looking +/- within
+    :return: blocks grouped by central mass
+    :rtype: list
+    """
+    num = 0
+    out = [[[], []]]
+    for ind, val in enumerate(ip[0]):
+        out[num][0].append(ip[0][ind])
+        out[num][1].append(ip[1][ind])
+        try:
+            if ip[0][ind + 1] - ip[0][ind] > dm:
+                num += 1
+                out.append([[], []])
+        except IndexError:
+            continue
+    return out
+
+
+def centroid(ipgroup):
+    """
+    takes a group of mz and intensity values and finds the centroid
+    this method results in substantially more error compared to the weighted_average method (~9 orders of
+    magnitude for C61H51IP3Pd)
+    """
+    return sum(ipgroup[0]) / len(ipgroup[0]), sum(ipgroup[1]) / len(ipgroup[1])
+
+
+def bar_isotope_pattern(
+        rawip: list,
+        delta: float = 0.5,
+        method: str = 'weighted',
+        verbose: bool = VERBOSE,
+):
+    """
+    Converts a raw isotope pattern into a bar isotope pattern. This groups mass defects
+    that are within a given difference from each other into a single *m/z* value and
+    intensity.
+
+    :param rawip: The raw isotope pattern with no grouping applied
+    :param delta: The *m/z* difference to check around a peak when grouping it into a single *m/z* value.
+        The script will look delta/2 from the peak being checked
+    :param method: Method of combining (weighted or centroid). Weighted is recommended for accuracy
+    :param verbose: chatty mode
+    :return: bar isotope pattern in ``[[m/z values],[intensity values]]`` format.
+    :rtype: list
+    """
+    if method not in VALID_GROUP_METHODS:
+        raise ValueError(f'The grouping method {method} is invalid. Choose from {", ".join(VALID_GROUP_METHODS)}')
+    if verbose is True:
+        sys.stdout.write('Generating bar isotope pattern')
+    if isinstance(rawip, Spectrum):  # if handed a Spectrum object, trim before continuing
+        rawip = rawip.trim()
+    groupedip = group_masses(rawip, delta / 2)
+    out = [[], []]
+    for group in groupedip:
+        if method == 'weighted':
+            x, y = weighted_average(*group)  # determine weighted mass and summed intensity
+        elif method == 'centroid':
+            x, y = centroid(group)
+        out[0].append(x)
+        out[1].append(y)
+    maxint = max(out[1])
+    for ind, val in enumerate(out[1]):
+        out[0][ind] = out[0][ind]  # / abs(charge)
+        out[1][ind] = val / maxint * 100.  # normalize to 100
+    if verbose is True:
+        sys.stdout.write(' DONE\n')
+    return out
+
+
+def normal_distribution(center, fwhm, height):
+    """
+    Generates a normal distribution about the center with the full width at half max specified. Y-values will be
+    normalized to the height specified.
+
+    :param center: center x value for the distribution
+    :param fwhm: full-width-at-half-maximum
+    :param height: maximum value for the y list
+    :return: x values, y values
+    :rtype: list
+    """
+    x = np.arange(
+        center - fwhm * 2,
+        center + fwhm * 2,
+        10 ** -autodec(fwhm),
+        dtype=np.float64,
+    )
+    y = stats.norm.pdf(  # generate normal distribution
+        x,
+        float(center),  # type-convert from sympy Float
+        standard_deviation(fwhm),
+    )
+    y /= max(y)  # normalize
+    y = y * height
+    return [x.tolist(), y.tolist()]
+
+
+def autodec(fwhm):
+    """
+    Automatically calculates the appropriate decimal place to track based on a full-width-at-half-maximum
+
+    :param fwhm: full-width-at-half-maximum
+    :return: decimal power
+    :rtype: int
+    """
+    shift = fwhm
+    n = 0
+    while shift < 1.:
+        n += 1
+        shift = fwhm * 10 ** n
+    return n + 1  # track 1 higher
+
+
+def gaussian_isotope_pattern(
+        barip: list,
+        fwhm: float,
+        verbose: bool = VERBOSE,
+):
+    """
+    Simulates the isotope pattern that would be observed in a mass
+    spectrometer with the resolution specified as a fwhm value.
+
+    :param barip: The isotope pattern to be simulated. This can be either the bar isotope
+        pattern or the raw isotope pattern (although this will be substantially
+        slower for large molecules).
+    :param fwhm: full-width-at-half-maximum
+    :param verbose: chatty mode
+    :return: The predicted gaussian isotope pattern in the form of a paired list
+        ``[[m/z values],[intensity values]]``
+    :rtype: list
+    """
+    spec = Spectrum(  # generate Spectrum object to encompass the entire region
+        autodec(fwhm),
+        start=min(barip[0]) - fwhm * 2,
+        end=max(barip[0]) + fwhm * 2,
+        empty=False,  # whether or not to use emptyspec
+        filler=0.,  # fill with zeros, not None
+    )
+    for ind, val in enumerate(barip[0]):  # generate normal distributions for each peak
+        # if verbose is True:
+        #    sys.stdout.write('\rSumming m/z %.3f %d/%d' %(val,ind+1,len(self.barip[0])))
+        nd = normal_distribution(val, fwhm, barip[1][ind])  # generate normal distribution for that peak
+        spec.add_spectrum(nd[0], nd[1])  # add the generated spectrum to the total spectrum
+    spec.normalize()  # normalize
+    gausip = spec.trim()  # trim None values and output
+    if verbose is True:
+        sys.stdout.write(' DONE\n')
+    return gausip
+
+
+def isotope_pattern_hybrid(
+        composition: dict,
+        fwhm: float,
+        decpl: int,
+        verbose: bool = VERBOSE,
+        dropmethod: str = None,
+        threshold: float = THRESHOLD,
+        npeaks: int = NPEAKS,
+        consolidate: float = CONSOLIDATE,
+        **kwargs,
+):
+    """
+    A hybrid isotope pattern calculator which calculates the isotope pattern from each element, then multiplies the
+    lists.
+
+    :param composition: composition dictionary
+    :param fwhm: full-width-at-half-maximum
+    :param decpl: decimal places to track in the Spectrum object
+    :param verbose: chatty mode
+    :param dropmethod: optional method to use for low-intensity peak dropping or consolidation. Valid options are
+        'threshold', 'npeaks', or 'consolidate'.
+    :param threshold: if the dropmethod is set to 'threshold', any peaks below this threshold will be dropped.
+    :param npeaks: if the dropmethod is set to 'npeaks', the top n peaks will be kept, with the rest being dropped.
+    :param consolidate: if the dropmethod is set to 'consolidate', any peaks below the threshold will be consolidated
+        into adjacent peaks using a weighted average. Any peaks that do not have a neighbour within 10^-`consolidate`
+        will be dropped entirely.
+    :return: isotope pattern as a Spectrum object
+    :rtype: Spectrum
+    """
+    eleips = {}  # dictionary for storing the isotope patterns of each element
+    for element, number in composition.items():
+        eleips[element] = isotope_pattern_combinatoric(  # calculate the isotope pattern for each element
+            {element: number},
+            decpl=decpl,
+            verbose=verbose,
+        ).trim()  # trim the generated spectra to lists
+
+    sortlist = []
+    for element in eleips:
+        sortlist.append((
+            len(eleips[element][0]),
+            element
+        ))
+    sortlist = sorted(sortlist)  # sorted list of elements based on the length of their isotope patterns
+    sortlist.reverse()
+    if verbose is True:
+        prog = Progress(
+            last=len(sortlist) - 1,
+            percent=False,
+            fraction=False,
+        )
+
+    spec = None
+    for lenlist, element in sortlist:
+        if verbose is True:
+            prog.string = f'Adding element {element} to isotope pattern'
+            prog.write(1)
+        if spec is None:
+            spec = Spectrum(
+                autodec(fwhm),  # decimal places
+                start=None,  # minimum mass
+                end=None,  # maximum mass
+                empty=True,  # whether or not to use emptyspec
+                filler=0.,  # fill with zeros, not None
+                specin=eleips[element],  # supply masses and abundances as initialization spectrum
+            )
+            if verbose is True:
+                prog.fin()
+
+            continue
+        spec.add_element(eleips[element][0], eleips[element][1])
+        spec.normalize(100.)  # normalize spectrum object
+        if dropmethod == 'threshold':  # drop values below threshold
+            spec.threshold(threshold)
+        elif dropmethod == 'npeaks':  # keep top n number of peaks
+            spec.keep_top_n(npeaks)
+        elif dropmethod == 'consolidate':  # consolidate values being dropped
+            spec.consolidate(
+                threshold,
+                3 * 10 ** -consolidate
+            )
+        if verbose is True:
+            sys.stdout.write(' DONE\n')
+    return spec
+
+
+class ReiterableCWR(object):
+    def __init__(self, isos, number):
+        """a reiterable version of combinations with replacements iterator"""
+        self.isos = isos  # isotopes group
+        self.number = number  # number of atoms of the element
+
+    def __iter__(self):
+        return cwr(self.isos, self.number)
+
+
+@st.profilefn
+def num_permu(lst, isos):
+    """
+    Calculates the number of unique permutations of the given set of isotopes for an element.
+    The calculation is generated as a sympy function before evaluation. numpy factorial is limited in the size of
+    factorials that are calculable, so sympy is required.
+
+    :param lst: list of isotopes in the combination
+    :param isos: possible isotopes for that element
+    :return: number of occurrences of this list of isotopes
+    :rtype: int
+    """
+    counts = [lst.count(x) for x in isos]  # counts the number of each isotope in the set
+    num = sym.factorial(len(lst))  # numerator is the factorial of the length of the list
+    denom = 1  # denominator is the product of the factorials of the counts of each isotope in the list
+    for count in counts:
+        denom *= sym.factorial(count)
+    return int((num / denom).evalf())  # divide, evaluate, and return integer
+
+
+@st.profilefn
+def product(*iterables):
+    """
+    cartesian product of iterables
+    from http://stackoverflow.com/questions/12093364/cartesian-product-of-large-iterators-itertools
+    """
+    if len(iterables) == 0:
+        yield ()
+    else:
+        it = iterables[0]
+        for item in it() if callable(it) else iter(it):
+            for items in product(*iterables[1:]):
+                yield (item,) + items
+
+
+@st.profilefn
+def numberofcwr(n, k):
+    """
+    calculates the number of combinations with repitition
+    n: number of things to choose from
+    k: choose k of them
+    """
+    fn = sym.factorial(n + k - 1)
+    fn /= sym.factorial(k)
+    fn /= sym.factorial(n - 1)
+    return fn.evalf()
+
+
+def cpu_list_product(iterable):
+    """returns the product of a list"""
+    prod = 1
+    for n in iterable:
+        prod *= n
+    return prod
+
+
+@st.profilefn
+def isotope_pattern_combinatoric(
+        comp: dict,
+        decpl: int,
+        verbose: bool = VERBOSE,
+        **kwargs,  # catch for extra keyword arguments
+):
+    """
+    Calculates the raw isotope pattern of a given molecular formula with mass defects preserved.
+    Uses a combinatorial method to generate isotope formulae
+
+    :param comp: composition dictionary
+    :param decpl: decimal places to track in the Spectrum object
+    :param verbose: chatty mode
+    :return: raw isotope pattern as a Spectrum object
+    :rtype: Spectrum
+    """
+    speciso = False  # set state for specific isotope
+    isos = {}  # isotopes dictionary
+    isosets = {}  # set of isotopes for each element
+    iterators = []  # list of iterators
+    nk = []
+    for element in comp:  # for each element
+        if element in mass_dict:
+            isosets[element] = []  # set of isotopes
+            for isotope in mass_dict[element]:  # for each isotope of that element in the mass dictionary
+                if isotope != 0 and mass_dict[element][isotope][1] != 0:  # of the intensity is nonzero
+                    isosets[element].append(isotope)  # track set of isotopes
+                    isos[isotope] = element  # create isotope,element association for reference
+            iterators.append(
+                ReiterableCWR(  # create iterator instance
+                    isosets[element],
+                    comp[element]
+                )
+            )
+            if verbose is True:
+                nk.append([  # track n and k for list length output
+                    len(isosets[element]),
+                    comp[element]
+                ])
+        else:  # if it's an isotope
+            speciso = True
+
+    spec = Spectrum(  # initiate spectrum object
+        decpl,  # decimal places
+        start=None,  # no minimum mass
+        end=None,  # no maximum mass
+        empty=True,  # whether or not to use emptyspec
+        filler=0.,  # fill with zeros, not None
+    )
+    if verbose is True:
+        counter = 0  # create a counter
+        iterations = int(cpu_list_product([numberofcwr(n, k) for n, k in nk]))  # number of iterations
+        prog = Progress(  # create a progress instance
+            string='Processing isotope combination',
+            last=iterations
+        )
+
+    for comb in product(*iterators):
+        if verbose is True:
+            counter += 1
+            # remaining = st.progress(counter,iterations,'combinations')
+            prog.write(counter)
+        num = 1  # number of combinations counter
+        x = 0.  # mass value
+        y = 1.  # intensity value
+        for tup in comb:  # for each element combination
+            element = isos[tup[0]]  # associate isotope to element
+            # counts = [tup.count(x) for x in isosets[element]] # count the number of occurances of each isotope
+            # num *= num_permu(tup,counts) # determine the number of permutations of the set
+            # for ind,isotope in enumerate(isosets[element]):
+            #    x += self.md[element][isotope][0] * counts[ind]
+            #    y *= self.md[element][isotope][1] ** counts[ind]
+            num *= num_permu(tup, isosets[element])  # multiply the number by the possible permutations
+            for isotope in tup:  # for each isotope
+                x += mass_dict[element][isotope][0]  # shift x
+                y *= mass_dict[element][isotope][1]  # multiply intensity
+        # add the x and y combination factored by the number of times that combination will occur
+        spec.add_value(x, y * num)
+
+    if speciso is True:  # if an isotope was specified
+        for element in comp:
+            if element not in mass_dict:  # if an isotope
+                ele, iso = string_to_isotope(element)  # determine element and isotope
+                spec.shift_x(mass_dict[ele][iso][0] * comp[element])  # shift the x values by the isotopic mass
+    spec.normalize()  # normalize the spectrum object
+    if verbose is True:
+        prog.fin()
+    return spec
+
+
+@st.profilefn
+def isotope_pattern_multiplicative(
+        comp: dict,
+        decpl: int,
+        verbose: bool = VERBOSE,
+        dropmethod: str = None,
+        threshold: float = THRESHOLD,
+        npeaks: int = NPEAKS,
+        consolidate: float = CONSOLIDATE,
+        **kwargs,
+):
+    """
+    Calculates the raw isotope pattern of a given molecular formula with mass defects preserved.
+
+    :param comp: The molecular composition dictionary. See ``Molecule.composition`` for more details.
+    :param decpl: The number of decimal places to track. This is normally controlled by the keyword
+        arguments of the class, but can be specified if called separately.
+    :param verbose: chatty mode
+    :param dropmethod: optional method to use for low-intensity peak dropping or consolidation. Valid options are
+        'threshold', 'npeaks', or 'consolidate'.
+    :param threshold: if the dropmethod is set to 'threshold', any peaks below this threshold will be dropped.
+    :param npeaks: if the dropmethod is set to 'npeaks', the top n peaks will be kept, with the rest being dropped.
+    :param consolidate: if the dropmethod is set to 'consolidate', any peaks below the threshold will be consolidated
+        into adjacent peaks using a weighted average. Any peaks that do not have a neighbour within 10^-`consolidate`
+        will be dropped entirely.
+    :return: Returns the isotope pattern with mass defects preserved (referred to as the 'raw'
+        isotope pattern in this script).
+    :rtype: Spectrum
+    """
+    spec = None  # initial state of spec
+    if verbose is True:
+        sys.stdout.write('Generating raw isotope pattern.\n')
+
+    for key in comp:  # for each element
+        if key in mass_dict:  # if not a single isotope
+            if verbose is True:
+                prog = Progress(string=f'Processing element {key}', last=comp[key])
+            masses = []  # list for masses of each isotope
+            abunds = []  # list for abundances
+            for mass in mass_dict[key]:
+                if mass != 0:
+                    if mass_dict[key][mass][1] > 0:  # if abundance is nonzero
+                        masses.append(mass_dict[key][mass][0])
+                        abunds.append(mass_dict[key][mass][1])
+            for n in range(comp[key]):  # for n number of each element
+                if verbose is True:
+                    prog.write(n + 1)
+                if spec is None:  # if spectrum object has not been defined
+                    spec = Spectrum(
+                        decpl,  # decimal places
+                        start=min(masses) - 10 ** -decpl,  # minimum mass
+                        end=max(masses) + 10 ** -decpl,  # maximum mass
+                        specin=[masses, abunds],  # supply masses and abundances as initialization spectrum
+                        empty=True,  # whether or not to use emptyspec
+                        filler=0.,  # fill with zeros, not None
+                    )
+                    continue
+                spec.add_element(masses, abunds)  # add the element to the spectrum object
+                spec.normalize(100.)  # normalize spectrum
+                if dropmethod == 'threshold':  # drop values below threshold
+                    spec.threshold(threshold)
+                elif dropmethod == 'npeaks':  # keep top n number of peaks
+                    spec.keep_top_n(npeaks)
+                elif dropmethod == 'consolidate':  # consolidate values being dropped
+                    # todo figure out what's wrong here
+                    raise NotImplementedError("There are bugs here, for the time being don't use the 'consolidate' "
+                                              "dropmethod.")
+                    spec.consolidate(
+                        threshold,
+                        3 * 10 ** -consolidate
+                    )
+        else:  # if specific isotope
+            ele, iso = string_to_isotope(key)  # find element and isotope
+            if verbose is True:
+                prog = Progress(string=f'Processing isotope {key}', fraction=False, percent=False)
+            if spec is None:  # if spectrum object has not been defined
+                spec = Spectrum(
+                    decpl,  # decimal places
+                    start=(mass_dict[ele][iso][0] * float(comp[key])) - 10 ** -decpl,  # minimum mass
+                    end=(mass_dict[ele][iso][0] * float(comp[key])) + 10 ** -decpl,  # maximum mass
+                    specin=[[mass_dict[ele][iso][0] * float(comp[key])], [1.]],
+                    # supply masses and abundances as initialization spectrum
+                    empty=True,  # whether or not to use emptyspec
+                    filler=0.  # fill with zeros, not None
+                )
+                continue
+            spec.shift_x(mass_dict[ele][iso][0])  # offset spectrum object by the mass of that
+        if verbose is True:
+            prog.fin(' ')
+    spec.normalize()
+    if verbose is True:
+        sys.stdout.write('DONE\n')
+    return spec
+
+
+def isotope_pattern_isospec(
+        comp: dict,
+        decpl: int,
+        verbose: bool = VERBOSE,
+        threshold: float = THRESHOLD,
+        **kwargs,
+):
+    """
+    Generates a raw isotope pattern using the isospecpy package. http://matteolacki.github.io/IsoSpec/
+
+    :param comp: composition dictionary
+    :param decpl: decimal places to track while converting from isospec to Spectrum
+    :param verbose: chatty mode
+    :param threshold: threshold level (relative, seems slightly buggy)
+    :param kwargs: catch for extra kwargs
+    :return: Spectrum object
+    """
+    global _CITATION_REMINDER
+    if _CITATION_REMINDER is False:  # remind the user on the first use
+        print('IsoSpecPy package was used, please cite https://dx.doi.org/10.1021/acs.analchem.6b01459')
+        _CITATION_REMINDER = True
+
+    if any([key not in mass_dict for key in comp]):
+        # todo see if there's a workaround for isotope specification
+        raise KeyError(f'Isotope specification is not supported in IsoSpec calling. Please use a different isotope '
+                       f'pattern generation method for isotopes. ')
+
+    # todo see if there's a way to use IsoThresholdGenerator instead
+    # use IsoSpec algorithm to generate configurations
+    iso_spec = IsoThreshold(
+        formula="".join(f'{ele}{num}' for ele, num in comp.items()),
+        threshold=threshold * 0.1,
+    )
+
+    spec = Spectrum(
+        decpl,  # decimal places
+        start=min(iso_spec.masses) - 10 ** -decpl,  # minimum mass
+        end=max(iso_spec.masses) + 10 ** -decpl,  # maximum mass
+        empty=True,
+        filler=0.  # fill with zeros, not None
+    )
+    # add values to Spectrum object
+    for mass, abund in zip(iso_spec.masses, iso_spec.probs):
+        spec.add_value(
+            mass,
+            abund
+        )
+    spec.normalize()  # normalize values to 100.
+    return spec
+
+
+def pattern_molecular_weight(mzs: list, intensities: list, charge: int = 1):
+    """
+    Calculates the molecular weight given by an isotope pattern.
+
+    :param mzs: m/z (x) values for pattern
+    :param intensities: intensity (y) values for the pattern
+    :param charge: charge for the molecule
+    :return: molecular weight
+    :rtype: float
+    """
+    return sum([  # sum
+        mz * intensity * charge  # of the product of the m/z, intensity, and charge
+        for mz, intensity in zip(mzs, intensities)  # for all the values
+    ]) / sum(intensities)  # divided by the sum of the intensities
+
+
+def molecular_weight_error(calculated: float, expected: float):
+    """
+    Calculate the error between a calculated and expected molecular weight. This method may be used as a validation
+    tool for calculated isotope patterns.
+
+    :param calculated: calculated molecular weight (derived from an isotope pattern)
+    :param expected: expected (true) molecular weight (derived from the molecular weights of the constituent elements)
+    :return: Calculated error. Typically a difference of 3 parts per million (3*10^-6) is deemed an acceptable
+        error.
+    :rtype: float
+    """
+    return (calculated - expected) / expected
+
+
+class Molecule(object):
+    _comp = {}  # storage for composition of the molecule
+    _mf = ''
+    verbose = VERBOSE
+
+    def __init__(self,
+                 string: (str, dict),
+                 charge=1,
+                 mass_key='nist_mass',
+                 verbose=False,
+                 ):
+        """
+        Calculates many properties of a specified molecule.
+
+        :param str, dict string: The molecule to interpret. A composition dictionary may also be specified here.
+        :param int, str charge: the charge of the molecule (for mass spectrometric applications).
+            This will affect any properties related to the mass to charge
+            ratio. If the charge is specified in the input molecular formula, this will be
+            overridden.
+        :param str mass_key: The mass dictionary to use for calculations. Default is nist_mass, but additional mass
+            dictionaries may be defined in the mass_dictionary file and retrieved using the dictionary name
+            used to define them.
+        :param bool verbose: Verbose output. Mostly useful when calculating for large molecules or while debugging.
+
+        **Notes regarding string specification**
+
+        - Common abbreviations may be predefined in mass_abbreviations.py (either locally or in the current working
+            directory)
+
+        - Use brackets to signify multiples of a given component (nested brackets are supported)
+
+        - Isotopes may be specified using an isotope-element format within a bracket (e.g. carbon 13 would be specified
+            as "(13C)" ). The mass of that isotope must be defined in the mass dictionary being used by the script
+            (default NIST mass).
+
+        - The charge may be specified in the formula, but care must be taken here. Charge must be specified in either
+            sign-value (e.g. '+2') or within a bracket. Otherwise, the script may attempt to interpret the charge as a
+            magnitude specifier of the previous block or as an isotope, and errors will be encountered.
+
+        - A composition dictionary with the format `{'Element': number_of_that_element, ...}` may be provided instead
+            of a string formula
+
+        """
+        if verbose is True:
+            sys.stdout.write(f'Generating molecule object from input {string}\n')
+        # split charge into value and sign
+        self.charge, self.sign = interpret_charge(charge)
+        self.mass_key = mass_key  # store mass dictionary that the script will use
+        self.verbose = verbose
+        if type(string) == dict:  # if a composition dictionary was provided
+            self.composition = string
+        elif type(string) == str:  # set string and interpret formula
+            self.molecular_formula = string
+        else:
+            raise TypeError(f'The provided string type is not interpretable: {type(string)}')
+
+        if self.verbose is True:
+            self.print_details()
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}({self.molecular_formula})'
+
+    def __str__(self):
+        return self.__repr__()
+
+    def __contains__(self, item):
+        if type(item) == str:
+            return item in self._comp
+        elif type(item) == list or type(item) == tuple:
+            return all([element in self._comp for element in item])
+        elif type(item) == dict:
+            return all([
+                element in self._comp and self._comp[element] >= num for element, num in item.items()
+            ])
+        elif isinstance(item, Molecule):
+            return self.__contains__(item.composition)
+        else:
+            raise TypeError(f'The item {item} is not a recognized type for containment checks. Type: {type(item)}')
+
+    def __iter__(self):
+        for element in self._comp:
+            yield element
+
+    def __getitem__(self, item):
+        return self._comp[item]
+
+    def __eq__(self, other):
+        if type(other) == dict:
+            return other == self._comp
+        elif isinstance(other, Molecule):
+            return other.composition == self._comp
+        return False
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __lt__(self, other):
+        if type(other) == dict:
+            return all([
+                number < self._comp[element] for element, number in other.items()
+            ])
+        elif isinstance(other, Molecule):
+            return all([
+                number < self._comp[element] for element, number in other.composition.items()
+            ])
+        else:
+            raise TypeError(f'Comparison of type {type(other)} to {self.__class__} is unsupported. ')
+
+    def __le__(self, other):
+        return self.__eq__(other) or self.__lt__(other)
+
+    def __gt__(self, other):
+        if type(other) == dict:
+            return all([
+                number > self._comp[element] for element, number in other.items()
+            ])
+        elif isinstance(other, Molecule):
+            return all([
+                number > self._comp[element] for element, number in other.composition.items()
+            ])
+        else:
+            raise TypeError(f'Comparison to type {type(other)} to {self.__class__} is unsupported. ')
+
+    def __ge__(self, other):
+        return self.__eq__(other) or self.__gt__(other)
+
+    def __getinitargs__(self):
+        return (
+            self.composition,
+            f'{self.charge}{self.sign}',
+            self.mass_key,
+            self.verbose,
+        )
+
+    def __reduce__(self):
+        """pickle support"""
+        return (
+            self.__class__,
+            self.__getinitargs__(),
+        )
+
+    def __add__(self, other):
+        """
+        Several supported addition methods:
+        If a valid molecular formula string is provided, that string will be added.
+        If another Molecule class instance is provided, the provided instance will be
+        added to the current instance.
+        """
+        if type(other) is str:
+            other = composition_from_formula(other)
+        elif isinstance(other, Molecule) is True:
+            other = other.composition
+        elif type(other) == dict:
+            pass
+        else:
+            raise ValueError(f'Addition of {other} to {self} is invalid')
+        new = copy.copy(self._comp)  # starter for new dictionary
+
+        for key in other:
+            try:
+                new[key] += other[key]
+            except KeyError:
+                new[key] = other[key]
+        return self.__class__(
+            new,
+            charge=f'{self.charge}{self.sign}'
+        )
+
+    def __radd__(self, other):
+        return self.__add__(other)
+
+    def __iadd__(self, other):
+        if type(other) is str:
+            other = composition_from_formula(other)
+        elif isinstance(other, Molecule) is True:
+            other = other.composition
+        elif type(other) == dict:
+            pass
+        else:
+            raise ValueError(f'Addition of {other} to {self} is invalid')
+        new = copy.copy(self._comp)  # starter for new dictionary
+        for key in other:
+            try:
+                new[key] += other[key]
+            except KeyError:
+                new[key] = other[key]
+        self.composition = new
+        return self
+
+    def __sub__(self, other):
+        """
+        See __add__ for details.
+        Subtract has a catch for a negative number of a given element
+        (the minimum that can be reached is zero).
+        """
+        if type(other) is str:
+            other = composition_from_formula(other)
+        elif isinstance(other, Molecule) is True:
+            other = other.composition
+        elif type(other) == dict:
+            pass
+        else:
+            raise ValueError(f'Addition of {other} to {self} is invalid')
+        new = copy.copy(self._comp)  # starter for new dictionary
+
+        for key in other:
+            if new[key] - other[key] < 0 or key not in new:
+                raise ValueError('Subtraction of {other[key]} {key} from {self} would yield a negative number of that '
+                                 'element.')
+            new[key] -= other[key]
+        return self.__class__(
+            new,
+            charge=f'{self.charge}{self.sign}'
+        )
+
+    def __rsub__(self, other):
+        return self.__sub__(other)
+
+    def __isub__(self, other):
+        if type(other) is str:
+            other = composition_from_formula(other)
+        elif isinstance(other, Molecule) is True:
+            other = other.composition
+        elif type(other) == dict:
+            pass
+        else:
+            raise ValueError(f'Addition of {other} to {self} is invalid')
+        new = copy.copy(self._comp)  # starter for new dictionary
+
+        for key in other:
+            if new[key] - other[key] < 0 or key not in new:
+                raise ValueError('Subtraction of {other[key]} {key} from {self} would yield a negative number of that '
+                                 'element.')
+            new[key] -= other[key]
+        self.composition = new
+        return self
+
+    def __mul__(self, other):
+        """allows integer multiplication of the molecular formula"""
+        if type(other) != int:
+            raise ValueError(f'Non-integer multiplication of a {self.__class__.__name__} object is unsupported')
+        new = copy.copy(self._comp)  # starter for new dictionary
+        for key in new:
+            new[key] = new[key] * other
+        return self.__class__(
+            new,
+            charge=f'{self.charge}{self.sign}'
+        )
+
+    def __rmul__(self, other):
+        return self.__mul__(other)
+
+    def __imul__(self, other):
+        if type(other) != int:
+            raise ValueError(f'Non-integer multiplication of a {self.__class__.__name__} object is unsupported')
+        new = copy.copy(self._comp)  # starter for new dictionary
+        for key in new:
+            new[key] = new[key] * other
+        self.composition = new
+        return self
+
+    def __truediv__(self, other):
+        """allows integer division of the molecular formula"""
+        if type(other) != int:
+            raise ValueError(f'Non-integer division of a {self.__class__.__name__} object is unsupported')
+        new = copy.copy(self._comp)  # starter for new dictionary
+        for key in new:
+            newval = new[key] / other
+            if newval.is_integer() is False:
+                raise ValueError(f'Division of {new[key]} {key} by {other} yielded a non-integer number {newval}')
+            new[key] = int(newval)
+        return self.__class__(
+            new,
+            charge=f'{self.charge}{self.sign}'
+        )
+
+    def __itruediv__(self, other):
+        if type(other) != int:
+            raise ValueError(f'Non-integer division of a {self.__class__.__name__} object is unsupported')
+        new = copy.copy(self._comp)  # starter for new dictionary
+        for key in new:
+            newval = new[key] / other
+            if newval.is_integer() is False:
+                raise ValueError(f'Division of {new[key]} {key} by {other} yielded a non-integer number {newval}')
+            new[key] = int(newval)
+        self.composition = new
+        return self
+
+    @property
+    def composition(self):
+        """Composition dictionary"""
+        return self._comp
+
+    @composition.setter
+    def composition(self, dct):
+        if type(dct) != dict:
+            raise TypeError('The composition must be a dictionary')
+        dct = copy.copy(dct)
+        dct = abbreviations(dct)  # check for and convert abbreviations
+        if 'charge' in dct:  # if charge was specified in the formula
+            self.charge, self.sign = interpret_charge(dct['charge'])
+            del dct['charge']
+        check_in_mass_dict(dct)  # check in mass dictionary
+        self._comp = dct  # set local dictionary
+
+    @property
+    def molecular_formula(self):
+        """Molecular formula of the molecule"""
+        out = ''
+        # todo catch carbon and hydrogen isotopes first
+        if 'C' in self.composition:  # carbon and hydrogen first according to hill formula
+            out += f'C{self.composition["C"]}' if self.composition['C'] > 1 else 'C'
+        if 'H' in self.composition:
+            out += f'H{self.composition["H"]}' if self.composition['H'] > 1 else 'H'
+        for key, val in sorted(self.composition.items()):  # alphabetically otherwise
+            if key != 'C' and key != 'H':
+                if key in mass_dict:
+                    out += f'{key}{self.composition[key]}' if self.composition[key] > 1 else f'{key}'
+                else:  # if an isotope
+                    ele, iso = string_to_isotope(key)
+                    out += f'({iso}{ele})'
+                    out += f'{self.composition[key]}' if self.composition[key] > 1 else ''
+        return out
+
+    @molecular_formula.setter
+    def molecular_formula(self, formula):
+        self.composition = composition_from_formula(formula)
+        self._mf = formula
+
+    @property
+    def molecular_formula_formatted(self):
+        """returns the subscript-formatted molecular formula"""
+        out = ''
+        if 'C' in self.composition:
+            out += f'C{to_subscript(self.composition["C"]) if self.composition["C"] > 1 else "C"}'
+        if 'H' in self.composition:
+            out += f'H{to_subscript(self.composition["H"]) if self.composition["H"] > 1 else "H"}'
+        for key, val in sorted(self.composition.items()):
+            if key not in ['C', 'H']:
+                if key in mass_dict:
+                    out += f'{key}{to_subscript(self.composition[key])}' if self.composition[key] > 1 else f'{key}'
+                else:
+                    ele, iso = string_to_isotope(key)
+                    out += f'{to_superscript(iso)}{ele}'
+                    out += f'{to_subscript(self.composition[key])}' if self.composition[key] > 1 else ''
+        return out
+
+    @property
+    def sf(self):
+        """legacy catch for shorthand 'string formula' attribute"""
+        return self.molecular_formula
+
+    @property
+    def molecular_weight(self):
+        """Molecular weight of the molecule"""
+        mwout = 0
+        for element, number in self.composition.items():
+            try:
+                mass = mass_dict[element]
+                for isotope in mass:
+                    if isotope == 0:
+                        continue
+                    # add every isotope times its natural abundance times the number of that element
+                    mwout += mass[isotope][0] * mass[isotope][1] * number
+            except KeyError:  # if isotope
+                ele, iso = string_to_isotope(element)
+                mwout += mass_dict[ele][iso][0] * number  # assumes 100% abundance if specified
+        return mwout
+
+    @property
+    def mw(self):
+        """legacy catch for shorthand molecular weight"""
+        return self.molecular_weight
+
+    @property
+    def percent_composition(self):
+        """Elemental percent composition of the molecule"""
+        pcompout = {}  # percent composition dictionary
+        for element, number in self.composition.items():
+            try:
+                mass = mass_dict[element]
+                for isotope in mass:
+                    if isotope == 0:
+                        continue
+                    if element not in pcompout:
+                        pcompout[element] = 0.
+                    # add mass contributed by that element
+                    pcompout[element] += mass[isotope][0] * mass[isotope][1] * number
+            except KeyError:  # if isotope
+                ele, iso = string_to_isotope(element)
+                pcompout[str(iso) + ele] = mass_dict[ele][iso][0] * number
+        mw = self.molecular_weight
+        for element in pcompout:  # determines the percent composition of each element
+            try:
+                pcompout[element] = pcompout[element] / mw
+            except ZeroDivisionError:
+                pcompout[element] = 0.
+        return pcompout
+
+    @property
+    def pcomp(self):
+        """legacy catch for shorthand percent composition"""
+        return self.percent_composition
+
+    @property
+    def monoisotopic_mass(self):
+        """An estimation of the exact mass given by the molecular formula. This is likely not accurate for high-mass
+        species"""
+        em = 0.
+        for element, number in self.composition.items():
+            try:
+                em += mass_dict[element][0][0] * number
+            except KeyError:
+                ele, iso = string_to_isotope(element)
+                em += mass_dict[ele][iso][0] * number
+        # # accounts for the mass of an electron (uncomment if this affects your data)
+        # if self.sign == '+':
+        #    em -= (9.10938356*10**-28)*charge
+        # if self.sign == '-':
+        #    em += (9.10938356*10**-28)*charge
+        return em / self.charge
+
+    @property
+    def standard_deviation_comp(self):
+        """
+        cacluates the standard deviation of the isotope pattern of the supplied composition
+        this calculation is based on Rockwood and Van Orden 1996 doi: 10.1021/ac951158i
+        """
+        stdev = 0.
+        for element, number in self.composition.items():
+            meanmass = 0
+            eledev = 0  # elemental deviation
+            mass = mass_dict[element]
+            for isotope in mass:  # calculate weighted average mass
+                if isotope != 0:
+                    meanmass += sum(mass[isotope])  # weighted average mass
+            for isotope in mass:
+                if mass != 0:
+                    eledev += mass[isotope][1] * (mass[isotope][0] - meanmass) ** 2
+            stdev += eledev * number
+        return np.sqrt(stdev)
+
+    def print_details(self):
+        """prints the details of the generated molecule"""
+        sys.stdout.write(f'{self}\n')
+        sys.stdout.write(f'formula: {self.molecular_formula}\n')
+        sys.stdout.write(f'molecular weight: {round(self.molecular_weight, 6)}\n')
+        sys.stdout.write(f'monoisotopic mass: {round(self.monoisotopic_mass, 6)}\n')
+        sys.stdout.write('\n')
+        self.print_percent_composition()
+
+    def print_percent_composition(self):
+        """prints the percent composition in a reader-friendly format"""
+        sys.stdout.write('elemental percent composition:\n')
+        pcomp = self.percent_composition
+        for element, percent in sorted(pcomp.items()):
+            sys.stdout.write(f'{element}: {percent * 100.:6.4}%\n')
+
+
+class IPMolecule(Molecule):
+    _ipmethod = None
+    _gausip = None  # gaussian isotope pattern storage
+    _dropmethod = None
+
+    def __init__(self,
+                 string: (str, dict),
+                 charge=1,
+                 consolidate=3,
+                 criticalerror=3 * 10 ** -6,
+                 decpl=7,
+                 dropmethod=None,
+                 emptyspec=True,
+                 groupmethod='weighted',
+                 ipmethod='hybrid',
+                 keepall=False,
+                 npeaks=5000,
+                 resolution=5000,
+                 threshold=0.01,
+                 save=False,
+                 verbose=VERBOSE,
+                 precalculated=None,
+                 ):
+        """
+        A class with many mass-spectrometric properties such as estimated exact masses, isotope patterns, error
+        estimators, and basic plotting tools.
+
+        :param str string: the molecule name to interpret. See Molecule documentation for more details
+        :param int, str charge: the charge of the molecule (for mass spectrometric applications).
+            This will affect any properties related to the mass to charge
+            ratio. If the charge is specified in the input molecular formula, this will be
+            overridden.
+
+        :param int, float resolution: The resolution of the instrument to simulate when generating the gaussian isotope
+            pattern. This also affects the bounds attribute.
+
+        :param int consolidate: When using the consolidate drop method, consolidate peaks within 10^-*consolidate*
+            of each other. See *dropmethod* for more details.
+
+        :param float criticalerror:
+            The critical error value used for warning the user of a potential calculation error.
+            This only affects the ``print_details()`` function output. Default 3*10**-6 (3 parts per million)
+
+        :param int decpl: The number of decimal places to track while calculating the isotope pattern.
+            Decreasing this will improve efficiency but decrease accuracy. Options: integer.
+
+        :param 'threshold', 'npeaks', 'consolidate' dropmethod: The peak drop method to use if desired.
+            Using a peak dropping method will improve calculation times, but decrease the accuracy of the
+            calculated isotope pattern. 'threshold' drops all peaks below a specified threshold value (specified using
+            the *threshold* keyword argument). 'npeaks' keeps the top *n* peaks, specified by the *npeaks* keyword
+            argument. 'consolidate' combines the intensity of peaks below the threshold value into the
+            nearest peak (within the delta specified by the *consolidate* keyword argument, this method is the most
+            accurate). The new peak *m/z* value is determined by the weighted average of the combined peaks. This will
+            be repeated until the peak is above the threshold or there are no near peaks.
+
+        :param bool emptyspec: Whether to use an empty spectrum obect. Disable this for very large molecules to
+            improve calculation time.
+
+        :param 'weighted', 'centroid' groupmethod: The grouping method to use when calculating the bar isotope pattern
+            from the raw isotope pattern. Weighted calculates the peak locations using the weighted average of the *m/z*
+            and intensity values. Centroid finds the center *m/z* value of a group of peaks.
+
+        :param 'multiplicative', 'combinatorial', 'hybrid', 'cuda', ipmethod: The method to use for determining the isotope
+            pattern. 'multiplicative' multiplies the existing list of intensities by each element. 'combinatorial' uses
+            combinatorics and iterators to calculate each possible combination. 'hybrid' uses combinatorics to calcuate
+            the pattern from each element, then multiplies those together
+
+        :param bool keepall: Whether to keep all peaks calculated in the isotope pattern. When false, this will drop
+            all intensities below 0.0001 after calculating the isotope pattern.
+
+        :param int npeaks: The number of peaks to keep if *dropmethod* is 'npeaks'. See *dropmethod* for more details.
+
+        :param float threshold: The threshold value determining whether or not to drop a peak. Only has an effect if
+            *dropmethod* is not ``None``. See *dropmethod* for more details.
+
+        :param bool verbose: Verbose output. Mostly useful when calculating for large molecules or while debugging.
+
+        """
+        # todo implement apply_threshold method for trimming resulting spectrum
+        self.ipmethod = ipmethod
+        self._spectrum_raw = None  # spectrum object holder
+        self._raw = None  # raw isotope pattern
+        self.bar_isotope_pattern = [[], []]
+        self.criticalerror = criticalerror
+        self.decpl = decpl
+        self.dropmethod = dropmethod
+        self.emptyspec = emptyspec
+        self.consolidate = consolidate
+        self.groupmethod = groupmethod
+        self.keepall = keepall
+        self.npeaks = npeaks
+        self.resolution = resolution
+        self.threshold = threshold
+        self.save = save  # todo reimplement and detail in docstring
+
+        if precalculated is not None:  # if precalculated values were provided, pull and set to prevent recalculation
+            self._comp = precalculated['composition']
+            self._spectrum_raw = precalculated['spectrum']
+            self.bar_isotope_pattern = precalculated['barip']
+            self._raw = precalculated['rawip']
+            self._gausip = precalculated['gausip']
+
+        Molecule.__init__(
+            self,
+            string,
+            charge,
+            verbose=verbose,
+        )
+
+        if save is True:
+            self.save_to_jcamp()
+
+    def __reduce__(self):
+        return (
+            self.__class__,
+            self.__getinitargs__(),
+        )
+
+    def __getinitargs__(self):
+        return (
+            self.composition,
+            self.charge,
+            self.consolidate,
+            self.criticalerror,
+            self.decpl,
+            self.dropmethod,
+            self.emptyspec,
+            self.groupmethod,
+            self.ipmethod,
+            self.keepall,
+            self.npeaks,
+            self.resolution,
+            self.threshold,
+            self.save,
+            self.verbose,
+            {  # precalculated values
+                'composition': self.composition,
+                'spectrum': self.spectrum_raw,
+                'rawip': self.raw_isotope_pattern,
+                'barip': self.bar_isotope_pattern,
+                'gausip': self.gaussian_isotope_pattern if self._gausip is not None else None,
+            },
+        )
+
+    @property
+    def ipmethod(self):
+        return self._ipmethod
+
+    @ipmethod.setter
+    def ipmethod(self, value):
+        if value not in VALID_IPMETHODS:
+            raise ValueError(f'The isotope pattern generation method {value} is not valid. ipmethod must be one '
+                             f'of: {", ".join(VALID_IPMETHODS)}')
+        self._ipmethod = value
+
+    @property
+    def dropmethod(self):
+        return self._dropmethod
+
+    @dropmethod.setter
+    def dropmethod(self, value):
+        if value not in VALID_DROPMETHODS:
+            raise ValueError(f'The intensity dropping method {value} is not valid. dropmethod must be one '
+                             f'of: {", ".join(VALID_DROPMETHODS)}')
+        self._dropmethod = value
+
+    @property
+    def estimated_exact_mass(self):
+        """determines the precise exact mass from the bar isotope pattern"""
+        ind = self.bar_isotope_pattern[1].index(
+            max(self.bar_isotope_pattern[1])
+        )
+        return self.bar_isotope_pattern[0][ind]
+
+    @property
+    def em(self):
+        """Legacy attribute access: estimated exact mass"""
+        return self.estimated_exact_mass
+
+    @property
+    def molecular_weight_estimated(self):
+        """The molecular weight of the molecule estimated by the isotope pattern"""
+        return pattern_molecular_weight(
+            *self.raw_isotope_pattern,
+            charge=self.charge,
+        )
+
+    @property
+    def pmw(self):
+        """Legacy retrieval of pattern molecular weight"""
+        return self.molecular_weight_estimated
+
+    @property
+    def error(self):
+        """Error of the generated isotope pattern"""
+        return molecular_weight_error(
+            calculated=self.molecular_weight_estimated,
+            expected=self.molecular_weight,
+        )
+
+    @property
+    def sigma(self):
+        """Standard deviation of the isotope pattern"""
+        return standard_deviation(self.fwhm)
+
+    @property
+    def nominal_mass(self):
+        """the nominal mass of the molecule"""
+        return int(round(self.em))
+
+    @property
+    def fwhm(self):
+        try:  # try to return from estimated, unless uncalculated, use monoisotopic
+            return self.estimated_exact_mass / self.resolution
+        except (IndexError, ValueError):
+            return self.monoisotopic_mass / self.resolution
+
+    @property
+    def barip(self):
+        """Legacy attribute access"""
+        return self.bar_isotope_pattern
+
+    @property
+    def raw_isotope_pattern(self):
+        if self._raw is None:
+            self._raw = self.spectrum_raw.trim()
+        return self._raw
+
+    @property
+    def rawip(self):
+        """Legacy attribute access"""
+        return self.raw_isotope_pattern
+
+    @property
+    def spectrum_raw(self):
+        return self._spectrum_raw
+
+    @property
+    def gaussian_isotope_pattern(self):
+        if self._gausip is None:  # if it hasn't been calculated, generate
+            self._gausip = gaussian_isotope_pattern(
+                self.bar_isotope_pattern,
+                self.fwhm
+            )
+        return self._gausip
+
+    @property
+    def gausip(self):
+        """Legacy retrieval"""
+        return self.gaussian_isotope_pattern
+
+    @property
+    def composition(self):
+        return self._comp
+
+    @composition.setter
+    def composition(self, dct):
+        if type(dct) != dict:
+            raise TypeError('The composition must be a dictionary')
+        if dct == self.composition:  # do nothing if the composition dictionary is the same as current
+            return
+        dct = copy.copy(dct)
+        dct = abbreviations(dct)  # check for and convert abbreviations
+        if 'charge' in dct:  # if charge was specified in the formula
+            self.charge, self.sign = interpret_charge(dct['charge'])
+            del dct['charge']
+        check_in_mass_dict(dct)  # check in mass dictionary
+        self._comp = dct  # set local dictionary
+        self._calculate_ips()  # calculate isotope patterns
+        # todo save to pickle
+
+    @property
+    def isotope_pattern_standard_deviation(self):
+        """
+        Cacluates the standard deviation of the isotope pattern of the supplied composition
+        this calculation is based on Rockwood and Van Orden 1996 doi: 10.1021/ac951158i
+        """
+        return np.sqrt(
+            sum([
+                intensity * (mz - self.pmw) ** 2  # weighted distance from the estimated molecular weight
+                for mz, intensity in zip(*self.raw_isotope_pattern)
+            ])
+        )
+
+    @property
+    def bounds(self):
+        """Convenient attribute access to default bounds. Call calculate_bounds for additional options. """
+        return self.calculate_bounds()
+
+    @property
+    def per_peak_bounds(self):
+        """Convenient attribute access to per-peak bounds. Call calculate_bounds for additional options. """
+        return self.calculate_bounds(perpeak=True)
+
+    def calculate_bounds(
+            self,
+            conf: float = 0.95,
+            perpeak: bool = False,
+            threshold: float = 0.01
+    ):
+        """
+        Calculates the *m/z* bounds of the isotope pattern of the molecule object based
+        on a confidence interval and the *m/z* values of the bar isotope pattern.
+        This can be used to automatically determine the integration bounds required to
+        contain XX% of the counts associated with that molecule in a mass spectrum.
+
+        :param conf: The confidence interval to use for calculating the bounds.
+            e.g. *0.95* corresponds to a 95% confidence interval.
+        :param perpeak: Whether or not to return the bounds required to integrate each
+            peak of the isotope pattern individually.
+            This can be useful in a very noisy mass spectrum to avoid
+            baseline noise within the integration interval.
+        :param threshold: The threshold used to determine whether a peak should be
+            included in the bounds.
+        :return: bounds.
+            If *perpeak* is False, this will return a two item list
+            corresponding to the start and end *m/z* bounds.
+            If *perpeak* is True, returns a dictionary of bounds with
+            the key format of
+            ``dict[parent m/z value]['bounds'] = [start m/z, end m/z]``
+
+        **Examples**
+
+        To determine the integration bounds of C61H51IP3Pd: 
+
+        ::
+
+            >>> mol = IPMolecule('C61H51IP3Pd')
+            >>> mol.calculate_bounds(0.95)
+            [1104.9458115053008, 1116.3249999321531]
+
+            >>> mol.calculate_bounds(0.99)
+            [1104.8877964620444, 1116.3830149754094]
+
+            >>> mol.calculate_bounds(0.95, True)
+            {'1105.1304418': {'bounds': (1104.9458115053008, 1105.3150720946992)},
+            '1106.13382235': {'bounds': (1105.9491920547823, 1106.3184526441808)},
+            '1107.12903188': {'bounds': (1106.9444015896975, 1107.3136621790959)},
+            '1108.13051519': {'bounds': (1107.9458848935217, 1108.3151454829201)},
+            '1109.13037767': {'bounds': (1108.9457473736579, 1109.3150079630564)},
+            '1110.13288962': {'bounds': (1109.9482593265234, 1110.3175199159218)},
+            '1111.13024042': {'bounds': (1110.9456101206658, 1111.3148707100643)},
+            '1112.13263766': {'bounds': (1111.9480073654438, 1112.3172679548422)},
+            '1113.13193341': {'bounds': (1112.9473031156144, 1113.3165637050129)},
+            '1114.13415503': {'bounds': (1113.9495247326277, 1114.3187853220261)},
+            '1115.13715205': {'bounds': (1114.9525217596001, 1115.3217823489986)},
+            '1116.14036964': {'bounds': (1115.9557393427547, 1116.3249999321531)}}
+
+        """
+        if self.verbose is True:
+            sys.stdout.write('Calculating bounds from simulated gaussian isotope pattern')
+        threshold = threshold * max(self.bar_isotope_pattern[1])
+        tempip = [[], []]
+        for ind, inten in enumerate(self.bar_isotope_pattern[1]):  # checks for intensities above threshold
+            if inten >= threshold:
+                tempip[0].append(self.bar_isotope_pattern[0][ind])
+                tempip[1].append(self.bar_isotope_pattern[1][ind])
+        if perpeak is True:  # if per-peak bounds are called for
+            out = {}
+            for mz in tempip[0]:
+                out[str(mz)] = {}
+                out[str(mz)]['bounds'] = stats.norm.interval(conf, mz, scale=self.sigma)
+        else:  # a general range that covers the entire isotope pattern
+            out = [stats.norm.interval(conf, tempip[0][0], scale=self.sigma)[0],
+                   stats.norm.interval(conf, tempip[0][-1], scale=self.sigma)[1]]
+        if self.verbose is True:
+            if perpeak is False:
+                sys.stdout.write(': %.3f-%.3f' % (out[0], out[1]))
+            sys.stdout.write(' DONE\n')
+        return out
+
+    def _calculate_ips(self):
+        """Call to calculate isotope patterns based on the specified parameters"""
+        # generates the raw isotope pattern (charge of 1)
+        if self.ipmethod == 'combinatorics':
+            calculator = isotope_pattern_combinatoric
+        elif self.ipmethod == 'multiplicative':
+            calculator = isotope_pattern_multiplicative
+        elif self.ipmethod == 'hybrid':
+            calculator = isotope_pattern_hybrid
+        # elif self.ipmethod == 'cuda':
+        #     calculator = isotope_pattern_cuda
+        elif self.ipmethod == 'isospec':
+            calculator = isotope_pattern_isospec
+        else:
+            raise ValueError(f'The isotope pattern method {self.ipmethod} is not valid')
+
+        self._spectrum_raw = calculator(
+            self.composition,
+            decpl=self.decpl,
+            verbose=self.verbose,
+            dropmethod=self.dropmethod,
+            threshold=self.threshold,
+            npeaks=self.npeaks,
+            consolidate=self.consolidate,
+            fwhm=self.fwhm,
+        )
+
+        # apply charge
+        self.spectrum_raw.charge = self.charge
+
+        # generate bar isotope pattern based on the raw pattern
+        self.bar_isotope_pattern = bar_isotope_pattern(
+            self.raw_isotope_pattern,
+            self.fwhm
+        )
+
+    def compare(self, exp):
+        """
+        Compares a provided mass spectrum (experimental) to the simulated gaussian
+        isotope pattern. Returns a standard error of the regression as an assessment
+        of the goodness of fit.
+
+        **Parameters**
+
+        exp: *list*
+            The experimentally acquired mass spectra provided as a paired list of lists
+            ``[[m/z values],[intensity values]]``
+
+
+        **Returns**
+
+        Standard error of the regression: *float*
+            A measure of the average distance between the experimental and predicted
+            values. Lower is better, although this is a qualitative assessment.
+
+        """
+
+        def sumsquare(lst):
+            """calculates the sum of squares"""
+            ss = 0
+            for val in lst:
+                ss += val ** 2
+            return ss
+        # TODO fix this method (worthwhile?)
+        #   - 2015-09-15 06 gives a bounds error
+        yvals = []
+        res = []
+        maxy = float(max(exp[1]))
+        if maxy == 0.:
+            return 'could not calculate'
+        for ind, val in enumerate(exp[1]):  # normalize y values
+            yvals.append(float(val) / maxy * 100.)
+        # avgy = sum(exp[1])/len(exp[1])
+        for ind, mz in enumerate(exp[0]):
+            if min(self.gausip[0]) < mz < max(self.gausip[0]):  # if within isotope pattern
+                nspind = self.spectrum_raw.index(mz)  # calculate index
+                if self.spectrum_raw.y[nspind] is not None:  # if the predicted intensity is not None
+                    # difference between observed and predicted (residuals)
+                    res.append(yvals[ind] - self.spectrum_raw.y[nspind])
+                    # tot.append(self.spec.y[nspind]-avgy) # difference between predicted and mean
+        # rsqrd = 1-(sumsquare(res)/sumsquare(tot)) # r-squared value (apparently not applicable to non-linear fits)
+        return np.sqrt(sumsquare(res) / len(res))
+
+    def compare_exact_mass(self, mass, use='est'):
+        """
+        Compares the provided mass to the exact mass of the calculated molecule.
+
+        **Parameters**
+
+        mass: *float*
+            experimental mass to compare
+
+        use: est or mi (optional)
+            Whether to compare the estimated exact mass or the monoisotopic
+            mass to the provided value. Default: est
+
+        **Returns**
+
+        relative error: *float*
+            The relative error of the provided mass to the exact mass
+        """
+        if use == 'est':
+            delta = mass - self.em
+            return delta / self.em * 10 ** 6
+        elif use == 'mi':
+            delta = mass - self.mimass
+            return delta / self.mimass * 10 ** 6
+
+    def load_from_pickle(self, customfile=None):
+        """loads data from pickle"""
+        raise NotImplementedError('This functionality has been temporarily disabled due to significant changes in the '
+                                  'class. ')
+        # TODO specify hierachy and pull if better method than specified
+        if customfile is None:  # if no directory was specified, use current working directory
+            customfile = os.path.join(
+                os.getcwd(),
+                'molecules',
+                self.molecular_formula(self.comp) + '.mol',
+            )
+        if os.path.isfile(customfile) is True:
+            if self.ipmethod.lower() == 'multiplicative':
+                key = 'multiplicative'
+            elif self.ipmethod.lower() == 'combinatorics':
+                key = 'combinatorics'
+            if self.dropmethod is not None:
+                key += ' %s' % self.dropmethod
+            subkey = self.decpl  # decimal places
+            with open(customfile, 'rb') as targetfile:
+                incoming = pickle.load(targetfile)
+                if key in incoming and subkey in incoming[key]:
+                    items = incoming[key][subkey]
+                    strcharge = '%s%d' % (self.sign, self.charge)
+                    if items['charge'] == strcharge:  # if the charge combination matches
+                        print('Loading data from saved file %s' % customfile)
+                        self.bar_isotope_pattern = items['bar isotope pattern']
+                        self.raw_isotope_pattern = items['raw isotope pattern']
+                        self.gausip = items['gaussian isotope pattern']
+                        self.mw = items['mw']
+                        self.mimass = items['monoisotopic mass']
+                        self.em = items['estimated exact mass']
+                        self.pcomp = items['percent composition']
+                        self.error = items['error']
+                        self.fwhm = items['full width at half max']
+                        self.sigma = items['standard deviation']
+                        self.sf = self.molecular_formula(self.comp)
+                        return True
+        return False  # if the exact match was not found, False
+
+    def print_details(self):
+        """prints the details of the generated molecule"""
+        sys.stdout.write(f'{self}\n')
+        sys.stdout.write(f'formula: {self.molecular_formula}\n')
+        sys.stdout.write(f'molecular weight: {round(self.molecular_weight, self.decpl)}\n')
+        sys.stdout.write(f'monoisotopic mass: {round(self.monoisotopic_mass, self.decpl)}\n')
+        sys.stdout.write(f'estimated exact mass: {round(self.estimated_exact_mass, self.decpl)}\n')
+        sys.stdout.write(f'error: {self.error:.3}\n')
+        if abs(self.error) > self.criticalerror:
+            sys.stdout.write(f'WARNING: Error is greater than {self.criticalerror}!\n')
+        sys.stdout.write('\n')
+        self.print_percent_composition()
+
+    def plot_bar_pattern(self):
+        """plots and shows the isotope bar pattern"""
+        fwhm = self.em / self.resolution
+        pl.bar(self.bar_isotope_pattern[0], self.bar_isotope_pattern[1], width=fwhm, align='center')
+        pl.xlabel('m/z', style='italic')
+        pl.ylabel('normalized intensity')
+        pl.ticklabel_format(useOffset=False)
+        pl.show()
+
+    def plot_gaussian_pattern(self, exp=None):
+        """plots and shows the simulated gaussian isotope pattern"""
+        pl.plot(*self.gaussian_isotope_pattern, linewidth=1)
+        if exp is not None:  # plots experimental if supplied
+            y = []
+            maxy = max(exp[1])
+            for val in exp[1]:  # normalize
+                y.append(val / maxy * 100)
+            comp = self.compare(exp)
+            pl.plot(exp[0], exp[1])
+            pl.text(max(exp[0]), 95, 'SER: ' + str(comp))
+            # pl.fill_between(x,self.gausip[1],exp[1],where= exp[1] =< self.gausip[1],interpolate=True, facecolor='red')
+        pl.fill(self.gausip[0], self.gausip[1], alpha=0.25)  # ,facecolor='blue')
+        pl.xlabel('m/z', style='italic')
+        pl.ylabel('normalized intensity')
+        pl.ticklabel_format(useOffset=False)
+        pl.show()
+
+    def plot_raw_pattern(self):
+        """plots and shows the raw isotope pattern (with mass defects preserved)"""
+        pl.bar(self.raw_isotope_pattern[0], self.raw_isotope_pattern[1], width=self.fwhm)
+        pl.xlabel('m/z', style='italic')
+        pl.ylabel('normalized intensity')
+        pl.ticklabel_format(useOffset=False)
+        pl.show()
+
+    def save_to_jcamp(self, name=None):
+        """
+        Saves the bar isotope pattern to JCAMP-DX file format
+        Output type roughly based on the output from ChemCalc.org
+        see http://www.jcamp-dx.org/protocols.html for details on the JCAMP-DX specifications.
+
+        :param name: optional name for the output file (default is {molecular formula}.jdx)
+        """
+        if os.path.isdir(os.path.join(os.getcwd(), 'molecules')) is False:
+            os.makedirs(os.path.join(os.getcwd(), 'molecules'))
+        if name is None:  # if no name supplied, auto generate
+            name = self.molecular_formula
+            name += '.jdx'
+        elif name.lower().endswith('.jdx') is False:
+            name += '.jdx'
+
+        if self.verbose is True:
+            sys.stdout.write(f'Saving {name} to {os.path.join(os.getcwd(), "molecules")}')
+            sys.stdout.flush()
+
+        header = [  # comment lines to put before data
+            # header items
+            f'TITLE= {self.molecular_formula}',
+            'JCAMP-DX= 5.01',
+            'DATA TYPE= MASS SPECTRUM',
+            'DATA CLASS= PEAK TABLE',
+            f'ORIGIN= Calculated spectrum from PythoMS {self.__class__} class https://github.com/larsyunker/PythoMS',
+            f'OWNER= {os.getlogin()}',
+            f'SPECTROMETER/DATA SYSTEM= {self.__class__} class {self.ipmethod} method',
+            f'CREATION DATE= {datetime.now().astimezone()}',
+            'XUNITS= M/Z',
+            'YUNITS= RELATIVE ABUNDANCE',
+            f'NPOINTS= {len(self.bar_isotope_pattern[0])}',
+            f'FIRSTX= {self.bar_isotope_pattern[0][0]}',
+            f'LASTX= {self.bar_isotope_pattern[0][1]}',
+
+            # user defined labels
+            f'$Molecular weight= {self.molecular_weight}',
+            f'$Resolution= {self.res}',
+            f'$Threshold= {self.threshold if self.threshold is not None else ""}',
+            f'$Error= {self.error:.2}',
+            f'$Nominal mass = {self.nominal_mass}',
+            f'$Monoisotopic mass= {self.monoisotopic_mass}',
+            f'$Estimated exact mass= {self.estimated_exact_mass}',
+        ]
+        with open(os.path.join(os.getcwd(), "molecules", name), 'wt') as outfile:
+            for line in header:  # write header lines
+                if len(line) != 0:
+                    outfile.write(f'##{line}\n')
+            outfile.write('##PEAK TABLE= (XY..XY)\n')
+            for mz, intensity in zip(*self.bar_isotope_pattern):  # write data lines
+                outfile.write(f'{mz}, {intensity}\n')
+            outfile.write('##END=\n')
+
+    def save_to_pickle(self, name=None):
+        """
+        Saves the molecule's properties to pickle
+        """
+        if os.path.isdir(os.path.join(os.getcwd(), 'molecules')) is False:
+            os.makedirs(os.path.join(os.getcwd(), 'molecules'))
+        if name is None:  # if no name supplied, auto generate
+            name = self.molecular_formula
+            name += '.mol'
+        elif name.lower().endswith('.mol') is False:
+            name += '.mol'
+
+        if self.verbose is True:
+            sys.stdout.write(f'Saving {name} to {os.path.join(os.getcwd(), "molecules")}')
+            sys.stdout.flush()
+
+        with open(os.path.join(os.getcwd(), "molecules", name), 'wb') as outfile:
+            pickle.dump(
+                self,
+                outfile
+            )
+
+        # todo differentiate between generation methods in the output files
+
+
+if __name__ == '__main__':  # for testing and troubleshooting
+    # st.printstart()
+    mol = IPMolecule(
+        'L2PdAr+I',
+        # charge= 2, # specify charge (if not specified in formula)
+        # res=1050000, # specify spectrometer resolution (default 5000)
+        verbose=True,
+        # decpl=10,
+        # dropmethod='threshold',
+        # threshold=0.00001,
+        # ipmethod='hybrid',
+        ipmethod='combinatorics',
+        # keepall=True,
+    )
+    # mol.print_details()
+    # st.printelapsed()
+    # st.printprofiles()

lib/pythoms/progress.py

@@ -0,0 +1,172 @@
+import sys
+
+
+class Progress(object):
+    def __init__(self,
+                 first: int = 1,  # the initial iteration
+                 last: int = 10,  # the final iteration
+                 string: str = 'Processing iteration',  # the string prefix that is returned
+                 fraction: bool = True,  # whether to output the fraction of things completed
+                 rng: bool = False,  # whether to output the range that the iterations span
+                 percent: bool = True,  # whether to show percent completion
+                 hash: bool = False,  # whether to have a hash bar for progress
+                 hashnum: int = 20,  # width of the hash progress bar
+                 endmsg: str = 'DONE',  # end message
+                 writeevery: int = 1,  # write output every n calls
+                 ):
+        """
+        A progress output object for use when performing a large number of
+        repititions of the same process and informing the user of progress
+        is desired.
+
+        :param first: The first iteration of the process.
+        :param last: The last iteration of the process.
+        :param string: The string prefix that is written (this is usually information about
+            the process.
+        :param fraction: Whether the fractional progress should be written in the printed string. e.g. 1/10.
+        :param rng: Whether the iteration range should be written in the printed string.
+            e.g. (1-10)
+        :param percent: Whether the percent progress should be written in the printed string.
+            e.g. 10.0%
+        :param hash: Whether a hash-type progress bar should be written in the printed
+            string. e.g. |#####       | Default: False
+        :param hashnum: If *hashes* is True, this is the width of the hash-type progress bar.
+        :param endmsg: The message that is printed when the `fin()` method is called.
+        :param writeevery: Write an output every n calls. This can be used if an iteration is
+            rapid and printing every output is not particularly useful.
+        
+        **Examples**
+        
+        ::
+        
+            >>> prog = Progress()
+            >>> prog.write(1)
+            Processing iteration #1/10 0.0%
+            
+            >>> prog.write(7)
+            Processing iteration #7/10 66.7%
+            
+            >>> for i in range(1,11):
+                    prog.write(i)
+                prog.fin()
+            Processing iteration #10/10 100.0% DONE
+                
+        
+        """
+        self.first = first
+        self.last = last
+        self.string = string
+        self.fraction = fraction
+        self.rng = rng
+        self.percent = percent
+        self.hash = hash
+        self.hashnum = hashnum
+        self.endmsg = endmsg
+        self.writeevery = writeevery
+        self.wr = sys.stdout.write
+        self.fl = sys.stdout.flush
+        self.count = 0
+        self.strlen = 0
+        self.current = 0  # current state
+        self.spinner = ['|', '/', '-', '\\']
+
+    def __str__(self):
+        """returns the progress string at the current iteration"""
+        return self.write(self.current, True)
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}({self.string} {self.first}-{self.last})'
+
+    def __getitem__(self, x):
+        """
+        Prints and returns the progress string at iteration x
+        This accomplishes the same thing as write()
+        """
+        return self.write(x)
+
+    @property
+    def perc(self):
+        try:
+            return round(
+                (float(self.current) - self.first)
+                / float(self.last - self.first)
+                * 100.,
+                1
+            )
+        except ZeroDivisionError:
+            return 0.
+
+    def write(self, current, suppress=False):
+        """
+        Writes the progress of the iteration
+
+        :param current: current iteration
+        :param suppress: suppress output
+        :return: formatted output string
+        """
+        self.count += 1  # keep count
+        if self.writeevery != 1:
+            # if the counter does not match the write, bail out
+            if self.count != self.last and self.count % self.writeevery != 0:
+                return None
+        self.current = current  # saves the current state
+        string = f'{self.string}'  # begin the string
+        if self.fraction is True:
+            string += f' #{current - self.first + 1}/{self.last - self.first + 1}'
+        if self.rng is True:
+            string += f' ({self.first}-{self.last})'
+        if self.percent is True:
+            string += f' {self.perc}%'
+        if self.hash is True:
+            string += self.hashes()
+        # create space filler if output has somehow shrunk below the length of the previous output
+        if len(string) < self.strlen:
+            string += ' ' * (self.strlen - len(string))
+        self.strlen = len(string)
+        # does not write string to terminal, instead returns the generated progress string
+        if suppress is True:
+            return string
+        try:
+            self.wr(f'\r{string}')
+        # a catch for I/O errors that sometimes pop up for large iteration processes
+        except ValueError:
+            pass
+        return string
+
+    def hashes(self):
+        """generates the hash-type progress bar if called for"""
+        out = ' |'
+        num = int(self.perc / 100. * self.hashnum)
+        out += '#' * num  # add completed
+        if num < self.hashnum:  # add spinner
+            out += self.spinner[self.count % 4]
+        out += ' ' * (self.hashnum - len(out) + 2)  # add still to go
+        out += '|'
+        return out
+
+    def fin(self, msg=None):
+        """
+        writes the completion message of the object and starts a new line
+        if msg is specified, that message will be written instead of the object's 
+        completion message
+        """
+        if msg is None:
+           msg = self.endmsg
+        self.wr(f' {msg}\n')
+        self.fl()  # flush output
+
+
+if __name__ == '__main__':  # for testing and troubleshooting
+    first = 1
+    finish = 255
+    prog = Progress(
+        first=first,
+        last=finish,
+        # hashes = True,
+    )
+    import time
+
+    for i in range(first, finish + 1):
+        prog.write(i)
+        time.sleep(0.01)
+    prog.fin()

lib/pythoms/scripttime.py

@@ -0,0 +1,146 @@
+"""
+ScriptTime class
+records timepoints in a python script
+
+new:
+    functional
+    added periter to print the average time per supplied number of iterations
+    created formattime to handle times less than 1 ms
+    removed secondstostr and replaced all calls with formattime
+    added function profiling
+    added toggle for profiling
+    changed from time.time() to time.clock() which seems to give much higher resolution
+    ---1.0---
+    removed timepoint function (now redundant with profiling capability)
+    updated print profile data function to be more detailed and easier to read
+    ---1.1---
+    ---1.2
+
+to add:
+    use time.time() in unix and time.clock() in windows
+"""
+import sys
+import time
+import numpy as np
+import datetime
+
+
+class ScriptTime(object):
+    def __init__(self, profile=False):
+        """
+        Class for storing timepoints in a python script
+        profile toggles whether the profiling functionality of the class will operate
+        """
+        self._start_seconds = time.time()  # start time (seconds since epoch)
+        self._end_seconds = None  # end time (seconds since epoch)
+        self._start_clock = time.localtime()  # start clock time
+        self._end_clock = None  # end clock time
+        self.profile = profile  # toggle for profiling functions
+        self.profiles = {}
+
+    def __str__(self):
+        """The string that is returned when printed"""
+        return f'{self.__class__.__name__} initiated at {self.start_time}'
+
+    def __repr__(self):
+        """The representation that is returned"""
+        return f'{self.__class__.__name__}({self.start_time})'
+
+    @property
+    def start_time(self):
+        return time.strftime("%I:%M:%S %p", self._start_clock)
+
+    @property
+    def end_time(self):
+        if self._end_clock is None:
+            return None
+        return time.strftime("%I:%M:%S %p", self._end_clock)
+
+    @property
+    def elapsed_time(self):
+        if self._end_seconds is None:
+            return time.time() - self._start_seconds
+        return self._end_seconds - self._start_seconds
+
+    def clearprofiles(self):
+        """clears the profile data"""
+        self.profiles = {}
+
+    def formattime(self, t):
+        """
+        Formats a time value in seconds to the appropriate string. This is now included for legacy support.
+        roughly based on formattime 
+        """
+        return str(datetime.timedelta(t))
+
+    def periter(self, num):
+        """
+        calculated elapsed time per unit iteration (designed for timing scripts)
+        """
+        sys.stdout.write('Average time per iteration: %s\n' % (self.formattime(self.elapsed_time / float(num))))
+
+    def printelapsed(self):
+        """prints the elapsed time of the object"""
+        if self._end_seconds is None:
+            self.triggerend()
+        sys.stdout.write(f'Elapsed time: {datetime.timedelta(seconds=self.elapsed_time)}\n')
+
+    def printend(self):
+        """prints the end time and the elapsed time of the object"""
+        if self._end_seconds is None:
+            self.triggerend()
+        sys.stdout.write(f'End time: {self.end_time} (elapsed: {datetime.timedelta(seconds=self.elapsed_time)})\n')
+
+    def printprofiles(self):
+        """prints the data for the profiled functions"""
+        sys.stdout.write('\nFunction profile data:\n')
+        sys.stdout.write(
+            '%15s  %6s  %13s  %13s  %13s  %13s\n' % ('function', 'called', 'avg', 'standard_deviation', 'max', 'min'))
+        for fname, data in self.profiles.items():
+            avg = sum(data[1]) / len(data[1])
+            sys.stdout.write('%15s  %6d  %13s  %13s  %13s  %13s\n' % (
+                fname,
+                data[0],
+                self.formattime(avg),
+                self.formattime(np.sqrt(sum((i - avg) ** 2 for i in data[1]) / (len(data[1]) - 1))),
+                self.formattime(max(data[1])),
+                self.formattime(min(data[1]))
+            ))
+
+    def printstart(self):
+        """prints the start (trigger) time of the object"""
+        sys.stdout.write('Start time: %s\n' % (time.strftime('%I:%M:%S %p', self._start_clock)))
+
+    def profilefn(self, fn):
+        """generates a profiled version of the supplied function"""
+
+        # from functools import wraps # unsure why these lines are present
+        # @wraps(fn)
+        def with_profiling(*args, **kwargs):
+            """decorates function with profiling commands"""
+            start_time = time.perf_counter()  # time that the function was called
+            ret = fn(*args, **kwargs)  # calls the function
+
+            elapsed_time = time.perf_counter() - start_time  # end time of the function
+            if fn.__name__ not in self.profiles:  # generates a dictionary key based on the function name if not present
+                self.profiles[fn.__name__] = [0, []]  # [number of times called, [list of durations]]
+            self.profiles[fn.__name__][0] += 1
+            self.profiles[fn.__name__][1].append(elapsed_time)
+            return ret  # returns the calculated call of the function
+
+        if self.profile is True:
+            return with_profiling  # returns the decorated function
+        else:
+            return fn
+
+    def triggerend(self):
+        """triggers endpoint and calculates elapsed time since start"""
+        self._end_seconds = time.time()
+        self._end_clock = time.localtime()
+
+
+if __name__ == '__main__':
+    st = ScriptTime()
+    time.sleep(2.)
+    st.triggerend()
+    st.printend()

lib/pythoms/senko_charge_assignment.py

@@ -0,0 +1,874 @@
+"""
+Automated Assignment of Charge States from Resolved Isotopic Peaks
+
+Implementation of methods from:
+Senko, M.W., Beu, S.C., and McLafferty, F.W. (1995)
+"Automated Assignment of Charge States from Resolved Isotopic Peaks for Multiply Charged Ions"
+J. Am. Soc. Mass Spectrom., 6, 52-56
+
+This module provides three complementary algorithms for charge state determination:
+1. Patterson Function - Best for low charge states (z < 5) with high S/N
+2. Fourier Transform - Best for high charge states (z > 5) with low resolving power
+3. Combination Method - Multiplies Patterson × Fourier (recommended for all cases)
+
+The methods achieved >95% accuracy in the original paper and work even when
+isotope clusters overlap.
+"""
+
+import numpy as np
+from scipy.interpolate import interp1d
+from scipy.signal import find_peaks
+
+
+def patterson_function(mz_array, intensity_array, charge_range=(1, 10), step_size=1/3):
+    """
+    Patterson function for charge state determination.
+
+    Best for low charge states (z < 5) with high S/N and resolving power.
+
+    From the paper:
+    P(ΔM) = Σ f(Mi - ΔM/2) * f(Mi + ΔM/2)
+
+    where ΔM is the inverse of the charge being evaluated.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        m/z values of the isotope envelope
+    intensity_array : np.ndarray
+        Intensity values
+    charge_range : tuple
+        (min_charge, max_charge) to test
+    step_size : float
+        Step size for charge evaluation (default 1/3 for smooth maps)
+
+    Returns:
+    --------
+    charges : np.ndarray
+        Array of charge values tested
+    patterson_map : np.ndarray
+        Patterson function values for each charge
+    """
+    min_z, max_z = charge_range
+
+    # Create interpolation function for intensity
+    # Use linear interpolation between data points
+    interp_func = interp1d(mz_array, intensity_array, kind='linear',
+                           bounds_error=False, fill_value=0.0)
+
+    # Generate charge values to test (with fractional steps for smooth map)
+    charges = np.arange(min_z - 1/3, max_z + 1, step_size)
+    patterson_map = np.zeros(len(charges))
+
+    for idx, z in enumerate(charges):
+        if z < 1:
+            continue
+
+        delta_m = 1.0 / z  # Spacing for this charge state
+
+        # Calculate Patterson function
+        # Sum over all m/z points
+        patterson_sum = 0.0
+        for mz in mz_array:
+            # Get intensities at mz - delta_m/2 and mz + delta_m/2
+            I_minus = interp_func(mz - delta_m / 2)
+            I_plus = interp_func(mz + delta_m / 2)
+            patterson_sum += I_minus * I_plus
+
+        patterson_map[idx] = patterson_sum
+
+    return charges, patterson_map
+
+
+def fourier_function(mz_array, intensity_array, charge_range=(1, 10)):
+    """
+    Fourier transform method for charge state determination.
+
+    Best for high charge states (z > 5) with low resolving power.
+    Produces sharper peaks than Patterson method.
+
+    The FFT considers isotopic peaks in terms of their frequency of occurrence,
+    not their spacing. The repetitive spacing produces a maximum in the frequency domain.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        m/z values of the isotope envelope
+    intensity_array : np.ndarray
+        Intensity values
+    charge_range : tuple
+        (min_charge, max_charge) to test
+
+    Returns:
+    --------
+    charges : np.ndarray
+        Array of charge values
+    fourier_map : np.ndarray
+        Fourier transform magnitude for each charge
+    """
+    min_z, max_z = charge_range
+
+    # Baseline correction - subtract minimum
+    baseline = np.min(intensity_array)
+    corrected_intensity = intensity_array - baseline
+
+    # Pad data to next power of 2 for efficient FFT
+    n_points = len(corrected_intensity)
+    n_padded = 2 ** int(np.ceil(np.log2(n_points)))
+    padded_intensity = np.zeros(n_padded)
+    padded_intensity[:n_points] = corrected_intensity
+
+    # Perform FFT
+    fft_result = np.fft.fft(padded_intensity)
+    fft_magnitude = np.abs(fft_result)
+
+    # Get frequency axis
+    # The m/z spacing
+    mz_spacing = np.mean(np.diff(mz_array))
+    frequencies = np.fft.fftfreq(n_padded, d=mz_spacing)
+
+    # Convert frequencies to charge states
+    # Isotope spacing = 1.003 / z (approximately 1/z)
+    # Frequency = 1 / spacing = z / 1.003
+    # So: z ≈ frequency * 1.003
+
+    # Map FFT results to charge states
+    charges = np.arange(min_z, max_z + 1)
+    fourier_map = np.zeros(len(charges))
+
+    for idx, z in enumerate(charges):
+        # Expected frequency for this charge
+        expected_freq = z / 1.003
+
+        # Find closest frequency in FFT
+        freq_idx = np.argmin(np.abs(frequencies - expected_freq))
+        fourier_map[idx] = fft_magnitude[freq_idx]
+
+    return charges, fourier_map
+
+
+def combination_function(mz_array, intensity_array, charge_range=(1, 10)):
+    """
+    Combination method: Patterson × Fourier.
+
+    RECOMMENDED for all cases. Achieves >95% accuracy.
+
+    From the paper:
+    C(z) = F(z) * P(z)
+
+    Only the true maximum should be present in both maps, and thus should be
+    most abundant in the combination map. This reduces false maxima from both methods.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        m/z values of the isotope envelope
+    intensity_array : np.ndarray
+        Intensity values
+    charge_range : tuple
+        (min_charge, max_charge) to test
+
+    Returns:
+    --------
+    charges : np.ndarray
+        Array of charge values
+    combination_map : np.ndarray
+        Combined Patterson × Fourier values
+    patterson_map : np.ndarray
+        Patterson function values
+    fourier_map : np.ndarray
+        Fourier transform values
+    """
+    # Get Patterson map
+    charges_p, patterson_map = patterson_function(mz_array, intensity_array, charge_range)
+
+    # Get Fourier map (interpolate to match Patterson charges)
+    charges_f, fourier_map_raw = fourier_function(mz_array, intensity_array, charge_range)
+
+    # Interpolate Fourier to match Patterson charge grid
+    fourier_interp = interp1d(charges_f, fourier_map_raw, kind='linear',
+                              bounds_error=False, fill_value=0.0)
+    fourier_map = fourier_interp(charges_p)
+
+    # Normalize both maps to [0, 1]
+    if np.max(patterson_map) > 0:
+        patterson_norm = patterson_map / np.max(patterson_map)
+    else:
+        patterson_norm = patterson_map
+
+    if np.max(fourier_map) > 0:
+        fourier_norm = fourier_map / np.max(fourier_map)
+    else:
+        fourier_norm = fourier_map
+
+    # Multiply the two maps
+    combination_map = patterson_norm * fourier_norm
+
+    return charges_p, combination_map, patterson_norm, fourier_norm
+
+
+def find_envelope_boundaries(mz_array, intensity_array, valley_threshold=0.02):
+    """
+    Find isotope envelope boundaries by locating global apex and global valleys.
+
+    Algorithm:
+    1. Find the global apex (highest point)
+    2. Smooth the signal to get envelope shape (ignore local isotope oscillations)
+    3. Go left/right from apex until smoothed intensity drops below threshold
+
+    This finds the true envelope boundaries, not local valleys between isotope peaks.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        m/z values
+    intensity_array : np.ndarray
+        Intensity values
+    valley_threshold : float
+        Valley is found when intensity drops below this fraction of max (default 0.02 = 2%)
+
+    Returns:
+    --------
+    dict with:
+        - 'global_apex_idx': int, index of global apex
+        - 'left_valley_idx': int, index of left boundary
+        - 'right_valley_idx': int, index of right boundary
+        - 'envelope_mz': np.ndarray, m/z values within envelope
+        - 'envelope_intensity': np.ndarray, intensity values within envelope
+    """
+    if len(mz_array) < 3:
+        return {
+            'global_apex_idx': 0,
+            'left_valley_idx': 0,
+            'right_valley_idx': len(mz_array) - 1,
+            'envelope_mz': mz_array,
+            'envelope_intensity': intensity_array
+        }
+
+    # Find global apex
+    global_apex_idx = np.argmax(intensity_array)
+    max_intensity = intensity_array[global_apex_idx]
+    threshold = max_intensity * valley_threshold
+
+    # Smooth the signal to find envelope shape
+    # Use a wider window to smooth over isotope peak oscillations
+    mz_span = mz_array[-1] - mz_array[0]
+    points_per_mz = len(mz_array) / mz_span if mz_span > 0 else 10
+    window_size = max(5, int(points_per_mz * 0.5))  # ~0.5 m/z window
+    if window_size % 2 == 0:
+        window_size += 1
+    window_size = min(window_size, len(intensity_array) // 3)  # Don't make window too big
+
+    # Pad and smooth using convolution
+    half_win = window_size // 2
+    padded = np.pad(intensity_array, half_win, mode='edge')
+    kernel = np.ones(window_size) / window_size
+    smoothed = np.convolve(padded, kernel, mode='valid')
+
+    # Ensure smoothed is same length as input
+    if len(smoothed) > len(intensity_array):
+        smoothed = smoothed[:len(intensity_array)]
+    elif len(smoothed) < len(intensity_array):
+        smoothed = np.pad(smoothed, (0, len(intensity_array) - len(smoothed)), mode='edge')
+
+    # Go left to find left valley (using smoothed signal)
+    left_valley_idx = 0
+    for i in range(global_apex_idx - 1, -1, -1):
+        if smoothed[i] < threshold:
+            left_valley_idx = i
+            break
+
+    # Go right to find right valley (using smoothed signal)
+    right_valley_idx = len(intensity_array) - 1
+    for i in range(global_apex_idx + 1, len(intensity_array)):
+        if smoothed[i] < threshold:
+            right_valley_idx = i
+            break
+
+    return {
+        'global_apex_idx': global_apex_idx,
+        'left_valley_idx': left_valley_idx,
+        'right_valley_idx': right_valley_idx,
+        'envelope_mz': mz_array[left_valley_idx:right_valley_idx+1],
+        'envelope_intensity': intensity_array[left_valley_idx:right_valley_idx+1]
+    }
+
+
+def extract_apexes(mz_array, intensity_array, min_prominence_ratio=0.05):
+    """
+    Extract local maxima (apexes) from a spectrum region.
+
+    These apexes represent the individual isotope peaks within an envelope.
+    Using apexes instead of raw data improves charge detection for complex
+    spectra like Duplex DNA where broad envelopes can confuse the algorithms.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        m/z values of the region
+    intensity_array : np.ndarray
+        Intensity values of the region
+    min_prominence_ratio : float
+        Minimum prominence as fraction of max intensity (default 0.05 = 5%)
+
+    Returns:
+    --------
+    apex_mz : np.ndarray
+        m/z values of the apexes
+    apex_intensity : np.ndarray
+        Intensity values of the apexes
+    apex_indices : np.ndarray
+        Indices of apexes in the original arrays
+    """
+    if len(mz_array) < 3:
+        return mz_array, intensity_array, np.arange(len(mz_array))
+
+    max_intensity = np.max(intensity_array)
+    min_prominence = max_intensity * min_prominence_ratio
+
+    # Find local maxima with sufficient prominence
+    apex_indices, properties = find_peaks(
+        intensity_array,
+        prominence=min_prominence,
+        distance=2
+    )
+
+    # If no apexes found, fall back to using the maximum point
+    if len(apex_indices) == 0:
+        max_idx = np.argmax(intensity_array)
+        apex_indices = np.array([max_idx])
+
+    apex_mz = mz_array[apex_indices]
+    apex_intensity = intensity_array[apex_indices]
+
+    return apex_mz, apex_intensity, apex_indices
+
+
+def assign_charge_senko(mz_array, intensity_array, charge_range=(1, 10),
+                        method='combination', return_all_maps=False):
+    """
+    Assign charge state using Senko et al. 1995 methods.
+
+    This is the main function to call for charge state assignment.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        m/z values of the isotope envelope
+    intensity_array : np.ndarray
+        Intensity values
+    charge_range : tuple
+        (min_charge, max_charge) to test
+    method : str
+        'patterson', 'fourier', or 'combination' (recommended)
+    return_all_maps : bool
+        If True, return all charge maps for visualization
+
+    Returns:
+    --------
+    dict with keys:
+        - 'charge': int, assigned charge state
+        - 'confidence': float, normalized score for assigned charge
+        - 'method': str, method used
+        - 'charge_map': dict with charges and scores (if return_all_maps=True)
+    """
+    if len(mz_array) < 2:
+        return {
+            'charge': None,
+            'confidence': 0.0,
+            'method': method,
+            'error': 'Insufficient data points'
+        }
+
+    # Choose method
+    if method == 'patterson':
+        charges, charge_map = patterson_function(mz_array, intensity_array, charge_range)
+    elif method == 'fourier':
+        charges, charge_map = fourier_function(mz_array, intensity_array, charge_range)
+    elif method == 'combination':
+        charges, charge_map, patterson_map, fourier_map = combination_function(
+            mz_array, intensity_array, charge_range
+        )
+    else:
+        raise ValueError(f"Unknown method: {method}")
+
+    # Find charge with maximum score
+    max_idx = np.argmax(charge_map)
+    assigned_charge = charges[max_idx]
+
+    # Round to nearest integer
+    assigned_charge = int(round(assigned_charge))
+
+    # Calculate confidence (normalized score)
+    if np.max(charge_map) > 0:
+        confidence = charge_map[max_idx] / np.max(charge_map)
+    else:
+        confidence = 0.0
+
+    result = {
+        'charge': assigned_charge,
+        'confidence': float(confidence),
+        'method': method
+    }
+
+    if return_all_maps:
+        result['charge_map'] = {
+            'charges': charges.tolist(),
+            'scores': charge_map.tolist()
+        }
+        if method == 'combination':
+            result['patterson_map'] = patterson_map.tolist()
+            result['fourier_map'] = fourier_map.tolist()
+
+    return result
+
+
+def extract_isotope_envelope(mz_array, intensity_array, peak_mz, window=2.0):
+    """
+    Extract an isotope envelope around a peak for charge state analysis.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        Full m/z array
+    intensity_array : np.ndarray
+        Full intensity array
+    peak_mz : float
+        Center m/z of the peak
+    window : float
+        Window size in m/z units (±window from peak_mz)
+
+    Returns:
+    --------
+    envelope_mz : np.ndarray
+        m/z values in the envelope
+    envelope_intensity : np.ndarray
+        Intensity values in the envelope
+    """
+    # Find region around peak
+    mask = (mz_array >= peak_mz - window) & (mz_array <= peak_mz + window)
+    envelope_mz = mz_array[mask]
+    envelope_intensity = intensity_array[mask]
+
+    return envelope_mz, envelope_intensity
+
+
+def find_peak_regions(mz_values, intensity_values, threshold=0.05, merge_gap=1.5):
+    """
+    Find isotope envelope regions using LOCAL MAXIMA detection.
+
+    Parameters:
+    -----------
+    mz_values : np.ndarray
+        m/z values
+    intensity_values : np.ndarray
+        Intensity values
+    threshold : float
+        Relative intensity threshold (0-1) - peaks below this are ignored
+    merge_gap : float
+        Merge regions separated by less than this m/z (same isotope envelope)
+
+    Returns:
+    --------
+    list of tuples (start_idx, end_idx) for each region
+    """
+    if len(mz_values) < 5:
+        return []
+
+    max_intensity = np.max(intensity_values)
+    mz_spacing = np.median(np.diff(mz_values))
+
+    # Estimate noise floor from the spectrum median (baseline)
+    noise_floor = np.median(intensity_values)
+    noise_threshold = noise_floor * 3  # 3× median as noise cutoff
+
+    print(f"[find_peak_regions] Max intensity: {max_intensity:.0f}, noise floor: {noise_floor:.0f}, noise threshold: {noise_threshold:.0f}, mz_spacing: {mz_spacing:.4f}")
+
+    min_height = max(max_intensity * threshold, noise_threshold)
+    min_prominence = max(min_height * 0.5, noise_threshold)
+    min_distance = max(10, int(10.0 / mz_spacing))
+
+    # Find peaks
+    peak_indices, properties = find_peaks(
+        intensity_values,
+        height=min_height,
+        prominence=min_prominence,
+        distance=min_distance
+    )
+
+    print(f"[find_peak_regions] height_threshold={min_height:.0f}, distance={min_distance} indices")
+    print(f"[find_peak_regions] Found {len(peak_indices)} peaks above threshold")
+    if len(peak_indices) > 0:
+        # Show top 5 peaks by intensity
+        peak_ints = intensity_values[peak_indices]
+        top_5_idx = np.argsort(peak_ints)[-5:][::-1]  # Get indices of top 5
+        print(f"[find_peak_regions] Top peaks: ", end="")
+        for i in top_5_idx:
+            if i < len(peak_indices):
+                mz = mz_values[peak_indices[i]]
+                inten = intensity_values[peak_indices[i]]
+                print(f"m/z={mz:.1f}(I={inten:.0f}), ", end="")
+        print()
+
+    if len(peak_indices) == 0:
+        # Fallback: try with lower requirements
+        peak_indices, properties = find_peaks(
+            intensity_values,
+            height=min_height * 0.5,
+            prominence=min_prominence * 0.5,
+            distance=min_distance // 2
+        )
+
+    if len(peak_indices) == 0:
+        return []
+
+    # For each detected peak, create a region around it (±5 m/z window)
+    # This captures the isotope envelope while avoiding merging nearby envelopes
+    envelope_half_width = 5.0  # m/z
+    envelope_half_idx = int(envelope_half_width / mz_spacing)
+
+    regions = []
+    for peak_idx in peak_indices:
+        left_idx = max(0, peak_idx - envelope_half_idx)
+        right_idx = min(len(mz_values) - 1, peak_idx + envelope_half_idx)
+        regions.append((left_idx, right_idx))
+
+    if len(regions) <= 1:
+        return regions
+
+    # Merge overlapping or close regions (same isotope envelope)
+    regions.sort(key=lambda x: x[0])
+
+    merged_regions = []
+    current_start, current_end = regions[0]
+
+    for i in range(1, len(regions)):
+        next_start, next_end = regions[i]
+
+        # Check for overlap or small gap
+        gap = mz_values[next_start] - mz_values[current_end] if next_start > current_end else 0
+
+        if next_start <= current_end or gap < merge_gap:
+            # Merge: extend current region
+            current_end = max(current_end, next_end)
+        else:
+            # Save current region and start new one
+            merged_regions.append((current_start, current_end))
+            current_start, current_end = next_start, next_end
+
+    merged_regions.append((current_start, current_end))
+
+    # print(f"[find_peak_regions] After merging: {len(merged_regions)} regions")
+    # for i, (s, e) in enumerate(merged_regions[:5]):  # Print first 5
+    #     print(f"  Region {i+1}: m/z {mz_values[s]:.1f} - {mz_values[e]:.1f}")
+
+    return merged_regions
+
+
+def weighted_centroid(mz_values, intensity_values, start_idx, end_idx):
+    """
+    Calculate peak centroid (m/z at maximum intensity).
+
+    Returns:
+    --------
+    centroid_mz : float
+        m/z at maximum intensity
+    max_intensity : float
+        Maximum intensity in the region
+    """
+    region_mz = mz_values[start_idx:end_idx+1]
+    region_int = intensity_values[start_idx:end_idx+1]
+
+    if len(region_mz) == 0 or np.sum(region_int) == 0:
+        return None, None
+
+    # Find the m/z at maximum intensity (peak apex)
+    max_idx = np.argmax(region_int)
+    centroid_mz = region_mz[max_idx]
+    max_intensity = region_int[max_idx]
+
+    return centroid_mz, max_intensity
+
+
+def measure_direct_spacing(mz_array, intensity_array):
+    """
+    Determine charge by counting apexes in a 1 m/z window.
+
+    Simple and robust approach: since isotope spacing = 1.003/z,
+    the number of isotope peaks in a 1 m/z window equals the charge state.
+
+    Filters out noise spikes (peaks too close together) before counting.
+
+    Returns:
+        dict with 'spacing', 'charge', 'num_peaks', 'has_alternating_pattern'
+    """
+    if len(mz_array) < 5:
+        return {'spacing': None, 'charge': None, 'num_peaks': 0, 'has_alternating_pattern': False}
+
+    # Extract apexes (local maxima) - use lower prominence for isotope peaks
+    peak_mzs, peak_ints, peaks = extract_apexes(mz_array, intensity_array, min_prominence_ratio=0.02)
+
+    if len(peaks) < 3:
+        return {'spacing': None, 'charge': None, 'num_peaks': len(peaks), 'has_alternating_pattern': False}
+
+    # Filter out noise spikes: peaks too close together (< 0.08 m/z) are likely noise
+    # For z=10, spacing would be ~0.1 m/z, so 0.08 is a safe minimum
+    MIN_SPACING = 0.08
+    filtered_mzs = [peak_mzs[0]]
+    filtered_ints = [peak_ints[0]]
+
+    for i in range(1, len(peak_mzs)):
+        spacing = peak_mzs[i] - filtered_mzs[-1]
+        if spacing >= MIN_SPACING:
+            # Normal spacing - keep this peak
+            filtered_mzs.append(peak_mzs[i])
+            filtered_ints.append(peak_ints[i])
+        else:
+            # Too close - keep the more intense one
+            if peak_ints[i] > filtered_ints[-1]:
+                filtered_mzs[-1] = peak_mzs[i]
+                filtered_ints[-1] = peak_ints[i]
+
+    filtered_mzs = np.array(filtered_mzs)
+    filtered_ints = np.array(filtered_ints)
+
+    if len(filtered_mzs) < 3:
+        return {'spacing': None, 'charge': None, 'num_peaks': len(filtered_mzs), 'has_alternating_pattern': False}
+
+    # COUNT APEXES IN 1 m/z WINDOW to determine charge
+    # Use multiple 1 m/z windows and take the most common count
+    mz_min = filtered_mzs[0]
+    mz_max = filtered_mzs[-1]
+    mz_span = mz_max - mz_min
+
+    if mz_span < 1.0:
+        # Envelope too small - count all peaks as the charge estimate
+        charge = len(filtered_mzs)
+        return {
+            'spacing': 1.003 / charge if charge > 0 else None,
+            'charge': charge,
+            'num_peaks': len(filtered_mzs),
+            'has_alternating_pattern': False
+        }
+
+    # Sample multiple 1 m/z windows centered at different positions
+    window_counts = []
+    step = 0.2  # Step through the envelope
+
+    for start_mz in np.arange(mz_min, mz_max - 1.0 + step, step):
+        end_mz = start_mz + 1.0
+        # Count peaks in this 1 m/z window
+        count = np.sum((filtered_mzs >= start_mz) & (filtered_mzs <= end_mz))
+        if count >= 1:
+            window_counts.append(count)
+
+    if len(window_counts) == 0:
+        return {'spacing': None, 'charge': None, 'num_peaks': len(filtered_mzs), 'has_alternating_pattern': False}
+
+    # Use the median count (robust to outliers at edges)
+    charge = int(round(np.median(window_counts)))
+
+    # Sanity check: charge should be between 1 and 10
+    charge = max(1, min(10, charge))
+
+    print(f"  [measure_direct_spacing] Counted apexes in 1 m/z windows: {window_counts[:10]}... -> z={charge}")
+
+    has_overlap = False
+    if charge >= 4 and len(filtered_mzs) >= 6:
+        # Check step-2 spacings: if peak[i+2] - peak[i] gives charge/2, two species overlap
+        step2_spacings = filtered_mzs[2:] - filtered_mzs[:-2]
+        step2_median = np.median(step2_spacings)
+        half_charge = charge / 2.0
+
+        if step2_median > 0:
+            step2_z = 1.003 / step2_median
+            spacing_ok = abs(step2_z - half_charge) < 1.0
+
+            # Intensity balance: true overlap has comparable even/odd intensities
+            even_avg = np.mean(filtered_ints[0::2])
+            odd_avg = np.mean(filtered_ints[1::2])
+            intensity_balance = min(even_avg, odd_avg) / max(even_avg, odd_avg) if max(even_avg, odd_avg) > 0 else 0
+
+            # Envelope roughness: overlap creates jagged envelope, single species is smooth
+            mid_ints = filtered_ints[1:-1]
+            neighbor_avg = (filtered_ints[:-2] + filtered_ints[2:]) / 2
+            roughness = np.mean(np.abs(mid_ints - neighbor_avg)) / np.mean(filtered_ints) if np.mean(filtered_ints) > 0 else 0
+
+            print(f"  [overlap check] step2_z={step2_z:.1f}, half_charge={half_charge:.1f}, "
+                  f"spacing_ok={spacing_ok}, intensity_balance={intensity_balance:.2f}, roughness={roughness:.2f}")
+
+            if spacing_ok and intensity_balance > 0.3 and roughness > 0.15:
+                corrected_charge = int(round(step2_z))
+                corrected_charge = max(1, min(10, corrected_charge))
+                print(f"  [overlap detection] Two overlapping species detected! "
+                      f"step2_z={step2_z:.1f}, balance={intensity_balance:.2f}, roughness={roughness:.2f} -> corrected z={corrected_charge}")
+                charge = corrected_charge
+                has_overlap = True
+
+    return {
+        'spacing': 1.003 / charge,
+        'charge': charge,
+        'num_peaks': len(filtered_mzs),
+        'has_alternating_pattern': has_overlap
+    }
+
+
+def detect_all_peaks_with_charge(mz_array, intensity_array,
+                                  prominence=0.05, charge_range=(1, 10),
+                                  method='combination', merge_gap=1.5):
+    """
+    Detect all isotope envelopes (peak regions) in a spectrum and assign charge states.
+
+    Each isotope envelope (M, M+1, M+2, ...) is detected as ONE peak region
+    and assigned ONE charge state.
+
+    Parameters:
+    -----------
+    mz_array : np.ndarray
+        Full spectrum m/z values
+    intensity_array : np.ndarray
+        Full spectrum intensity values
+    prominence : float
+        Relative intensity threshold for region detection (0-1)
+    charge_range : tuple
+        (min_charge, max_charge) to test
+    method : str
+        'patterson', 'fourier', or 'combination'
+    merge_gap : float
+        Merge regions separated by less than this m/z (default 1.5)
+
+    Returns:
+    --------
+    list of dicts, each containing:
+        - 'mz': float, peak centroid m/z
+        - 'intensity': float, peak maximum intensity
+        - 'charge': int, assigned charge
+        - 'confidence': float, confidence score
+        - 'method': str, method used
+    """
+    if len(mz_array) == 0:
+        return []
+
+    regions = find_peak_regions(mz_array, intensity_array, prominence, merge_gap)
+
+    print(f"[detect_all_peaks] Found {len(regions)} initial peak regions")
+
+    if len(regions) == 0:
+        return []
+
+    # For each region (isotope envelope), assign ONE charge
+    results = []
+
+    for start_idx, end_idx in regions:
+        # Get initial region data
+        region_mz = mz_array[start_idx:end_idx+1]
+        region_int = intensity_array[start_idx:end_idx+1]
+
+        # STEP 1: Find envelope boundaries using global apex → global valleys
+        # This refines the region to the actual isotope envelope (removes noise)
+        envelope = find_envelope_boundaries(region_mz, region_int)
+        envelope_mz = envelope['envelope_mz']
+        envelope_int = envelope['envelope_intensity']
+
+        # Use envelope data for analysis (refined boundaries)
+        if len(envelope_mz) >= 3:
+            analysis_mz = envelope_mz
+            analysis_int = envelope_int
+        else:
+            # Fall back to original region if envelope is too small
+            analysis_mz = region_mz
+            analysis_int = region_int
+
+        # Calculate centroid from the refined envelope
+        global_apex_idx = envelope['global_apex_idx']
+        centroid_mz = region_mz[global_apex_idx] if global_apex_idx < len(region_mz) else None
+        max_intensity = np.max(analysis_int) if len(analysis_int) > 0 else 0
+
+        if centroid_mz is None:
+            continue
+
+        # Skip if region is too small for reliable charge assignment
+        if len(analysis_mz) < 3:
+            # Skip this peak - not enough data points
+            print(f"  Skipping peak at m/z {centroid_mz:.2f}: only {len(analysis_mz)} data points in envelope")
+            continue
+
+        # STEP 2: Assign charge using Senko method on the refined envelope
+        try:
+            charge_result = assign_charge_senko(
+                analysis_mz, analysis_int, charge_range, method
+            )
+            charge = charge_result['charge']
+            confidence = charge_result['confidence']
+
+            # STEP 3: VALIDATION using apex counting in 1 m/z window
+            spacing_result = measure_direct_spacing(analysis_mz, analysis_int)
+            if spacing_result['charge'] is not None and spacing_result['num_peaks'] >= 4:
+                spacing_charge = spacing_result['charge']
+
+                # If Senko gives low charge (z<=3) but apex counting gives high charge (z>=5),
+                # trust the apex counting - Senko often fails on complex Ag spectra
+                if charge <= 3 and spacing_charge >= 5:
+                    print(f"  Apex counting correction at m/z {centroid_mz:.2f}: z={charge} -> z={spacing_charge} (Senko gave implausibly low charge)")
+                    charge = spacing_charge
+                    confidence = 0.85
+
+                # If overlap detected (two interleaved species), use corrected charge
+                if spacing_result.get('has_alternating_pattern') and spacing_charge != charge:
+                    print(f"  Overlap correction at m/z {centroid_mz:.2f}: z={charge} -> z={spacing_charge} (two interleaved species)")
+                    charge = spacing_charge
+                    confidence = 0.90
+
+            # Add ALL peaks with valid charge assignments (no confidence threshold)
+            # Display confidence so users can judge reliability themselves
+            if charge is not None:
+                results.append({
+                    'mz': float(centroid_mz),
+                    'intensity': float(max_intensity),
+                    'charge': charge,
+                    'confidence': float(confidence),
+                    'method': method
+                })
+                if confidence < 0.5:
+                    print(f"Low confidence charge at m/z {centroid_mz:.2f}: z={charge}, confidence={confidence:.2f}")
+                else:
+                    print(f"Detected charge at m/z {centroid_mz:.2f}: z={charge}, confidence={confidence:.2f}")
+            else:
+                # Skip only if charge assignment completely failed (returned None)
+                print(f"Skipping peak at m/z {centroid_mz:.2f} - charge assignment failed")
+
+        except Exception as e:
+            # Skip this peak - Senko algorithm failed with exception
+            print(f"Skipping peak at m/z {centroid_mz:.2f} - Error: {e}")
+
+    return results
+
+
+# Example usage
+if __name__ == '__main__':
+    print("Senko Charge Assignment Module")
+    print("=" * 60)
+    print("Based on: Senko et al., J. Am. Soc. Mass Spectrom. 1995, 6, 52-56")
+    print()
+
+    # Simulate an isotope envelope for z=3
+    # Isotope spacing = 1.003/3 ≈ 0.334 Da
+    mz_sim = np.array([1000.0, 1000.334, 1000.668, 1001.002, 1001.336])
+    # Gaussian-like envelope
+    intensity_sim = np.array([10, 45, 100, 75, 30])
+
+    print("Simulated isotope envelope (z=3):")
+    print(f"  m/z spacing: ~{np.mean(np.diff(mz_sim)):.3f}")
+    print(f"  Expected for z=3: {1.003/3:.3f}")
+    print()
+
+    # Test all three methods
+    for method in ['patterson', 'fourier', 'combination']:
+        result = assign_charge_senko(mz_sim, intensity_sim, charge_range=(1, 10), method=method)
+        print(f"{method.capitalize()} Method:")
+        print(f"  Assigned charge: {result['charge']}")
+        print(f"  Confidence: {result['confidence']:.3f}")
+        print()
+
+    print("=" * 60)
+    print("Module ready for integration!")

lib/pythoms/spectrum.py

@@ -0,0 +1,900 @@
+"""
+This class is designed to efficiently combine, add to, or otherwise manipulate
+spectra together whose dimensions are not equal.
+For example, combining mass spectra together where resolution to the 3rd
+decimal (not to the 10th decimal) is desired.
+Upon initialization, specify the number of decimal places desired.
+Start and end values for the x bounds may also be specified, and
+an input spectrum can be provided (this spectrum will be added to
+the object on initialization).
+When adding a value to the Spectrum object, it will find the closest x value
+with the decimal place specified and add the y value to that x in the object.
+e.g. if the decimal place is 3, adding x=545.34898627,y=10 will add 10 to x=545.349
+
+Once the desired spectrum has been constructed, calling Spectrum.trim() will return
+an [[x values],[y values]] list with only the x values that have intensities. Other
+manipulations are available, see below for details.
+
+IGNORE:
+CHANGELOG
+---2.5---
+- added the ability to not provide start and end points for an unfilled spectrum
+---2.6
+- added applycharge function to apply the charge to a mass list
+IGNORE
+"""
+import numpy as np
+from random import random
+from bisect import bisect_left as bl
+
+
+def weighted_average(xvals, yvals):
+    """
+    Determines the weighted average of a group of masses and abundances
+
+    :param list xvals: x values
+    :param list yvals: y values
+    :return: weighted average, summed intensity
+    :rtype: tuple of float
+    """
+    if sum(yvals) == 0:  # catch for no intensity
+        return sum(xvals) / len(xvals), 0.
+    return (
+        sum([x * y for x, y in zip(xvals, yvals)]) / sum(yvals),  # weighted m/z
+        sum(yvals)  # summed intensity
+    )
+
+
+def full_spectrum_list(start, end, decpl, filler=None):
+    """
+    Generates two paired lists (one m/z, one None) from start to end with a specified number of decimal places.
+
+    :param float start: The start value for the x list.
+    :param float end: The end value for the x list.
+    :param int decpl: The decimal places to use for the generated list.
+    :param filler: The filler value for the y list
+    :return: A list of x values and a list of y values (specified by the ``filler`` keyword argument) of the
+        same length.
+    :rtype: tuple of lists
+
+    **Notes**
+
+    The maximum x value will be larger than end by 10^-``decpl`` to include the
+    actual end value in the x list.
+
+    """
+    x = np.arange(  # generate x values
+        start,
+        end + 10 ** -decpl,
+        10 ** -decpl
+    )
+    return (
+        x.tolist(),  # convert to list
+        [filler] * len(x),  # generate y list of equal length
+    )
+
+
+class Spectrum(object):
+    _start = -np.inf
+    _end = np.inf
+    _charge = 1
+
+    def __init__(self,
+                 decpl,
+                 start=50.,
+                 end=2000.,
+                 empty=False,
+                 filler=None,
+                 specin=None,
+                 ):
+        """
+        A class for subtracting, combining, adding-to, and otherwise manipulating spectra with non-equal dimensions.
+        The object will track *x* values to a specified decimal place and can efficiently add a new value to a growing
+        list of values. e.g. adding two spectra together that do not have an intensity value for every *x* value
+        (a common operation for combining mass spectra). On initialization, specify the number of decimal places to
+        track using the ``decpl`` argument. Other behaviour of the class can be tweaked with the keyword arguments.
+
+        :param int decpl: The decimal places to track the *x* values two. e.g. a value of 3 will track
+            *x* values to the nearest 0.001.
+        :param float,None start: The minimum *x* value to track. Attempts to add an *x* value less than this
+            will be ignored by the instance.
+        :param float,None end: The maximum *x* value to track. Attempts to add an *x* value greater than this will be
+            ignored by the instance.
+        :param list specin: An spectrum to be added to the object on initialization. The format should be
+            ``[[x values],[y values]]``.
+        :param bool empty: Whether the spectrum object should be filled or empty. An empty spectrum will have no *x*
+            or *y* values on initialization, and will add values with each call of ``Spectrum.addvalue()``. A filled
+            spectrum will generate an *x* list from *start* to *end* with spacing 10^-``decpl`` and a *y* list of equal
+            length filled with the value specified by the ``filler`` kwarg. If the number of items to be contained in
+            the spectrum is substantially less than ``(end-start)*10^decpl`` it can be more efficient to set this to
+            ``True``. If not, then set this to False to reduce computational overhead.
+        :param filler: The y value to use if there is no y value. This can affect the functionality of some of the
+            functions in this class. If ``Spectrum.addelement()`` is to be used (e.g. by the Molecule class),
+            filler must be ``0.``.
+
+        **Basic Examples**
+
+        Specify the number of decimal places to track on initialization.
+
+        >>> spec = Spectrum(3)
+
+        *x*, *y* pairs may be added using the ``add_value`` method
+
+        >>> spec.add_value(55.67839, 100)
+
+
+        When the spectrum has been manipulated to the user's satisfaction, it may be easily converted to
+        ``[[x values], [y values]`` format using the ``trim()`` method.
+
+        >>> spec.trim()
+        [[55.678], [100]]
+
+        The incoming x value will be compared to the current x list for equivalent x values. If a matching x value is
+        found, the y value is added to the existing value.
+
+        >>> spec.add_value(55.67799, 100)  # equivalent to 55.678
+        >>> spec.trim()
+        [[55.678], [200]]
+        >>> spec.add_value(55.67744, 99)  # equivalent to 55.677
+        >>> spec.trim()
+        [[55.677, 55.678], [99, 200]]
+
+
+        **y-value manipulation**
+
+        The y values may be manipulated in a variety of ways.
+
+        - The ``normalize()`` method will normalize the y values in the instance to the specified value.
+        - The ``threshold()`` method will drop y values below a certain value (either relative or absolute).
+        - The ``keep_top_n()`` method keeps the top n peaks.
+        - The ``consolidate()`` method groups values together using a weighted average algorithm to keep the lowest
+            y value above a given threshold but still retain the information in the spectrum.
+
+        **spectrum constraint methods**
+
+        - Values below a certain x value may be dropped by calling the ``drop_below()`` method.
+        - Values above a certain x value may be dropped by calling the ``drop_above()`` method.
+        """
+        self.x = []
+        self.y = []
+        self.decpl = decpl
+        self.empty = empty
+        self.filler = filler
+
+        if empty is False and any([val is None for val in [start, end]]):
+            raise ValueError(f'A start and end value must be specified for a filled '
+                             f'{self.__class__.__name__} instance. ')
+
+        # set start and end values for the spectrum
+        if start is not None:
+            self._start = start
+        if end is not None:
+            self._end = end
+
+        if self.empty is False:
+            self.x, self.y = full_spectrum_list(  # m/z and intensity lists
+                self.start,
+                self.end,
+                decpl=decpl,
+                filler=filler,
+            )
+
+        if specin is not None:
+            self.add_spectrum(specin[0], specin[1])
+
+    def __str__(self):
+        return f'Full spectrum from {self.start} to {self.end} keeping {self.decpl} decimal places'
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}({self.start}, {self.end}, {self.decpl})'
+
+    def __getinitargs__(self):
+        return (
+            self.decpl,
+            self.start,
+            self.end,
+            self.empty,
+            self.filler,
+            [self.x, self.y]
+        )
+
+    def __reduce__(self):
+        return (
+            self.__class__,
+            self.__getinitargs__()
+        )
+
+    def __copy__(self):
+        return Spectrum(
+            *self.__getinitargs__()
+        )
+
+    def __deepcopy__(self, memodict={}):
+        return self.__copy__()
+
+    def __len__(self):
+        return len(self.x)
+
+    def __getitem__(self, ind):
+        """
+        if supplied index is an integer, return the x and y value of that index in the list
+        if a float, return the intensity of that x value
+        """
+        if type(ind) is int:
+            return [self.x[ind], self.y[ind]]
+        elif type(ind) is float:  # returns the intensity value of the specified m/z
+            if ind < self.start or ind > self.end:
+                raise IndexError(
+                    'The supplied float %f is outside of the m/z range of this Spectrum instance (%.3f -%.3f)' % (
+                        ind, self.start, self.end))
+            return self.y[self.index(ind)]
+
+    def __add__(self, x):
+        """
+        Since addition to this class requires generating a complete copy of the class then addition,
+        using the built in addition methods is recommended
+        e.g. to add a single value use .addvalue()
+        to add a spectrum use .addspectrum()
+        """
+        kwargs = {
+            'empty': self.empty,
+            'filler': self.filler,
+        }
+        if isinstance(x, self.__class__) is True:  # if it is another Spectrum instance
+            if x.decpl != self.decpl:
+                raise ValueError(
+                    'The decimal places of the two spectra to be added are not equal. Addition is not supported')
+            newstart = min(self.start, x.start)  # find new start m/z
+            newend = max(self.end, x.end)  # find new end m/z
+            tempspec = Spectrum(  # temporary instance with self as specin
+                self.decpl,
+                start=newstart,
+                end=newend,
+                specin=[self.x, self.y],
+                **kwargs,
+            )
+            tempspec.add_spectrum(x.x, x.y)  # add incoming spectrum
+            return tempspec
+        elif type(x) is int:  # add this integer to every m/z
+            tempspec = Spectrum(
+                self.decpl,
+                start=self.start,
+                end=self.end,
+                **kwargs
+            )
+            y = np.asarray(self.y)
+            y += x
+            tempspec.y = y.tolist()
+            return tempspec
+        elif len(x) == 2 and len(x[0]) == len(x[1]):  # if it is a list of paired lists (another spectrum)
+            tempspec = Spectrum(
+                self.decpl,
+                start=self.start,
+                end=self.end,
+                **kwargs,
+            )
+            tempspec.y = list(self.y)
+            tempspec.add_spectrum(x[0], x[1])
+            return tempspec
+        else:
+            return 'Addition of %s to the Spectrum class is unsupported' % str(x)
+
+    def __sub__(self, x):
+        kwargs = {
+            'empty': self.empty,
+            'filler': self.filler,
+        }
+        if isinstance(x, self.__class__) is True:  # if it is another Spectrum instance
+            if x.decpl != self.decpl:
+                raise ValueError(
+                    'The decimal places of the two spectra to be added are not equal. Subtraction is not supported')
+            newstart = min(self.start, x.start)  # find new start m/z
+            newend = max(self.end, x.end)  # find new end m/z
+            tempspec = Spectrum(
+                self.decpl,
+                start=newstart,
+                end=newend,
+                specin=[self.x, self.y],
+                empty=self.empty,
+                filler=self.filler
+            )  # temporary instance
+            tempspec.add_spectrum(x.x, x.y, True)  # subtract incoming spectrum
+            return tempspec
+        elif type(x) is int:  # add this integer to every m/z
+            tempspec = Spectrum(
+                self.decpl,
+                start=self.start,
+                end=self.end,
+                **kwargs
+            )
+            y = np.asarray(self.y)
+            y -= x
+            tempspec.y = y.tolist()
+            return tempspec
+        elif len(x) == 2 and len(x[0]) == len(x[1]):  # if it is a list of paired lists (another spectrum)
+            tempspec = Spectrum(
+                self.decpl,
+                start=self.start,
+                end=self.end,
+                **kwargs
+            )
+            tempspec.y = list(self.y)
+            tempspec.add_spectrum(x[0], x[1], True)  # subtract the incoming spectrum
+            return tempspec
+        else:
+            return 'Subtraction of %s from the Spectrum class is unsupported' % str(x)
+
+    def __mul__(self, x):
+        raise AttributeError('Multiplication of the Spectrum class is unsupported')
+
+    def __truediv__(self, x):
+        raise AttributeError('Division of the Spectrum class is unsupported')
+
+    def __pow__(self, x):
+        raise AttributeError('Raising a Spectrum instance to a power is unsupported.\nAlso... really?!')
+
+    @property
+    def start(self):
+        """The start value for the spectrum object"""
+        return self._start
+
+    @start.setter
+    def start(self, value):
+        if value is None:
+            value = -np.inf
+        value = round(value, self.decpl)
+        if value > self._start:  # if trimming is required
+            index = self.index(value)  # find index
+            del self.x[:index]  # trim spectra
+            del self.y[:index]
+        self._start = value
+
+    @start.deleter
+    def start(self):
+        self._start = -np.inf
+
+    @property
+    def end(self):
+        return self._end
+
+    @end.setter
+    def end(self, value):
+        if value is None:
+            value = np.inf
+        value = round(value, self.decpl)
+        if value < self._end:
+            index = self.index(value)  # find index
+            self.x = self.x[:index]  # trim lists
+            self.y = self.y[:index]
+        self._end = value
+
+    @end.deleter
+    def end(self):
+        self._end = np.inf
+
+    @property
+    def charge(self):
+        """Charge for the spectrum (in mass spectrometry, the x values are mass over charge)"""
+        return self._charge
+
+    @charge.setter
+    def charge(self, charge):
+        if charge == self._charge:  # if already set, ignore
+            return
+        try:  # if numpy array, cheat
+            self.x /= charge
+        except TypeError:  # otherwise iterate over list
+            for ind, val in enumerate(self.x):
+                self.x[ind] = val / (charge / self._charge)
+        # set new bounds
+        self.start /= charge
+        self.end /= charge
+        self._charge = charge
+
+    @charge.deleter
+    def charge(self):
+        setattr(self, 'charge', 1)
+
+    def add_element(self, masses, abunds):
+        """
+        Adds the masses and abundances of an element to the current spectrum object.
+        This is more efficient than creating a new spectrum object every time an
+        element is added.
+
+        :param list masses: List of masses (*x* values).
+        :param list abunds: abundances (*y* values, paired with ``masses``)
+
+        For example, to add a single atom of carbon to the ``Spectrum`` object
+
+            >>> Spectrum.add_element(
+                [12.0, 13.0033548378],
+                [0.9893, 0.0107]
+            )
+
+        **Note**
+
+        This function will encounter an error if there are None values in the y list.
+        If you intend to use this function, set the *filler* keyword argument to be
+        some value that is not None (i.e. ``0.``).
+
+        """
+        if len(masses) != len(abunds):
+            raise ValueError(
+                f'The dimensions of the supplied lists are not equal ({len(masses)} != {len(abunds)})')
+        if self.filler is None and self.count_none() > 0:
+            raise ValueError('add_element cannot operate on a y list populated with None values')
+
+        # create matricies of new x and y values
+        newx = np.asarray(self.x) + np.asarray(
+            [[val] for val in masses]  # values must be boxed for appropriate combination
+        )
+        newy = np.asarray(self.y) * np.asarray(
+            [[val] for val in abunds]
+        )
+
+        ## does not call for a new disposable object
+        """
+        extending the spectrum object then dropping is very fast,
+        but requires subtracting the original spectrum before dropping
+        slicing, deepcopy, list(), building the subtraction into the boxxed lists, and switching the array calls
+        are all slower than generating a temporary Spectrum object
+        """
+        # self.newend(max(masses) + max(self.x)) # define new end point for Spectrum object
+        # for i in range(newx.shape[0]): # add calculated masses and intensities to object
+        #    if i == 0:
+        #        self.addspectrum(newx[i],newy[i],True) # subtract original spectrum
+        #        continue
+        #    self.addspectrum(newx[i],newy[i])
+        # self.addspectrum(oldx,oldy,True) # subtract old spectrum
+        # self.dropbelow(min(masses) + min(self.x)) # drop values below new start point
+
+        tempspec = Spectrum(
+            self.decpl,
+            start=min(masses) + self.start - 10 ** -self.decpl,
+            end=max(masses) + self.end + 10 ** -self.decpl,
+            empty=self.empty,
+            filler=self.filler,
+        )
+        for x, y in zip(newx, newy):
+            tempspec.add_spectrum(x, y)
+
+        # for i in range(newx.shape[0]):
+        #     tempspec.addspectrum(newx[i], newy[i])
+        self.x = tempspec.x  # redefine the x and y lists
+        self.y = tempspec.y
+        self._start = min(masses) + self.start - 10 ** -self.decpl
+        self._end = max(masses) + self.end + 10 ** -self.decpl
+
+    def add_value(self, xval, yval, subtract=False):
+        """
+        Adds an intensity value to the x value specified.
+
+        :param float xval: The *x* value. This value will be rounded to the decimal place specified on calling this class.
+        :param float yval:  The *y* value to add to the *y* list.
+        :param bool subtract: Make this ``True`` if you wish to subtract the *y* value from the current *y* value at
+            the specified x.
+
+        **Examples**
+
+            >>> spec = Spectrum(3)
+            >>> spec.trim()
+            [[], []]
+
+            >>> spec.add_value(673.9082342357,100)
+            >>> spec.trim()
+            [[673.908], [100]]
+
+            >>> spec.add_value(1523.25375621,200)
+            >>> spec.add_value(50.89123,300)
+            >>> spec.trim()
+            [[50.891, 673.908, 1523.254], [300, 100, 200]]
+
+
+        **Note**
+
+        If the x value is not within the x bounds specified by the keyword
+        arguments *start* and *end*, the supplied y value will not be added
+        to the current spectrum object.
+
+        """
+        if yval is not None:  # if handed an actual value
+            try:  # try indexing
+                index = self.index(xval)
+                if subtract is True:  # set sign based on input
+                    sign = -1
+                else:
+                    sign = 1
+                if self.empty is False:  # if x list filled
+                    try:
+                        self.y[index] += yval * sign  # try to add value
+                    except TypeError:
+                        self.y[index] = yval * sign  # if None, then set to value
+                else:
+                    if len(self.x) == 0 and index == 0:
+                        self.x.insert(index, round(xval, self.decpl))
+                        self.y.insert(index, yval * sign)
+                    elif index == len(self.x):  # if at end of list
+                        self.x.append(round(xval, self.decpl))
+                        self.y.append(yval)
+                    elif self.x[index] != round(xval, self.decpl):  # if the index does not equal the value
+                        self.x.insert(index, round(xval, self.decpl))  # insert x value at specified index
+                        self.y.insert(index, yval * sign)  # insert the y value
+                    else:
+                        try:  # otherwise add
+                            self.y[index] += yval * sign
+                        except TypeError:  # or set to value if None
+                            self.y[index] = yval * sign
+            except ValueError:  # if index is not in spectrum
+                pass  # do nothing (the value will not be added to the spectrum)
+
+    def add_spectrum(self, x, y, subtract=False):
+        """
+        Adds an entire x and y list to the spectrum object.
+        This avoids having to call ``Spectrum.addvalue()`` in loop form
+        for a list of values.
+
+        :param list x: List of x values. These may be unsorted, but are assumed to be paired with the supplied *y* list.
+        :param list y: List of y values, paired with *x*.
+        :param bool subtract: Whether or not to subtract the y intensities from the current Spectrum object.
+        """
+        if len(x) != len(y):
+            raise ValueError('The add_spectrum() method only supports two lists of the same dimension')
+        for ind, mz in enumerate(x):
+            if y[ind] != self.filler:  # drops filler values at this point
+                self.add_value(mz, y[ind], subtract)
+
+    def check_none(self):
+        """counts the number of not-None values in the current *y* list (for debugging)"""
+        return len(self.y) - self.count_none()
+
+    def count_none(self):
+        """counts the number of None values in the current *y* list (for debugging)"""
+        return self.y.count(None)
+
+    def consolidate(self, threshold, within, method='abs'):
+        """
+        A method of reducing the number of values in the spectrum object by consolidating y values below the specified
+        threshold with nearby values. The method of combination is a weighted average. The intensities of adjacent
+        values are combined until the threshold is passed or until no adjacent values within the specified x delta
+        can be found.
+
+        :param float threshold: The threshold value, below which the value will be consolidated into adjacent peaks.
+        :param float within: The x delta to look within when consolidating peaks.
+        :param 'abs' or 'rel' method: Whether to use an absolute or relative threshold.
+        :return:
+        """
+        def adjacent(index):
+            """
+            locates the index of the closest x value to the provided index
+            (only returns an index if there is a value within the given delta
+            """
+            i = None
+            if index != 0 and self.x[index] - self.x[index - 1] <= within:  # if previous index is nearer than within
+                if self.y[index - 1] != 0:  # if the peak has intensity
+                    i = index - 1
+                    delta = self.x[index] - self.x[index - 1]
+            if index != len(self.x) - 1 and self.x[index + 1] - self.x[
+                index] <= within:  # if next index is nearer than within
+                if self.y[index + 1] != 0:  # if the peak has intensity
+                    if i is not None:  # if i is already defined
+                        if self.x[index + 1] - self.x[index] <= within:  # if the greater than is closer
+                            i = index + 1
+                    else:
+                        i = index + 1
+            return i
+
+        for ind in range(len(self.y)):
+            if self.y[ind] < threshold and self.y[ind] != 0.:
+                cur = ind
+                closest = adjacent(cur)  # looks for adjacent peaks within the delta
+                while self.y[cur] < threshold and closest is not None:
+                    self.add_value(  # subtract the current value
+                        self.x[cur],
+                        self.y[cur],
+                        True
+                    )
+                    self.add_value(  # subtract the adjacent value
+                        self.x[closest],
+                        self.y[closest],
+                        True
+                    )
+                    wx, wy = weighted_average(  # weighted average of removed values
+                        [self.x[cur], self.x[closest]],
+                        [self.x[cur], self.y[closest]]
+                    )
+                    self.add_value(wx, wy)  # add the weighted average to the spectrum
+                    cur = self.index(wx)  # set current index to that of the new value
+                    # cur = closest # set current index to the one being tested
+                    closest = adjacent(cur)
+        self.threshold(threshold, method)  # drop any peaks that could not be combined
+
+    def cp(self):
+        """returns a list (clone) of the spectrum"""
+        return [list(self.x), list(self.y)]
+
+    def fill_with_zeros(self, value=0.):
+        """
+        Replaces any ``None`` values in the *y* list with the specified value.
+
+        :param value: value to replace ``None`` with.
+        :return: new y list
+        :rtype: list
+        """
+        for ind, inten in enumerate(self.y):
+            if inten is None:
+                self.y[ind] = value
+        return self.y
+
+    def index(self, xval):
+        """
+        Locates the index of the specified x value in the object's x list.
+
+        :param float xval: The x value to locate in the list.
+        :return: The integer index for the x value in the x list.
+        :rtype: int
+
+        **Notes**
+
+        If the *empty* keyword argument is True, the index will be located using the bisect module. If the x value is
+        not in the current x list, the appropriate insertion index is returned. If the *empty* keyword argument is
+        False, the index will be calculated based on the ``start`` and ``decpl`` values of the object (this is more
+        computationally efficient than bisection).
+        """
+        if xval > self.end or xval < self.start:
+            raise ValueError(
+                f'The x value {xval} is outside of the x-list range of this {self.__class__.__name__} instance '
+                f'({self.start}, {self.end}).'
+            )
+        if self.empty is True:  # if spectrum is unfilled, searching is required
+            return bl(self.x, round(xval, self.decpl))
+        else:  # otherwise, calculation of the index is more efficient
+            return int(
+                round(  # round after multiplication
+                    (xval - self.start) * (10 ** self.decpl)  # calculate index location
+                )
+            )
+
+    def nearest_x_index(self, xval):
+        """
+        Finds the index of the closest x value to the one provided. This method differs from `index()` in that this
+        finds the closest value and index finds the insertion point to maintain an ordered list.
+
+        :param xval: x value to find
+        :return: index of nearest value
+        """
+        if xval < self.start:
+            return 0
+        if xval > self.end:
+            return len(self.x) - 1
+        if self.empty is False:
+            return self.index(xval)
+        index = self.index(xval)
+        if index == len(self.x):
+            return len(self.x) - 1
+        potentials = [index]
+        if index + 1 != len(self.x):
+            potentials.append(index + 1)
+        if index != 0:
+            potentials.append(index - 1)
+        return min(
+            potentials,
+            key=lambda x: abs(xval - self.x[x])
+        )
+
+    def keep_top_n(self, n=5000):
+        """
+        Keeps the top n peaks and sets the intensity of those below that value to be zero.
+
+        :param int n: The number of values to keep in the list.
+
+        **Notes**
+
+        If there is more than one y value equal to the nth lowest value, then all of those values will be retained.
+
+        """
+        if n > len(self.x):  # do nothing if number is longer than the number of values in the Spectrum object
+            return
+        self.threshold(  # use the threhold method
+            sorted(  # sort the y list in reverse order
+                self.y,
+                reverse=True,
+            )[n],  # use the value at the nth index as the threshold value
+            'abs',  # apply the absolute threshold
+        )
+
+    def max(self):
+        """
+        Locates the maximum intensity in the y list and returns the x and y values of that point.
+
+        :return: Returns the x and y values of the maximum y value.
+        :rtype: tuple of float
+        """
+        locs = np.where(  # locate index of maximum values
+            np.asarray(self.y) == max(self.y)
+        )
+        if len(locs[0]) > 1:  # if there is more than one value equal to the maximum
+            out = []
+            for i in locs[0]:
+                out.append([self.x[i], self.y[i]])
+            return out
+        return self.x[locs[0][0]], self.y[locs[0][0]]
+
+    def normalize(self, new_top=100.):
+        """
+        Normalizes the y values to the specified value.
+
+        :param float new_top: The new value for the maximum y value.
+        """
+        # old numpy way (probably less efficient)
+        # m = max(self.y)  # current maximum y value
+        # self.y = np.asarray(self.y)
+        # self.y /= m
+        # self.y *= new_top
+        # self.y = self.y.tolist()
+        scalar = new_top / max(self.y)  # calculate the appropriate scalar
+        for ind, inten in enumerate(self.y):
+            if inten is not None:
+                self.y[ind] *= scalar
+
+    def shift_x(self, value):
+        """
+        Offsets all *x* values by the specified value.
+
+        :param float value: The amount to offset the x values by.
+        """
+        for ind, val in enumerate(self.x):
+            self.x[ind] += value
+        if self.start != -np.inf:
+            self.start += value
+        if self.end != np.inf:
+            self.end += value
+
+    def sum(self):
+        """
+        Calculates and returns the sum of all y values in the object.
+
+        :return: The sum of all y values in the y list.
+        :rtype: float
+        """
+        return sum(
+            [y for y in self.y if y is not None]
+        )
+
+    def reset_y(self):
+        """
+        Resets the y values in the Spectrum object. This allows reuse of the same Spectrum object without regenerating.
+        """
+        self.y = [self.filler for val in self.y]
+
+    def threshold(self, thresh, method='abs'):
+        """
+        Removes all y values below the specified threshold value.
+
+        :param float thresh: The threshold y value to drop below.
+        :param 'abs' or 'rel' method: Whether the specifed *thresh* value is absolute or relative to the maximum y
+            value.
+        """
+        if method == 'rel':  # if relative, calculate relative threshold
+            thresh *= max(self.y)
+        if self.empty is True:  # removes values from the list
+            x = []
+            y = []
+            for ind, inten in enumerate(self.y):
+                if inten >= thresh:
+                    x.append(self.x[ind])
+                    y.append(inten)
+            self.x = x
+            self.y = y
+        else:
+            for ind, inten in enumerate(self.y):
+                if inten < thresh:
+                    self.y[ind] = self.filler  # sets the value to the filler value
+
+    def trim(self, zeros=False, xbounds=None):
+        """
+        Trims x and y pairs that have None intensity and returns the trimmed list.
+        This is the most efficient way of converting a Spectrum object to an x and y list.
+
+        :param bool zeros: Specifies whether there should be zeros at the start and end values. This can be used to
+            generate continuum spectra across the range [start,end]. If there are non-zero intensity values at the
+            start or end point, they will not be affected.
+        :param list xbounds: This can specify a subsection of the x and y spectra to trim to. None will return the entire
+            contents of the Spectrum object, and specifying ``[x1,x2]]`` will return the x and y lists between
+            *x1* and *x2*.
+        :return: trimmed spectrum in the form ``[[x values], [y values]]``
+        :rtype: list of lists
+        """
+        # retrieve boundaries
+        if xbounds is None:
+            xbounds = [self.start, self.end]
+        elif xbounds[0] is None:
+            xbounds[0] = self.start
+        elif xbounds[1] is None:
+            xbounds[1] = self.end
+
+        xout = []
+        yout = []
+
+        for ind in range(self.index(xbounds[0]), self.index(xbounds[1])):  # iterate over slice
+            if self.y[ind] is not self.filler:
+                xout.append(round(self.x[ind], self.decpl))  # rounded to avoid array floating point weirdness
+                yout.append(self.y[ind])
+
+        if zeros is True:  # if zeros was specified, check for and insert values as necessary
+            if len(xout) == 0:  # if there is no intensity in the spectrum
+                xout = [float(self.start), float(self.end)]
+                yout = [0., 0.]
+            if xout[0] != self.start:
+                xout.insert(0, self.start)
+                yout.insert(0, 0.)
+            if xout[-1] != self.end:
+                xout.append(self.end)
+                yout.append(0.)
+        return [xout, yout]
+
+
+def check_indexing(n=1000, dec=3):
+    """
+    Validates the indexing functionality of the Spectrum class
+
+    :param n: number of iterations
+    :param dec: decimal place for the Spectrum object
+    :return: number of mismatches, details
+    """
+    spec = Spectrum(3)
+    mismatch = 0
+    mml = []
+    for i in range(n):
+        num = random()
+        mz = num * 2000.
+        try:
+            index = spec.index(mz)
+        except ValueError:
+            continue
+        if round(mz, dec) != round(spec.x[index], dec):
+            mismatch += 1
+            mml.append([mz, round(mz, dec), round(spec.x[index], dec)])
+    return mismatch, mml
+
+
+if __name__ == '__main__':
+    pass
+    # spec = Spectrum(3)
+    # spec = Spectrum(4,start=12.0,end=13.0033548378,specin=[[12.0,13.0033548378],[0.9893, 0.0107]],empty=True,filler=0.)
+    # masses = [12.0,13.0033548378]
+    # abunds = [0.9893, 0.0107]
+
+    # spec = Spectrum(10,start=1,end=3,specin=[[1.00782503207,2.0141017778],[0.999885,0.000115]],empty=True,filler=0.)
+    # masses = [1.00782503207,2.0141017778]
+    # abunds = [0.999885,0.000115]
+
+    # dec = 4
+    # spec = Spectrum(dec,start=1,end=3,specin=[[1.00782503207,2.0141017778],[0.999885,0.000115]],empty=True,filler=0.)
+    # masses = [15.99491461956,16.9991317,17.999161]
+    # abunds = [0.99757,0.00038,0.00205]
+    #
+    #
+    # print spec
+    #
+    # thresh = 0.01
+    # cons = 3*10**-dec
+    #
+    # for i in range(3900):
+    #    sys.stdout.write('\rcarbons: %d' %(i+1))
+    #    spec.addelement([12.0,13.0033548378],[0.9893, 0.0107])
+    #    spec.normalize(100.)
+    #    spec.consolidate(thresh,cons)
+    # sys.stdout.write('\n')
+    # print 'length of x:', len(spec.x)
+    # for i in range(2401):
+    #    sys.stdout.write('\roxygens: %d' %(i+1))
+    #    spec.addelement(masses,abunds)
+    #    spec.normalize(100.)
+    #    spec.consolidate(thresh,cons)
+    # sys.stdout.write('\n')
+    # print 'length of x:',len(spec.x)
+    #
+    # st.printelapsed()
+    # st.printprofiles()
+    # mismatch,mml = checkindexing(1000,3)
+    # print mismatch

lib/pythoms/tome.py

@@ -0,0 +1,1237 @@
+"""
+Tome v02 A compilation of all Lars' python scripts as callable functions
+
+IGNORE:
+functions:
+    autoresolution (estimates the resolution of a spectrum)
+    bindata (bins a list of values)
+    binnspectra (bins n mass spectra together into a single mass spectrum)
+    bincidspectra (bins mass spectra together based on their collision voltage)
+    filepresent (checks for a file or directory in the current working directory)
+    find_all (finds all locations of files of a given name in a provided directory)
+    linmag (generates a list of values which is linear in magnification)
+    linramp (generates a list of values which is linear from start to finish)
+    locateinlist (locates a value or the closest value to it in a sorted list)
+    lyround (rounds a number given a particular base number)
+    mag (calculates and returns the magnification of a given y value relative to the start)
+    normalize (normalizes a list to a given value)
+    plotms (plots a mass spectrum)
+    sigmafwhm (cacluates sigma and fwhm from a resolution and a mass)
+    strtolist (converts a string to a list)  
+    version_input (uses the appropriate user input function depending on the python version)      
+
+changelog:
+    created mzML class and moved many functions to work within that class (removed several functions from Tome)
+    added strtolist
+    moved classes to separate files
+    fullspeclist has been moved to _Spectrum class (there were issues with mutation of the original)
+    calcindex has also been moved to _Spectrum class (it is used solely in that class)
+    moved colours to _Colour class
+    removed automz (now handled in the Molecule class)
+    created bincidspectra to bin spectra with the same cid together
+    removed loadwb, openpyxlcheck, pullparams (now included in XLSX class)
+    generalized filepresent
+    removed pwconvert (now included in mzML class)
+    completely rewrote resolution
+    rewrote resolution again to check multiple portions of the spectrum
+    significant change to plotms
+    moved alpha to XLSX class
+    ---v02---
+IGNORE
+"""
+import os
+import sys
+import scipy as sci
+import numpy as np
+from .spectrum import Spectrum
+from bisect import bisect_left, bisect_right
+from .colour import Colour
+from .molecule import IPMolecule
+import pylab as pl
+
+# ----------------------------------------------------------
+# -------------------FUNCTION DEFINITIONS-------------------
+# ----------------------------------------------------------
+
+
+def resolution(x, y, index=None, threshold=5):
+    """
+    Finds the resolution and full width at half max of a spectrum
+
+    :param x: list of mz values
+    :param y: corresponding list of intensity values
+    :param index: index of maximum intensity (optional; used if the resolution of a specific peak is desired)
+    :param threshold: signal to noise threshold required to output a resolution
+    :return: resolution
+    """
+    y = sci.asarray(y)  # convert to array for efficiency
+    if index is None:  # find index and value of maximum
+        maxy = max(y)
+        index = sci.where(y == maxy)[0][0]
+    else:
+        maxy = y[index]
+    # if intensity to average is below this threshold (rough estimate of signal/noise)
+    if maxy / (sum(y) / len(y)) < threshold:
+        return None
+    halfmax = maxy / 2
+    indleft = int(index) - 1  # generate index counters for left and right walking
+    indright = int(index) + 1
+    while y[indleft] > halfmax:  # while intensity is still above halfmax
+        indleft -= 1
+    while y[indright] > halfmax:
+        indright += 1
+    return x[index] / (x[indright] - x[indleft])  # return resolution (mz over full width at half max)
+
+
+def autoresolution(x, y, n=10, v=True):
+    """
+    Attempts to determine the resolution of a provided spectrum by finding n pseudo-random
+    samples, then finding a peak in each of those samples to determine the resolution.
+
+
+    **Parameters**
+
+    x: *list*
+        List of x values (1D list)
+
+    y: *list*
+        List of y values (1D list, must be the same length as *x*)
+
+    n: *int*, optional
+        Number of sections to check in the supplied spectrum
+
+    v: *Bool*, optional
+        Verbose toggle
+
+    
+    **Returns**
+    
+    resolution: *float*
+        The average resolution value determined by the function
+
+    """
+    if len(x) == 0 or len(y) == 0:
+        raise ValueError('the function has been handed an empty list')
+
+    if v is True:
+        sys.stdout.write('\rEstimating resolution of the spectrum')
+
+    # find some peaks in the spectrum
+    split = int(len(y) / n)
+    start = 0
+    end = start + split
+    splity = []
+    for i in range(n):
+        splity.append(sci.asarray(y[start:end]))
+        start += split
+        end += split
+    inds = []
+    for ind, section in enumerate(splity):
+        maxy = max(section)
+        if maxy == max(section[1:-1]):  # if max is not at the edge of the spectrum
+            inds.append(sci.where(section == maxy)[0][0] + split * ind)
+
+    res = []
+    for ind in inds:  # for each of those peaks
+        res.append(resolution(x, y, ind))
+    res = [y for y in res if y is not None]  # removes None values (below S/N)
+    res = sum(res) / len(res)  # calculate average
+    if v is True:
+        sys.stdout.write(': %.1f\n' % res)
+    return res  # return average
+
+
+def bindata(n, lst, v=1):
+    """
+    Bins a list of values into bins of size *n*.
+
+    **Parameters**
+    
+    n: *int*
+        Number of values to bin together. e.g. ``n = 4`` would bin the first four values into a single value, then the next 4, etc.
+
+    lst: *list*
+        List of values to bin.
+
+    v: *int* or *float*, optional
+        Bin scalar. The calculated bin values will be divided by this value. e.g. if ``n = v`` the output values will be an average of each bin.
+
+    **Returns**
+
+    binned list: *list*
+        A list of binned values.
+
+
+    **Notes**
+
+    - If the list is not divisible by `n`, the final bin will not be included in the output list. (The last values will be discarded.)
+
+    """
+    out = []
+    delta = 0
+    ttemp = 0
+    for ind, val in enumerate(lst):
+        delta += 1
+        ttemp += val  # add current value to growing sum
+        if delta == n:  # critical number is reached
+            out.append(ttemp / float(v))  # append sum to list
+            delta = 0  # reset critical count and sum
+            ttemp = 0
+    return out
+
+
+def binnspectra(lst, n, dec=3, start=50., end=2000.):
+    """
+    Sums n spectra together.
+
+    **Parameters**
+
+    lst: *list*
+        A list of paired lists of the form ``[ [[x1,x2,...,xn],[y1,y2,...,yn]] , [[],[]] ,...]``
+        where each index of the parent list is one paired spectrum of x and y values.
+        The x values of one index do not have to be the same. The spectra will be combined based on the x value rounded to the nearest 10^-`dec`.
+
+    n: *int*
+        The number of adjacent spectra to bin together. e.g. ``n = 4`` would bin the first four spectra into a single spectrum, then the next 4, etc.
+    
+    dec: *int*
+        The decimal place to track the x values to. e.g. ``dec = 3`` would track x values to the nearest 0.001 (10^-3)
+
+    start: *float*, optional
+        The minimum x value to track in the summed spectra.
+
+    end: *float*, optional
+        The maximum x value to track in the summed spectra.
+
+    **Returns**
+
+    binned spectrum list: *list*
+        A list of paired lists (similar to *lst*) where each index is a binned spectrum.
+        If there is only one item in the binned spectra, this returns a single paired list
+        of the form ``[[x values],[y values]]``.
+    """
+    out = []
+    delta = 0
+    spec = Spectrum(
+        dec,
+        start=start - 1,
+        end=end + 1,
+    )
+    for ind, (x, y) in enumerate(lst):  # for each timepoint
+        delta += 1
+        sys.stdout.write('\rBinning spectrum #%i/%i  %.1f%%' % (ind + 1, len(lst), float(ind) / float(len(lst)) * 100.))
+        spec.add_spectrum(x, y)  # add spectrum
+        if delta == n:  # critical number is reached
+            out.append(spec.trim(zeros=True))  # append list
+            spec.reset_y()  # reset y list in object
+            delta = 0  # reset critical sum
+    sys.stdout.write(' DONE\n')
+    if len(out) == 1:  # if there is only one item
+        return out[0]
+    return out
+
+
+def bincidspectra(speclist, celist, dec=3, startmz=50., endmz=2000., threshold=0, fillzeros=False):
+    """
+    Bins mass spectra together based on the collision voltage of associated with each spectrum.
+
+    **Parameters**
+
+    speclist: *list*
+        A list of lists of the form ``[ [[x1,x2,...,xn],[y1,y2,...,yn]] , [[],[]] ,...]``
+        where each index of the parent list is one paired spectrum of x and y values.
+        The x values of one index do not have to be the same. The spectra will be combined based on the x value rounded to the nearest 10^-`dec`.
+
+    celist: *list*
+        A list of collision energy values, where each index corresponds to the spectrum at that index of *speclist*. This list must be the same length as *speclist*.
+
+    dec: *int*
+        The decimal place to track the x values to. e.g. ``dec = 3`` would track x values to the nearest 0.001 (10^-3)
+    
+    startmz: *float*, optional
+        The minimum mass to charge value to track in the summed spectra.
+
+    end: *float*, optional
+        The maximum mass to charge value to track in the summed spectra.
+
+    threshold: *float*, optional
+        The minimum y value intensity to track.
+
+    fillzeros: *bool*, optional
+        Whether to fill the resulting spectra with 0. for every value of x that does not have intensity.
+
+    **Returns**
+
+    specout: *list*
+        A list of paired lists (similar to *speclst*) where each index is a binned spectrum.
+
+    cv: *list*
+        A sorted list of collision voltages with each index corresponding to that index in *specout*.
+
+    """
+    binned = {}
+
+    for ind, ce in enumerate(celist):
+        sys.stdout.write('\rBinning spectrum by CID value #%i/%i  %.1f%%' % (
+        ind + 1, len(celist), float(ind + 1) / float(len(celist)) * 100.))
+        if ce not in binned:  # generate key and spectrum object if not present
+            binned[ce] = Spectrum(dec, start=startmz, end=endmz)
+        else:  # otherwise add spectrum
+            binned[ce].add_spectrum(speclist[ind][0], speclist[ind][1])
+
+    if threshold > 0 or fillzeros is True:  # if manipulation is called for
+        for vol in binned:  # for each voltage
+            sys.stdout.write('\rZero filling spectrum for %s eV' % str(vol))
+            if threshold > 0:
+                binned[vol].threshold(threshold)  # apply threshold
+            if fillzeros is True:
+                binned[vol].fill_with_zeros()  # fill with zeros
+        sys.stdout.write(' DONE\n')
+
+    cv = []  # list for collision voltages
+    specout = []  # list for spectra
+    for vol, spec in sorted(binned.items()):
+        sys.stdout.write('\rTrimming spectrum for %s eV' % str(vol))
+        cv.append(vol)  # append voltage to list
+        specout.append(spec.trim())  # append trimmed spectrum to list
+    sys.stdout.write(' DONE\n')
+    sys.stdout.flush()
+    return specout, cv
+
+
+def find_all(fname, path):
+    """
+    Finds all files matching a specified name within the directory specified.
+
+    **Parameters**
+
+    fname: *string*
+        The name of the file to be located
+
+    path: *string*
+        The absolute directory path to search.
+
+    
+    **Returns**
+
+    list of locations: *list*
+        A list of all possible paths matching the filename in the specified directory.
+
+    """
+    locations = []
+    for root, dirs, files in os.walk(path):
+        if fname in files:
+            locations.append(os.path.join(root, fname))
+    return locations
+
+
+def linmag(vali, magstart, magend, dur):
+    """
+    Generates a ramp of values that is linear in magnification.
+
+    **Parameters**
+
+    vali: *float*
+        The initial y value at the start of the ramp.
+
+    magstart: *float*
+        The magnification at the start of the ramp.
+
+    magend: *float*
+        The magnification at the end of the ramp.
+
+    dur: *int*
+        The desired number of steps to get from *magstart* to *magend*.
+
+
+    **Returns**
+
+    list of magnifications: *list*
+        A list of magnifications corresponding to the ramp.
+
+    """
+    out = []
+    for i in range(dur):
+        out.append(float(vali) / ((magend - magstart) / dur * i + magstart))
+    return out
+
+
+def linramp(valstart, valend, dur):
+    """
+    Generates a linear ramp of values.
+
+    **Parameters**
+
+    valstart: *float*
+        The value at the start of the ramp.
+
+    valend: *float*
+        The value at the end of the ramp.
+
+    dur: *int*
+        The number of steps in the ramp.
+
+
+    **Returns**
+
+    List of ramped values: *list*
+
+    """
+    out = []
+    for i in range(int(dur)):
+        out.append(((float(valend - valstart)) / (float(dur))) * i + valstart)
+    return out
+
+
+def locate_in_list(lst, value, bias='closest', within=0.1):
+    """
+    Finds index in a sorted list of the value closest to a given value
+
+    If two numbers are equally close, return the smallest number.
+    roughly based on http://stackoverflow.com/questions/12141150/from-list-of-integers-get-number-closest-to-a-given-value
+
+    :param lst: list of values to search
+    :param value: value number to find
+    :param bias: 'lesser' will return the position of the value just less than the provided value.
+        'greater' will return the position of the value just greater than the provided value.
+        'closest' will return the index of the nearest value to the one provided
+    :param within: If the bias is closest, the position will only be returned if the position is this value away from
+        the actual value
+    :return: index of the position
+    :rtype: int
+    """
+    pos = bisect_left(lst, value)
+    if pos == 0:  # if at start of list
+        return pos
+    elif pos == len(lst):  # if insertion is beyond index range
+        return pos - 1
+    if lst[pos] == value:  # if an exact match is found
+        return pos
+    if bias == 'greater':  # return value greater than the value (bisect_left has an inherent bias to the right)
+        return pos
+    if bias == 'lesser':  # return value lesser than the provided
+        return pos - 1
+    if bias == 'closest':  # check differences between index and index-1 and actual value, return closest
+        adjval = abs(lst[pos - 1] - value)
+        curval = abs(lst[pos] - value)
+        if adjval > within and curval > within:  # if the value is outside of the lookwithin bounds
+            return None
+        if adjval < curval:  # if the lesser value is closer
+            return pos - 1
+        if adjval == curval:  # if values are equidistant
+            return pos - 1
+        else:
+            return pos
+
+
+def lyround(x, basen):
+    """
+    Rounds the specified number using a specific base
+
+    **Parameters**
+
+    x: *float*
+        The value to be rounded
+
+    basen: *int*
+        The number base to use for rounding
+
+
+    **Returns**
+
+    value: *float*
+        The rounded value.
+
+    **Notes**
+
+    This function is based on http://stackoverflow.com/questions/2272149/round-to-5-or-other-number-in-python
+    """
+    base = basen ** (int(len(str(int(x)))) - 1)
+    return int(base * round(float(x) / base))
+
+
+def mag(initial, current):
+    """
+    Calculates the magnification of a specified value
+
+    **Parameters**
+
+    intial: *float*
+        initial value (magnificiation of 1)
+
+    current: *float*
+        current value
+
+
+    **Returns**
+
+    magnification: *float*
+        the magnification of the current value
+    """
+    return float(initial) / float(current)
+
+
+def normalize(lst, maxval=1.):
+    """
+    Normalizes a list of values with a specified value.
+
+    **Parameters**
+
+    lst: *list*
+        List of values to be normalized
+
+    maxval: *float*, optional
+        The maximum value that the list will have after normalization.
+
+
+    **Returns**
+
+    normalized list: *list*
+        A list of values normalized to the specified value.
+
+    """
+    listmax = max(lst)
+    for ind, val in enumerate(lst):
+        lst[ind] = float(val) / float(listmax) * maxval
+    return lst
+
+
+def localmax(x: list, y: list, xval: float, lookwithin: float = 1.):
+    """
+    Finds the local maximum within +/- lookwithin of the xval
+
+    :param x: x list
+    :param y: y list
+    :param xval:
+    :param lookwithin:
+    :return: maximum y value
+    :rtype: float
+    """
+    l = bisect_left(x, xval - lookwithin)
+    r = bisect_right(x, xval + lookwithin)
+    return max(y[l:r])
+
+
+def trimspectrum(x: list, y: list, left: float, right: float, outside: bool = False):
+    """
+    Trims a spectrum to the left and right bounds specified
+
+    :param x: x value list
+    :param y: y value list
+    :param left: left trim value
+    :param right: right trim value
+    :param outside: Whether to include the next point outside of the trimmed spectrum. This provides continuity if the
+        spectrum is to be used for image generation.
+    :return: new spectrum
+    :rtype: tuple of list
+    """
+    # find indicies
+    l = locate_in_list(x, left, 'greater')
+    r = locate_in_list(x, right, 'lesser')
+    if outside is True:
+        l -= 1
+        r += 1
+    return x[l:r + 1], y[l:r + 1]  # trim spectrum
+
+
+def estimated_exact_mass(
+        x: list,
+        y: list,
+        em: float,
+        simmin: float,
+        simmax: float,
+        lookwithin: float = 1,
+):
+    """
+    Estimates the exact mass of a peak in a spectrum within a provided simulated set of bounds
+
+    :param x: x value list
+    :param y: y value list
+    :param em: estimated exact mass for the species
+    :param simmin: minimum bound for the simulated isotope pattern
+    :param simmax: maximum bounds for the simulated isotope pattern
+    :param lookwithin: +/- bounds for the search
+    :return: estimated exact mass
+    :rtype: float
+    """
+    # narrow range to that of the isotope pattern
+    l = bisect_left(x, simmin - lookwithin)
+    r = bisect_right(x, simmax + lookwithin)
+    locmax = max(y[l:r])  # find local max in that range
+    for ind, val in enumerate(y):
+        if val == locmax:  # if the y-value equals the local max
+            if l <= ind <= r:  # and if the index is in the range (avoids false locations)
+                return x[ind]
+    difleft = abs(em - simmin)
+    difright = abs(em - simmax)
+    return '>%.1f' % max(difleft, difright)  # if no match is found, return maximum difference
+
+
+# TODO change simdict to be nonmutable
+def plot_mass_spectrum(
+        realspec,
+        simdict={},
+        mz='auto',  # m/z bounds for the output spectrum
+        outname='spectrum',  # name for the output file
+        output='save',  # 'save' or 'show' the figure
+        simtype='bar',  # simulation overlay type ('bar' or 'gaussian')
+        spectype='continuum',  # spectrum type ('continuum' or 'centroid')
+        maxy='max',  # max or value
+        norm=True,  # True or False
+        simnorm='spec',  # top, spec, or value
+        xlabel=True,  # show x label
+        ylabel=True,  # show y label
+        xvalues=True,  # show x values
+        yvalues=True,  # show y values
+        showx=True,  # show x axis
+        showy=True,  # how y axis
+        offsetx=True,  # offset x axis (shows low intensity species better)
+        fs=16,  # font size
+        lw=1.5,  # line width for the plotted spectrum
+        axwidth=1.5,  # axis width
+        simlabels=False,  # show labels isotope for patterns
+        bw='auto',  # bar width for isotope patterns (auto does 2*fwhm)
+        specfont='Arial',  # the font for text in the plot
+        size=[7.87, 4.87],  # size in inches for the figure
+        dpiout=300,  # dpi for the output figure
+        exten='png',  # extension for the output figure
+        resolution=None,  # resolution to use for simulations (if not specified, automatically calculates)
+        res_label=False,  # output the resolution of the spectrum
+        delta=False,  # output the mass delta between the spectrum and the isotope patterns
+        stats=False,  # output the goodness of match between the spectrum and the predicted isotope patterns,
+        speccolour='k',  # colour for the spectrum to be plotted
+        padding='auto',  # padding for the output plot
+        verbose=True,  # verbose setting
+        normwindow='fwhm',  # the width of the window to look for a maximal value around the expected exact mass for a peak
+        annotations=None,  # annotations for the spectrum in dictionary form {'thing to print':[x,y],}
+        normrel=100.,  # the maximum value for normalization
+        ipmol_kwargs={},  # IPMolecule keyword arguments
+        **kwargs
+):
+    """
+    Plots and saves a publication quality mass spectrum with optional overlaid isotope patterns
+
+    :param list realspec: A paired list of x and y values of the form ``[[x values],[y values]]``
+    :param dict simdict: This can either be a molecular formula to predict the isotope pattern of (string),
+        a list of formulae, or a dictionary of the form
+        ``simdict = {'formula1':{'colour':<hex or name or RGB tuple>, 'alpha':float}, ...}``.
+        If this is dictionary is left empty, no isotope patterns will be overlaid on the output
+        spectrum.
+    :param list mz: The *m/z* bounds for the output spectrum. Default: 'auto', but can be supplied
+        with a tuple or list of length 2 of the form ``[x start, x end]``.
+    :param str outname: Name of the file to be saved.
+    :param str output: Save ('save') or show ('show') the figure.
+    :param str simtype: The type for the isotope pattern simulation overlay. Options: 'bar' or 'gaussian'.
+    :param str spectype: The type of spectrum being handed to the function. Options: 'continuum' or 'centroid'.
+    :param float maxy: The maximum y value for the spectrum. Options: 'max' or specify a value
+    :param bool norm: Normalize the spectrum. Options: bool
+    :param str, float simnorm: Normalize the isotope pattern simulations to what value. Options: 'top', 'spec', or
+        specify a value. Top will normalize the patterns to ``maxy``, and will only function if maxy is not 'max'.
+        Spec will normalize the patterns to the maximum spectrum y value within the x bounds of the
+        simulated pattern.
+        Specifying a value will normalize all isotope patterns to that value.
+    :param bool xlabel: Whether to show the label for the *m/z* axis.
+    :param bool ylabel: Whether to show the y-axis label.
+    :param bool xvalues: Whether to show the values of the x-axis.
+    :param bool yvalues: Whether to show the values of the y-axis.
+    :param bool showx: Whether to show the x-axis line.
+    :param bool showy: Whether to show the y-axis line.
+    :param bool offsetx: Whether to offset the x-axis slightly.
+        Enabling this shows makes it easier to see low intensity peaks.
+    :param int fs: Font size to use for labels.
+    :param float lw: Line width for the plotted spectrum.
+    :param float axwidth: Line width for the axes and tick marks. Default 1.5
+    :param bool simlabels: Whether to show the names of the simulated isotope patterns.
+        The names will be exactly as supplied in ``simdict``.
+    :param float bw: The width of the bar in *m/z* for bar isotope patterns. Options: 'auto' or float.
+        This only has an affect if *simtype* is 'bar'.
+        Auto make the bars equal to 2 times the full width at half max of the peak they are simulating.
+    :param str specfont: The font to use for text in the plot. The specified font must be accepted by matplotlib.
+    :param list size: The size in inches for the output figure. This must be a list of length 2 of the form
+        ``[width,height]``.
+    :param int dpiout: The dots per inch for the output figure.
+    :param str exten: The file extension for the output figure. Options: 'png', 'svg', or other supported by matplotlib.
+    :param float resolution: Override the auto-resolution calculation with a specified instrument resolution
+    :param bool res_label: Whether to output the resolution of the spectrum onto the figure.
+    :param bool delta: Whether to calculate and output the mass delta between the exact mass predicted by the isotope
+        pattern simulation and the location of the maximum intensity within the bounds specified by *normwindow*.
+    :param bool stats: Whether to calculate and output the goodness of fit between the predicted isotope pattern and
+        the supplied spectrum. This functionality is still a work in progress.
+    :param speccolour: The colour for the real spectrum , # colour for the spectrum to be plotted
+    :param list padding: This allows the user to specify the subplot padding of the output figure.
+        Options: 'auto' or list of the form ``[left,right,bottom,top]`` scalars.
+    :param bool verbose: Verbose option for the script. Options: bool.
+    :param float normwindow: The *m/z* window width within with too look for a maximum intensity value.
+        This will only have an effect if *delta* is ``True``.
+        Options: 'fwhm' for full width at half max or float.
+    :param dict annotations: Annotations for the spectrum in dictionary form: ``{'thing to print':[x,y],}``.
+    :param normrel: The maximum value for normalization. This can be used to globally set the top value for normalizing
+        simulated isotope patterns. This is used most often to show the lack of an isotope pattern in the shown area.
+    :param ipmol_kwargs: Keyword arguments to use for IPMolecule calls. See IPMolecule for more details.
+    :param kwargs: catch for unused kwargs
+    """
+    def checksimdict(dct):
+        """
+        checks the type of simdict, converting to dictionary if necessary
+        also checks for alpha and colour keys and adds them if necessary (defaulting to key @ 0.5)
+        """
+        if type(dct) is not dict:
+            if type(dct) is str:
+                dct = {dct: {}}
+            elif type(dct) is list or type(dct) is tuple:
+                tdct = {}
+                for i in dct:
+                    tdct[i] = {}
+                dct = tdct
+        for species in dct:
+            if 'colour' not in dct[species]:
+                dct[species]['colour'] = 'k'
+            if 'alpha' not in dct[species]:
+                dct[species]['alpha'] = 0.5
+        return dct
+
+    if resolution is None:
+        if spectype != 'centroid':
+            resolution = autoresolution(realspec[0], realspec[1])  # calculate resolution
+        else:
+            resolution = 5000
+
+    simdict = checksimdict(simdict)  # checks the simulation dictionary
+    for species in simdict:  # generate Molecule object and set x and y lists
+        simdict[species]['colour'] = Colour(simdict[species]['colour'])
+        simdict[species]['mol'] = IPMolecule(
+            species,
+            resolution=resolution,
+            **ipmol_kwargs,
+        )
+        # simdict[species]['mol'] = Molecule(species, res=res, dropmethod='threshold')
+        if simtype == 'bar':
+            simdict[species]['x'], simdict[species]['y'] = simdict[species]['mol'].barip
+        if simtype == 'gaussian':
+            simdict[species]['x'], simdict[species]['y'] = simdict[species]['mol'].gausip
+
+    if mz == 'auto':  # automatically determine m/z range
+        if verbose is True:
+            sys.stdout.write('Automatically determining m/z window')
+        mz = [10000000, 0]
+        for species in simdict:
+            simdict[species]['bounds'] = simdict[species]['mol'].bounds  # calculate bounds
+            if simdict[species]['bounds'][0] < mz[0]:
+                mz[0] = simdict[species]['bounds'][0] - 1
+            if simdict[species]['bounds'][1] > mz[1]:
+                mz[1] = simdict[species]['bounds'][1] + 1
+        if mz == [10000000, 0]:
+            mz = [min(realspec[0]), max(realspec[0])]
+        if verbose is True:
+            sys.stdout.write(': %i - %i\n' % (int(mz[0]), int(mz[1])))
+            sys.stdout.flush()
+
+    realspec[0], realspec[1] = trimspectrum(  # trim real spectrum for efficiency
+        realspec[0],
+        realspec[1],
+        mz[0] - 1,
+        mz[1] + 1
+    )
+
+    if len(realspec[0]) == 0:  # catch for empty spectrum post-trim (usually user error)
+        raise ValueError(f'There are no spectral values in the specified m/z bounds ({mz[0]}-{mz[1]}). Common causes: '
+                         f'no values in the loaded spectrum within the window of interest, an error in specifying the '
+                         f'molecule(s) to simulate')
+
+    if norm is True:  # normalize spectrum
+        realspec[1] = normalize(realspec[1], normrel)
+
+    for species in simdict:  # normalize simulations
+        if simnorm == 'spec':  # normalize to maximum around exact mass
+            if normwindow == 'fwhm':  # if default, look within the full width at half max
+                window = simdict[species]['mol'].fwhm
+            else:  # otherwise look within the specified value
+                window = normwindow
+            simdict[species]['y'] = normalize(
+                simdict[species]['y'],
+                localmax(
+                    realspec[0],
+                    realspec[1],
+                    simdict[species]['mol'].estimated_exact_mass,
+                    window
+                )
+            )
+        elif simnorm == 'top':  # normalize to top of the y value
+            if maxy == 'max':
+                raise ValueError('Simulations con only be normalized to the top of the spectrum when the maxy setting '
+                                 'is a specific value')
+            simdict[species]['y'] = normalize(simdict[species]['y'], maxy)
+        elif type(simnorm) is int or type(simnorm) is float:  # normalize to specified value
+            simdict[species]['y'] = normalize(simdict[species]['y'], simnorm)
+        if delta is True:
+            if normwindow == 'fwhm':  # if default, look within the full width at half max
+                window = simdict[species]['mol'].fwhm
+            else:  # otherwise look within the specified value
+                window = normwindow
+            est = estimated_exact_mass(  # try to calculate exact mass
+                realspec[0],
+                realspec[1],
+                simdict[species]['mol'].estimated_exact_mass,
+                simmin=simdict[species]['mol'].estimated_exact_mass,
+                simmax=simdict[species]['mol'].estimated_exact_mass,
+                lookwithin=window,
+                # min(simdict[species]['x']),
+                # max(simdict[species]['x'])
+            )
+            if type(est) is float:
+                simdict[species]['delta'] = '%.3f (%.1f ppm)' % (
+                simdict[species]['mol'].estimated_exact_mass - est, simdict[species]['mol'].compare_exact_mass(est))
+            else:
+                simdict[species]['delta'] = est
+
+    pl.clf()  # clear and close figure if open
+    pl.close()
+    fig = pl.figure(figsize=tuple(size))
+    ax = fig.add_subplot(111)
+
+    ax.spines["right"].set_visible(False)  # hide right and top spines
+    ax.spines["top"].set_visible(False)
+
+    if showx is False:
+        ax.spines["bottom"].set_visible(False)  # hide bottom axis
+    if showy is False:
+        ax.spines["left"].set_visible(False)  # hide left axis
+
+    for axis in ["top", "bottom", "left", "right"]:
+        ax.spines[axis].set_linewidth(axwidth)
+
+    if offsetx is True:  # offset x axis
+        ax.spines["bottom"].set_position(('axes', -0.01))
+
+    font = {'fontname': specfont, 'fontsize': fs}  # font parameters for axis/text labels
+    tickfont = pl.matplotlib.font_manager.FontProperties(  # font parameters for axis ticks
+        family=specfont,
+        size=fs
+    )
+
+    ax.set_xlim(mz)  # set x bounds
+
+    if maxy == 'max':  # set y bounds
+        ax.set_ylim(0., max(realspec[1]))
+        top = max(realspec[1])
+    elif type(maxy) is int or type(maxy) is float:
+        ax.set_ylim(0., maxy)
+        top = maxy
+
+    if simtype == 'bar':  # generates zeros for bottom of bars (assumes m/z spacing is equal between patterns)
+        for species in simdict:
+            simdict[species]['zero'] = []
+            for i in simdict[species]['x']:
+                simdict[species]['zero'].append(0.)
+        for species in simdict:  # for each species
+            for subsp in simdict:  # look at all the species
+                if subsp != species:  # if it is not itself
+                    ins = bisect_left(simdict[subsp]['x'], simdict[species]['x'][-1])  # look for insertion point
+                    if 0 < ins < len(simdict[subsp]['x']):  # if species highest m/z is inside subsp list
+                        for i in range(ins):  # add intensity of species to subsp zeros
+                            # used -ins+i-1 to fix an error, with any luck this won't break it next time
+                            simdict[subsp]['zero'][i] += simdict[species]['y'][-ins + i]
+    # include resolution if specified (and spectrum is not centroid)
+    if res_label is True and spectype != 'centroid':
+        ax.text(
+            mz[1],
+            top * 0.95,
+            f'resolution: {str(round(resolution))}',
+            horizontalalignment='right',
+            **font
+        )
+
+    for species in simdict:  # plot and label bars
+        if simtype == 'bar':
+            if bw == 'auto':
+                bw = simdict[species]['mol'].fwhm * 2
+            else:
+                bw = bw
+            ax.bar(
+                simdict[species]['x'],
+                simdict[species]['y'],
+                bw,
+                alpha=simdict[species]['alpha'],
+                color=simdict[species]['colour'].mpl,
+                linewidth=0,
+                align='center',
+                bottom=simdict[species]['zero']
+            )
+        elif simtype == 'gaussian':
+            ax.plot(
+                simdict[species]['x'],
+                simdict[species]['y'],
+                alpha=simdict[species]['alpha'],
+                color=simdict[species]['colour'].mpl,
+                linewidth=lw
+            )
+            ax.fill_between(
+                simdict[species]['x'],
+                0,
+                simdict[species]['y'],
+                alpha=simdict[species]['alpha'],
+                color=simdict[species]['colour'].mpl,
+                linewidth=0
+            )
+        # if any labels are to be shown
+        if simlabels is True or stats is True or delta is True:
+            string = ''
+            bpi = simdict[species]['y'].index(max(simdict[species]['y']))  # index of base peak
+            if simlabels is True:  # species name
+                string += species
+                if stats is True or delta is True:  # add return if SER or delta is called for
+                    string += '\n'
+            if stats is True:  # standard error of regression
+                string += f'SER: {simdict[species]["mol"].compare(realspec)} '
+            if delta is True:  # mass delta
+                string += f'mass delta: {simdict[species]["delta"]}'
+            ax.text(
+                simdict[species]['x'][bpi],
+                top * 1.01,
+                string,
+                color=simdict[species]['colour'].mpl,
+                horizontalalignment='center',
+                **font
+            )
+
+    if spectype == 'continuum':
+        ax.plot(
+            realspec[0],
+            realspec[1],
+            linewidth=lw,
+            color=Colour(speccolour).mpl
+        )
+    elif spectype == 'centroid':
+        dist = []
+        for ind, val in enumerate(realspec[0]):  # find distance between all adjacent m/z values
+            if ind == 0:
+                continue
+            dist.append(realspec[0][ind] - realspec[0][ind - 1])
+        dist = sum(dist) / len(dist)  # average distance
+        ax.bar(
+            realspec[0],
+            realspec[1],
+            dist * 0.75,
+            linewidth=0,
+            color=Colour(speccolour).mpl,
+            align='center',
+            alpha=0.8
+        )
+
+    if annotations is not None:
+        for label in annotations:
+            ax.text(
+                annotations[label][0],
+                annotations[label][1],
+                label,
+                horizontalalignment='center',
+                **font
+            )
+
+            # show or hide axis values/labels as specified
+    if yvalues is False:  # y tick marks and values
+        ax.tick_params(axis='y', labelleft='off', length=0)
+    else:  # y value labels
+        ax.tick_params(
+            axis='y',
+            length=axwidth * 3,
+            width=axwidth,
+            direction='out',
+            right=False,
+        )
+        for label in ax.get_yticklabels():
+            label.set_fontproperties(tickfont)
+    if ylabel is True:  # y unit
+        if top == 100:  # normalized
+            ax.set_ylabel('relative intensity', **font)
+        else:  # set to counts
+            ax.set_ylabel('intensity (counts)', **font)
+
+    if xvalues is False:  # x tick marks and values
+        ax.tick_params(axis='x', labelbottom='off', length=0)
+    else:  # x value labels
+        ax.tick_params(
+            axis='x',
+            length=axwidth * 3,
+            width=axwidth,
+            direction='out',
+            top=False,
+        )
+        for label in ax.get_xticklabels():
+            label.set_fontproperties(tickfont)
+    if xlabel is True:  # x unit
+        ax.set_xlabel('m/z', style='italic', **font)
+
+    pl.ticklabel_format(useOffset=False)  # don't use the stupid shorthand thing
+    if padding == 'auto':
+        pl.tight_layout(pad=0.5)  # adjust subplots
+        if simlabels is True or stats is True or delta is True:
+            pl.subplots_adjust(top=0.90)  # lower top if details are called for
+    elif type(padding) is list and len(padding) == 4:
+        pl.subplots_adjust(
+            left=padding[0],
+            right=padding[1],
+            bottom=padding[2],
+            top=padding[3]
+        )
+
+    if output == 'save':  # save figure
+        outname = ''  # generate tag for filenaming
+        for species in simdict:
+            outname += ' ' + species
+        outname = outname + outname + '.' + exten
+        pl.savefig(
+            outname,
+            dpi=dpiout,
+            format=exten,
+            transparent=True
+        )
+        if verbose is True:
+            sys.stdout.write('Saved figure as:\n"%s"\nin the working directory' % outname)
+
+    elif output == 'show':  # show figure
+        pl.show()
+
+
+def plotuv(wavelengths, intensities, **kwargs):
+    """
+    Plots and saves a publication quality UV-Vis figure.
+
+    **Parameters**
+
+    wavelengths: *list*
+        A list of wavelengths
+
+    intensities: *list*
+        A list of intensity values paired by index to *wavelengths*
+
+
+    **Returns**
+
+    return item: ``None``
+        This function has no pythonic return.
+
+    **\*\*kwargs**
+
+    axwidth: 1.5
+        Line width for the axes and tick marks. Options: float.
+
+    colours:
+        A list of colours to be used if the fuction is supplied with multiple traces.
+
+    dpiout: 300
+        The dots per inch for the output figure. Options: integer.
+
+    exten: 'png'
+        The file extension for the output figure. Options: 'png', 'svg', or other supported by matplotlib.
+
+    fs: 16
+        Font size to use for labels. Options: integer or float.
+
+    legloc: 0
+        The matplotlib legend location key.
+        See http://matplotlib.org/api/legend_api.html for location codes.
+
+    lw: 1.5
+        Line width for the plotted spectrum. Options: float.
+
+    outname: 'UV-Vis spectrum'
+        Name for the output file. Options: string.
+
+    output: 'save'
+        Save ('save') or show ('show') the figure.
+
+    padding: 'auto'
+        This allows the user to specify the subplot padding of the output figure.
+        Options: 'auto' or list of the form ``[left,right,bottom,top]`` scalars.
+
+    size: [7.87,4.87]
+        The size in inches for the output figure. This must be a list of length 2 of the form
+        ``[width,height]``.
+
+    specfont: 'Arial'
+        The font to use for text in the plot. The specified font must be accepted by matplotlib.
+
+    times: None
+        A list of timepoints for each provided trace. These are used as labels in the legend.
+
+    verbose: True
+        Verbose option for the script. Options: bool.
+
+    xrange: None
+        The limits for the x axis. Options None or ``[x min,x max]``
+
+    yrange: None
+        The limits for the y axis. Options None or ``[y min,y max]``
+
+
+    """
+    settings = {  # default settings for the function
+        'outname': 'UV-Vis spectrum',  # name for the output file
+        'fs': 16,  # font size
+        'lw': 1.5,  # line width for the plotted spectrum
+        'axwidth': 1.5,  # axis width
+        'size': [7.87, 4.87],  # size in inches for the figure
+        'dpiout': 300,  # dpi for the output figure
+        'exten': 'png',  # extension for the output figure
+        'specfont': 'Arial',  # the font for text in the plot
+        # colours to use for multiple traces in the same spectrum (feel free to specify your own)
+        'colours': ['#a6cee3', '#1f78b4', '#b2df8a', '#33a02c', '#fb9a99', '#e31a1c', '#fdbf6f', '#ff7f00', '#cab2d6',
+                    '#6a3d9a', '#ffff99', '#8dd3c7', '#ffffb3', '#bebada', '#fb8072', '#80b1d3', '#fdb462', '#b3de69',
+                    '#fccde5', '#d9d9d9', '#bc80bd', '#ccebc5', ],
+        'xrange': None,  # the limits for the x axis
+        'yrange': None,  # the limits for the y axis
+        'times': None,  # time points for each provided trace (for legend labels)
+        'output': 'save',  # 'save' or 'show' the figure
+        'padding': None,  # padding for the output plot
+        'verbose': True,  # chatty
+        'legloc': 0,  # legend location (see http://matplotlib.org/api/legend_api.html location codes)
+    }
+    if set(kwargs.keys()) - set(settings.keys()):  # check for invalid keyword arguments
+        string = ''
+        for i in set(kwargs.keys()) - set(settings.keys()):
+            string += ' %s' % i
+        raise KeyError('Unsupported keyword argument(s): %s' % string)
+
+    settings.update(kwargs)  # update settings from keyword arguments
+
+    pl.clf()  # clear and close figure if open
+    pl.close()
+    fig = pl.figure(figsize=tuple(settings['size']))
+    ax = fig.add_subplot(111)
+
+    ax.spines["right"].set_visible(False)  # hide right and top spines
+    ax.spines["top"].set_visible(False)
+
+    font = {'fontname': settings['specfont'], 'fontsize': settings['fs']}  # font parameters for axis/text labels
+    tickfont = pl.matplotlib.font_manager.FontProperties(family=settings['specfont'],
+                                                         size=settings['fs'])  # font parameters for axis ticks
+
+    if type(intensities[0]) is float:  # if the function has only been handed a single spectrum
+        intensities = [intensities]
+
+    # determine and set limits for axes
+    if settings['xrange'] is None:  # auto determine x limits
+        settings['xrange'] = [min(wavelengths), max(wavelengths)]
+    if settings['yrange'] is None:  # auto determine y limits
+        settings['yrange'] = [0, 0]
+        for spec in intensities:
+            if max(spec) > settings['yrange'][1]:
+                settings['yrange'][1] = max(spec)
+    ax.set_xlim(settings['xrange'])  # set x bounds
+    ax.set_ylim(settings['yrange'])  # set y bounds
+
+    # apply font and tick parameters to axes
+    ax.tick_params(axis='x', length=settings['axwidth'] * 3, width=settings['axwidth'], direction='out', top='off')
+    for label in ax.get_xticklabels():
+        label.set_fontproperties(tickfont)
+    ax.tick_params(axis='y', length=settings['axwidth'] * 3, width=settings['axwidth'], direction='out', right='off')
+    for label in ax.get_yticklabels():
+        label.set_fontproperties(tickfont)
+    for axis in ["top", "bottom", "left", "right"]:
+        ax.spines[axis].set_linewidth(settings['axwidth'])
+
+    if settings['times'] is not None:
+        if len(settings['times']) != len(intensities):
+            raise IndexError('The numer of times provided do not match the number of traces provided.')
+
+    for ind, spec in enumerate(intensities):  # plot traces
+        if settings['times'] is not None:
+            string = 't = ' + str(round(settings['times'][ind], 1)) + 'm'
+            ax.plot(wavelengths, spec, label=string, color=Colour(settings['colours'][ind]).mpl,
+                    linewidth=settings['lw'])
+        else:
+            ax.plot(wavelengths, spec, color=Colour(settings['colours'][ind]).mpl, linewidth=settings['lw'])
+
+    if settings['times'] is not None:
+        ax.legend(loc=0, frameon=False)
+
+    ax.set_xlabel('wavelength (nm)', **font)
+    ax.set_ylabel('absorbance (a.u.)', **font)
+
+    if settings['padding'] is None:
+        pl.tight_layout(pad=0.5)  # adjust subplots
+    elif type(settings['padding']) is list and len(settings['padding']) == 4:
+        pl.subplots_adjust(left=settings['padding'][0], right=settings['padding'][1], bottom=settings['padding'][2],
+                           top=settings['padding'][3])
+
+    if settings['output'] == 'save':  # save figure
+        outname = settings['outname'] + '.' + settings['exten']
+        pl.savefig(outname, dpi=settings['dpiout'], format=settings['exten'], transparent=True)
+        if settings['verbose'] is True:
+            sys.stdout.write('Saved figure as:\n"%s"\nin the working directory' % outname)
+
+    elif settings['output'] == 'show':  # show figure
+        pl.show()
+
+
+def sigmafwhm(res, x):
+    """
+    Calculates the full width at half max and standard deviation for a spectrum peak.
+
+    **Parameters**
+
+    res: *float*
+        The resolution of the peak in question
+
+    x: *float*
+        The x value of the peak in question
+
+
+    **Returns**
+
+    fwhm: *float*
+        The full width at half max of the peak.
+
+    sigma: *float*
+        The standard deviation of the peak.
+
+    """
+    fwhm = x / res
+    sigma = fwhm / (2 * np.sqrt(2 * np.log(2)))  # based on the equation FWHM = 2*sqrt(2ln2)*sigma
+    return fwhm, sigma
+
+
+def strtolist(string):
+    """
+    Converts a string to a list with more flexibility than ``string.split()``
+    by looking for both brackets of type ``(,),[,],{,}`` and commas.
+
+    **Parameters**
+
+    string: *string*
+        The string to be split.
+
+
+    **Returns**
+
+    split list: *list*
+        The split list
+
+
+    **Examples**
+
+    ::
+
+        >>> strtolist('[(12.3,15,256.128)]')
+            [12.3, 15, 256.128]
+
+    """
+    out = []
+    temp = ''
+    brackets = ['(', ')', '[', ']', '{', '}']
+    for char in list(string):
+        if char not in brackets and char != ',':
+            temp += char
+        if char == ',':
+            try:
+                out.append(int(temp))
+            except ValueError:
+                out.append(float(temp))
+            temp = ''
+    if len(temp) != 0:  # if there is a weird ending character
+        try:
+            out.append(int(temp))
+        except ValueError:
+            out.append(float(temp))
+    return out