irspec 0.1.0__py3-none-any.whl

irspec/__init__.py

@@ -0,0 +1,2 @@
+"""irspec -- infrared spectra for chemistry students (see README.md and CHANGELOG.md)."""
+__version__ = "0.1.0"

irspec/__main__.py

@@ -0,0 +1,4 @@
+"""python -m irspec  ==  the irspec command."""
+from .cli import main
+
+main()

irspec/absorbance_to_transmittance.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""absorbance_to_transmittance.py -- convert an IR spectrum's y-axis between
+Absorbance and %Transmittance for nulabreport figures.
+
+WHY THIS EXISTS
+    nulabreport's \\irspectrum / \\irspectrumcompare macros just plot whatever
+    y-column a CSV gives them; they do not know or care whether that column
+    is Absorbance or %Transmittance. When a report puts several reference
+    spectra on comparable axes (this lab's own OMNIC exports are always
+    %Transmittance, 0-100), a source that is natively Absorbance has to be
+    converted on purpose -- silently mixing the two on one figure, or on
+    stacked panels a reader will visually compare, misleads regardless of
+    axis labels. This script does that conversion, once, in a place that
+    documents the formula, rather than as an unrepeatable one-off snippet
+    buried in a chat session.
+
+    Do NOT convert the other direction (Transmittance -> Absorbance) as a
+    way to "normalise everything to Absorbance" instead -- this lab's own
+    instrument output and house convention are %Transmittance; Absorbance
+    sources get converted to match, not the reverse. convert_series() below
+    supports both directions for completeness (and because the algebra is
+    symmetric), but the CLI defaults to --to transmittance for that reason.
+
+THE FORMULA
+    Absorbance and (fractional) Transmittance are related by the
+    Beer-Lambert definition A = -log10(T), i.e. T = 10^(-A), where T runs
+    0-1. This lab's %Transmittance convention is just T x 100:
+
+        %T = 100 x 10^(-A)
+        A  = -log10(%T / 100)
+
+    Both directions are monotonic and well-defined for A >= 0 (equivalently
+    0 < %T <= 100); A < 0 (%T > 100) can occur in noisy baseline data and is
+    passed through the same formula rather than clipped, so a slightly
+    negative-absorbance noise point becomes a slightly-over-100 %T point
+    instead of silently disappearing.
+
+INPUT / OUTPUT FORMAT
+    Same "plain" CSV convention used everywhere else in this pipeline
+    (spa_tool.py's write_plain_csv(), jdx_tool.py's decoded output): a
+    one-line header "wavenumber,intensity" followed by comma-delimited
+    rows, decimal point (not comma), ascending or descending wavenumber
+    order preserved as given -- this script does not resort or resample,
+    it only rewrites the intensity column in place.
+
+USAGE
+    python3 absorbance_to_transmittance.py IN.csv --out OUT.csv
+    python3 absorbance_to_transmittance.py IN.csv --out OUT.csv --to absorbance
+
+    IN.csv and OUT.csv may be the same path (the file is fully read before
+    anything is written).
+
+EXAMPLE (this report's actual use, 2026-09-18)
+    literature/webbook/plain/PROPIOPHENONE.csv was decoded from the NIST
+    Chemistry WebBook's native Absorbance .jdx (see
+    literature/webbook/decode_notes.md) and left as Absorbance in an
+    earlier pass of this report so as not to silently misrepresent the
+    source. Once the report started stacking it directly against
+    Transmittance curves in \\irspectrumcompare figures, the honest fix was
+    to convert it, not just label it:
+
+        python3 nulabreport/tools/absorbance_to_transmittance.py \\
+            literature/webbook/plain/PROPIOPHENONE.csv \\
+            --out literature/webbook/plain/PROPIOPHENONE.csv
+
+    The original Absorbance values are not lost: they still live untouched
+    in the raw source, literature/webbook/csv/PROPIOPHENONE.csv (semicolon-
+    delimited, decimal-comma, as downloaded), which this script never
+    reads or writes -- only the derived "plain" CSV is rewritten.
+"""
+
+import argparse
+import csv
+import math
+
+
+def convert_series(intensities, to="transmittance"):
+    """Convert a list of y-values between Absorbance and %Transmittance.
+
+    to="transmittance": treats input as Absorbance, returns %Transmittance
+        via %T = 100 * 10**(-A).
+    to="absorbance":     treats input as %Transmittance, returns Absorbance
+        via A = -log10(%T / 100).
+    """
+    if to == "transmittance":
+        return [100.0 * (10.0 ** (-a)) for a in intensities]
+    elif to == "absorbance":
+        out = []
+        for pct_t in intensities:
+            if pct_t <= 0:
+                raise ValueError(
+                    f"%T value {pct_t!r} is <= 0; cannot take log10 for "
+                    "Absorbance conversion"
+                )
+            out.append(-math.log10(pct_t / 100.0))
+        return out
+    else:
+        raise ValueError(f"unknown --to target: {to!r}")
+
+
+def read_plain_csv(path):
+    with open(path, newline="") as f:
+        reader = csv.reader(f)
+        header = next(reader)
+        rows = [(row[0], float(row[1])) for row in reader if row]
+    return header, rows
+
+
+def write_plain_csv(path, header, wavenumbers, intensities, digits=4):
+    with open(path, "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(header)
+        for wn, inten in zip(wavenumbers, intensities):
+            writer.writerow([wn, f"{inten:.{digits}f}"])
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument("csv_in", help="input plain CSV (wavenumber,intensity)")
+    ap.add_argument("--out", required=True, help="output CSV path (may equal csv_in)")
+    ap.add_argument(
+        "--to",
+        choices=["transmittance", "absorbance"],
+        default="transmittance",
+        help="conversion direction (default: transmittance, i.e. input is "
+        "treated as Absorbance)",
+    )
+    ap.add_argument("--digits", type=int, default=4, help="decimal places on output")
+    args = ap.parse_args()
+
+    header, rows = read_plain_csv(args.csv_in)
+    wavenumbers = [wn for wn, _ in rows]
+    intensities = [inten for _, inten in rows]
+
+    converted = convert_series(intensities, to=args.to)
+
+    write_plain_csv(args.out, header, wavenumbers, converted, digits=args.digits)
+
+    label = "%Transmittance" if args.to == "transmittance" else "Absorbance"
+    print(f"wrote {len(converted)} points to {args.out} ({label})")
+
+
+if __name__ == "__main__":
+    main()

irspec/absorptivity_to_absorbance.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""absorptivity_to_absorbance.py -- NIST QUANT-IR gas-phase .jdx -> true
+Absorbance CSVs, for any report.
+
+    python3 absorptivity_to_absorbance.py FILE.jdx --name NAME \\
+        --out csv/NAME.csv --plain-out plain/NAME.csv  (--peak-a A | --cl CL)
+
+Self-contained, like this folder's other tools: what a future session needs
+is in this docstring.
+
+===============================================================================
+1. WHAT THE FILE HOLDS, AND WHAT IT IS NOT
+===============================================================================
+NIST QUANT-IR gas-phase spectra on the WebBook (##$NIST SOURCE=QUANT-IR, e.g.
+1634-04-4-IR.jdx, MTBE, seen 2026-10-06) carry ##YUNITS=(micromol/mol)-1m-1
+(base 10): the decadic absorption coefficient per (umol/mol x m), i.e.
+
+        alpha = A / (c * L)        c in umol/mol (mole fraction), L in m
+
+so values are ~1e-3 and are NOT an absorbance. jdx_tool.py reads them as
+"Absorbance" (same upward bands, nothing converted) so it can decode the
+file, but they cannot go on an axis next to real spectra, and pgfplots stops
+with "Dimension too large" at that magnitude.
+
+===============================================================================
+2. THE CONVERSION
+===============================================================================
+Beer-Lambert, linear in concentration x path:
+
+        A = alpha * c * L = alpha * CL,        CL in umol/mol x m
+
+The file does NOT state c or L (it says "Primary Gas Standard" and a multipass
+cell, nothing numeric), and this script never invents them. You must give the
+product, one of two ways:
+
+  --cl CL        the real c x L, umol/mol x m, if you know it from the
+                 source paper/NIST's record (a true absorbance).
+  --peak-a A     scale so the strongest band reaches absorbance A (CL =
+                 A / max alpha). Peak-normalised: the SHAPE and band ratios
+                 are exact (A is linear in alpha), the absolute height is a
+                 choice, not a measurement. Say so in the figure caption
+                 ("scaled to strongest band A = 1").
+
+Because the conversion is a single multiplier, band ratios, positions and
+widths are those of the original; only the y scale changes. The archival
+CSV is written too, in Absorbance, through jdx_tool.py's own writers (same
+shapes as any other jdx_tool output). Both CSVs are therefore ready for
+spa_peaks.py --axis Absorbance and \\irspectrum {Absorbance}.
+
+Then, as for every Absorbance source, run absorbance_to_transmittance.py on
+the plain CSV: the house convention is %T only. With --peak-a the %T depth
+is as arbitrary as the chosen A, so say so in the caption.
+
+Verified 2026-10-06 on 1634-04-4-IR.jdx: output max = the --peak-a value,
+band ratios identical to the input's, plain CSV 650+ cm-1 only.
+"""
+import argparse
+import os
+import sys
+
+from . import jdx_tool  # noqa: E402  (decoder and house CSV writers)
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument("jdx", help="QUANT-IR .jdx with absorptivity y-units")
+    ap.add_argument("--name", required=True, help="NAME_WITH_UNDERSCORES (CSV header)")
+    ap.add_argument("--out", required=True, help="archival CSV path")
+    ap.add_argument("--plain-out", required=True, help="plain CSV path")
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--cl", type=float, help="c x L, umol/mol x m (true absorbance)")
+    g.add_argument("--peak-a", type=float, help="scale so max band = this absorbance")
+    args = ap.parse_args()
+
+    xs, ys, meta = jdx_tool.read_jdx(args.jdx)
+    with open(args.jdx, encoding="utf-8", errors="replace") as f:
+        if "(MICROMOL/MOL)-1M-1" not in f.read().upper():
+            sys.exit(f"{args.jdx}: y-units are not (micromol/mol)-1m-1; nothing to convert")
+    top = max(ys)
+    if top <= 0:
+        sys.exit("no positive band in the spectrum")
+    cl = args.cl if args.cl is not None else args.peak_a / top
+    ys = [y * cl for y in ys]
+    jdx_tool.write_csv(xs, ys, meta, args.out, args.name)
+    jdx_tool.write_plain_csv(xs, ys, meta, args.plain_out)
+    how = "c x L given" if args.cl is not None else f"peak-normalised, strongest band A = {args.peak_a}"
+    print(f"{args.jdx}: A = alpha x {cl:.6g} ({how}); max A {max(ys):.4f} "
+          f"-> {args.out}, {args.plain_out}")
+
+
+if __name__ == "__main__":
+    main()

irspec/cli.py

@@ -0,0 +1,54 @@
+"""The `irspec` command: one entry point over the tools.
+
+    irspec session DIR      a folder of spectra -> CSVs, peaks, figure PDF
+    irspec export PDF ...   PNG/TIFF/SVG pictures from a figure PDF
+    irspec plot DIR ...     the figures drawn by matplotlib or R, no TeX needed
+    irspec spa ...          OMNIC .SPA -> CSVs, peaks, legacy plots   (spa_tool)
+    irspec jdx ...          JCAMP-DX -> CSVs                          (jdx_tool)
+    irspec peaks ...        peak-pick a .SPA, .jdx or CSV             (spa_peaks)
+    irspec digitize ...     a spectrum published as a picture -> CSVs (ir_digitize)
+    irspec a2t ...          Absorbance <-> %Transmittance             (absorbance_to_transmittance)
+    irspec absorptivity ... QUANT-IR absorptivity -> Absorbance       (absorptivity_to_absorbance)
+    irspec corr ...         Pearson r between spectra                 (ir_corr)
+
+`session` is the command most people want; the others are its steps, for when
+one step is all that is needed (`irspec jdx convert X.jdx`). Each takes its
+own --help.
+"""
+import importlib
+import sys
+
+from . import __version__
+
+COMMANDS = {
+    "session": "session",
+    "export": "export",
+    "plot": "plot",
+    "spa": "spa_tool",
+    "jdx": "jdx_tool",
+    "peaks": "spa_peaks",
+    "digitize": "ir_digitize",
+    "a2t": "absorbance_to_transmittance",
+    "absorptivity": "absorptivity_to_absorbance",
+    "corr": "ir_corr",
+}
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(__doc__.strip())
+        return
+    if argv[0] in ("-V", "--version"):
+        print(f"irspec {__version__}")
+        return
+    cmd = argv[0]
+    if cmd not in COMMANDS:
+        sys.exit(f"irspec: unknown command {cmd!r}; choose from: {', '.join(COMMANDS)}")
+    mod = importlib.import_module(f"irspec.{COMMANDS[cmd]}")
+    sys.argv = [f"irspec {cmd}", *argv[1:]]
+    mod.main()
+
+
+if __name__ == "__main__":
+    main()

irspec/data/fonts/OFL.txt

@@ -0,0 +1,92 @@
+Copyright 2001-2021 The STIX Fonts Project Authors (https://github.com/stipub/stixfonts), with Reserved Font Name "TM Math". STIX Fonts™ is a trademark of The Institute of Electrical and Electronics Engineers, Inc.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

irspec/data/fonts/README.txt

@@ -0,0 +1,10 @@
+STIX Two Text (Regular, Italic) and STIX Two Math, unmodified, from the STIX Fonts
+Project (https://github.com/stipub/stixfonts), version 2.13 (Text) and 2.12 (Math).
+Copyright 2001-2021 The STIX Fonts Project Authors. Licensed under the SIL Open
+Font License, Version 1.1: the full text is in OFL.txt, and the fonts' own license
+fields say the same.
+
+irspec uses them only when STIX Two is not installed on the machine: matplotlib and
+R draw with them, and the plain-lualatex fallback loads them from irspec-fonts/.
+They are not sold or distributed on their own; they travel with irspec under the
+same license terms.