Matematyka: DataBank

Krótki opis usługi

Usługa do równoległego i wielosesyjnego gromadzenia i monitorowania danych do celów analiz matematycznych i statystycznych.

Adres usługi: elder13.man.poznan.pl/redcap/

Aktywowanie usługi

Aby móc korzystać z usługi należy:

Założyć konto w portalu PLGrid: Zakładanie konta w portalu.
Wygenerować certyfikat: Aplikowanie, rejestracja i użycie certyfikatu.
Aktywacja usługi:
1. Zalogować się w: Portal PLGrid.
2. Przejść do zakładki 'Moje Konto'
3. W katalogu usług znaleźć 'Platforma dziedzinowa: Matematyka'.
4. Znaleźć usługę DATA BANK i kliknąć 'Aplikuj o usługę' .

Pierwsze kroki

Pierwsze logowanie
1. Wejść na stronę usługi:
2. Kliknąć w przycisk 'Log in using PlGrid OpenID'
3. Strona automatycznie zostanie przekierowana do strony OpenID PLGridu:
4. Podać swoją nazwę użytkownika portalu PLGrid oraz hasło.
5. Po pomyślnej weryfikacji danych, w usłudze DATA BANK zostanie utworzone automatycznie konto użytkownika. Następnie użytkownik zostanie przekierowany z powrotem do usługi DATA BANK.
Strona domowa usługi
1. Home - link do strony domowej
2. My projects - projekty, do których użytkownik posiada dostęp
3. Create New Project - dodawanie nowego projektu
4. Training Resources - materiały do nauki obsługi usługi
5. Help & FAQ - pomoc
6. Send-it - moduł, który umożliwia bezpieczne przesyłanie plików
Tworzenie projektu
Na stronie głównej usługi wybrać zakładkę 'Create New Project'. Poniżej przedstawiono przykładowy projekt z wykorzystaniem szablonu:
Ustawienia projektu
Po stworzeniu projektu pojawi się lista kontrolna projektu ('checklist') wskazująca podstawowe zadania, które powinny być wykonane przed zmianą fazy projektu z fazy deweloperskiej do fazy produkcji (w projekcie będącym w fazie produkcji nie możliwości zmiany struktury formularzy przez zwykłych użytkowników). Zadaniami mogą być: tworzenie struktur przechowujących (opisujących dane), nadawanie uprawnień, ustawienia modułów (np. moduł api, raportów itp).
Przygotowanie struktur do wprowadzania danych - tworzenie formularza (data instrument)
Każdy formularz definiuje w jaki sposób dane powinny być wprowadzane oraz w jaki sposób powinny być przechowywane. Każdy formularz składa się z pól, które mogą przechowywać wartości opisujące jakiś obiekt czy zjawisko (np. karta pacjenta). Różne typy pól opisane są tutaj.
Project Setup/ Online designer
1. Każdy formularz składa się z pól. Poniżej przedstawiono możliwe pola w usłudze:
  1. Text box - zwykłe pole tekstowe (jedna linia)
  2. Notes box - pole tekstowe służące do przechowywania dłuższych tekstów (wiele linii)
  3. Calculated field - pole zawierające funkcję agregujące wartości z innych pól danego projektu. Agregowane pola nie mogą zawierać wartości tekstowych. Nazwy agregowanych pól należy umieszczać w nawiasach kwadratowych '[Variable Name]' ('Variable Name' - systemowa nazwa pojedynczego pola, unikalna dla danego projektu). Poniżej przykładowa funkcja BMI:
    [weight] / ([height]^2)
  4. Multiple choice (drop down list) - wybór jednej opcji z listy rozwijanej
  5. Multiple choice (radio buttons) - wybór jednej opcji (bez listy rozwijanej)
  6. Checkboxes - wybór wielu opcji z listy:
  7. Yes/No - wybór tak/nie
  8. True/False - wybór prawda/fałsz
  9. Slider - suwak:
  10. File upload - dodatkowe pole służące dodawaniu plików przez użytkowników wypełniających ankietę/formularz (np. swoje zdjęcie).
  11. Descriptive text - przechowuje dodatkowe dokumenty dla formularza, np. jego opis lub wskazówki dotyczące danego formularza
  12. Begin new section - dzieli formularz na sekcje:
2. Status formularzy
- - niekompletny - nie wszystkie dane zostały uzupełnione
  - niekompletny pusty - dane nie zostały w ogóle wprowadzone
  - niezweryfikowany - dane wypełnione, ale nie sprawdzone
  - kompletny - dany formularz zawiera poprawne dane
Dodawanie nowego rekordu
1. zakładka Add/Edit Records
2. Podać identyfikator nowego rekordu (w ustawieniach projektu można również ustawić automatyczne generowanie identyfikatora rekordu)
3. Zatwierdzić oraz uzupełnić dostępne pola, np:
Raporty
Raport jest dynamicznym widokiem, który przechowuje wybrane pola ze zdefiniowanych wcześniej formularzy (data instruments). W raporcie można umieścić dowolne pole (field) z danego projektu. Dodatkowo dla każdego pola można zdefiniować warunki, które będą określały jakie rekordy zostaną umieszczone w raporcie (filtrowanie rekordów). Raporty można tworzyć za pomocą 'Report Builder'a - przycisk w menu z lewej strony, zakładka 'Applications'. Jeżeli przycisku nie ma w tej zakładce to znaczy, że nie posiadasz odpowiednich uprawnień do projektu lub moduł ten został wyłączony z danego projektu.
Przykładowy raport:
Data Quality
Panel umożliwiający przeszukiwanie danych pod kątem ich poprawności (brakujące pola, wartości przekraczające zakres itp).
Import danych
Obsługiwany przez usługę szablon importowanego pliku można pobrać w zakładce 'Data import tool' .
Przykładowy plik z danymi demograficznymi.Wczytane dane z pliku trzeba zaakceptować przed dodaniem do bazy.
Ubieganie się o token
Token to unikalny klucz, który umożliwia dostęp do danych poprzez API.
Aby uzyskać własny token:
1. My Projects -> Wejść w wybrany projekt -> Zakładka Applications (menu z lewej strony) -> wejść w API (brak opcji API oznacza brak uprawnień do korzystania z tej opcji)
2. Kliknąć w 'Request API token':
3. Poczekać, aż administrator zatwierdzi token
4. Po zatwierdzeniu tokenu token powinien być widoczny dla użytkownika
API raportu (Report API)
1. Opis
  To API umożliwia eksportowanie zbioru wierszy, które są zawarte w wybranym raporcie
2. URL
  https://elder13.man.poznan.pl/redcap/api/
3. Wspierane metody żądań (request methods)
  POST
4. Parametry
  Wymagane
  1. token
    token dla API jest to specjalny unikalny kod, przypisany do projektu oraz użytkownika.
  2. content
    report
  3. report_id
    1. <id raportu> - identyfikator raportu, który chcemy wyeksportować.
    2. 'integer' - zwraca liczbę wierszy, które obejmuje raport
    3. 'all' - zwraca strukturę wszystkich raportów przypisanych do danego projektu
  4. format
    csv,json, xml [default]
  5. type
    - flat - zwraca jeden rekord na każdy wiersz w raporcie [domyślnie]
    - eav - zwraca jeden wiersz na każdą osobną wartość (komórka tabeli) występującą w raporcie
      - dla projektów typu: 'Non-longitudinal': każdy rekord składa się z 3 pól: rekord*, nazwa_pola,wartość
      - dla projektów typu: 'Longitudinal': każdy rekord składa się z 4 pól: rekord*, nazwa_pola,wartość,<nazwa_eventu>
    * Rekord odnosi się do pola <study_id> lub jakiekolwiek innego klucza identyfikującego wiersz
  Opcjonalne
  - rawOrLabel
    raw [domyślnie] - pokazuje wartości kodowane (np. dla pola płeć: kobieta oznaczona byłaby jako 0), label - pokazuje etykietę przypisaną do wartości kodowanych, both - zwraca kodowaną wartość wraz z jej etykietą
  - eventName
    unique zwraca unikalną nazwę wydarzenia, label - zwraca etykietę
  - events
    lista nazw wydarzeń dla których zwracane maja być rekordy - tylko dla projektów typu: 'longitudinal projects'
5. Rezultat:
  przykładowy rezultat:
```
EAV XML:
<?xml version="1.0" encoding="UTF-8" ?>
<records>
   <item>
      <record></record>
      <field_name></field_name>
      <value></value>
      <redcap_event_name></redcap_event_name>
   </item>
</records>

Flat XML:
<?xml version="1.0" encoding="UTF-8" ?>
<records>
   <item>
      each data point as an element
      ...
   </item>
</records>
```
  Więcej informacji o dostępnych funkcjach API znajduje się tutaj.
Dodawanie Skryptu do aplikacji
1. Przykład wczytania pliku wejściowego: data=read.csv('<:inputname>' ). Pole ‘<:inputname>’ w trakcie przygotowania skryptu dla użytkownika zmieniana jest na faktyczna nazwę pliku.
2. Predefiniowane skrypty R należy dodawać do katalogu : ‘<ścieżka_do_redcap>/redcap_<wersja>/Resources/rscript’ np. ‘/var/www/html/redcap/redcap_v5.9.0/Resources/rscript’
3. Opis skryptu należy dodać do katalogu : ‘<ścieżka_do_redcap>/redcap_<wersja>/Resources/rscriptdesc’ np. ‘/var/www/html/redcap/redcap_v5.9.0/Resources/rscriptdesc’
4. Nazwa pliku ze skryptem oraz jego opis muszą być takie same.
5. Plik z opisem składa się z 2 linii:
  1. Nazwa skryptu
  2. Opis skryptu
Zlecanie obliczeń przez QCG-icon (przed następnymi krokami należy zainstalować aplikację QCG-icon)
1. Przygotowanie danych:
  1. Wybierz odpowiedni raport z listy dostępnych raportów.
    Kliknij w link R/JNLP (rysunek poniżej)
  2. Przygotowanie pliku do eksportu:
    Data Export Tool -> Advanced Data Export (Display advanced options).
    Wybrać odpowiednie nagłówki i zatwierdzić (submit), np:
    
    Z zakładki PlGrid wybrać jnlp:
  3. Wybór skryptu z listy:
  4. Uruchomić qcg-run.jnlp (Java Network Launch Protocol)
  5. Ustawianie ścieżki do QCG-icon oraz do folderu z wynikami
  6. Podać token do API projektu
  7. Jeżeli wprowadzone ustawienia są poprawne powinna uruchomić się aplikacja QCG-icon (skrypt wejściowy wraz z danymi są już wybrane). Obsługa: QCG-icon_manual