pychemstation 0.10.12__tar.gz → 0.10.13__tar.gz

pychemstation-0.10.13/.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "python.testing.unittestArgs": [
+        "-v",
+        "-s",
+        "./tests",
+        "-p",
+        "test_*.py"
+    ],
+    "python.testing.pytestEnabled": false,
+    "python.testing.unittestEnabled": true,
+    "python.analysis.typeCheckingMode": "standard"
+}

{pychemstation-0.10.12 → pychemstation-0.10.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pychemstation
-Version: 0.10.12
+Version: 0.10.13
 Summary: Library to interact with Chemstation software, primarily used in Hein lab
 Project-URL: Documentation, https://pychemstation-e5a086.gitlab.io/pychemstation.html
 Project-URL: Repository, https://gitlab.com/heingroup/device-api/pychemstation

pychemstation-0.10.13/cmd

@@ -0,0 +1 @@
+8 response$ = _METHPATH$

pychemstation-0.10.13/out.txt

@@ -0,0 +1,8 @@
+response$ = AcqStatus$
+response$ = _METHPATH$
+response$ = _SEQUENCEPATHS$
+response$ = _DATAPATHS$
+response$ = _METHPATH$
+response$ = _SEQUENCEPATHS$
+response$ = _DATAPATHS$
+response$ = _METHPATH$

pychemstation-0.10.13/paper.bib

@@ -0,0 +1,89 @@
+@misc{AccelerationConsortium,
+    title = {Acceleration {{Consortium}}},
+    urldate = {2025-04-16},
+    howpublished = {https://acceleration.utoronto.ca/events/acceleration-consortium-fall-research-symposium},
+    file = {/Users/lucyhao/Zotero/storage/KJJAD45E/acceleration-consortium-fall-research-symposium.html}
+}
+
+@misc{BourneGroupHPLCMethodOptimisationGUIHPLC,
+    title = {Bourne-{{Group}}/{{HPLCMethodOptimisationGUI}}: {{HPLC}} Method Optimisation Using Machine Learning},
+    urldate = {2025-04-16},
+    howpublished = {https://github.com/Bourne-Group/HPLCMethodOptimisationGUI}
+}
+
+@misc{ChromatographyMethodDevelopment,
+    title = {Chromatography {{Method Development}} - {{OpenLab ChemStation}} {\textbar} {{Agilent}}},
+    urldate = {2025-04-16},
+    howpublished = {https://www.agilent.com/en/product/software-informatics/analytical-software-suite/chromatography-data-systems/openlab-chemstation},
+    file = {/Users/lucyhao/Zotero/storage/KBK2IZV3/openlab-chemstation.html}
+}
+
+@misc{CroningpAnalyticallabware2025,
+    title = {Croningp/Analyticallabware},
+    year = {2025},
+    month = mar,
+    urldate = {2025-04-16},
+    howpublished = {croningp}
+}
+
+@article{dixonOperatorfreeHPLCAutomated2024a,
+    title = {Operator-Free {{HPLC}} Automated Method Development Guided by {{Bayesian}} Optimization},
+    author = {Dixon, Thomas M. and Williams, Jeanine and Besenhard, Maximilian and Howard, Roger M. and MacGregor, James and Peach, Philip and Clayton, Adam D. and Warren, Nicholas J. and Bourne, Richard A.},
+    year = {2024},
+    month = aug,
+    journal = {Digital Discovery},
+    volume = {3},
+    number = {8},
+    pages = {1591--1601},
+    publisher = {RSC},
+    issn = {2635-098X},
+    doi = {10.1039/D4DD00062E},
+    urldate = {2025-04-16},
+    abstract = {The need to efficiently develop high performance liquid chromatography (HPLC) methods, whilst adhering to quality by design principles is of paramount importance when it comes to impurity detection in the synthesis of active pharmaceutical ingredients. This study highlights a novel approach that fully automates HPLC method development using black-box single and multi-objective Bayesian optimization algorithms. Three continuous variables including the initial isocratic hold time, initial organic modifier concentration and the gradient time were adjusted to simultaneously optimize the number of peaks detected, the resolution between peaks and the method length. Two mixtures of analytes, one with seven compounds and one with eleven compounds, were investigated. The system explored the design space to find a global optimum in chromatogram quality without human assistance, and methods that gave baseline resolution were identified. Optimal operating conditions were typically reached within just 13 experiments. The single and multi-objective Bayesian optimization algorithms were compared to show that multi-objective optimization was more suitable for HPLC method development. This allowed for multiple chromatogram acceptance criteria to be selected without having to repeat the entire optimization, making it a useful tool for robustness testing. Work in this paper presents a fully ``operator-free'' and closed loop HPLC method optimization process that can find optimal methods quickly when compared to other modern HPLC optimization techniques such as design of experiments, linear solvent strength models or quantitative structure retention relationships.},
+    langid = {english},
+    file = {/Users/lucyhao/Zotero/storage/R6J4X3FX/Dixon et al. - 2024 - Operator-free HPLC automated method development guided by Bayesian optimization.pdf;/Users/lucyhao/Zotero/storage/U6VQC54Q/Dixon et al. - 2024 - Operator-free HPLC automated method development guided by Bayesian optimization.pdf}
+}
+
+@misc{DynamicSamplingAutonomous,
+    title = {Dynamic Sampling in Autonomous Process Optimization - {{Chemical Science}} ({{RSC Publishing}})},
+    urldate = {2025-04-16},
+    howpublished = {https://pubs.rsc.org/en/content/articlelanding/2024/sc/d3sc06884f\#!divAbstract},
+    file = {/Users/lucyhao/Zotero/storage/V9P3MB47/d3sc06884f.html}
+}
+
+@misc{HeinGroupHplcmethodoptimization2025,
+    title = {Hein {{Group}} / Hplc-Method-Optimization {$\cdot$} {{GitLab}}},
+    year = {2025},
+    month = apr,
+    journal = {GitLab},
+    urldate = {2025-04-16},
+    abstract = {GitLab.com},
+    howpublished = {https://gitlab.com/heingroup/hplc-method-optimization},
+    langid = {english}
+}
+
+@article{robertsAutomatingStochasticAntibody2025,
+    title = {Automating Stochastic Antibody--Drug Conjugation: A Self-Driving Lab Approach for Enhanced Therapeutic Development},
+    shorttitle = {Automating Stochastic Antibody--Drug Conjugation},
+    author = {Roberts, Liam and Reish, Matthew E. and Yang, Jerrica and Zhang, Wenyu and Derasp, Joshua S. and Hein, Jason E.},
+    year = {2025},
+    month = apr,
+    journal = {Digital Discovery},
+    volume = {4},
+    number = {4},
+    pages = {979--986},
+    publisher = {RSC},
+    issn = {2635-098X},
+    doi = {10.1039/D4DD00363B},
+    urldate = {2025-04-16},
+    abstract = {Antibody--drug conjugates (ADCs) have become a promising cancer treatment over the past two decades due to their on-target drug-release capabilities. However, labor-intensive manual conjugations currently limit the throughput of ADC synthesis. Herein, we introduce a Self-Driving Lab (SDL) for automated stochastic antibody--drug conjugation and characterization. The robotic platform performs conjugations and determines drug to antibody ratios from chromatography data, enabling the production of target ADCs iteratively in a closed loop. Our SDL establishes a robust foundation for increasing ADC production throughput and accelerating the development of cancer therapeutics.},
+    langid = {english},
+    file = {/Users/lucyhao/Zotero/storage/ENB4N88F/Roberts et al. - 2025 - Automating stochastic antibody–drug conjugation a self-driving lab approach for enhanced therapeuti.pdf;/Users/lucyhao/Zotero/storage/MQW4T3ZY/Roberts et al. - 2025 - Automating stochastic antibody–drug conjugation a self-driving lab approach for enhanced therapeuti.pdf}
+}
+
+@article{schneiderMacroProgrammingGuide,
+    title = {Macro {{Programming Guide}}},
+    author = {Schneider, J{\"u}rgen},
+    langid = {english},
+    file = {/Users/lucyhao/Zotero/storage/QKT883DB/Schneider - Macro Programming Guide.pdf}
+}

pychemstation-0.10.13/paper.md

@@ -0,0 +1,133 @@
+---
+title: 'pychemstation: A Python package for automated control of Chemstation using MACROs'
+tags:
+  - Python
+  - Self Driving Labs
+  - SDL
+  - HPLC
+  - Automation
+authors:
+  - name: Lucy Hao
+    email: lucyhao@chem.ubc.ca
+    orcid: 0000-0003-0296-3591
+    affiliation: 1
+  - name: Maria Politi
+    email: politim@chem.ubc.ca
+    orcid: 0000-0002-5815-3371
+    affiliation: "1, 3"
+  - name: Jason Hein
+    email: jhein@chem.ubc.ca
+    orcid: 0000-0002-4345-3005
+    affiliation: "1, 2, 3, 4"
+affiliations:
+  - name: Department of Chemistry, The University of British Columbia, Vancouver, Canada
+    index: 1
+  - name: Department of Chemistry, University of Bergen, Norway
+    index: 2
+  - name: Acceleration Consortium, University of Toronto, Toronto, ON, Canada
+    index: 3
+  - name: Telescope Innovations Corp., Vancouver, BC, Canada
+    index: 4
+date: 17 April 2025
+bibliography: paper.bib
+---
+
+# Summary
+
+`pychemstation` is a Python package that automates the use of high-performance liquid chromatography (HPLC) machines using
+Chemstation [@ChromatographyMethodDevelopment]. Python enables easy adoption by chemists and integrates smoothly with
+existing data analysis and robotics packages used in developing automated chemical workflows. The `pychemstation` API
+provides users with a simple class-based interface to automate common operations such as running analytical methods and
+sequences, modifying methods and sequences, and extracting chromatograms after runs. `pychemstation` provides this functionality by generating MACROs (a command
+protocol developed by Agilent) which are sent to ChemStation for execution. With HPLC being one of the most widely
+used analytical methods in research and industry, `pychemstation` opens the doors to using this powerful analytical technique in automated chemical workflows.
+
+# Statement of need
+
+Chemists run hundreds of analytical measurements to gain insight into chemical reactions. 
+This amounts to hours of manual labour to interact with graphical user interfaces (GUIs) to modify analytical methods,
+run the methods, and then extract data to gain scientific insight. Tasks such as these are amenable to automation, leading to a broader research
+goal to automate experiments through self-driving labs (SDLs) [@robertsAutomatingStochasticAntibody2025; @DynamicSamplingAutonomous].
+SDLs are robotic platforms that autonomously plan and execute hundreds of chemical reactions. Building an SDL requires
+every step a chemist would do by hand to be automated, one of them being the running of analytical equipment such as HPLC. 
+Building autonomous chemical requires the development of robust software tools that enable control and communication with analytical hardware.
+
+`pychemstation` was designed to be used by chemists to control Agilent-specific HPLC machines in their day-to-day
+operations or in developing SDLs. The development of `pychemstation` stemmed from the desire for a 
+robust strategy to interact with Chemstation, moving away from the fragile and cumbersome development of the “mouse and
+keyboard” interaction strategy with the GUI. Development began from the augmentation of an existing Python codebase for
+sending MACROs to Chemstation, with addition more MACROs through trial-and-error and previous published work 
+[@CroningpAnalyticallabware2025; @dixonOperatorfreeHPLCAutomated2024a; @BourneGroupHPLCMethodOptimisationGUIHPLCl; @schneiderMacroProgrammingGuide].
+`pychemstation` has already been used in several of the Hein group's projects, including SDLs for kinetics,
+liquid-liquid extraction and development of a Python based tool for autonomous data-driven HPLC method
+development [@AccelerationConsortium; @HeinGroupHplcmethodoptimization2025]. Built with robustness and ease-of-use in
+mind, `pychemstation` frees the chemist from repetitive tasks and gives SDL developers the ability to seamlessly interact with
+HPLC machines through an API, enhancing productivity and enabling more efficient software integration.
+
+# Description
+
+`pychemstation` controls the operation of Chemstation through a set of `Controller` classes which generate MACROs based
+on Python dataclasses. A schematic describing the package architecture is shown below in figure 1.
+
+![A class architecture diagram for `pychemstation`. The
+`CommunicationController` handles all communication between a user's Python program and a Chemstation instance. All other controllers extend an abstract
+`ABCTableController` which provides table loading and editing functionality all controllers require. The
+`RunController` is another abstract class including more functionality related to editing and triggering a run/runs.
+`RunController` also provides a polling functionality to let the user know when a run is complete, and returns the file paths containing the data from the run. The
+`DeviceController` load and edit details about hardware.](imgs/control.png)
+
+MACROs enabling functionality beyond method editing were discovered using a MACRO editor and Chemstation's built in
+MACRO help [@schneiderMacroProgrammingGuide; @ChromatographyMethodDevelopment].
+Python tests were written to ensure proper functionality of all the methods available in the `HPLCController` class that
+most users interact with, shown in figure 2. These tests include both unit (testing the individual controller
+classes) and integration tests (such as editing of methods and running them immediately after with retrieval of run
+data). Tests were run on two different HPLC machines in the Hein group.
+
+![All methods available for use in the `HPLCController` class](imgs/hplc.png)
+
+The `HPLCController` class contains a series of subclasses of `RunController` and `DeviceController`. 
+`RunController` subclasses, `MethodController` and `SequenceController`, generate MACROs related to runs, 
+such as triggering runs and returning data. The `DeviceController` subclasses are a new edition, allowing users to load 
+details about the injector, diode array detector, column/thermostat and pumps. The subclasses extending 
+`DeviceController` are in active development.
+
+The `RunController` subclasses provide `pychemstation`'s main functionality. The `MethodController` triggers method runs for one sample, while the `SequenceController` can trigger a runf o
+After a run is triggered, the `RunController` can either block until the HPLC is done the run or immediately return. If the user
+chooses to return before the HPLC is done a run, they choose to check how much time is remaining for the run. After the
+run, the `RunController` returns all the necessary file paths for further data processing. The UV chromatogram is returned per active channel, or for the entire
+scanned spectrum. There is limited data processing functionality for the auto-generated report in the `ReportProcessor`
+classes, thus other Python libraries are recommended for more in depth processing.
+
+The `MethodController` edits the pump timetable while the `SequenceController` edits the sequence table. An example is
+shown below. Various combinations of parameters and editing scenarios were tested to ensure the generated MACROs could
+handle different types of parameter updates.
+
+![An example of a Method pump timetable](imgs/method%20timetable.png)
+![An example of a Sequence table](imgs/img.png)
+
+A summary of available methods and functionality are shown in the tables below.
+
+| Run Controller | Features                                                                                                   |
+|----------------|------------------------------------------------------------------------------------------------------------|
+| Sequence       | Switch, Load sequence details, Edit sequence table entries, Run sequence, Retrieve sequence run data files |
+| Method         | Switch, Load method timetable, Edit method timetable, Run method, Retrieve method run data files           |
+
+| Device Controller    | Features                                                                            |
+|----------------------|-------------------------------------------------------------------------------------|
+| Pump                 | Edit parameters (flow, pressure, organic modifier), solvent and waste bottle status |
+| Diode Array Detector | Read and set active wavelengths                                                     |
+| Injector             | Change injection volume                                                             |
+| Columns              | Read active column, edit active column                                              |
+
+Thus, `pychemstation` provides both high-level and low-level control of an HPLC machine that uses Agilent's Chemstation
+software. More information and use case examples can be found in
+the [documentation](https://pychemstation-e5a086.gitlab.io/pychemstation.html).
+
+# Acknowledgements
+
+We acknowledge contributions from Wesley McNutt, Matthew Reish and Clark Zhang and funding support from AC, NSERC,
+Canada
+NRC,
+CFFI (?).
+
+# References

{pychemstation-0.10.12 → pychemstation-0.10.13}/pychemstation/control/controllers/data_aq/sequence.py

@@ -70,19 +70,22 @@ class SequenceController(RunController):
                 f"couldn't read rows or sequence name: {seq_name.err_value}"
             )
 
-    def try_int(self, val: Any) -> Optional[int]:
+    @staticmethod
+    def try_int(val: Any) -> Optional[int]:
         try:
             return int(val)
         except ValueError:
             return None
 
-    def try_float(self, val: Any) -> Optional[float]:
+    @staticmethod
+    def try_float(val: Any) -> Optional[float]:
         try:
             return float(val)
         except ValueError:
             return None
 
-    def try_vial_location(self, val: Any) -> Tray:
+    @staticmethod
+    def try_vial_location(val: Any) -> Tray:
         try:
             return VialBar(val) if val <= 10 else FiftyFourVialPlate.from_int(num=val)
         except ValueError:
@@ -451,14 +454,19 @@ class SequenceController(RunController):
     def get_data(
         self, custom_path: Optional[str] = None
     ) -> List[AgilentChannelChromatogramData]:
-        seq_file_dir = (
-            SequenceDataFiles(dir=custom_path, sequence_name="")
-            if custom_path
-            else self.data_files[-1]
-        )
-        self.data_files[-1] = self._fuzzy_match_most_recent_folder(
+        print(custom_path)
+        if custom_path:
+            self.data_files.append(
+               SequenceDataFiles(dir=custom_path, sequence_name="") 
+            )
+        seq_file_dir = self.data_files[-1]
+        possible_seq_file_name = self._fuzzy_match_most_recent_folder(
             seq_file_dir
-        ).ok_value
+        )
+        if possible_seq_file_name.is_ok():
+            self.data_files[-1] = possible_seq_file_name.ok_value
+        else:
+            raise UserWarning(f"{possible_seq_file_name.err_value}")
         spectra: List[AgilentChannelChromatogramData] = []
         for row in self.data_files[-1].child_dirs:
             self.get_spectrum_at_channels(row)

pychemstation-0.10.13/pychemstation/control/controllers/devices/__init__.py

@@ -0,0 +1,6 @@
+from .injector import InjectorController
+from .pump import PumpController
+from .column import ColumnController
+from .dad import DADController
+
+__all__ = ["InjectorController", "PumpController", "ColumnController", "DADController"]

{pychemstation-0.10.12 → pychemstation-0.10.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pychemstation"
-version = "0.10.12"
+version = "0.10.13"
 description = "Library to interact with Chemstation software, primarily used in Hein lab"
 authors = [{ name = "lucyhao", email = "hao.lucyy@gmail.com" }]
 requires-python = ">=3.10"
@@ -118,4 +118,4 @@ docstring-code-format = true
 #
 # This only has an effect when the `docstring-code-format` setting is
 # enabled.
-docstring-code-line-length = "dynamic"
+docstring-code-line-length = "dynamic"

{pychemstation-0.10.12 → pychemstation-0.10.13}/tests/constants.py

@@ -34,7 +34,8 @@ DEFAULT_METHOD_254 = "GENERAL-POROSHELL-30sec_Isohold"
 DEFAULT_SEQUENCE = "hplc_testing"
 
 # CONSTANTS: paths only work in Hein group HPLC machine in room 242
-DEFAULT_COMMAND_PATH = "C:\\Users\\User\\Desktop\\Lucy\\"
+# DEFAULT_COMMAND_PATH = "C:\\Users\\User\\Desktop\\Lucy\\"
+DEFAULT_COMMAND_PATH = os.getcwd()
 
 # these CONSTANTS work in rm 254
 DEFAULT_COMMAND_PATH_254 = "D:\\git_repositories\\hplc_comm\\"

{pychemstation-0.10.12 → pychemstation-0.10.13}/tests/files/test_offline.py

@@ -97,6 +97,16 @@ class TestOffline(unittest.TestCase):
             )
         except Exception:
             self.fail("should not get here")
+    
+    def test_get_seq_data(self):
+        seq_path = "hplc_testing 2025-03-27 17-13-47"
+        try:
+            data = self.hplc_controller.get_last_run_sequence_data(
+                custom_path=os.path.join(self.cwd, seq_path)
+            )
+            self.assertEqual(len(data), 4)
+        except Exception as e:
+            self.fail(f"should not get here: {e}")
 
     def test_get_seq_uv(self):
         seq_path = "hplc_testing 2025-03-27 17-13-47"

{pychemstation-0.10.12 → pychemstation-0.10.13}/uv.lock

@@ -873,7 +873,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8c/de/8eb6fffecd9c5f129461edcdd7e1ac944f9de15783e3d89c84ed6e0374bc/lxml-5.3.2-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:aa837e6ee9534de8d63bc4c1249e83882a7ac22bd24523f83fad68e6ffdf41ae", size = 5652903 },
     { url = "https://files.pythonhosted.org/packages/95/79/80f4102a08495c100014593680f3f0f7bd7c1333b13520aed855fc993326/lxml-5.3.2-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:da4c9223319400b97a2acdfb10926b807e51b69eb7eb80aad4942c0516934858", size = 5491813 },
     { url = "https://files.pythonhosted.org/packages/15/f5/9b1f7edf6565ee31e4300edb1bcc61eaebe50a3cff4053c0206d8dc772f2/lxml-5.3.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:dc0e9bdb3aa4d1de703a437576007d366b54f52c9897cae1a3716bb44fc1fc85", size = 5227837 },
-    { url = "https://files.pythonhosted.org/packages/5c/17/c31d94364c02e3492215658917f5590c00edce8074aeb06d05b7771465d9/lxml-5.3.2-cp310-cp310-win32.whl", hash = "sha256:5f94909a1022c8ea12711db7e08752ca7cf83e5b57a87b59e8a583c5f35016ad", size = 3477533 },
+    { url = "https://files.pythonhosted.org/packages/dd/53/a187c4ccfcd5fbfca01e6c96da39499d8b801ab5dcf57717db95d7a968a8/lxml-5.3.2-cp310-cp310-win32.win32.whl", hash = "sha256:dd755a0a78dd0b2c43f972e7b51a43be518ebc130c9f1a7c4480cf08b4385486", size = 3477533 },
     { url = "https://files.pythonhosted.org/packages/f2/2c/397c5a9d76a7a0faf9e5b13143ae1a7e223e71d2197a45da71c21aacb3d4/lxml-5.3.2-cp310-cp310-win_amd64.whl", hash = "sha256:d64ea1686474074b38da13ae218d9fde0d1dc6525266976808f41ac98d9d7980", size = 3805160 },
     { url = "https://files.pythonhosted.org/packages/84/b8/2b727f5a90902f7cc5548349f563b60911ca05f3b92e35dfa751349f265f/lxml-5.3.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:9d61a7d0d208ace43986a92b111e035881c4ed45b1f5b7a270070acae8b0bfb4", size = 8163457 },
     { url = "https://files.pythonhosted.org/packages/91/84/23135b2dc72b3440d68c8f39ace2bb00fe78e3a2255f7c74f7e76f22498e/lxml-5.3.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:856dfd7eda0b75c29ac80a31a6411ca12209183e866c33faf46e77ace3ce8a79", size = 4433445 },
@@ -1611,7 +1611,7 @@ wheels = [
 
 [[package]]
 name = "pychemstation"
-version = "0.10.11"
+version = "0.10.12"
 source = { editable = "." }
 dependencies = [
     { name = "aghplctools" },
@@ -1619,7 +1619,6 @@ dependencies = [
     { name = "pandas" },
     { name = "pdoc" },
     { name = "polling" },
-    { name = "pre-commit" },
     { name = "rainbow-api" },
     { name = "result" },
     { name = "scipy" },
@@ -1644,7 +1643,6 @@ requires-dist = [
     { name = "pandas", specifier = ">=2.0.3" },
     { name = "pdoc", specifier = ">=14.7.0" },
     { name = "polling", specifier = ">=0.3.2" },
-    { name = "pre-commit", specifier = ">=4.2.0" },
     { name = "rainbow-api", specifier = ">=1.0.10" },
     { name = "result", specifier = ">=0.17.0" },
     { name = "scipy", specifier = ">=1.10.1" },

pychemstation-0.10.12/.git

@@ -1 +0,0 @@
-gitdir: /Users/lucyhao/Codes/hein-lab/pychemstation-worktree/pychemstation/.git/worktrees/v0.10.x

pychemstation-0.10.12/pychemstation/control/controllers/devices/__init__.py

@@ -1,3 +0,0 @@
-from .injector import InjectorController
-
-__all__ = ["InjectorController"]