Skip to content
Snippets Groups Projects
Commit 12b63a7d authored by Vanessa Stehr's avatar Vanessa Stehr
Browse files

Fix typos in flat-tables-de.md

parent f5e66f7e
No related branches found
No related tags found
No related merge requests found
Pipeline #52193 failed
Stage: test
Hide whitespace changes
Inline Side-by-side
doc/tabellen/flat-tables-de.md
+ 39
− 38
View file @ 12b63a7d
## Implementierung, Reshaping und Testmethodik
Diese Dokumentation beschreibt die Implementierung einer flachen (Flatt-)Tabellendarstellung im DCC-Format, die Reshaping-Methodik sowie die Validierung dieser Darstellung und ihrer Parser mittels Primfaktorzerlegung.
Diese Dokumentation beschreibt die Implementierung einer flachen (Flat-)Tabellendarstellung im DCC-Format, die Reshaping-Methodik sowie die Validierung dieser Darstellung und ihrer Parser mittels Primfaktorzerlegung.
## 1. Flatt-Format vs. Long-Darstellung
## 1. Flat-Format vs. Long-Format
### Flatt-Format
### Flat-Format
In vielen Anwendungsfällen, wie etwa bei der Erfassung von Mikroskopbildern, werden höherdimensionale Daten in einem rasterartigen Format erfasst. Hierbei wird die Lichtintensität auf einem Gitter aus X- und Y-Positionen gemessen.
- **Long-Darstellung:**
- **Long-Format:**
Alle möglichen Kombinationen der Indexwerte (z. B. X und Y) werden explizit in der Tabelle gespeichert. Dies führt zu einer sehr großen Datenmenge, da redundante Indexwerte mehrfach vorkommen.
- **Flatt-Format:**
Die Indexwerte werden jeweils nur einmal als separate dcc:Quantities abgelegt, während die eigentlichen Messdaten in einer einzigen, flachen Liste gespeichert werden.
- **Flat-Format:**
Die Indexwerte werden jeweils nur einmal als separate `dcc:Quantities` abgelegt, während die eigentlichen Messdaten in einer einzigen, flachen Liste gespeichert werden.
Beispiel:
Bei einer Messung mit 1920 × 1080 Positionen würden im Long-Format ca. 2 × 2.073.600 Indexwerte gespeichert werden. Im Flatt-Format sind lediglich 1920 Werte für die X-Position und 1080 Werte für die Y-Position notwendig – eine Einsparung von **99,8 %** der Indexwerte.
Bei einer Messung mit 1920 × 1080 Positionen würden im Long-Format ca. 2 × 2.073.600 Indexwerte gespeichert werden. Im Flat-Format sind lediglich 1920 Werte für die X-Position und 1080 Werte für die Y-Position notwendig – eine Einsparung von **99,8 %** der Indexwerte.
Die Umrechnung von einem n-dimensionalen Index in einen eindimensionalen Flatt-Index erfolgt mittels der folgenden Formel:
Die Umrechnung von einem n-dimensionalen Index in einen eindimensionalen Flat-Index erfolgt mittels der folgenden Formel:
$$
\text{Index} = \sum_{k=0}^{N-1} \left( i_k \times \prod_{j=k+1}^{N-1} d_j \right)
......@@ -30,15 +30,15 @@ Diese Methode entspricht der **Row-Major-Order** (C-Style-Order), wie sie in Pro
### Long-Darstellungen müssen nicht speziell getestet werden
In der Long-Darstellung werden alle Indexkombinationen vollständig gespeichert, sodass keine Umrechnung von mehrdimensionalen in eindimensionale Werte erfolgt.
Dadurch ist das Risiko eines Mapping-Fehlers nicht vorhanden. Dennoch ist es sinnvoll und empfolen, zu prüfen, ob alle dcc:qunatites anch dem Parsen die selbe Länge haben um auszuschießen, dass das inkorrekte Parsen von Whitspaces wie z.B. beim Zeilenumbruch '\n\r' zu leeren Elementen geführt haben.
Im Flatt-Format hingegen findet eine Kompression der Indexinformationen statt – hier muss für jede Parser Implementierung einmal überprüft werden, ob die Umrechnung (Reshaping) korrekt vorgenommen wurde.
Dadurch ist das Risiko eines Mapping-Fehlers nicht vorhanden. Dennoch ist es sinnvoll und empfohlen, zu prüfen, ob alle `dcc:quantities` nach dem Parsen die selbe Länge haben, um auszuschließen, dass das inkorrekte Parsen von Whitespaces wie z.B. beim Zeilenumbruch '\n\r' zu leeren Elementen geführt hat.
Im Flat-Format hingegen findet eine Kompression der Indexinformationen statt – hier muss für jede Parserimplementierung einmal überprüft werden, ob die Umrechnung (Reshaping) korrekt vorgenommen wurde.
Genau diese Validierung erfolgt im Folgenden mittels Primfaktorzerlegung.
## 2. Validierung mittels Primfaktorzerlegung
### Mathematischer Hintergrund
Jeder Indexvektor in der Flatt-Tabelle besteht aus einer Folge von Primzahlen. Ein Eintrag $T(i_0, i_1, \dots, i_{N-1})$ der flachen Datenliste wird als Produkt definiert:
Jeder Indexvektor in der Flat-Tabelle besteht aus einer Folge von Primzahlen. Ein Eintrag $T(i_0, i_1, \dots, i_{N-1})$ der flachen Datenliste wird als Produkt definiert:
$$
T(i_0, i_1, \dots, i_{N-1}) = \prod_{k=0}^{N-1} p_{k, i_k}
......@@ -61,14 +61,14 @@ Stimmt die durch die Primfaktorzerlegung erhaltene Faktorliste mit der erwartete
### 1 oder 0 Indizierung
In diesem Beispil und im Python-Code wird wie in C und Python üblich mit 0 startend indiziert, die Methdoik lässt sich analog auch auf 1 Indizierung wie in Fortran, R oder Matlab anwenden.
In diesem Beispiel und im Python-Code wird wie in C und Python üblich mit 0 startend indiziert, doch die Methodik lässt sich analog auch auf 1 Indizierung wie in Fortran, R oder Matlab anwenden.
## 3. Beispiel-XML und Implementierung des Reshapings
Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle, in der die Indexvektoren und die flachen Daten als dcc:Quantities abgelegt sind. Die XML-Struktur enthält außerdem detaillierte Beschreibungen in Englisch und Deutsch, die erläutern, wie die Reshaping-Umrechnung und die Validierung mittels Primfaktorzerlegung erfolgen.
Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flat-Tabelle, in der die Indexvektoren und die flachen Daten als `dcc:Quantity`s abgelegt sind. Die XML-Struktur enthält außerdem detaillierte Beschreibungen in Englisch und Deutsch, die erläutern, wie die Reshaping-Umrechnung und die Validierung mittels Primfaktorzerlegung erfolgen.
```xml
<dcc:list refType="basic_3IndexFlattTable">
<dcc:list refType="basic_3IndexFlatTable">
<dcc:name>
<dcc:content lang="en">3D Table with Index Vectors</dcc:content>
<dcc:content lang="de">3D Tabelle mit Indexvektoren</dcc:content>
......@@ -87,11 +87,11 @@ Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle,
und wird verwendet, um die korrekte Neuordnung der Daten zu überprüfen.
</dcc:content>
</dcc:description>
<dcc:list refType="basic_FlattTableIndices">
<dcc:quantity refType="basic_FlattTableIndex0">
<dcc:list refType="basic_FlatTableIndices">
<dcc:quantity refType="basic_FlatTableIndex0">
<dcc:name>
<dcc:content lang="en">Index 0 first</dcc:content>
<dcc:content lang="de">Index 0 erster</dcc:content>
<dcc:content lang="de">Index 0 Erster</dcc:content>
</dcc:name>
<dcc:description>
<dcc:content lang="en">
......@@ -106,10 +106,10 @@ Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle,
<si:unitXMLList>\one</si:unitXMLList>
</si:realListXMLList>
</dcc:quantity>
<dcc:quantity refType="basic_FlattTableIndex1">
<dcc:quantity refType="basic_FlatTableIndex1">
<dcc:name>
<dcc:content lang="en">Index 1 second</dcc:content>
<dcc:content lang="de">Index 1 zweiter</dcc:content>
<dcc:content lang="de">Index 1 Zweiter</dcc:content>
</dcc:name>
<dcc:description>
<dcc:content lang="en">
......@@ -124,10 +124,10 @@ Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle,
<si:unitXMLList>\one</si:unitXMLList>
</si:realListXMLList>
</dcc:quantity>
<dcc:quantity refType="basic_FlattTableIndex2">
<dcc:quantity refType="basic_FlatTableIndex2">
<dcc:name>
<dcc:content lang="en">Index 2 third</dcc:content>
<dcc:content lang="de">Index 2 dritter</dcc:content>
<dcc:content lang="de">Index 2 Dritter</dcc:content>
</dcc:name>
<dcc:description>
<dcc:content lang="en">
......@@ -143,10 +143,10 @@ Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle,
</si:realListXMLList>
</dcc:quantity>
</dcc:list>
<dcc:list refType="basic_FlattTableData">
<dcc:list refType="basic_FlatTableData">
<dcc:name>
<dcc:content lang="en">Data Quantities</dcc:content>
<dcc:content lang="de">Daten Quantities</dcc:content>
<dcc:content lang="de">Daten-Quantities</dcc:content>
</dcc:name>
<dcc:description>
<dcc:content lang="en">
......@@ -155,7 +155,7 @@ Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle,
to test the correct reshaping of the data.
</dcc:content>
<dcc:content lang="de">
Diese flachgelegte Datenanordnung wird durch Multiplikation der Indexvektoren erzeugt.
Diese flache Datenanordnung wird durch Multiplikation der Indexvektoren erzeugt.
Die Primfaktorzerlegung jedes Wertes entspricht seinem Multi-Index und wird verwendet, um
die korrekte Neuordnung der Daten zu überprüfen.
</dcc:content>
......@@ -167,7 +167,7 @@ Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle,
</dcc:name>
<si:realListXMLList>
<si:valueXMLList>
<!-- The additional whitespaces and linefeed are only for visualisation! The Last index dimension is written in consecutive blocks. -->
<!-- The additional whitespaces and linefeed are only for visualization! The last index dimension is written in consecutive blocks. -->
130 170 190 230 290
182 238 266 322 406
286 374 418 506 638
......@@ -190,22 +190,23 @@ Die folgende XML-Struktur demonstriert ein Beispiel für eine 3D-Flatt-Tabelle,
Die Generierung der flachen Tabelle erfolgt durch die folgende Methode:
1. **Generierung der Indexvektoren:**
Für jede Dimension wird eine Folge aufteigend sortierte Liste von disjunkten Primzahlen erzeugt.
Für jede Dimension wird eine Folge aufsteigend sortierte Liste von disjunkten Primzahlen erzeugt.
2. **Reshaping mittels Broadcasting:**
Die einzelnen Primzahlvektoren werden so umgeformt, dass sie über alle Dimensionen hinweg miteinander multipliziert werden können. Das Ergebnis ist eine n-dimensionale Tabelle, deren Werte das Produkt der jeweiligen Indexwerte sind.
3. **Flattening:**
Die n-dimensionale Tabelle wird in eine flache, eindimensionale Liste (C-Style, row-major) umgewandelt.
Der folgende Python-Codeausschnitt zeigt die wesentlichen Schritte:
Der pytest in der Datei [test_flatt_table.py](../../tests/test_flatt_table.py) überprüft die korrekte Umrechnung der n-dimensionalen Indexwerte in die flache Liste.
Dabei werden immer der erste un der letzte Wert in der hochdimensionellen-Tabelle so wie 1000 zufällige Index-Kombinationen überprüft.
Der pytest in der Datei [test_flat_table.py](../../tests/test_flat_table.py) überprüft die korrekte Umrechnung der n-dimensionalen Indexwerte in die flache Liste.
Dabei werden immer der erste und der letzte Wert in der hochdimensionalen Tabelle so wie 1000 zufällige Index-Kombinationen überprüft.
```python
import os # Importiere das OS-Modul zur Arbeit mit Dateisystemen
import numpy as np # Importiere NumPy als np zur Arbeit mit Arrays und numerischen Operationen
import uuid # Importiere das UUID-Modul zur Generierung von eindeutigen Identifikatoren
def is_prime(n): # Definiert Funktion is_prime zur Überprüfung, ob eine Zahl n eine Primzahl ist
# this algorithmus is neither fast nor efficient,
# This algorithm is neither fast nor efficient,
# but it is simple and works for our purpose and can be implemented in any programming language
if n < 2: # Falls n kleiner als 2 ist, ist es keine Primzahl
return False # Gib False zurück, da n keine Primzahl ist
......@@ -215,7 +216,7 @@ def is_prime(n): # Definiert Funktion is_prime zur Überprüfung, ob eine Zahl
return True # Wenn keine Teilbarkeit gefunden wurde, ist n eine Primzahl, also gib True zurück
def next_n_primes(n, start=2): # Definiert Funktion next_n_primes zur Generierung der nächsten n Primzahlen ab einem Startwert
#This function generates the next n primes starting from the given start value
# This function generates the next n primes starting from the given start value
primes = [] # Initialisiere eine leere Liste zur Speicherung der gefundenen Primzahlen
num = start # Setze die Zählvariable num auf den Startwert
while len(primes) < n: # Solange die Anzahl der gefundenen Primzahlen kleiner als n ist
......@@ -260,14 +261,14 @@ def generate_indices_xml(prime_arrays): # Definiert Funktion generate_indices_x
ordinal_en = f"index {i}" # Andernfalls verwende einen generischen Text für Englisch
ordinal_de = f"Index {i}" # Andernfalls verwende einen generischen Text für Deutsch
value_list = " ".join(map(str, arr)) # Erzeuge einen String, der alle Primzahlen des Arrays mit Leerzeichen getrennt enthält
snippet = f''' <dcc:quantity refType="basic_FlattTableIndex{i}">
snippet = f''' <dcc:quantity refType="basic_FlatTableIndex{i}">
<dcc:name>
<dcc:content lang="en">Index {i} {ordinal_en}</dcc:content>
<dcc:content lang="de">Index {i} {ordinal_de}</dcc:content>
</dcc:name>
<dcc:description>
<dcc:content lang="en">This index vector contains the prime numbers used for dimension {i} (zero indexd) of the flat table.</dcc:content>
<dcc:content lang="de">Dieser Indexvektor enthält die Primzahlen, die für die Dimension {i} (nullindiziert) der flachen Tabelle verwendet werden.</dcc:content>
<dcc:content lang="en">This index vector contains the prime numbers used for dimension {i} (zero indexed) of the flat table.</dcc:content>
<dcc:content lang="de">Dieser Indexvektor enthält die Primzahlen, die für die Dimension {i} (null-indiziert) der flachen Tabelle verwendet werden.</dcc:content>
</dcc:description>
<si:realListXMLList>
<si:valueXMLList>{value_list}</si:valueXMLList>
......@@ -319,7 +320,7 @@ def populate_dcc_xml(shape=[2, 3, 5, 7, 11], numbers_per_line=None, lines_per_bl
<dcc:content lang="de">{len(shape)}D Tabelle mit Indexvektoren</dcc:content>
</dcc:name>
<dcc:data>
<dcc:list refType="basic_{len(shape)}IndexFlattTable">
<dcc:list refType="basic_{len(shape)}IndexFlatTable">
<dcc:name>
<dcc:content lang="en">{len(shape)}D Table with Index Vectors</dcc:content>
<dcc:content lang="de">{len(shape)}D Tabelle mit Indexvektoren</dcc:content>
......@@ -338,10 +339,10 @@ def populate_dcc_xml(shape=[2, 3, 5, 7, 11], numbers_per_line=None, lines_per_bl
und wird verwendet, um die korrekte Neuordnung der Daten zu überprüfen.
</dcc:content>
</dcc:description>
<dcc:list refType="basic_FlattTableIndices">
<dcc:list refType="basic_FlatTableIndices">
{indices_xml}
</dcc:list>
<dcc:list refType="basic_FlattTableData">
<dcc:list refType="basic_FlatTableData">
<dcc:name>
<dcc:content lang="en">Data Quantities</dcc:content>
<dcc:content lang="de">Daten Quantities</dcc:content>
......@@ -353,7 +354,7 @@ def populate_dcc_xml(shape=[2, 3, 5, 7, 11], numbers_per_line=None, lines_per_bl
to test the correct reshaping of the data.
</dcc:content>
<dcc:content lang="de">
Diese flachgelegte Datenanordnung wird durch Multiplikation der Indexvektoren erzeugt.
Diese flache Datenanordnung wird durch Multiplikation der Indexvektoren erzeugt.
Die Primfaktorzerlegung jedes Wertes entspricht seinem Multi-Index und wird verwendet, um
die korrekte Neuordnung der Daten zu überprüfen.
</dcc:content>
......@@ -391,6 +392,6 @@ def save_xml_output(xml_content, filepath): # Definiert Funktion zum Speichern
if __name__ == '__main__': # Prüfe, ob dieses Skript direkt ausgeführt wird
shape_vector = [2, 3, 5, 7, 11] # Definiere den Dimensionsvektor für die Tabelle
xml_output = populate_dcc_xml(shape=shape_vector) # Erzeuge das XML-Template basierend auf dem Dimensionsvektor
output_path = os.path.join("..", "data", "nDFlattTableParsingTest.xml") # Definiere den Pfad, unter dem das XML gespeichert werden soll
output_path = os.path.join("..", "data", "nDFlatTableParsingTest.xml") # Definiere den Pfad, unter dem das XML gespeichert werden soll
save_xml_output(xml_output, output_path) # Speichere das erzeugte XML-Template in der angegebenen Datei
```
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment