Das sdata-Format¶

Ingolf Lepenies, lepy@mailbox.org

Ein Beispiel zur Ablage einer Tabelle im sdata-Format¶

Dieses Beispiel zeigt die Ablage einer Tabelle mit zwei Spalten im sdata-Format.

In [1]:

import pandas as pd
df = pd.DataFrame({"column_a": [1.1, 2.1, 3.5],
                   "column_b": [2.4, 5.2, 2.2]}, index=[0, 'max_b', 2])
df.index.name = "index" 
df

Out[1]:

	column_a	column_b
index
0	1.1	2.4
max_b	2.1	5.2
2	3.5	2.2

sdata steht für strukturierte Daten. sdata ist eine unter der MIT-Lizenz veröffentlichte open-source Python-Bibiothek, welche das sdata-Format unterstützt. Installiert wird die Bibliothek mittels pip install sdata. Die Dokumentation wird unter sdata.readthedocs.io veröffentlicht.

In [2]:

import sdata
print("sdata v{}".format(sdata.__version__))

sdata v0.8.4

Die Komponenten des sdata-Formates¶

Das sdata-Datenformat Data besteht aus drei Komponenten: den Daten (hier eine Tabelle table), den Metadaten metadata (name, uuid, ...) und einer Beschreibung der Daten description.

In [3]:

data = sdata.Data(name="my data name", table=df, description="my data description")
print("data:            \t {0}".format(type(data)))
print("data.metadata:   \t {0}".format(type(data.metadata)))
print("data.table:      \t {0}".format(type(data.table)))
print("data.description:\t {0}".format(type(data.description)))

data:            	 <class 'sdata.Data'>
data.metadata:   	 <class 'sdata.metadata.Metadata'>
data.table:      	 <class 'pandas.core.frame.DataFrame'>
data.description:	 <class 'str'>

sdata.Data.metadata¶

Jeder Datensatz Data benötigt einen Namen name. Die vom User vorgegebene Identifikation des Datensatzes ist aber mit einer hohen Wahrscheinlichkeit nicht eindeutig, da i.d.R sehr kurze Bezeichnungen gewählt werden.

In [4]:

data = sdata.Data(name="basic example")
print("data.name:\t '{0.name}'".format(data))

data.name:	 'basic example'

Zur Identifikation eines Datensatzes ist eine möglichst eindeutige Bezeichnung hilfreich. Üblicherweise wird hierzu ein sogenannter Universally Unique Identifier [uuid] (https://de.wikipedia.org/wiki/Universally_Unique_Identifier) verwendet. Diese Merkmale eines Datensatzes werden im sdata-Format in den Metadaten gespeichert. Diese uuid wird automatisch bei jeder Instanziierung eines sdata.Data-Objektes generiert.

In [5]:

data = sdata.Data(uuid="8b1e85eded1241eb854be3365bcf9884")
print("data.uuid:\t '{0.uuid}'".format(data))

data.uuid:	 '8b1e85eded1241eb854be3365bcf9884'

Die uuid kann aber auch basierend auf einem - möglichst eindeutigen - Names generiert werden.

In [6]:

my_uuid = sdata.uuid_from_str("Das ist ein möglichst eindeutiger Name für die Daten")
data = sdata.Data(uuid=my_uuid)
print("data.uuid:\t '{0.uuid}'".format(data))

data.uuid:	 '06f8c76b037c3636a40246f024e87574'

Die Komponente metadata hat also mindestenz zwei Attribute name und uuid. Die einfachste Form eines Attributes stellt ein key-value-Tupel dar, d.h. eine Verknüpfung einer Bedeutung mit einer Ausprägung, z.B. Augenfarbe="blau" oder name="basic example".

In [7]:

attribute1 = sdata.Attribute("Augenfarbe", "blau")
attribute1

Out[7]:

(Attr'Augenfarbe':blau(str))

Ein Attribut (Eigenschaft) des Datenobjektes hat im sdata-Format die Felder

name ... Name des Attributes
value ... Wert des Attributes
dtype ... Datentyp des Attributwertes values (default=str)
unit ... physikalische Einheit des Attributes (optional)
description ... Beschreibung des Attributes (optional)
label ... optionales Label des Attributes, z.B. für Plotzwecke

In [8]:

attribute2 = sdata.Attribute(name="answer", 
                             value=42, 
                             dtype="int", 
                             unit="-", 
                             description="""The Answer to the Ultimate Question of Life, The Universe, and Everything""", 
                             label="Die Antwort")
attribute2.to_dict()

Out[8]:

{'name': 'answer',
 'value': 42,
 'unit': '-',
 'dtype': 'int',
 'description': 'The Answer to the Ultimate Question of Life, The Universe, and Everything',
 'label': 'Die Antwort'}

Attribute werden in den Metadaten gespeichert.

In [25]:

metadata = sdata.Metadata()
metadata.add(attribute1)
metadata.add(attribute2)
print(metadata)
print(metadata.df)

(Metadata'N.N.':3 ['sdata_version', 'Augenfarbe', 'answer'])
                        name  value dtype unit  \
key                                              
sdata_version  sdata_version  0.8.4   str    -   
Augenfarbe        Augenfarbe   blau   str    -   
answer                answer     42   int    -   

                                                     description        label  
key                                                                            
sdata_version                                                                  
Augenfarbe                                                                     
answer         The Answer to the Ultimate Question of Life, T...  Die Antwort

Ein Attribut - auch Eigenschaft genannt - stellt demnach ein Merkmal des Datenobjektes dar. Nützlich ist auch eine Angabe einer physikalischen Größe, welche i.d.R. Einheiten behaftet ist. Exemplarisch ist hier ein Attribut Temperatur mit der Ausprägung 25.4°C aufgeführt. Die physikalische Einheit wird im Attributfeld unit abgelegt (unit="degC") und der Zahlenwert im Feld value=25.4. Da eine physikalische Größe aus dem Produkt einer (reelen) Zahl und einer physikalischen Einheit besteht, sieht das sdata-Attribut-Format auch ein Attributfeld dtype zur Definition des Datentypes für den Attributwert value vor. Ferner kann jedes Attribut im Feld description genauer beschrieben werden. Optional kann auch ein Label für Plot-Zwecke angegeben werden.

In [26]:

data = sdata.Data(name="basic example", 
                  uuid="38b26864e7794f5182d38459bab85842", 
                  table=df)
data.metadata.add("Temperatur", 
                  value=25.4, 
                  dtype="float", 
                  unit="degC", 
                  description="Temperatur", 
                  label="Temperatur T [°C]")
print(data.metadata.df)

                        name                             value  dtype  unit  \
key                                                                           
sdata_version  sdata_version                             0.8.4    str     -   
name                    name                     basic example    str     -   
uuid                    uuid  38b26864e7794f5182d38459bab85842    str     -   
Temperatur        Temperatur                              25.4  float  degC   

              description              label  
key                                           
sdata_version                                 
name                                          
uuid                                          
Temperatur     Temperatur  Temperatur T [°C]

sdata.Data.table¶

Das eigentliche Datenobjekt table ist als pandas.DataFrame repräsentiert, d.h. jede Zelle der Tabelle ist durch ein Tupel (index, column) indiziert. Jede Spalte (column) ist durch den Spaltennamen (hier z.B. time oder temperature) indizierbar. Jede Zeile (row) ist durch den index indiziert, wobei der index auch alphanumerisch sein kann (z.B. 'max_temp').

In [11]:

df = pd.DataFrame({"time": [1.1, 2.1, 3.5],
                   "temperature": [2.4, 5.2, 2.2]}, index=[0, 'max_temp', 2])
df.index.name = "index" 
df

Out[11]:

	time	temperature
index
0	1.1	2.4
max_temp	2.1	5.2
2	3.5	2.2

sdata.Data.decription¶

Die Beschreibung description ist vom Typ str.

In [12]:

data.description = "Messergebnis Temperatur."
print(data.description)

Messergebnis Temperatur.

Es ist möglich eine vereinfachte Auszeichnungssprache wie Markdown verwendbar. Beispielhaft ist hier Datenbeschreibung mit Überschriften und Formel aufgeführt.

Messergebnis Temperatur.¶

subheader¶

a remarkable text

Bullet list:

aaa
- aaa.b
bbb

Numbered list:

$f(x) = \frac{1}{2}\sin(x)$

code:

name="basic example"

A Link.

In [13]:

data.description = r"""# Messergebnis Temperatur
## subheader

a remarkable text

Bullet list:

- aaa
    - aaa.b
- bbb


Numbered list:

1. foo
1. bar

$f(x) = \frac{1}{2}\sin(x)$

code:

    name = "basic example"

A [Link](https://github.com/lepy/sdata)."""

In [14]:

print(data.description)

# Messergebnis Temperatur
## subheader

a remarkable text

Bullet list:

- aaa
    - aaa.b
- bbb


Numbered list:

1. foo
1. bar

$f(x) = \frac{1}{2}\sin(x)$

code:

    name = "basic example"

A [Link](https://github.com/lepy/sdata).

Beispiel einer Temperaturmessung-001¶

Die Daten bestehen aus einer Tabelle mit zwei Spalten für die Zeit und eine gemessene Temperatur.

In [15]:

df = pd.DataFrame({"time": [1.1, 2.1, 3.5],
                   "temperature": [2.4, 5.2, 2.2]},
                  index=[0, 'max_temp', 2])
df

Out[15]:

	time	temperature
0	1.1	2.4
max_temp	2.1	5.2
2	3.5	2.2

Das sdata.Data-Objekt wird mit einen Names und einer aus dem Namen generierten uuid versehen. Weiterhin wird für jede Spalte der Tabelle ein Attribut definiert, welche u.a. die physikalische Einheit der Spaltenwerte abbildet.

In [16]:

data_name = "Temperaturmessung-001"
data = sdata.Data(name=data_name, 
                  uuid=sdata.uuid_from_str(data_name),
                  table=df,
                  description="Messergebnis Temperatur")
data.metadata.add("time", 
                  value=None, 
                  dtype="float", 
                  unit="s", 
                  description="Zeitachse", 
                  label="time $t$")
data.metadata.add("temperature", 
                  value=None, 
                  dtype="float", 
                  unit="°C", 
                  description="Zeitachse", 
                  label="temperature $T$")
data.describe()

Out[16]:

	0
metadata	5
table_rows	3
table_columns	2
description	23

In [18]:

import matplotlib.pyplot as plt
fig, ax = plt.subplots()

x_var = "time"
y_var = "temperature" 

x_attr = data.metadata.get(x_var)
y_attr = data.metadata.get(y_var)

ax.plot(data.df[x_var], data.df[y_var], label=data.name)
ax.legend(loc="best")
ax.set_xlabel("{0.label} [{0.unit}]".format(x_attr))
ax.set_ylabel("{0.label} [{0.unit}]".format(y_attr))
print("plot")

plot

Export¶

Der Export kann in verschiedene Formate erfolgen.

In [19]:

import os
filepath_xlsx = os.path.join("/tmp", data.osname + ".xlsx")
data.to_xlsx(filepath=filepath_xlsx)
print("Saved '{0.name}' to '{1}'.".format(data, filepath_xlsx))

Saved 'Temperaturmessung-001' to '/tmp/temperaturmessung-001.xlsx'.

In [20]:

filepath_json = os.path.join("/tmp", data.osname + ".json")
data.to_json(filepath=filepath_json)
print("Saved '{0.name}' to '{1}'.".format(data, filepath_json))

Saved 'Temperaturmessung-001' to '/tmp/temperaturmessung-001.json'.

In [21]:

filepath_csv = os.path.join("/tmp", data.osname + ".csv")
data.to_csv(filepath=filepath_csv)
print("Saved '{0.name}' to '{1}'.".format(data, filepath_csv))

Saved 'Temperaturmessung-001' to '/tmp/temperaturmessung-001.csv'.

Import¶

Der Import kann aus den verschiedene Export-Formate erfolgen.

In [22]:

filepath_xlsx = os.path.join("/tmp", data.osname + ".xlsx")
data_xlsx = data.from_xlsx(filepath=filepath_xlsx)
data_xlsx

Out[22]:

(Data 'Temperaturmessung-001':e13d9387728c375eb98686eacf42b6df)

In [23]:

filepath_json = os.path.join("/tmp", data.osname + ".json")
data_json = data.from_json(filepath=filepath_json)
data_json

Out[23]:

(Data 'Temperaturmessung-001':e13d9387728c375eb98686eacf42b6df)

Jedes sdata.Data-Objekt kann seinen Hash-Wert bestimmen. Dieser Hash-Wert, hier ein sha3-256, kann u.a. zum Vergleich der Daten benutzt werden.

In [24]:

assert data.sha3_256==data_xlsx.sha3_256
assert data.sha3_256==data_json.sha3_256

print(data.sha3_256)
print(data_xlsx.sha3_256)
print(data_json.sha3_256)

7d681f4302252912cc9ad1c90f5a2b4be37362cfcecfdfe00f8d6ffee6faf48a
7d681f4302252912cc9ad1c90f5a2b4be37362cfcecfdfe00f8d6ffee6faf48a
7d681f4302252912cc9ad1c90f5a2b4be37362cfcecfdfe00f8d6ffee6faf48a

Zusammenfassung¶

Das sdata-Format bietet eine einfache Möglichkeit Daten lesbar für Menschen und zugleich maschinenlesbar abzulegen. Dies wird u.a. durch die Import-Export-Formate xlsx, json, csv gewährleistet. Durch die Qualifikation der Massendaten durch Metadaten und einer Beschreibung in Textform ist eine vollständige Beschreibung der Daten möglich. Die open-source Python-Bibliothek sdata erlaubt eine einfach Benutzung und Erweiterung des Datenformates.