Terminologia

Geny sa reprezentowane przez klasę Gene.

W próbkach (klasa Sample) przechowywane są wartości ekspresji dla poszczególnych genów.

Wiele próbek, pogrupowanych według wspólnej cechy, zapisywanych jest w klasie SampleCollection.

Wspólną cechą może być to, że wszystkie próbki pochodzą z tkanki nowotworowej, albo że wszystkie pochodzą od roślin poddanych stresowi solnemu (lub ekspozycji na silne nasłonecznienie). Inną cechą wspólną może być to, że wszystkie próbki pochodzą od pacjentów zdrowych (czy osobników "wild-type", jeśli badamy inne organizmy).

"Kolekcja próbek" najcześciej reprezentuje pewien "fenotyp".

Kolekcja gromadząca próbki ze źródła (od osobników, z tkanek) o badanej cesze (czyli tej, która nas interesuje) odpowiada fenotypowi badanemu (w kodzie i anglojęzycznej części dokumentacji: case)

Przeciwieństwem fenotypu badanego jest fenotyp kontrolny (control). Próbkami fenotypu kontrolnego mogą być wspomniane wcześniej wyniki pacjentów zdrowych / osobników "wild-type".

Pod hasłem eksperyment rozumiemy zbiór: fenotypu badanego, fenotypu kontrolnego oraz metody, która posłuży do odnalezienia/analizy szlaków o znacząco zmienionym poziomie ekspresji. Eksperyment jest reprezentowany przez klasę Experiment, a poszczególne metody dziedziczą z klasy Method.

O programie

Struktura repozytorium

Wewnątrz głównego katalogu (pathways-analysis) znajdziesz następujące programy:
patapy.py i run_tests.sh.

Za interfejs wiersza poleceń (rezultat patapy.py) odpowiada kod z command_line/main.py.
Testy znajdują się w katalogu tests, w plikach z prefixem test_ (pozostałe pliki definiują funkcje pomocnicze).
Dokumentacja znajduje się w katalogu docs, w plikach z rozszerzeniem .rst.
Poszczególne metody są implementowane w modułach pakietu methods.

Struktura programu (pipeline)

Opcje podane przez użytkownika są wstępnie przetwarzane przez parser argumentów (część pakietu command_line), a następnie tworzone są instancje klas: Gene, Sample, Phenotype i Experiment. Obiekt typu Experiment (jako, że zawiera wszystkie dane dostarczone przez użytkownika) jest później przekazywany do Method.run(experiment) wybranej metody.

Jak zacząć?

Zakładamy że masz już konto na GitHubie. Jeśli nie, możesz założyć je za darmo na stronie github.com.
Dodatkowo powinnaś / powinienneś mieć zainstalowane programy git oraz Python3.6 oraz znać podstawy systemu git i programowania w języku Python.

1) Stwórz prywatną kopię naszego projektu:

  • po chwili zostanie dla Ciebie utworzona kopia repozytorium, której możesz użyć do dalszej pracy; możesz ją znaleźć pod adresem: github.com/{twój_nickname}/pathways-analysis

2) Pobierz repozytorium na swój komputer i skonfiguruj zgodnie z instrukcją:

git clone https://github.com/{twój_nickname}/pathways-analysis
cd pathways-analysis
git remote add upstream https://github.com/kn-bibs/pathways-analysis

3) Uruchom program

Aby zainstalować wymagane zależności (inne programy które są nam niezbędne) uruchom:

python3.6 -m pip install -r requirements.txt

Jeżeli znajdując się w katalogu pathways-analysis, po wykonaniu komendy:

./patapy.py -h

zobaczysz instrukcję osbługi programu, to wszystko jest w porządku.
Jeśli nie, to warto zapytać na slacku, pokazując dokładnie co wydarzyło się po wpisaniu powyższej komendy.

3) Dodaj swój kod / test / popraw literówkę / uzupełnij dokumentację

Jeśli nie wiesz do czego się zabrać, zapytaj na slacku. Jeśli dodajesz nowy kod, postaraj się, aby spełniał standardy czystego kodu oraz posiadał stosowną dokumentację. Nowa funkcjonalność powinna być odpowiednio przetestowana, a nowe testy powinny znaleźć się w folderze tests.

Za dużo na raz? Nie panikuj! Zmiany możesz wprowadzać etapami, swój kod konsultować z innymi członkami koła na slacku lub na naszych spotkaniach. Zawsze znajdzie się ktoś kto Ci pomoże.

4) Uruchom testy

Nawet jeżeli Twoje zmiany wydają się być trywialne, pamiętaj aby uruchomić testy:

./run_tests.sh

Jeżeli ostatnia linia świeci na zielono (wszystkie test przebiegły pomyślnie), wszystko jest w porządku. W przeciwnym razie przeczytaj dokładnie wiadomości podawane przez program testujący - pomogą Ci one zlokalizować źródło problemu. W razie jakichkolwiek wątpliwości - zapytaj innych - może ktoś już wcześniej napotkał na dany problem.

5) Zapisz swoje zmiany i wyślij na serwer

Teraz możesz wprowadzić dowolne zmiany, dodać je za pomocą komendy git add lub git commit oraz wysłać na serwer GitHub'a korzystając z git push (po potwierdzeniu Twoimi danymi logowania). Podstawy pracy z programem git opisane są we wprowadzeniu programistycznym: Git(Hub).

Pamiętaj, że w razie jakichkolwiek problemów możesz śmiało zadawać pytania na naszym slacku. Mamy nawet specjalny kanał na pytania o gita: #git_pytania: nawet najstarszym wyjadaczom git potrafi czasem sprawiać problemy.

6) Pull Request

Po wysłaniu zmian na serwer przyszła pora na wysłanie prośby o włączenie Twoich modyfikacji do głownego repozytorium (czyli Pull Request'a). Możesz to zrobić przez stronę github.com/kn-bibs/pathways-analysis - jeżeli jesteś zalogowana / zalogowany, prawdopodobnie automatycznie wyświtli Ci się sugestia wysłania PR. Jeśli takiej sugestii nie widzisz, spróbój postępować zgodnie z oficjalną instrukcją: help.github.com/articles/creating-a-pull-request-from-a-fork.

7) Code review

Twój kod zostanie automatycznie sprawdzony pod kątem poprawności, stylu i złożoności. Automatycznie zostaną też uruchomione testy. Jeśli wszystko pójdzie dobrze, ktoś z większym doświadczeniem (lub równym, jeśli nie ma nikogo o dłuższym stażu) postara się wskazać jak uczynić Twój kod lepszym. Jeśli zostaniesz poproszona / poproszony o zmiany, wystarczy że skomittujesz nowe zmiany (git commit) oraz wyślesz je na serwer (git push) - zostaną one automatycznie dodane do Twojego Pull Request'a.

8) Aktualizacja Twojej kopii (Twojego forka)

Co jakiś czas zajdzie potrzeba pobrania zmian wprowadzony przez innych w głównym repozytorium. Służy do tego polecenie:

git pull upstream master

Czysty kod

Każdy może mieć własne preferencje co do tego jak powinien wyglądać idealny kod; aby jednak nie wchodzić w dysputy nad wyższością jednego z rozwiązań nad drugim przy większych projektach stosuje się określone standardy.

W świecie języka Python standarem zalecanym przez twórców jest tzw PEP8, który rozwiązuje większość konfliktów (czy należy używać spacji czy tabulacji? Czy pomiędzy definicjami funkcji powinien znaleźć się odstęp?), a niemal każdy z wyborów znajduje poparcie w wieloletnim doświadczeniu programistów, którzy kształtowali ten standard.

Przykładowo, PEP8 nakazuje zawsze stosować indentacje za pomocą czterech spacji, dwie linie odstępu pomiędzy definicjami funkcji oraz wskazuje że w operacjach przypisania (poza definicjami argumentów domyślnych) elementy po obu stronach znaku równości powinny być oddzielone pojedynczą spacją.

Na naszym slacku mamy kanał #czysty_kod, na którym możesz poczytać nasze zapytać o to jak przepisać dany kod, aby był zgodny z PEP8 i innymi dobrymi praktykami. Można tam śmiało wrzucać każdy fragment swojego kodu.

Zobacz więcej:

Dokumentacja

Dokumanie kodu

Dokumentacja klas i funkcji polega na dodawaniu tzw. "docstringów", czyli napisów których celem jest dokumentowanie kodu. Całkiem logiczne, nie? Przykładowo wygląda to tak:

def sum(a, b):
    """Sums a and b."""
    return a + b

W naszym projekcie posługujemy się konwencją Google, która określa jak powinien wyglądać przejrzysty docstring, aby możliwe było wykorzystanie programu do automatycznej generacji stron z dokumentacją kodu (Sphinx).

Bardziej rozbudowany docstring może zawierać opis argumentów oraz zwracanych wartości.

def launch_rocket(destination, payload):
    """Launch a rocket with given payload to specified destination.

    Args:
        destination: A tuple(Planet, City).
            The City has to exist on the given Planet.

        payload:
            All the staff you want to transport to the destination.
            Please remember, that weight limits apply.

    Returns:
        An identificaton number of the newly started filght.
    """
    weight = measure_weight(payload)
    rocket = order_from_warehose(cabaple_of_carying=weight)
    # note: regsitration office will verify the destination
    flight = register_flight(rocket, destination)
    flight.start()
    return flight.id

Zobacz więcej:

Zaawansowane wskazówki:

  • Aby zrobić przykład z kodem na kilka linii potrzeba użyć Example:: (podwójny dwukropek jest niezbędny aby uzyskać ładne podświetlanie składni).
  • Zwięzła lista znaczników, które można wykorzystać wewnątrz docstringów: rst-cheatsheet.

Kompilowanie dokumentacji

Znajdując się w katalogu pathways-analysis, przejdź do katalogu docs po czym użyj polecenia make html.

cd docs
make html

Jeśli wyskoczą jakieś błędy, spróbuj powtórzyć make html.

Gotową dokumentację możesz otworzyć w dowolnej przeglądarce; znajduje się ona w podkatalogu pathways-analysis/docs/_build/html/. Przykładowo, możesz teraz wejść na stronę główną poprzez Firefox'a:

firefox _build/html/index.html &

lub Chrome:

google-chrome _build/html/index.html &

results matching ""

    No results matching ""