Answers.Body: <p>This sounds like a job for the <code>CombinatorialDerivation</code> class, which is designed for representing libraries and the relationship between derived designs and the originals.</p>
  <h3>About <code>CombinatorialDerivation</code></h3>
  <p>In SBOL 3, a <code>CombinatorialDerivation</code> takes a <code>Component</code> in its <code>template</code> property to represent the system that you intend to vary:</p>
  <ul>
  <li>Some of the <code>Features</code> of the template <code>Component</code> are designated as the variables of the library via <code>VariableFeature</code> child objects of the <code>CombinatorialDerivation</code>, which point at the variables with their <code>variable</code> property.</li>
  <li>The values that can be filled in for each variable are then designated via the <code>variant*</code> properties of the <code>VariableFeature</code>.</li>
  <li>Finally, the distribution of values is determined by the <code>strategy</code> property of the <code>CombinatorialDerivation</code> and the <code>cardinality</code> properties of each variable.</li>
  </ul>
  <h3>Representing Random Mutagenesis</h3>
  <p>In the case of random mutagenesis, if I'm understanding your design correctly, you would represent it with a <code>CombinatorialDerivation</code> as follows:</p>
  <ul>
  <li>The <code>template</code> is <code>Component</code> of type DNA with the original sequence. Each site designated for mutagenesis can be designated with a <code>SequenceFeature</code>.</li>
  <li>For each of the mutagenesis sites, create a <code>VariableFeature</code> in the <code>CombinatorialDerivation</code> with the corresponding <code>SequenceFeature</code> as its <code>variable</code> and a set of <code>variant</code> values for each of the mutant options set by your primers. The cardinality is probably <code>one</code> (if every site has to be hit by <em>something</em> in your protocol) or <code>zeroOrOne</code> (if sites might or might not be hit).</li>
  <li>The <code>strategy</code> for the <code>CombinatorialDerivation</code> is <code>sample</code>, since only a few of the many possibilities will actually be realized.</li>
  </ul>
  <h3>Representing Samples and Characterized Constructs</h3>
  <p>Now, when you take it to the lab, you can represent your aliquot with an <code>Implementation</code> whose <code>wasDerivedFrom</code> points to the <code>CombinatorialDerivation</code>, representing the fact that you've got a randomly generated library whose contents are not precisely known.</p>
  <p>Finally, once you've got your isolated products represented as <code>Component</code>s, there is a recommended best practice to use <code>wasDerivedFrom</code> links to connect the derived <code>Component</code> and its varied <code>Feature</code>s back to the <code>CombinatorialDerivation</code> and its template. If you make a <code>Collection</code> of your results, the <code>Collection</code> should also link to the <code>CombinatorialDerivation</code>.
  This should then capture the relationship between all of the products, their associated data, and the original mutagenesis design.</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2021-04-02T14:49:57.297Z
Answers.Text: I have some code for doing a similar task that I'm happy to share if that's of interest; it happens to not have yet been posted publicly yet, but I can quickly clean it up a bit and do so if desired.
Answers.UserDisplayName: jakebeal
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2021-04-03T12:39:41.420Z
Answers.Text: No need to rush posting of the code. I'm working toward the framework outlined in my question, but have a lot of other things to do first. I just wanted to make sure I was pointed in the right direction.
Answers.UserDisplayName: David Ross
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2021-04-03T12:50:19.337Z
Answers.Text: I do have one clarifying question/comment: From the "Representing Random Mutagenesis" part of your answer, if we are going to use mutagenic PCR to make the protein variants, then every base in the protein coding sequence would be a potential mutagenesis site. So, I would need to define ~1000 `SequenceFeature`s, one for each base in the protein coding sequence. Is that right? 
  This seems a bit cumbersome, but but not too hard to write code for. Does the idea of a `SequenceFeature` for each base in a protein coding sequence raise any red flags for you though?
Answers.UserDisplayName: David Ross
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2021-04-03T17:18:07.000Z
Answers.Text: @DavidRoss I think I misunderstood your protocol: I thought it was something [like this protocol](https://theolb.readthedocs.io/en/latest/molecular-biology/pcr-mutagenesis.html) for targeted swaps with a random subset of a fixed set of variations.  If you're randomly varying every base in a large region, then making a `SequenceFeature` for every base in the sequence does raise a red flag to me.  I don't think we've worked out a best practice for this case yet, but my thought would be to mark the whole region as one `SequenceFeature` and tag it with a `variant` of all `NNNNN....` bases
Answers.UserDisplayName: jakebeal
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2021-04-03T17:18:54.387Z
Answers.Text: That way, you're saying "replace this region with indeterminate bases" and any variant you find will be an appropriate realization of that specification.
Answers.UserDisplayName: jakebeal
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2021-04-02T11:54:33.340Z
Answers.LastActivityDate: 2021-04-02T11:54:33.340Z
Answers.UserDisplayName: jakebeal
Body: <p>In our lab, we work with synthetic biology components with partially random sequences (similar to work in directed evolution). So, for example, we have a plasmid design with several components, including one protein coding sequence that will be created from a wild-type sequence via mutagenic PCR.</p>
  <p>At the design stage, we don't know the exact DNA sequence for any of the resulting variants of that protein coding sequence. We just know the wild-type sequence and the average number of mutations we'd like to apply.
  How can we represent that design in SBOL (via the <code>Component</code> class)?</p>
  <p>Then, when we implement the design, we end up with a single sample that contains plasmids with 10^5-10^6 (or more) different protein coding sequences. We then measure the complete DNA sequence for every plasmid variant, but I don't want to end up with &gt;10^5 different SBOL definitions to describe the sample.
  How can we best represent that sample in SBOL (via the <code>Implementation</code> class)?</p>
  <p>Finally, we also end up measuring the performance of every plasmid variant, and we identify the specific protein coding sequences for useful and/or interesting variants. We then design and build specific, clonal plasmids with those useful/interesting protein coding sequences.
  Representing those clonal plasmids as SBOL <code>Components</code> seems pretty straight-forward, but is there a good way to capture the relationships with the original random-library plasmid design and the specific implementation of that design that we built and measured?</p>
  
Tags: <sbol><variants><library>
Title: How to represent random sequence elements in SBOL?
ThreadText: # How to represent random sequence elements in SBOL?
  
  (Asked by: username_0 on 2021-03-31)
  
  In our lab, we work with synthetic biology components with partially random sequences (similar to work in directed evolution). So, for example, we have a plasmid design with several components, including one protein coding sequence that will be created from a wild-type sequence via mutagenic PCR.
  
  At the design stage, we don't know the exact DNA sequence for any of the resulting variants of that protein coding sequence. We just know the wild-type sequence and the average number of mutations we'd like to apply.
  How can we represent that design in SBOL (via the `Component` class)?
  
  Then, when we implement the design, we end up with a single sample that contains plasmids with 10^5-10^6 (or more) different protein coding sequences. We then measure the complete DNA sequence for every plasmid variant, but I don't want to end up with >10^5 different SBOL definitions to describe the sample.
  How can we best represent that sample in SBOL (via the `Implementation` class)?
  
  Finally, we also end up measuring the performance of every plasmid variant, and we identify the specific protein coding sequences for useful and/or interesting variants. We then design and build specific, clonal plasmids with those useful/interesting protein coding sequences.
  Representing those clonal plasmids as SBOL `Components` seems pretty straight-forward, but is there a good way to capture the relationships with the original random-library plasmid design and the specific implementation of that design that we built and measured?
  
  **Tags:** sbol, variants, library
  
  
  ---
  
  ## 1 answers
  
  ### Answer by username_1 on 2021-04-02. Score: 3 | Accepted answer
  
  This sounds like a job for the `CombinatorialDerivation` class, which is designed for representing libraries and the relationship between derived designs and the originals.
  
  ### About `CombinatorialDerivation`
  
  In SBOL 3, a `CombinatorialDerivation` takes a `Component` in its `template` property to represent the system that you intend to vary:
  
  * Some of the `Features` of the template `Component` are designated as the variables of the library via `VariableFeature` child objects of the `CombinatorialDerivation`, which point at the variables with their `variable` property.
  * The values that can be filled in for each variable are then designated via the `variant*` properties of the `VariableFeature`.
  * Finally, the distribution of values is determined by the `strategy` property of the `CombinatorialDerivation` and the `cardinality` properties of each variable.
  
  ### Representing Random Mutagenesis
  
  In the case of random mutagenesis, if I'm understanding your design correctly, you would represent it with a `CombinatorialDerivation` as follows:
  
  * The `template` is `Component` of type DNA with the original sequence. Each site designated for mutagenesis can be designated with a `SequenceFeature`.
  * For each of the mutagenesis sites, create a `VariableFeature` in the `CombinatorialDerivation` with the corresponding `SequenceFeature` as its `variable` and a set of `variant` values for each of the mutant options set by your primers. The cardinality is probably `one` (if every site has to be hit by *something* in your protocol) or `zeroOrOne` (if sites might or might not be hit).
  * The `strategy` for the `CombinatorialDerivation` is `sample`, since only a few of the many possibilities will actually be realized.
  
  ### Representing Samples and Characterized Constructs
  
  Now, when you take it to the lab, you can represent your aliquot with an `Implementation` whose `wasDerivedFrom` points to the `CombinatorialDerivation`, representing the fact that you've got a randomly generated library whose contents are not precisely known.
  
  Finally, once you've got your isolated products represented as `Component`s, there is a recommended best practice to use `wasDerivedFrom` links to connect the derived `Component` and its varied `Feature`s back to the `CombinatorialDerivation` and its template. If you make a `Collection` of your results, the `Collection` should also link to the `CombinatorialDerivation`.
  This should then capture the relationship between all of the products, their associated data, and the original mutagenesis design.
  
  > **Comments:**
  > **username_1**: I have some code for doing a similar task that I'm happy to share if that's of interest; it happens to not have yet been posted publicly yet, but I can quickly clean it up a bit and do so if desired.  
  > **username_0**: No need to rush posting of the code. I'm working toward the framework outlined in my question, but have a lot of other things to do first. I just wanted to make sure I was pointed in the right direction.  
  > **username_0**: I do have one clarifying question/comment: From the "Representing Random Mutagenesis" part of your answer, if we are going to use mutagenic PCR to make the protein variants, then every base in the protein coding sequence would be a potential mutagenesis site. So, I would need to define ~1000 `SequenceFeature`s, one for each base in the protein coding sequence. Is that right?  This seems a bit cumbersome, but but not too hard to write code for. Does the idea of a `SequenceFeature` for each base in a protein coding sequence raise any red flags for you though?  
  > **username_1**: @username_0 I think I misunderstood your protocol: I thought it was something [like this protocol](https://theolb.readthedocs.io/en/latest/molecular-biology/pcr-mutagenesis.html) for targeted swaps with a random subset of a fixed set of variations.  If you're randomly varying every base in a large region, then making a `SequenceFeature` for every base in the sequence does raise a red flag to me.  I don't think we've worked out a best practice for this case yet, but my thought would be to mark the whole region as one `SequenceFeature` and tag it with a `variant` of all `NNNNN....` bases  
  > **username_1**: That way, you're saying "replace this region with indeterminate bases" and any variant you find will be an appropriate realization of that specification.  
  
  ---
  
  