Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Update the analysis docs #173

Closed
wants to merge 4 commits into from
Closed

docs: Update the analysis docs #173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
66c9add
docs: Update the analysis docs
Jan 7, 2022
9453781
docs: Update the metadata command docs
Jan 7, 2022
a7ae6d3
docs: Update the permission command docs
Jan 7, 2022
30fdab4
docs: Update the repositories command docs
Jan 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions docs/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,12 @@
* [1. Introduction](README.md)
* [2. Installation & Usage](chapters/installation_and_use.md)
* [3. Analysis](chapters/analysis.md)
* [List available analysis types](chapters/analysis.md#list-available-analysis-types)
* [Retrieve the schema of an analysis type](chapters/analysis.md#retrieve-the-schema-of-an-analysis-type)
* [Create a new analysis](chapters/analysis.md#create-a-new-analysis)
* [Create an analysis](chapters/analysis.md#create-an-analysis)
* [Delete an analysis](chapters/analysis.md#delete-an-analysis)
* [Publish an analysis](chapters/analysis.md#publish-an-analysis)
* [Get analysis drafts](chapters/analysis.md#get-analysis-drafts)
* [Get drafts analyses](chapters/analysis.md#get-analysis-drafts)
* [Get published analyses](chapters/analysis.md#get-published-analyses)
* [Retrieve the schema of an analysis type](chapters/analysis.md#retrieve-the-schema-of-an-analysis-type)
* [List available analysis types](chapters/analysis.md#list-available-analysis-types)
* [5. Metadata](chapters/metadata.md)
* [Retrieve analysis metadata](chapters/metadata.md#retrieve-analysis-metadata)
* [Update an analysis](chapters/metadata.md#update-an-analysis)
Expand Down
274 changes: 135 additions & 139 deletions docs/chapters/analysis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Analysis

The `analysis` command group allows the user to interact with their analyses through the terminal. The supported commands are the following:
The `analysis` command group allows users to interact with their analyses through the terminal. The supported commands are the following:

```
**[terminal]
Expand All @@ -17,68 +17,25 @@ Commands:
delete Delete your analysis.
get List your draft analysis.
get-published List your published analysis.
publish Publish analysis with given pid.
publish Publish analysis with given PID.
schema Get JSON schema for analysis metadata.
types List all types of analysis you can create.
```

### Create an analysis
#### Description

#### List available analysis types
- Allows the user to create a new analysis.
- To create a new analysis, the user needs to pass metadata in a JSON format (either from a file or directly from the terminal).
- The user needs to know the structure of the analysis, use the `analysis schema <your-analysis-type>` command to check for valid metadata.
- The supported options are the following:

**Description:**

Using this command the user can take a quick look at which analysis types are available to them, in order to use it for the creation of a new analysis.

**Usage:**

```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis types]
[
"alice-analysis",
"atlas-analysis".
...
]
```


#### Retrieve the schema of an analysis type

**Description:**

Allows the user retrieve the JSON schema of a specified analysis type.

**Usage:**

```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis schema <ANALYSIS-TYPE>]
{
"$schema": "http://json-schema.org/draft-04/schema#",
"additionalProperties": true,
"dependencies": {
"analysis_reuse_mode": {
"properties": {
...
}
```

**Options:**

| Name | Type | Desc |
| :-------------- | :----- | :---------------------------------------------------------------------- |
| ANALYSIS_TYPE | TEXT | Type of analysis [required] |
| --version | TEXT | Version of the schema |
| --for-published | FLAG | Show schema for published analysis (may be different than draft schema) |


#### Create a new analysis

**Description:**

Allows the user to create a new analysis.

**Usage:**
| Name | Type | Desc |
| :--------------- | :------- | :---------------------------------------------------------------- |
| --json / -j | TEXT | JSON data from command line. (mutually exclusive with --jsonfile) |
| --jsonfile / -f | FILENAME | JSON file. (mutually exclusive with --json) |
| --type / -t | TEXT | Type of analysis |
#### Usage

```
**[terminal]
Expand All @@ -91,68 +48,45 @@ Allows the user to create a new analysis.
}
```

**Extended Description:**

In order to create a new analysis, the user needs to pass metadata in a JSON format (either from a file or directly from the terminal). The user needs to know the structure of the analysis, in order to provide valid metadata (use `analysis schema <your-analysis-type>` command to check).

**Options:**

| Name | Type | Desc |
| :---------- | :------- | :---------------------------------------------------------------- |
| --json | TEXT | JSON data from command line. (mutually exclusive with --jsonfile) |
| --jsonfile | FILENAME | JSON file. (mutually exclusive with --json) |
| --type / -t | TEXT | Type of analysis |

### Delete an analysis
#### Description

#### Delete an analysis

**Description:**

Allows the user to delete an analysis draft.

**Usage:**

```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis delete --pid <analysis-pid>]
Analysis has been deleted
```

**Options:**
- Allows the user to delete an analysis draft.
- Note that the published analysis cannot be deleted.
- The supported options are the following:

| Name | Type | Desc |
| :---------- | :------- | :---------------------------------------------------- |
| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] |


#### Publish an analysis

**Description:**

Allows the user to publish an analysis (removing it from the drafts), and get the new PID of the published analysis.

**Usage:**
#### Usage

```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis publish --pid <analysis-pid>]
Your analysis has been published with PID: CAP.XXX.ABCD.ABCD
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis delete --pid <analysis-pid>]
Analysis has been deleted
```

**Options:**

| Name | Type | Desc |
| :---------- | :------- | :---------------------------------------------------- |
| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) [required] |


#### Get analysis drafts

**Description:**

Allows the user to retrieve one or more analysis drafts, that they have access to.

**Usage:**
### Get drafts analyses
#### Description

- Allows retrieving one or more drafts analyses accessible to the user.
- The user can use the `get` command for three cases:
- Retrieve all the draft analyses they have created.
- Retrieve a single draft analysis by its PID.
- Retrieve the draft analyses available to them (both created by them and given access to them by other users).
- The supported options are the following:

| Name | Type | Desc |
| :----------- | :------- | :--------------------------------------------------------------------- |
| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) |
| --all | FLAG | Show all (not only yours) |
| --query / -q | TEXT | A free text query (e.g `test` or `basic_info.analysis_title:test`) |
| ----search / -s | TEXT | Search through facets (e.g. `type=my-analysis`) |
| --type / -t | TEXT | Type of analysis |
| --sort | TEXT | The available values are "bestmatch", "mostrecent" [default=mostrecent]|
| --page | INT | Shows results on the specified page. [default=1] |
| --size | INT | Number of results on a page. [default=10] |
#### Usage

```
**[terminal]
Expand Down Expand Up @@ -197,31 +131,65 @@ Allows the user to retrieve one or more analysis drafts, that they have access t
]
```

**Extended Description:**

There are 3 separate situations, that the user may need to use the `get` command for:

1. Retrieve all the draft analysis they have created.
2. Retrieve a single draft analysis by its PID.
3. Retrieve the draft analyses available to them (both created by them and given access to them by other users).

The two additional arguments presented above, are used for cases 2 and 3.

**Options:**
```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis get -q basic_info.analysis_title:test]
[
{
"created": "2022-01-05T08:57:08.661809+00:00",
"metadata": {
"basic_info": {
"analysis_title": "Test"
},
"general_title": "Test Alice"
},
"pid": "3ec3b81e4f3643ce91e4396891dbcb03",
"updated": "2022-01-05T08:57:22.734703+00:00"
}
]
```

| Name | Type | Desc |
| :---------- | :------- | :---------------------------------------- |
| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) |
| --all | FLAG | Show all (not only yours) |
```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis get -s type=alice-analysis]
[
{
"created": "2022-01-05T08:57:08.661809+00:00",
"metadata": {
"basic_info": {
"analysis_title": "Test"
},
"general_title": "Test Alice"
},
"pid": "3ec3b81e4f3643ce91e4396891dbcb03",
"updated": "2022-01-05T08:57:22.734703+00:00"
}
]
```

### Get published analyses

#### Get published analyses
#### Description

**Description:**
- Allows retrieving one or more published analyses accessible to the user.
- The user can use the `get-published` command for three cases
- Retrieve all the published analyses they have created.
- Retrieve a single published analysis by its PID.
- Retrieve the published analyses available to them (both created by them and given access to them by other users).
- The supported options are the following:

Allows the user to retrieve one or more published analyses, that they have access to.
| Name | Type | Desc |
| :----------- | :------- | :--------------------------------------------------------------------- |
| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) |
| --all | FLAG | Show all (not only yours) |
| --query / -q | TEXT | A free text query (e.g `test` or `basic_info.analysis_title:test`) |
| ----search / -s | TEXT | Search through facets (e.g. `type=my-analysis`) |
| --type / -t | TEXT | Type of analysis |
| --sort | TEXT | The available values are "bestmatch", "mostrecent" [default=mostrecent]|
| --page | INT | Shows results on the specified page. [default=1] |
| --size | INT | Number of results on a page. [default=10] |

**Usage:**
#### Usage

```
**[terminal]
Expand Down Expand Up @@ -270,20 +238,48 @@ Allows the user to retrieve one or more published analyses, that they have acces
]
```

**Extended Description:**
### Retrieve the schema of an analysis type

#### Description

There are 3 separate situations, that the user may need to use the `get-published` command for:
- Allows the user to retrieve the JSON schema of a specified analysis type.
- The supported options are the following:

1. Retrieve all the published analysis they have created.
2. Retrieve a single published analysis by its PID.
3. Retrieve the published analyses available to them (both created by them and given access to them by other users).
| Name | Type | Desc |
| :-------------- | :----- | :---------------------------------------------------------------------- |
| ANALYSIS_TYPE | TEXT | Type of analysis [required] |
| --version | TEXT | Version of the schema |
| --for-published | FLAG | Show schema for published analysis (may be different from draft schema) |

The two additional arguments presented above, are used for cases 2 and 3.
#### Usage

**Options:**
```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis schema <ANALYSIS-TYPE>]
{
"$schema": "http://json-schema.org/draft-04/schema#",
"additionalProperties": true,
"dependencies": {
"analysis_reuse_mode": {
"properties": {
...
}
```

### List available analysis types

#### Description

- The user can take a quick look at which analysis types are available to create a new analysis.

| Name | Type | Desc |
| :---------- | :------- | :---------------------------------------- |
| --pid / -p | TEXT | Your analysis PID (Persistent Identifier) |
| --all | FLAG | Show all (not only yours) |
#### Usage

```
**[terminal]
**[prompt user@pc]**[path ~]**[delimiter $ ]**[command cap-client analysis types]
[
"alice-analysis",
"atlas-analysis".
...
]
```
Loading