<commit_before>
= [.ebi-color]#How to curate a sample in BioSamples#
:last-update-label!:

== User requirements
I want to improve the quality of metadata for a sample in BioSamples but I'm not the
owner of the sample

== Requirements
- You need an AAP account to proceed with this recipe
- Your AAP account should be able to submit to the domain you're going to use in the curation object

==  Steps

=== 1. Get the JSON Web Token from AAP
Start by getting your JWT to use in your application

You can do that in curl for example using the next command
```
TOKEN=$(curl --user <app-user>:<aap-password> https://api.aai.ebi.ac.uk/auth)
```

=== 2. Produce a BioSamples curation object in JSON format

In order to update a field in a sample without being the sample owner
you need to create a BIoSamples curation object and populate the
`attributesPre` field with the value you want to change and
the `attributesPost` field with the value you want to insert

Let's start with a sample like this one (note that for simplicity
we just reduced the number of attributes):
```
{
  "name": "OAR_USU_Benz2616_LNG",
  "accession": "SAMN08432304",
  "domain": "self.BiosampleImportNCBI",
  "release": "2018-01-29T00:00:00Z",
  "update": "2018-06-08T16:22:08.220Z",
  "characteristics": {
    "breed": [
      {
        "text": "Rambouillet"
      }
    ],
    "development stage": [
      {
        "text": "adult",
      }
    ]
    ...
  }
}
```

Let's say for example we want add an ontology code to an attribute that doesn't have it, like
the `development stage`.
Here's the attribute how it looks like before our curation:

```
{
    "type": "development stage",
    "value": "adult"
}
```
Here's the attribute how we want it to be:
```
{
    "type": "development stage",
    "value": "adult",
    "iri": "iri": [
      "http://www.ebi.ac.uk/efo/EFO_0001272"
    ]
}
```

In order to apply this curation to sample `SAMN08432304`,
we must create a curation object like this one
```
{
    "sample": "SAMN08432304",
    "curation": {
      "attributesPre": [
        {
          "type": "development stage",
          "value": "adult"
        }
      ],
      "attributesPost": [
        {
          "type": "development stage",
          "value": "adult",
          "iri": [
            "http://www.ebi.ac.uk/efo/EFO_0001272"
          ]
        }
      ],
      "externalReferencesPre": [ ],
      "externalReferencesPost": [ ],
    },
    "domain": "self.MyPersonalDomain"
}
```
We are now ready to submit the curation object to BioSamples

=== 3. Submit the curation object using a POST request to the

You can now submit a POST request to BioSamples, using whatever service/app you like.
Here we are going to submit our curation object using cURL

```
$ curl 'https://www.ebi.ac.uk/biosamples/samples/{sample-accession}/curationlinks' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer $TOKEN' -d '{
"sample": "SAMN08432304",
"curation": {
  "attributesPre": [
    {
      "type": "development stage",
      "value": "adult"
    }
  ],
  "attributesPost": [
    {
      "type": "development stage",
      "value": "adult",
      "iri": [
        "http://www.ebi.ac.uk/efo/EFO_0001272"
      ]
    }
  ],
  "externalReferencesPre": [ ],
  "externalReferencesPost": [ ],
},
"domain": "self.MyPersonalDomain"
'
```

== Templates
=== Attribute and external reference curation template
```
{
  "sample" : <accession-of-the-interested-sample>,
  "curation" : {<commit_msg>Integrates Jun suggested updates<commit_after>
= [.ebi-color]#How to curate a sample in BioSamples#
:last-update-label!:

== User requirements
I want to improve the quality of metadata for a sample in BioSamples but I'm not the
owner of the sample

== Requirements
- You need an AAP account to proceed with this recipe
- Your AAP account should be able to submit to the domain you're going to use in the curation object

==  Steps

=== 1. Get the JSON Web Token from AAP

Start by getting your AAP JWT to use in your application.

You can do that in curl for example using the next command
```
TOKEN=$(curl --user <app-user>:<aap-password> https://api.aai.ebi.ac.uk/auth)
```

For more details on AAP, check out https://aai.ebi.ac.uk[their website]

=== 2. Produce a BioSamples curation object in JSON format

In order to update a field in a sample without being the sample owner
you need to create a BIoSamples curation object and populate the
`attributesPre` field with the value you want to change and
the `attributesPost` field with the value you want to insert

Let's start with a sample like this one (note that for simplicity
we just reduced the number of attributes):
```
{
  "name": "OAR_USU_Benz2616_LNG",
  "accession": "SAMN08432304",
  "domain": "self.BiosampleImportNCBI",
  "release": "2018-01-29T00:00:00Z",
  "update": "2018-06-08T16:22:08.220Z",
  "characteristics": {
    "breed": [
      {
        "text": "Rambouillet"
      }
    ],
    "development stage": [
      {
        "text": "adult",
      }
    ]
    ...
  }
}
```

Let's say for example we want add an ontology code to an attribute that doesn't have it, like
the `development stage`.
Here's the attribute how it looks like before our curation:

```
{
    "type": "development stage",
    "value": "adult"
}
```
Here's the attribute how we want it to be:
```
{
    "type": "development stage",
    "value": "adult",
    "iri": "iri": [
      "http://www.ebi.ac.uk/efo/EFO_0001272"
    ]
}
```

In order to apply this curation to sample `SAMN08432304`,
we must create a curation object like this one
```
{
    "sample": "SAMN08432304",
    "curation": {
      "attributesPre": [
        {
          "type": "development stage",
          "value": "adult"
        }
      ],
      "attributesPost": [
        {
          "type": "development stage",
          "value": "adult",
          "iri": [
            "http://www.ebi.ac.uk/efo/EFO_0001272"
          ]
        }
      ],
      "externalReferencesPre": [ ],
      "externalReferencesPost": [ ],
    },
    "domain": "self.MyPersonalDomain"
}
```
We are now ready to submit the curation object to BioSamples

=== 3. Submit the curation object to BioSamples using a POST request

You can now submit a POST request to BioSamples, using whatever service/app you like.
Here we are going to submit our curation object using cURL

```
$ curl 'https://www.ebi.ac.uk/biosamples/samples/SAMN08432304/curationlinks' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer $TOKEN' -d '{
"sample": "SAMN08432304",
"curation": {
  "attributesPre": [
    {
      "type": "development stage",
      "value": "adult"
    }
  ],
  "attributesPost": [
    {
      "type": "development stage",
      "value": "adult",
      "iri": [
        "http://www.ebi.ac.uk/efo/EFO_0001272"
      ]
    }
  ],
  "externalReferencesPre": [ ],
  "externalReferencesPost": [ ],
},
"domain": "self.MyPersonalDomain"
'
```

== Templates
=== Attribute and external reference curation template
```
{
  "sample" : <accession-of-the-interested-sample>,
  "curation" : {
{'fraction_non_alphanumeric': 0.13258808546766662, 'fraction_numerical': 0.02688552426772322, 'mean_word_length': 2.9596638655462186, 'pattern_counts': {'":': 80, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 5, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3523047', 'n_tokens_mistral': 2481, 'n_tokens_neox': 2244, 'n_words': 755}