Biblioteka funkcji Matlab wspomagająca współpracę ze SWIP5 może być podzielona na kilka rodzajów funkcji

1. Funkcje wspomagające dostęp do pól struktury MatlabQML i operacje na nich

Są to funkcje przydatne do pisania własnych procedur operujących na danych MatlabQML.

  • [value] = getOptional( owner, field) - Funkcja pobiera z struktury MatlabQML opcjonalny obiekt o nazwie field. Zwraca jego kopię lub obiekt pusty jeżeli pole jest niezdefiniowane
  • [value] = isOptionalTree( owner, field1, field2,...) - Funkcja testuje istnienie opcjonalnego drzewa obiektów struktury MatlabQML obiektu owner. Zwraca kopię ostatniego obiektu z listy drzewa lub wartość pustą jeżeli dla kolejnych pół field* w strukturze obiekt o danej nazwie jest pusty lub nie istnieje. W przypadku tylko jednego pola w ścieżce, funkcja getOptionalTree jest wolniejsza niż funkcja getOptional, której należy użyć zamiast tego.
  • [value] = getOptionalValue( owner, field ) - Funkcja zwraca wartość value z opcjonalnego obiektu jeśli obiekt istnieje lub NaN, jeśli nie istnieje. W zależności od typu opcjonalnego obiektu może to to być wartość  typu rzeczywistego (obiekt typu RealQuantity), całkowitego (obiekt typu IntQuantity) lub czasu (obiekt typu TimeQuantity) . W wielu strukturach QuakeML wartość ta i obiekt typu Quantity ją przechowujący nie są opcjonalne i musi być zaznaczona w QuakeML. W takich przypadkach użycie tej funkcja nie jest wymagana. Szybsze jest wywołanie po prostu „owner.field.value” . Wejściowe wartości: owner - struktura zawierająca obiektu typu Quantity , field - nazwa pola (ciąg znaków) z obiektem.
  • [result] = isOptional( owner, field) - sprawdza, czy w obiekcie MatlabQML owner jest zdefiniowane opcjonalne pole field. Jeżeli brak pola field lub jest w nim pusty obiekt, zwraca fałsz.
  • [result] = isOptionalTree( owner, field1, field2,...) - Funkcja testuje istnienie opcjonalnego drzewa obiektów struktury MatlabQML obiektu owner. Zwraca fałsz jeżeli dla kolejnych pół field* w strukturze obiekt o danej nazwie jest pusty lub nie istnieje. W przypadku tylko jednego pola w ścieżce, funkcja isOptionalTree jest wolniejsza niż funkcja isOptional, której należy użyć zamiast tego.
  • [chanEq] = channelsEqual( channeln, channel2 ) - Funkcja p orównuje dwie nazwy kanałów obejmujące kody sieci, stacji, lokalizacji i kanału  w formacie WaveformStreamID. Jeśli w jednej nazwie kod sieci jest pusta lub nie istnieje, ignoruje porównanie sieci kodów sieci. Tak samo jest w przypadku kodu lokalizacji. Pierwsze zmienna wejściowa (channeln) może być wektorem WaveformStreamID, wtedy wynik jest wektorem logicznym. Druga zmienna wejściowa (channel2 ) musi być pojedynczym obiektem WaveformStreamID.
  • [staEq] = stationsEqual( stationn, station2 ) - Funkcja p orównuje dwie nazwy kanałów obejmujące kody sieci i stacji  w formacie WaveformStreamID. Jeśli w jednej nazwie kod sieci jest pusta lub nie istnieje, ignoruje porównanie sieci kodów sieci i porównuje tylko kody stacji. Pierwsze zmienna (stationn) może być wektorem WaveformStreamID, wtedy wynik jest wektorem logicznym. Druga zmienna wejściowa (station2) musi być pojedynczym obiektem WaveformStreamID.
  • [item, index] = findPublicID( tabela, id ) - Funkcja wyszukuje w tabeli element o identyfikatorze publicID = id. Tabelą może być dowolna tablica struktur zawierająca obiekty publicID, np.: events, pick, amplitudes, origins. Identyfikator (id) może być ciągiem znaków lub strukturą publicID z polem resourceID. Jeśli szukany identyfikator publiczny nie istnieje lub jest błędny, funkcja zwróci pustą zmienne. Element zwraca kopię znalezionego elementu w tabeli (item) oraz jego indeks (index) w tablicy, jeżeli chcemy modyfikować obiekt.

Funkcje getOptional,  getOptionalTree, i getOptionalValue należy zawsze stosować dla pół opcjonalnych- oznaczanych w opise QukeML jako [0..1] lub [0..*]. W przypadku tylko pół struktury, które na pewno występują w QuakeML można stosować odwołania do nich poprzez kropkę, t.j. np. zamiast wywołania value = getOptional( owner, 'field' ) zastosować value =owner.field albo zamiast value = getOptionalTree( owner, 'field1', 'filed2') zastosować value = owner.field1.filed2 .

2. Funkcje zamieniające obiekty MatlabQML na typowe obiekty Matlaba

Zamieniają one pewne obiekty MatlabQML do postaci ułatwiającej manipulowanie nimi w Matalabie.

  • [staName] = stationName2string( waveformId ) - Funkcja k onwertuje obiekt waveformId na ciąg nazwy stacji (sieć + stacja) do postaci 'nn.ssss', gdzie nn jest kodem sieci a ssss kodem stacji. W przypadku braku kodu sieci nazwa zwracana jest w postaci '.ssss'.

  • [chanName] = channelName2string( waveformId ) - Funkcja k onwertuje obiekt waveformId na ciąg nazwy kanału(sieć + stacja + lokalizacja + strumeniń) do postaci 'nn.ssss.ll.ccc', gdzie nn jest kodem sieci, ssss kodem stacji, ll kodel lokalizacji a ccc kodem kanału. W przypadku braku kodu lokalizacjin nazwa zwracana jest w postaci kropek, np. 'nn.ssss..ccc'.

  • [timesamples] = unixTimeSamples( data ) - Funkcja tworzy próbki z taktami czasowymi w formacie czasu UNIX (sekundy od 1970-01-01) odpowiadające próbkom w przebiegu. Zmwinne wejsciowe: data - struktura danych Waveform. Funkcja zwraca timesamples - tablicę cazsów kolejnych próbek o takim samym rozmiarze jak próbki sygnału. Przykładowe wywołanie:. t = unixTimeSamples(WaveForms(1).data(1)).

  • [data] = timeQML2Date( czas ) - Funkcja konwertuje pełny format czasu SWIP5 MatlabQML (struktura mikrosekund i łańcuch) na format Matlab DateTime Czasem wejściowym może być struktura TimeQuantity lub sam obiekt czasu.

3. Funkcje ogólne pobierające typowe wartości sejsmiczne z obiektu zjawiska sejsmicznego (event)

Są to najczęściej stosowane funkcje przy operacjach na wstrząsach. Napisane są w wykorzystaniem biblioteki funkcji wspomagających (pkt.1).

  • [latitude, longitude, depth, time, porigin] = event2coordinates( event, ... ) - Funkcja zwraca współrzędne zjawiska. Używa getOrigin, aby uzyskać współrzędne. (Zobacz funkcję getOrigin). Wejście: event - obiekt event QuakeML, Parametry opcjonalne: 'methodID', method, ... - znajduje tylko źródła wstrząsu zlokalizowane przez metodę o nazwie method; 'earthModelID', model, ... - znajduje tylko współrzędne zlokalizowany przy użyciu modelu prędkości Ziemi o nazwie model. Wartości wyjściowe: szerokość (latitude) i długość (longitude) geograficzna w stopniach, głębokość (depth) hipocentrum w km, czas wstrząsu (time) w formacie Matlab DateTime, porigin - kopia kopia obiektu origin. Jeśli nie może znaleźć źródła, funkcja zwraca wartości NaN i pusty porigin. Uwaga, w przypadku istnienia kilku lokalizacji i braku lokalizacji preferowanej, wybór lokalizacji, której współrzędne zostaną wypisane, może być losowy.
  • [value, type, magnitude] = getMagnitude( event, fn1, fn2, ...) - Funkcja wynajduje magnitudę zjawiska. Najpierw sprawdza, czy którykolwiek z nazw magnitud fn* jest preferowaną magnitudą zjawiska. Następnie szuka nazwy magnitudy fn1. Gdy nie może jej znaleźć, szuka magnitud stacyjnych fn1 i zwraca ich średnią wartość. Gdy nie może znaleźć magnitudy fn1, szuka magnitudy fn2 i tak dalej. Zwraca wartości: value - wartość magnitudy, type - typ magnitudy,  magnitude - kopia obiektu magnitudy, lub wartość pustą w przypadku wartości średniej magnitud stacyjnych. Przykładowe wywołanie: magnitude = getMagnitude( event, 'ML' ). Uwaga, w przypadku istnienia kilku równorzędnych magnitud tego samego typu i braku magnitudy preferowanej, wybór magnitudy przez tą funkcję może być losowy.
  • [value, type, ns] = getMagnitudeFromStaMagnitudes( event, fn1, fn2, ...) - Funkcja szuka magnitud stacyjnych fn1 i zwraca ich średnią wartość. Gdy nie może znaleźć magnitudy fn1, szuka magnitudy fn2 i tak dalej. Zwraca wartości: value - wartość średnia magnitud stacyjnych, type - typ magnitudy, ns - ilość stacji użytych do liczenia magnitudy, lub wartości [NaN, '', 0] w przypadku braku magnitud. Przykładowe wywołanie: magnitude = getMagnitudeFromStaMagnitudes( event, 'ML' ).
  • getMeanMag - Inna wersja liczenia magnitudy z magnitud stacyjnych z dodatkowymi opcjonalnymi parametrami.
  • [ value, type ] = getMomentTensor( focalMechanism ) - Funkcja pobiera macierz MT ze struktury focalMechanism (nie momentTensor) lub NaN, jeśli MT nie istnieje. Zwraca wartość macierzy value:
     | Mtt  Mtp  Mrt |
    | Mtp Mpp Mrp |
    | Mrt  Mrp  Mrr |
    i typ tensora momentu - type: „FULL”, „TRACE0”, „DC” lub pusty „”.
  • [origin] = getOrigin( event, ... ) - Funkcja p obiera obiekt źródła (origin) z obiektu zjawiska sejsmicznego (event). Jeśli preferowane źródło jest niezdefiniowane, przyjmuje ostatnie źródło z listy źródeł. J eśli jest ich wiele, to ostatnie może być przypadkowe.   Parametry opcjonalne: 'methodID', method, ... - znajduje tylko źródła wstrząsu zlokalizowane przez metodę o nazwie method; 'earthModelID', model, ... - znajduje tylko współrzędne zlokalizowany przy użyciu modelu prędkości Ziemi o nazwie model. Wyjście: origin - kopia obiektu źródła w formacie MatlabQML. Jeśli pochodzenie nie istnieje lub nie spełnia opcjonalnego parametru, wyjście jest pustym obiektem. Uwaga, w przypadku istnienia kilku lokalizacji i braku lokalizacji preferowanej, wybór lokalizacji może być losowy.
  • [picks] = getPicks (event, ...) - Funkcja pobiera wybrane piki faz z wstrząsu. Wejście: event - obiekt zdarzenia QuakeML Parametry: ..., 'sta', 'NN.SSS', ... - wyszukaj tylko nazwę stacji w postaci: NN - nazwa sieci, SSS - nazwa stacji. Jeśli sieć jest niezdefiniowana (pusta) kropka musi znajdować się na początku nazwy stacji, np. getPicks( zdarzenie, 'sta', 'VN.TLE'); ..., 'nazwa', 'P', ... - znajdź tylko zdefiniowaną fazę, np. getPicks( zdarzenie, 'name','Pg'). Dozwolonych jest wiele parametrów. np. getPicks(Event, 'sta', 'VN.TLE', 'name','Pg', 'name','Sg').

4. Funkcja do pracy na katalogu (wielu wstrząsach)

  • [out] = forAllEvents(quakeml, func, ...) - Funkcja ta pazwala otrzymywać jednym poleceniem tabelę wyników dla całego katalogu. Dla wszystkich zjawisk sejsmicznych zarejestrowanych w obiekcie quakeml, funkcja func jest wywoływana. Może to być funkcja specjalnie napisana lub jedna z funkcji bibliotecznych (patrz pkt. 3). Obiekt event musi być pierwszym parametrem funkcji func. Inne parametry func są opcjonalne i są tam przepisywane kolejne parametry wywoania forAllEvents . W wyniku wywołania funkcji dostajemy tablice komórkowa (cell). Każda linia odpowiada każdemu zjawisku, a każda kolumna odpowiada każdej zmiennej wyjściowej z func.

          Przykłady wywołania forAllEvents:
          magnitudes = forAllEvents(QuakeML, @getMagnitude, 'ML')
          dcr = forAllEvents(QuakeML, @CompareFM);
          resCNUD = linkCell(forAllEvents(QuakeML, @getResiduals, 'Stacja', 'CNUD'));
          evt = forAllEvents(QuakeML, @getOrigin, 'methodID', 'smi:igf.edu.pl/LocSAT');

5. Funkcje pomocnicze do manipulacja na parametrach (opcjach) wołania funkcji Matlabowej

Funkcje to są koniecznie, gdyż wiele pozostałych funkcji korzysta z nich. Można z nich korzystać przy pisaniu własnych funkcji

  • arispar
  • armanypars
  • aroptions
  • arparameters

6. Inne funkcje wspomagające przygotowanie danych do pracy w SWIP5 niezwiązane z MatlabQML.

Poniższa lista zawiera funkcje i skrypty przydatne do przygotowania pracy w SWIP5. Nie są one związane z przetwarzaniem wstrząsów i zapisów sejsmicznych w Matlabie. Funkcje te m.in. pozwalają przygotować parametry do pracy w SWIP5 na podstawie obiektów z platformy Episodes.

  • createXMLShapes(filename , shape1, shape2, ..., option1, optional_val1, ..., shapeN, ...) - Funkcja createXMLShapes tworzy kształty XML dla map SWIP5. Parametry wejściowe: filename - nazwa pliku, w którym zostanie zapisany kształt. Rozszerzenie nazwy pliku powinno być „.xml”, shape* - tablica struktur kształtów z czterema polami: 1. Lat jest wektorem szerokości punktów polilinii granicy kształtu. 2. Long jest wektorem długości geograficznych punktów polilinii granicy kształtu. Liczba wartości w Lat i Log musi być taka sama. 3. Contour to kolor RGB konturu kształtu, po którym następuje tabela [r,g,b,w] gdzie: r - czerwony, g - zielony, b - niebieski, w - szerokość linii. Zalecana wartość to [0,0,0,1] (czarny) 4. Face to kolor RGB lica kształtu, po którym następuje tabela [r,g,b,a] gdzie a - przezroczystość. Zalecana wartość to [1,1,1,1] (biały) 5. Name - opcjonalny tekst opisujący kształt. Musi być jeden lub wiele kształtów. Jeśli pola Kontur lub Ściana są niezdefiniowane, przyjmowane są domyślne kontury i ściany. Domyślny kontur to [0,7, 0,7, 0,7, 1], podczas gdy domyślna powierzchnia to [0,9, 0,9, 0,9, 0]. Domyślne wartości dla foliowania kształtów można zmienić za pomocą opcji ..., option*, optional_val*, ... - zmiany domyślnego konturu lub twarzy dla kolejnych kształtów. Istnieją trzy możliwości: ..., 'Contour', new_default_contour, ... - definiuje nowy domyślny kolor konturu dla kolejnych kształtów. Wartości konturu znajdują się w parametrze new_default_contour po opcji. ..., 'Face', new_default_face, ... - definiuje nowy domyślny kolor płaszczyzny dla następujących kształtów. ..., 'Default colors', ... - przywraca początkowe kolory konturu i powierzchni. Po opcji nie następuje parametr. Opcje mogą znajdować się przed pierwszym kształtem lub między kształtami w wywołaniu funkcji. Opcje tekstowe: Istnieje 5 opcji pozycji tekstu w stosunku do kształtu: ...,'top',... ...,'bottom',... ...,'left',... ...,'right',... ...,'middle',... Proste użycie createXMLShape z plikiem kształtów odcinków: 1. Wywołać clear; 2. Przeczytać plik kształtów z Episodes; 3. Wywołać createXMLShapes(nazwa pliku, d)
  • ISEPOSVelcityModel_to_Vel2Grid(vp, fileName, ...) Funkcja konwertuje model prędkości ISEPOS na linie tekstowe zgodne z NonLinLoc. Zmienna wejściowe: vp -model prędkości, fileName - nazwa .. Parametr opcjonalny: ..., 'density', den - ustaw domyślną gęstość na den (domyślnie 2700)


  • No labels

Podręcznik użytkownika SWIP5