{"action":"created","comment":{"url":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/comments/91673891","pull_request_review_id":12181965,"id":91673891,"diff_hunk":"@@ -124,66 +124,193 @@ In addition to samples and their data, collections may contain\n Data objects that store analysis results (*e.g.,* differential\n expressions). Samples and Data objects may be in multiple collections.\n \n-**Study** is an *upgraded* collection with some additional metadata.\n-Study relates the provenance or reason samples were generated. Each\n-sample can belong to only one study.\n-\n .. figure:: images/collections_relation.jpg\n    :width: 100 %\n \n-   Relations between samples, collections and studies. Samples\n+   Relations between samples and collections. Samples\n    are groups of Data objects originating from the same biological\n    sample—all Data objects in a sample are derived from a single NGS\n    reads file. Collections are arbitrary groups of samples\n    and Data objects that store analysis results.\n \n-Samples, collections and studies have their own annotations, and\n-the Data objects they contain have separate annotations. An example\n-of the annotation field on a Study is ``organism`` and an example\n-of the annotation field on a Sample is a ``barcode``. The annotation\n-for sample (also collection and study) represents all Data objects\n-attached to it.\n-\n .. TODO: Image where clear distinction between Resolwe models /\n          endpoints and resdk classes is presented.\n \n+Annotations\n+===========\n+\n+Annotations are presented as descriptors, where each descriptor is defined in\n+descriptor schemas. Annotations for data objects, samples and collections are\n+following different descriptor schemas. For example reads data object can be\n+annotated with 'reads' descriptor schema, while sample can be annotated by\n+'sample-geo' annotation schema. Each data object that is part of sample is\n+also connected to sample annotation, so that the annotation for sample (also\n+collection) represents all Data objects attached to it. Examples of descriptors\n+and descriptor schemas are described in details in `Resolwe Bioinformatics\n+documentation`_.\n+\n+.. _Resolwe Bioinformatics documentation: http://resolwe-bio.readthedocs.io\n+\n+Here we show how to annotate reads data object by defining descriptor:\n+\n+.. code-block:: python\n+\n+    annotation_reads = {\n+        'experiment_type': 'RNA-seq',\n+        'protocols': {\n+            'growth_protocol': 'my growth protocol',\n+            'treatment_protocol': 'my treatment protocol',\n+            'library_prep': 'lybrary construction protocol',\n+        },\n+        'reads_info': {\n+            'seq_date': '2016-10-13',\n+            'instrument_type': 'Illumina',\n+            'facility': 'my favorite facility',\n+        }\n+    }\n+\n+We can now annotate ``reads`` data object by adding descriptor and descriptor schema:\n+\n+.. code-block:: python\n+\n+    #define the chosen descriptor schema,\n+    reads.descriptor_schema = 'reads'\n+\n+    #define the reads descriptor, with\n+    reads.descriptor = annotation_reads\n+\n+    #save the annotation\n+    reads.save()\n+\n+We can also define descriptor and descriptor schema directly when calling\n+'res.run' function as described in The run method section.\n+\n+Managing presamples and samples\n+===============================\n+\n+When you upload new data that belongs to the biological sample or run analysis\n+on such data, process automatically create new (pre)sample for created object\n+or add it to the an existing sample. For example if we upload fastq reads file\n+and annotate presample to become sample, aligned bam and bai files will be also\n+part of this same sample.\n+\n+When new sample is created, it is called ``presample``, which means that it is\n+not yet annotated. To annotate it, fill its descriptor and set ``presample``\n+property to ``False``. Following is an example of annotation of presample,\n+that was automatically created when reads were uploaded.\n+\n+.. code-block:: python\n+\n+    annotation_sample = {\n+        'sample': {\n+            'annotator': 'my name',\n+            'organism': 'Homo sapiens',\n+            'source': 'isolated DNA',\n+            'cell_type': 'houman podocytes',\n+            'genotype': 'abcg2-',\n+            'molecule': 'total RNA',\n+            'optional_char': ['my_characteristic:{}'.format('value')],\n+            'description': 'any additional description',\n+            },\n+        'other': 'any other information',\n+    }\n+\n+    # define presample name\n+    reads.presample.name = 'My favorite sample'\n+\n+    #add descriptor schema to sample\n+    reads.presample.descriptor_schema = 'sample'\n+\n+    # define presample description\n+    reads.presample.descriptor = annotation_sample\n+\n+    # transform presample to sample\n+    reads.presample.presample = False\n+\n+    #save presample as sample with the same name\n+    reads.presample.save()\n+\n+.. note::\n+    When presample is marked as annotated, we can access it as ``sample`` property:\n+\n+    .. code-block:: python\n+\n+        reads.sample\n+\n+Additionally, we can also confirm that the sample is annotated, change sample\n+name or slug:\n+\n+.. code-block:: python\n+\n+    #change sample name and slug\n+    reads.sample.name = 'My sample 2'\n+    reads.sample.slug = 'my-sample-2'\n+    reads.sample.save()\n+\n+\n+Managing collections\n+====================\n+\n+To keep a clear structure of data objects and samples we can create collections.\n+Here is an example how to create new collection and add/remove data to/from","path":"docs/intro.rst","position":164,"original_position":164,"commit_id":"d3562d6d8e72c0eefc7e0c85de9bd3c1f1cfde54","original_commit_id":"d3562d6d8e72c0eefc7e0c85de9bd3c1f1cfde54","user":{"login":"jkokosar","id":2889622,"avatar_url":"https://avatars.githubusercontent.com/u/2889622?v=3","gravatar_id":"","url":"https://api.github.com/users/jkokosar","html_url":"https://github.com/jkokosar","followers_url":"https://api.github.com/users/jkokosar/followers","following_url":"https://api.github.com/users/jkokosar/following{/other_user}","gists_url":"https://api.github.com/users/jkokosar/gists{/gist_id}","starred_url":"https://api.github.com/users/jkokosar/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jkokosar/subscriptions","organizations_url":"https://api.github.com/users/jkokosar/orgs","repos_url":"https://api.github.com/users/jkokosar/repos","events_url":"https://api.github.com/users/jkokosar/events{/privacy}","received_events_url":"https://api.github.com/users/jkokosar/received_events","type":"User","site_admin":false},"body":"Here is an example of how to..","created_at":"2016-12-09T08:16:33Z","updated_at":"2016-12-09T08:23:38Z","html_url":"https://github.com/genialis/resolwe-bio-py/pull/64#discussion_r91673891","pull_request_url":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64","_links":{"self":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/comments/91673891"},"html":{"href":"https://github.com/genialis/resolwe-bio-py/pull/64#discussion_r91673891"},"pull_request":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64"}}},"pull_request":{"url":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64","id":96090822,"html_url":"https://github.com/genialis/resolwe-bio-py/pull/64","diff_url":"https://github.com/genialis/resolwe-bio-py/pull/64.diff","patch_url":"https://github.com/genialis/resolwe-bio-py/pull/64.patch","issue_url":"https://api.github.com/repos/genialis/resolwe-bio-py/issues/64","number":64,"state":"open","locked":false,"title":"Update SDK documentation","user":{"login":"JenkoB","id":9283107,"avatar_url":"https://avatars.githubusercontent.com/u/9283107?v=3","gravatar_id":"","url":"https://api.github.com/users/JenkoB","html_url":"https://github.com/JenkoB","followers_url":"https://api.github.com/users/JenkoB/followers","following_url":"https://api.github.com/users/JenkoB/following{/other_user}","gists_url":"https://api.github.com/users/JenkoB/gists{/gist_id}","starred_url":"https://api.github.com/users/JenkoB/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JenkoB/subscriptions","organizations_url":"https://api.github.com/users/JenkoB/orgs","repos_url":"https://api.github.com/users/JenkoB/repos","events_url":"https://api.github.com/users/JenkoB/events{/privacy}","received_events_url":"https://api.github.com/users/JenkoB/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-12-01T13:43:20Z","updated_at":"2016-12-09T08:23:38Z","closed_at":null,"merged_at":null,"merge_commit_sha":"52db72ba1c54f162071407b7fe22f258688f128e","assignee":{"login":"jkokosar","id":2889622,"avatar_url":"https://avatars.githubusercontent.com/u/2889622?v=3","gravatar_id":"","url":"https://api.github.com/users/jkokosar","html_url":"https://github.com/jkokosar","followers_url":"https://api.github.com/users/jkokosar/followers","following_url":"https://api.github.com/users/jkokosar/following{/other_user}","gists_url":"https://api.github.com/users/jkokosar/gists{/gist_id}","starred_url":"https://api.github.com/users/jkokosar/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jkokosar/subscriptions","organizations_url":"https://api.github.com/users/jkokosar/orgs","repos_url":"https://api.github.com/users/jkokosar/repos","events_url":"https://api.github.com/users/jkokosar/events{/privacy}","received_events_url":"https://api.github.com/users/jkokosar/received_events","type":"User","site_admin":false},"assignees":[{"login":"jkokosar","id":2889622,"avatar_url":"https://avatars.githubusercontent.com/u/2889622?v=3","gravatar_id":"","url":"https://api.github.com/users/jkokosar","html_url":"https://github.com/jkokosar","followers_url":"https://api.github.com/users/jkokosar/followers","following_url":"https://api.github.com/users/jkokosar/following{/other_user}","gists_url":"https://api.github.com/users/jkokosar/gists{/gist_id}","starred_url":"https://api.github.com/users/jkokosar/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jkokosar/subscriptions","organizations_url":"https://api.github.com/users/jkokosar/orgs","repos_url":"https://api.github.com/users/jkokosar/repos","events_url":"https://api.github.com/users/jkokosar/events{/privacy}","received_events_url":"https://api.github.com/users/jkokosar/received_events","type":"User","site_admin":false}],"milestone":null,"commits_url":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64/commits","review_comments_url":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64/comments","review_comment_url":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/comments{/number}","comments_url":"https://api.github.com/repos/genialis/resolwe-bio-py/issues/64/comments","statuses_url":"https://api.github.com/repos/genialis/resolwe-bio-py/statuses/d3562d6d8e72c0eefc7e0c85de9bd3c1f1cfde54","head":{"label":"JenkoB:update-SDK-documentation","ref":"update-SDK-documentation","sha":"d3562d6d8e72c0eefc7e0c85de9bd3c1f1cfde54","user":{"login":"JenkoB","id":9283107,"avatar_url":"https://avatars.githubusercontent.com/u/9283107?v=3","gravatar_id":"","url":"https://api.github.com/users/JenkoB","html_url":"https://github.com/JenkoB","followers_url":"https://api.github.com/users/JenkoB/followers","following_url":"https://api.github.com/users/JenkoB/following{/other_user}","gists_url":"https://api.github.com/users/JenkoB/gists{/gist_id}","starred_url":"https://api.github.com/users/JenkoB/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JenkoB/subscriptions","organizations_url":"https://api.github.com/users/JenkoB/orgs","repos_url":"https://api.github.com/users/JenkoB/repos","events_url":"https://api.github.com/users/JenkoB/events{/privacy}","received_events_url":"https://api.github.com/users/JenkoB/received_events","type":"User","site_admin":false},"repo":{"id":72686729,"name":"resolwe-bio-py","full_name":"JenkoB/resolwe-bio-py","owner":{"login":"JenkoB","id":9283107,"avatar_url":"https://avatars.githubusercontent.com/u/9283107?v=3","gravatar_id":"","url":"https://api.github.com/users/JenkoB","html_url":"https://github.com/JenkoB","followers_url":"https://api.github.com/users/JenkoB/followers","following_url":"https://api.github.com/users/JenkoB/following{/other_user}","gists_url":"https://api.github.com/users/JenkoB/gists{/gist_id}","starred_url":"https://api.github.com/users/JenkoB/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JenkoB/subscriptions","organizations_url":"https://api.github.com/users/JenkoB/orgs","repos_url":"https://api.github.com/users/JenkoB/repos","events_url":"https://api.github.com/users/JenkoB/events{/privacy}","received_events_url":"https://api.github.com/users/JenkoB/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/JenkoB/resolwe-bio-py","description":"Resolwe Bioinformatics Python API","fork":true,"url":"https://api.github.com/repos/JenkoB/resolwe-bio-py","forks_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/forks","keys_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/keys{/key_id}","collaborators_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/teams","hooks_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/hooks","issue_events_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/issues/events{/number}","events_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/events","assignees_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/assignees{/user}","branches_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/branches{/branch}","tags_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/tags","blobs_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/git/refs{/sha}","trees_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/git/trees{/sha}","statuses_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/statuses/{sha}","languages_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/languages","stargazers_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/stargazers","contributors_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/contributors","subscribers_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/subscribers","subscription_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/subscription","commits_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/commits{/sha}","git_commits_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/git/commits{/sha}","comments_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/comments{/number}","issue_comment_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/issues/comments{/number}","contents_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/contents/{+path}","compare_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/compare/{base}...{head}","merges_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/merges","archive_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/downloads","issues_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/issues{/number}","pulls_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/pulls{/number}","milestones_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/milestones{/number}","notifications_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/labels{/name}","releases_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/releases{/id}","deployments_url":"https://api.github.com/repos/JenkoB/resolwe-bio-py/deployments","created_at":"2016-11-02T22:26:33Z","updated_at":"2016-11-02T22:26:34Z","pushed_at":"2016-12-02T07:43:57Z","git_url":"git://github.com/JenkoB/resolwe-bio-py.git","ssh_url":"git@github.com:JenkoB/resolwe-bio-py.git","clone_url":"https://github.com/JenkoB/resolwe-bio-py.git","svn_url":"https://github.com/JenkoB/resolwe-bio-py","homepage":null,"size":568,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"genialis:master","ref":"master","sha":"d8c4b53b6aa36d932f36b35bde6d62eca0e7c5eb","user":{"login":"genialis","id":2120224,"avatar_url":"https://avatars.githubusercontent.com/u/2120224?v=3","gravatar_id":"","url":"https://api.github.com/users/genialis","html_url":"https://github.com/genialis","followers_url":"https://api.github.com/users/genialis/followers","following_url":"https://api.github.com/users/genialis/following{/other_user}","gists_url":"https://api.github.com/users/genialis/gists{/gist_id}","starred_url":"https://api.github.com/users/genialis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/genialis/subscriptions","organizations_url":"https://api.github.com/users/genialis/orgs","repos_url":"https://api.github.com/users/genialis/repos","events_url":"https://api.github.com/users/genialis/events{/privacy}","received_events_url":"https://api.github.com/users/genialis/received_events","type":"Organization","site_admin":false},"repo":{"id":53089675,"name":"resolwe-bio-py","full_name":"genialis/resolwe-bio-py","owner":{"login":"genialis","id":2120224,"avatar_url":"https://avatars.githubusercontent.com/u/2120224?v=3","gravatar_id":"","url":"https://api.github.com/users/genialis","html_url":"https://github.com/genialis","followers_url":"https://api.github.com/users/genialis/followers","following_url":"https://api.github.com/users/genialis/following{/other_user}","gists_url":"https://api.github.com/users/genialis/gists{/gist_id}","starred_url":"https://api.github.com/users/genialis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/genialis/subscriptions","organizations_url":"https://api.github.com/users/genialis/orgs","repos_url":"https://api.github.com/users/genialis/repos","events_url":"https://api.github.com/users/genialis/events{/privacy}","received_events_url":"https://api.github.com/users/genialis/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/genialis/resolwe-bio-py","description":"Resolwe Bioinformatics Python API","fork":false,"url":"https://api.github.com/repos/genialis/resolwe-bio-py","forks_url":"https://api.github.com/repos/genialis/resolwe-bio-py/forks","keys_url":"https://api.github.com/repos/genialis/resolwe-bio-py/keys{/key_id}","collaborators_url":"https://api.github.com/repos/genialis/resolwe-bio-py/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/genialis/resolwe-bio-py/teams","hooks_url":"https://api.github.com/repos/genialis/resolwe-bio-py/hooks","issue_events_url":"https://api.github.com/repos/genialis/resolwe-bio-py/issues/events{/number}","events_url":"https://api.github.com/repos/genialis/resolwe-bio-py/events","assignees_url":"https://api.github.com/repos/genialis/resolwe-bio-py/assignees{/user}","branches_url":"https://api.github.com/repos/genialis/resolwe-bio-py/branches{/branch}","tags_url":"https://api.github.com/repos/genialis/resolwe-bio-py/tags","blobs_url":"https://api.github.com/repos/genialis/resolwe-bio-py/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/genialis/resolwe-bio-py/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/genialis/resolwe-bio-py/git/refs{/sha}","trees_url":"https://api.github.com/repos/genialis/resolwe-bio-py/git/trees{/sha}","statuses_url":"https://api.github.com/repos/genialis/resolwe-bio-py/statuses/{sha}","languages_url":"https://api.github.com/repos/genialis/resolwe-bio-py/languages","stargazers_url":"https://api.github.com/repos/genialis/resolwe-bio-py/stargazers","contributors_url":"https://api.github.com/repos/genialis/resolwe-bio-py/contributors","subscribers_url":"https://api.github.com/repos/genialis/resolwe-bio-py/subscribers","subscription_url":"https://api.github.com/repos/genialis/resolwe-bio-py/subscription","commits_url":"https://api.github.com/repos/genialis/resolwe-bio-py/commits{/sha}","git_commits_url":"https://api.github.com/repos/genialis/resolwe-bio-py/git/commits{/sha}","comments_url":"https://api.github.com/repos/genialis/resolwe-bio-py/comments{/number}","issue_comment_url":"https://api.github.com/repos/genialis/resolwe-bio-py/issues/comments{/number}","contents_url":"https://api.github.com/repos/genialis/resolwe-bio-py/contents/{+path}","compare_url":"https://api.github.com/repos/genialis/resolwe-bio-py/compare/{base}...{head}","merges_url":"https://api.github.com/repos/genialis/resolwe-bio-py/merges","archive_url":"https://api.github.com/repos/genialis/resolwe-bio-py/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/genialis/resolwe-bio-py/downloads","issues_url":"https://api.github.com/repos/genialis/resolwe-bio-py/issues{/number}","pulls_url":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls{/number}","milestones_url":"https://api.github.com/repos/genialis/resolwe-bio-py/milestones{/number}","notifications_url":"https://api.github.com/repos/genialis/resolwe-bio-py/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/genialis/resolwe-bio-py/labels{/name}","releases_url":"https://api.github.com/repos/genialis/resolwe-bio-py/releases{/id}","deployments_url":"https://api.github.com/repos/genialis/resolwe-bio-py/deployments","created_at":"2016-03-03T22:42:08Z","updated_at":"2016-10-28T07:11:09Z","pushed_at":"2016-12-02T07:43:58Z","git_url":"git://github.com/genialis/resolwe-bio-py.git","ssh_url":"git@github.com:genialis/resolwe-bio-py.git","clone_url":"https://github.com/genialis/resolwe-bio-py.git","svn_url":"https://github.com/genialis/resolwe-bio-py","homepage":null,"size":687,"stargazers_count":1,"watchers_count":1,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":7,"mirror_url":null,"open_issues_count":7,"forks":7,"open_issues":7,"watchers":1,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64"},"html":{"href":"https://github.com/genialis/resolwe-bio-py/pull/64"},"issue":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/issues/64"},"comments":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/issues/64/comments"},"review_comments":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64/comments"},"review_comment":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/pulls/64/commits"},"statuses":{"href":"https://api.github.com/repos/genialis/resolwe-bio-py/statuses/d3562d6d8e72c0eefc7e0c85de9bd3c1f1cfde54"}}}}
{"actor":{"display_login":"jkokosar"}}