Przed skorzystaniem z usługi należy zapoznać się z informacjami wstępnymi zawierającymi opis kroków umożliwiających dostęp do interfejsu programistycznego CLARIN-PL.
Usługa MDS służy do wizualizacji danych wysokowymiarowych poprzez redukcję wymiarowości do przestrzeni 2D lub 3D.
Usługę można uruchomić za pomocą zapytania LPMN w usłudze LPMN Client:
Usługę można wywołać w systemie Windows z wartościami domyślnymi za pomocą następującego zapytania LPMN: ['unzip','mds3']
['unzip',{'mds3':{'method':'umap','input_type':'embedder','export_bokeh':True}}] - metoda redukcji wymiarowości - umap, dane wejściowe w postaci wektorów osadzeń uzyskanych z Embeddera, wizualizacja danych wyjściowych wyeksportowana do pliku results.html.method: określenie metody redukcji wymiarowości. Dostępne metody:
tsne - ang. t-Distributed Stochastic Neighbor Embeddingumap - ang. Uniform Manifold Approximation and Projectionmds - ang. Multidimensional Scaling, opcja domyślnanmds - ang. Non-Metric Multidimensional ScalingParametry specyficzne dla danej metody są opisane w osobnej sekcji.
normalization: metoda normalizacji wektorów przed redukcją wymiarowości.
l2 - obecnie jedyna dostępna metoda działająca tylko dla danych wejściowych w formacieembeddingNone - opcja domyślnadim: docelowa wymiarowość redukcji. Dostępne opcje:
2 - opcja domyślna3seed: ziarno stosowane w przypadku niedeterministycznych metod redukcji. Domyślnie: 1234.metric: rodzaj metryki stosowanej do określenia odległości między punktami. Dostępne opcje:
cosine - opcja domyślnaeuclideanexport_png - wizualizacja danych wyjściowych formacie .png:
False - opcja domyślnaTrueexport_bokeh - wizualizacja danych wyjściowych wyeksportowana do pliku results.html:
False - opcja domyślnaTrueinput_type: format danych wejściowych. Dostępne opcje:
embedderembeddingdistancesimilaritytopicsNone - opcja domyślnaWięcej informacji w sekcji Rodzaje Wejść.
MDS i nMDS:
n_iter: maksymalna liczba iteracji algorytmu SMACOF. Możliwe, że metoda zbiegnie do rozwiązania w mniejszej liczbie kroków.n_init: liczba wykonań algorytmu SMACOF z różnymi punktami startowymi. Domyślnie: 4.eps: próg zbieżności SmaCof. Domyślnie 1e-3.T-SNE:
perplexity: parametr określający kompromis pomiędzy lokalnym (niskie wartości) a globalnym (wysokie wartości) odwzorowaniem struktury. Przy dużych wartościach (>1000, zależnie od zbioru danych) staje się podobny do PCA. Zalecane wartości są zwykle w zakresie 10-50. Domyślnie: 10.n_iter: liczba kroków optymalizacji gradient descent.learning_rate: stała uczeniaPCA:
Brak parametrów specyficznych dla metody.
Uwaga: Metoda PCA działa tylko dla danych wejściowych w formatach embeddingg i topics. Jeżeli dane wejściowe są w formie macierzy dystansu lub podobieństwa, należy użyć metody mds lub nmds.
UMAP:
Brak parametrów specyficznych dla metody.
Katalog .zip z danymi wejściowymi w jednym z 5 typów wspieranych formatów:
Katalog wejściowy powinien zawierać plik odpowiadający wybranemu typowi danych wejściowych (input_type):
weighted.jsondistance.jsonsimilarity.jsonTOPICS_FILEEMBEDDER_DIRSzczegółowe informacje na temat każdego z formatów są dostępne poniżej.
W tym formacie każdy punkt jest opisany przez wektor stałej wielkości.
Format katalogu wejściowego:
input_dir
|--weighted.json
|--...
Format pliku weighted.json:
{
"rowlabels": [
"document1",
"document2",
"document3",
...
],
"arr": [
[0.121, 0.421, -0.111, 0.125, ...], # Embedding vector of document1
[0.881, 0.511, -0.132, 0.625, ...], # Embedding vector of document2
[0.081, 0.211, -0.101, 0.925, ...], # Embedding vector of document3
...
],
... # Other entries are allowed but not parsed
}
Macierz odległości to macierz kwadratowa, w której komórka o pozycji (m,n) definiuje odległość pomiędzy n-tym i m-tym punktem. Format ten zakłada symetrię, tzn. M(m,n) musi być równe M(n,m).
Format katalogu wejściowego:
input_dir
|--distance.json
|--...
Format pliku distance.json:
{
"rowlabels": [
"document1",
"document2",
"document3",
...
],
"arr": [
[0.121, 0.421, 0.111, 0.125, ...],
[0.881, 0.511, 0.132, 0.625, ...],
[0.081, 0.211, 0.101, 0.925, ...],
...
], # A square nxn non-negative, symetric matrix where entry of index (m, n) is distance between m-th and n-th documents
... # Other entries are allowed but not parsed
}
Macierz podobieństwa jest bardzo podobna do macierzy odległości, różni się jednak interpretacją wartości w macierzy. W macierzy podobieństwa każda wartość opisuje to, jak podobne są 2 dokumenty, natomiast w macierzy odległości to, jak są różne.
Format katalogu wejściowego:
input_dir
|--similarity.json
|--...
Format pliku similarity.json:
{
"rowlabels": [
"document1",
"document2",
"document3",
...
],
"arr": [
[0.121, 0.421, -0.111, 0.125, ...], # Embedding of document 1
[0.881, 0.511, -0.132, 0.625, ...], # Embedding of document 2
[0.081, 0.211, -0.101, 0.925, ...], # Embedding of document 3
...
], # A square nxn non-negative, symetric matrix where entry of index (m, n) is similarity measure of m-th and n-th documents
... # Other entries are allowed but not parsed
}
Można też wykorzystać skład tematyczny dokumentów i zinterpretować go jako osadzenie w rzadkiej, wielowymiarowej przestrzeni. Wtedy osadzenie definiuje się następująco:
doc_m = [topic_1, topic_2, ..., topic_n]
Gdzie topic_n opisuje, jak bardzo dokument m należy do tematu topic_n. Np. zakładając, że zdefiniowane są trzy tematy, to
[0.91, 0, 0.19]
oznacza, że dokument składa się w 91% z tematu 1, 19% z tematu 2 i 0% z tematu 3.
Format katalogu wejściowego:
input_dir
|--topics.json
|--...
Format pliku topics.json:
{
"docs": [
"document1": {
"topic1": 0.0019,
"topic3": 0.9981,
},
"document2": {
"topic2": 1.0 # Note - if topic is not specified in given document, it's implicitly assumed to be equal to 0
},
"document3": {
"topic1": 0.6457,
"topic2": 0.1986,
"topic3": 0.1557
},
...
],
"topics": [
"topic1": {
"water": 0.2152, # Tokens that define the topics. Topics definitions (currently) are not used for mds. MDS service only needs to know what topics exists
"earth": 0.1304,
"life": 0.0123,
...
},
"topic2": {
"fries": 0.2152,
"burger": 0.1304,
"hotdog": 0.0123,
...
},
"topic3": {
"church": 0.2152,
"priest": 0.1304,
"cathedral": 0.0123,
...
}
...
],
... # Other entries are allowed but not parsed
}
Ten format wymaga podfolderu o nazwie catalog z dokumentami w formacie json line. Każdy dokument powinien zawierać jsona z następującymi kluczami:
"text" - treść zdania
"embedding" - przypisane mu wektory osadzeń
Format katalogu wejściowego:
input_dir
|--catalog
| --document1
| --document2
| --...
| --documentX
|--...
Format pliku document:
{"text": "Originally, the new album ...", "embedding": [0.06480148434638977, 0.1550612896680832, -0.008114025928080082, ...]}
{"text": "Today, recording music resembles a ...", "embedding": [-0.025914771482348442, 0.27748793363571167, -0.01087457500398159, ...]}
Poniżej zostały zdefiniowane dodatkowe pliki wejściowe, których obecność nie jest wymagana.
Plik, który przypisuje każdy punkt do kategorii. W jednym pliku można zdefiniować wiele przypisań punkt-kategoria.
Struktura katalogu wejściowego:
input_dir
|--labels.json
|--...
Struktura pliku labels.json:
{
"rowlabels": [
"document1", # Document names compatible with the ones defined in the input file
"document2",
"document3",
...
],
"groups": {
"languages": {
"polish", # Assigment of document1 in category 'languages'
"polish", # Assigment of document2 in category 'languages'
"english", # Assigment of document3 in category 'languages'
...
},
"sentiment": {
"positive", # Assigment of document1 in category 'sentiment'
"positive", # Assigment of document2 in category 'sentiment'
"neutral", # Assigment of document3 in category 'sentiment'
...
},
... # More categories
},
... # Other entries are allowed but not parsed
}
Plik topics.json (Zobacz 4. Subject composition embedding) jest parsowany nawet jeśli nie został wybrany jako plik wejściowy. Zawiera on informacje o tematach każdego dokumentu, które zostaną przekazane do końcowego pliku json.
Struktura katalogu wyjściowego:
output_dir
|--result.json
|--result.png
|--result_category1.png
|--result_category2.png
|--...
|--result_categoryN.png
Pliki result*.png powstają jedynie, jeżeli export_png zostanie ustawione na True.
result.jsonPlik results.json składa się z sześciu pól:
x: Współrzędne punktów na osi xy: Współrzędne punktów na osi yz: (opcjonalnie) Współrzędne punktów na osi z. Występuje tylko, jeżeli dim ustawiono na 3labels: Nazwy każdego punktucategories: Przypisania punktów do kategorii. W przykładzie poniżej, książki są podzielone ze względu na czas powstania jak i na gatunek.type: Typ punktu. Obecnie zdefiniowane są 2 typy: data - normalny punkt, topic - Specjalny punkt, określający położenie centrum tematu.{
"x": [
-105.99490356445312,
9.57337760925293,
17.01878547668457,
-101.49317932128906,
12.965667724609375,
...
],
"y": [
-97.20722198486328,
14.849251747131348,
-85.53638458251953,
-93.25206756591797,
-77.4927978515625,
-104.14188385009766,
...
],
"z": [
53.90522003173828,
-110.36262512207031,
-86.60794830322266,
46.40607833862305,
-92.60964965820312,
32.516143798828125,
97.01101684570312,
...
],
"labels": [
"książka1",
"książka2",
"książka3",
"książka4",
"książka5",
"książka6",
"książka7",
...
]
"categories": {
"epoka": [
"renesans",
"renesans",
"barok",
"renesans",
"odrodzenie",
"odrodzenie",
...
],
"gatunek": [
"romans",
"romans",
"wojny",
"romans",
"komedia",
...
],
...
},
"type": [
"data",
"data",
"data",
"data",
"data",
"data",
...
]
}
W Colabie:
(C) CLARIN-PL