Tagreader

https://equinor.github.io/tagreader-python/
Admin
Tagreader is a Python package for reading timeseries data from the OSIsoft PI and Aspen Infoplus.21...
Tokens:7,376
Snippets:93
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install tagreader with notebook dependencies

Source: https://equinor.github.io/tagreader-python/docs/about/introduction

Installs the optional dependencies required to run the Jupyter Notebook examples located in /examples. The quickstart notebook is available in the repository.

```bash
pip install tagreader[notebooks]  
```

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

### Install project packages with Poetry

Source: https://equinor.github.io/tagreader-python/docs/contribute/development-guide/setup

Installs the project's Python package dependencies using Poetry.

```bash
$ poetry install  
```

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

### Read timeseries data with IMSClient

Source: https://equinor.github.io/tagreader-python/docs/about/introduction

Basic usage example: creates an IMSClient with a data source name and IMSType "aspenone", searches for tags matching a pattern, and reads timeseries data for two tags over a one-hour interval with a 60-second resolution. The IMSType and service URLs must be provided for non-internal usage.

```python
import tagreader  

c = tagreader.IMSClient("mysource", "aspenone")  

print(c.search("tag*"))  

df = c.read_tags(["tag1", "tag2"], "18.06.2020 08:00:00", "18.06.2020 09:00:00", 60)  
```

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

### Connect to PINO PI data source using REST Web API

Source: https://equinor.github.io/tagreader-python/docs/about/usage/basic-usage

Creates an IMSClient for the PINO PI data source using the 'piwebapi' type and connects. This is the basic connection example.

```python
c = tagreader.IMSClient("PINO", "piwebapi")  

c.connect()  
```

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

### Install Poetry

Source: https://equinor.github.io/tagreader-python/docs/contribute/development-guide/setup

Installs Poetry, which is used to manage Python package dependencies for the project.

```bash
$ pip install poetry  
```

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

### Install tagreader with pip

Source: https://equinor.github.io/tagreader-python/docs/about/introduction

Installs the tagreader package from PyPI using pip. Requires Python >= 3.8 on Windows, Linux, or macOS. The following dependencies are installed automatically: pandas, requests, requests-kerberos, certifi, and diskcache.

```bash
pip install tagreader  
```

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

### Advanced time zone usage with IMSClient and tz_convert

Source: https://equinor.github.io/tagreader-python/docs/about/usage/time-zone

Shows how to create an IMSClient with a custom time zone, convert a naive datetime to a specific time zone, and read data with a time interval. The example uses the tz argument to set output time zone to US/Central, creates a timezone object for America/Sao_Paulo, and converts the resulting dataframe to Europe/Oslo.

```python
import tagreader  

from datetime import datetime, timedelta  

from dateutil import tz  

c = tagreader.IMSClient("PINO", "pi", tz="US/Central")  # Force output data to Houston time  

c.connect()  

tzinfo = tz.gettz("America/Sao_Paulo")  # Generate timezone object for Rio local time  

event_time = datetime(2020, 7, 20, 15, 5, 0, tzinfo=tzinfo)  

start_time = event_time - timedelta(minutes=30)  

end_time = event_time + timedelta(minutes=10)  

df = c.read(["BA:CONC.1"], start_time, end_time, ts=60)  

df_to_Norway = df.tz_convert("Europe/Oslo")  # Create a copy of the dataframe with Norwegian time stamps  
```

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

### List available data sources with list_sources()

Source: https://equinor.github.io/tagreader-python/docs/about/usage/data-source

Query available data sources for IP.21 and PI Web API. When called with imstype set to 'ip21', the registry at HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\PISystem\PI-SDK is searched. When called with 'piwebapi', the web server URL is queried for the complete list of data sources.

```python
from tagreader import list_sources  

list_sources("ip21")  

list_sources("piwebapi")  
```

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

### Initialize pre-commit hooks

Source: https://equinor.github.io/tagreader-python/docs/contribute/development-guide/setup

Initializes pre-commit in the local repository, setting up git pre-commit hooks that run tests, sanitizers, and formatters on every commit.

```bash
pre-commit install  
```

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

### list_sources()

Source: https://equinor.github.io/tagreader-python/docs/about/usage/data-source

Documentation for the list_sources() method, which queries for available PI and IP.21 servers.

```APIDOC
## list_sources(imstype, url=None, verify_ssl=True, auth=None)

### Description
Queries for available PI and IP.21 servers. When called with a Web API `imstype` (`piwebapi` or `aspenone`), it connects to the web server URL and queries for the available list of data sources. When called with `imstype` set to `pi` or `ip21`, it searches the Windows registry for available servers.

### Method
Function call

### Parameters
- **imstype** (string) - Required - The name of the IMS type to query. Valid values: `piwebapi`, `aspenone`, `pi`, `ip21`.
- **url** (string) - Optional - Path to server root, e.g. "https://aspenone/ProcessData/AtProcessDataREST.dll" or "https://piwebapi/piwebapi". Default: Path to Equinor server corresponding to selected `imstype` if `imstype` is `piwebapi` or `aspenone`.
- **verify_ssl** (boolean) - Optional - Whether to verify SSL certificate sent from server. Default: `True`.
- **auth** (object) - Optional - Auth object to pass to the server for authentication. Default: Kerberos-based auth objects that work with Equinor servers.

### Request Example
```python
from tagreader import list_sources

list_sources("ip21")
list_sources("piwebapi")
```

### Response
Returns a list of available data sources. For Web API queries, the list is normally the complete set of data sources available on the server. For registry queries, the list contains servers to which the user is authorized.
```

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

### Enable caching with SmartCache

Source: https://equinor.github.io/tagreader-python/docs/about/usage/caching

Enables caching using the recommended SmartCache. The cache file is created on use and can significantly speed up queries. Note that snapshots are never cached and raw data is currently not cached.

```python
from pathlib import Path  
from tagreader.cache import SmartCache  

c = tagreader.IMSClient("PINO", "pi", cache=SmartCache(path=Path(".cache"))  
c.connect()  

```

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

### Run pre-commit on all files

Source: https://equinor.github.io/tagreader-python/docs/contribute/development-guide/setup

Runs pre-commit manually on all files. Can be skipped on commits with `git commit --no-verify`, but skipping is discouraged.

```bash
pre-commit run --all-files  
```

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

### Search for tags using tag name, description, or both

Source: https://equinor.github.io/tagreader-python/docs/about/usage/basic-usage

Shows how to use the search() method with tag name, description, or both. The wildcard '*' can be used. If both tag and desc are provided, both must match.

```python
c = tagreader.IMSClient("PINO", "piwebapi")  

c.connect()  

c.search("cd*158")  

c.search(desc="*reactor*")  

c.search(tag="BA:*", desc="*Temperature*")  
```

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

### Read interpolated data with 3-minute intervals

Source: https://equinor.github.io/tagreader-python/docs/about/usage/basic-usage

Creates an IMSClient, connects, and reads interpolated data for tag 'BA:ACTIVE.1' between the given timestamps with a 180-second interval. The timestamps are provided as strings and the interval is passed as the fourth positional argument.

```python
c = tagreader.IMSClient("PINO", "piwebapi")  

c.connect()  

df = c.read(['BA:ACTIVE.1'], '05-Jan-2020 08:00:00', '05/01/20 11:30am', 180)  

  


```

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

### Fetch units and descriptions and plot a tag

Source: https://equinor.github.io/tagreader-python/docs/about/usage/fetching-metadata

Fetches units and descriptions for a list of tags, then plots one tag with the description as title and the unit as y-axis label. Requires a client instance `c` and a DataFrame `df` containing the tag data.

```python
tags = ["BA:ACTIVE.1", "BA:LEVEL.1", "BA:CONC.1"]  

units = c.get_units(tags)  

desc = c.get_descriptions(tags)  

tag = "BA:CONC.1"  

df[tag].plot(grid=True, title=desc[tag]).set_ylabel(units[tag])  

```

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

### Connect to Peregrino IP.21 data source with timezone and URL

Source: https://equinor.github.io/tagreader-python/docs/about/usage/basic-usage

Connects to the Peregrino IP.21 data source using AspenTech Process Data REST Web API, specifying Rio local time for naive timestamps and returned data, and using the local endpoint in Brazil.

```python
c = tagreader.IMSClient(datasource="PER",  

                        imstype="aspenone",  

                        tz="America/Sao_Paulo",  

                        url="https://aspenone-per.equinor.com/ProcessExplorer/ProcessData/AtProcessDataREST.dll")  

c.connect()  
```

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

### Connect to AspenTech Web API with NTLM authentication and SSL verification disabled

Source: https://equinor.github.io/tagreader-python/docs/about/usage/basic-usage

Connects to a custom AspenTech Web API URL using NTLM authentication instead of default Kerberos and ignoring the server's host certificate. Requires the requests_ntlm package and getpass for credentials.

```python
import getpass  
from requests_ntlm import HttpNtlmAuth  
user = "mydomain\\" + getpass.getuser()  
pwd = getpass.getpass()  
auth = HttpNtlmAuth(user, pwd)  
c = tagreader.IMSClient(datasource="myplant",  

                        url="https://api.mycompany.com/aspenone",  

                        imstype="aspenone",  

                        auth=auth,  

                        verify_ssl=False)  

c.connect()  
```

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

### Import tagreader module

Source: https://equinor.github.io/tagreader-python/docs/about/usage/basic-usage

Imports the tagreader module to access its functionality.

```python
import tagreader  
```

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

### Disable caching with cache=None

Source: https://equinor.github.io/tagreader-python/docs/about/usage/caching

Disables caching by setting the cache parameter to None. The client will not use a local SQLite cache, and all reads will query the data source directly.

```python
c = tagreader.IMSClient("PINO", "pi", cache=None)  

c.connect()  

```

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

### Read average value with 3-minute intervals

Source: https://equinor.github.io/tagreader-python/docs/about/usage/basic-usage

Reads the average value for tag 'BA:CONC.1' within each 3-minute interval between the given timestamps. Uses the read_type parameter set to tagreader.ReaderType.AVG.

```python
df = c.read(['BA:CONC.1'], '05-Jan-2020 08:00:00', '05/01/20 11:30am', 180, read_type=tagreader.ReaderType.AVG)  


```
Tokens:
Raw