ALS Archiver Tools

A Python library for interacting with EPICS archiver data. This tool allows you to easily download and process data from EPICS archiver servers.

📑 Table of Contents

• ⚙️ Installation
• 🚀 Getting Started
• 🤝 Contributing
• 📝 Citing
• 📄 License

⚙️ Installation

Using pip

You can install this package through pip:

pip install als-archiver-tools

From source

If you want to install from source:

git clone https://github.com/andrea-pollastro/als-archiver-tools.git
cd archivertools
pip install -e .

🚀 Getting Started

Interactions with the archiver are managed by the ArchiverClient class. Let's see some examples.

📥 Single PV data downloading

To download the data of a given PV, refer to the .download_data() function:

from datetime import datetime
from archivertools import ArchiverClient

# Initialize the client with your archiver server URL
archiver = ArchiverClient(archiver_url="http://your-archiver-url")
data = archiver.download_data(pv_name="your:pv:name", 
                              precision=100,
                              start=datetime(year=2023, month=4, day=25, hour=22), 
                              end=datetime(year=2023, month=4, day=25, hour=23))
print(data.head())

The returned PV object contains:

pv.name  # PV name (string)
pv.raw_data  # Raw data as pandas.DataFrame
pv.clean_data  # Cleaned data as pandas.DataFrame
pv.properties  # PV properties as pandas.DataFrame
pv.first_timestamp  # First timestamp as datetime
pv.last_timestamp  # Last timestamp as datetime

🧮 Data matching

For a given list of PVs, data can be matched according to their timestamps. The list must be a sequence of str. PVs could have different archiving policies. In order to have a matching on the timestamps, they must follow the same archiving policy (this means that all the archiving policies of the listed PVs must be reduced to a common archiving policy). The parameter precision allows to select the precision of the individual PVs to allow the data matching.

Example:

pv_list = ['PV_NAME_1', 'PV_NAME_2']
matched_data = archiver.match_data(
    pv_list=pv_list,
    precision=100,
    start=datetime(year=2023, month=4, day=25, hour=22),
    end=datetime(year=2023, month=4, day=25, hour=23),
)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📝 Citing

This package was developed in 2023 during my stay at Berkeley, hosted by the Accelerator Physics Group (ALS, LBNL). It was used throughout the experimental phase that led to the publication Application of deep learning methods for beam size control during user operation at the Advanced Light Source.

If you use this package in your work, please cite:

@article{hellert2024application,
  title={Application of deep learning methods for beam size control during user operation at the Advanced Light Source},
  author={Hellert, Thorsten and Ford, Tynan and Leemann, Simon C and Nishimura, Hiroshi and Venturini, Marco and Pollastro, Andrea},
  journal={Physical Review Accelerators and Beams},
  volume={27},
  number={7},
  pages={074602},
  year={2024},
  publisher={APS}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.