Corrections to code example for constructing a CRISPR circuit PDF

[minnatwang]

Some parts of the code example for constructing a CRISPR circuit PDF are unclear or don't cover steps that the user encounters in Eclipse. I'd suggest the instructions be updated as follows:

• Move Figure 1 above the "Modeling CRISPR repression using libSBOLj 2.1.0" section
• Right now copying and pasting directly from the PDF results in the line #s being copied as well, which means the user has to delete all the line numbers one-by-one after pasting the code into Eclipse; change the format of the PDF so this doesn't happen (this is applicable for 21 images of code in the PDF)
• "Creating SBOL Document" section - reformat the last paragraph (explaining each method/statement) as bullet points for readability
• "Creating TopLevel objects" section - reiterate that all code should be pasted within the main method
• As you copy and paste code into Eclipse, you get errors for unhandled exceptions. The instructions should either a) mention that these errors will exist as you paste in code and explain how to fix them (or not to worry about them) or b) add SBOLValidationException and SBOLConversionException to the throws statement in the main method description
• For the SBOL writer try-catch statement, get rid of SMLStreamException and CoreIoException--Eclipse says neither of these are necessary
• Add a link to the examples directory mentioned at the end of page 15

[EDIT 12.19]

• In Table 1 & Table 2 on page 8, somehow indicate the objects that the sample code already took care of (e.g. EYFP_gene_constraint, CRP_b, EYFP_gene minus the sequence, EYFP_cds). Use an asterisk?
• Change GAL4VP16_gene_constraint to Gal4VP16_gene_constraint in Table 2 & Table 3. Make sure the rest of that capitalization is consistent as well.
• Table 3: change "EYFP_Activation" to "EYFP_activation"
• Edit language and text to make it clear that sample code won't work unless code for Tables 1, 2 and 3 are included. Bold it or color it to make it clear.
• On page 9 second-to-last paragraph, add "Remember to use the CRPb circuit module definition" as the last sentence.
• Page 11: edit headline to say "Other Features of libSBOLj"
• Table 3: change "EYFP_BFP_deg" to "EYFP_deg"
• Table 3: change "cas9m_BFP_gRNA_b_BFP_deg" to "cas9m_BFP_gRNA_b_deg"
• Page 12, line 8 of code box, change "Titel" to "Title"

[3ach]

Hi Minna -- the SBOLValidationException gives reference to a specific SBOL validation rule which may help you in diagnosing your problem. Your screenshot does not give the full error code, but it begins sbol-1060. Take a peek at the SBOL specification for more information on that group of errors, and please post the full validation rule identifier so that we can help diagnose the issue.

[cjmyers]

Hi Minna,

The full validation error message is:

Exception in thread "main" org.sbolstandard.core2.SBOLValidationException: sbol-10604: The URI contained by the definition property MUST refer to a ComponentDefinition object. Reference: SBOL Version 2.1.0 Section 7.7.1 on page 26 : http://sbols.org/CRISPR_Example/CRPb_characterization_circuit/1.0 at org.sbolstandard.core2.ModuleDefinition.createFunctionalComponent(ModuleDefinition.java:644) at org.sbolstandard.core2.ModuleDefinition.createFunctionalComponent(ModuleDefinition.java:601) at org.sbolstandard.core2.examples.CopyOfRepressionModel.main(CopyOfRepressionModel.java:201)

If you examine the line of code that is causing, it you find:

    CRPb_circuit.createFunctionalComponent(
            "EYFP",
            AccessType.PRIVATE,
            "EYFP",
            version,
            DirectionType.NONE);

The message is stating essentially that the ComponentDefinition for EYFP cannot be found. On page 8, second paragraph, it says "Other ComponentDefinition objects can be created using the same set of method calls. As an exercise, the reader is encouraged to specify them according to Table 1 and 2.” Perhaps, we should not use the word “encouraged”, since it will not work if you don’t do this step. The tutorial is not meant to give you complete code but representative code. The user is expected to follow the patterns and write their own code. So, perhaps we should change the text to, “As an exercise, the reader should next create the ComponentDefinitions specified in Table 1 and 2."

On Nov 28, 2016, at 7:31 AM, Zach Zundel notifications@github.com wrote:

Hi Minna -- the SBOLValidationException gives reference to a specific SBOL validation rule which may help you in diagnosing your problem. Your screenshot does not give the full error code, but it begins sbol-1060. Take a peek at the SBOL specification http://sbolstandard.org/wp-content/uploads/2016/10/BBF-RFC112-SBOL2.1.0.pdf#page=76 for more information on that group of errors, and please post the full validation rule identifier so that we can help diagnose the issue.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/SynBioDex/libSBOLj/issues/415#issuecomment-263201556, or mute the thread https://github.com/notifications/unsubscribe-auth/ADWD95r5984NXUTVnNosHOUPLxc7x3bsks5rCoNngaJpZM4K9W-D.

[cjmyers]

These are good suggestions. One comment though is I’m not sure we want to make it easy to cut and paste code from the tutorial. Shouldn’t the users be forced to type this themselves? We need to make sure that there is actually some thought going into building it, so the user actually learns how to use the library. I think the action of typing them (plus the additional pieces of code we don’t provide) is crucial to the user’s understanding process.

Minna: after completing the tutorial, do you feel like if you were given a similar diagram and asked to create it using libSBOLj that you could? The goal of the tutorial is to ensure that people doing it would be able to port their knowledge into using the library within their own application.

[minnatwang]

Thanks for the feedback. I'll go through and finish the code based on what's in the tables.

@cjmyers, I would say it still might be good practice to make the text boxes copy-paste friendly. There are some segments, such as the sequences for CRa_U6 promoter and others in the same box, that would be difficult and tedious to type. If we do want to discourage readers from copying and pasting, we could include screenshots rather than text, but I don't recommend it.

In reference to page 8 paragraph 2, I'd suggest we change to the following: "As an exercise, the reader should next create the ComponentDefinitions specified in Table 1 and 2. Please note that the code will not run correctly unless these ComponentDefinitions are created." with the last piece in bold or italicized or a different color--whatever will make it stand out.

If I were given a similar diagram and asked to create it, I think I could do it. This tutorial seems to be fairly comprehensive.

[minnatwang]

@cjmyers, will most circuits being modeled with SBOL be a similar level of complexity and have as many elements as this one? If not, it might be useful to include a tutorial for a smaller, simpler circuit and let the user choose which tutorial to follow in the beginning. It'd be more work, but it could help the user get used to the software and not be overwhelmed. But if this is a fairly basic synthetic biology circuit, or it's doubtful that scientists would feel overwhelmed, it probably wouldn't be worth it.

[cjmyers]

Additional tutorials would be wonderful focusing on different aspects. The current one covers a lot of the classes but not all. Additional smaller ones could target additional aspects, which would be nice. BTW: developers will not build SBOL for designs directly like this. Instead they will build software that, for example provides a GUI for design, such as our SBOLDesigner tool. The software will need to call these methods though to convert the user input into SBOL data objects.

Please try adding the following code at the bottom of your solution to validate and compare your result with an existing solution. Change path to where you put the attached file.

    SBOLValidate.validateSBOL(doc, true, true, true);
    if (SBOLValidate.getNumErrors() > 0) {
        for (String error : SBOLValidate.getErrors()) {
            System.out.println(error);
        }
        return;
    }
    //SBOLWriter.write(doc, "/Users/myers/RepressionModel.rdf");
    SBOLDocument doc2 = SBOLReader.read("/Users/Myers/RepressionModel.rdf");
    SBOLValidate.compareDocuments("Mine", doc, "Solution", doc2);

Note there will be differences in the GenericTopLevel due to a known bug. No other differences should be reported though.

On Dec 7, 2016, at 10:37 PM, Minna Wang notifications@github.com wrote:

@cjmyers https://github.com/cjmyers, will most circuits being modeled with SBOL be a similar level of complexity and have as many elements as this one? If not, it might be useful to include a tutorial for a smaller, simpler circuit and let the user choose which tutorial to follow in the beginning. It'd be more work, but it could help the user get used to the software and not be overwhelmed. But if this is a fairly basic synthetic biology circuit, or it's doubtful that scientists would feel overwhelmed, it probably wouldn't be worth it.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/SynBioDex/libSBOLj/issues/415#issuecomment-265657518, or mute the thread https://github.com/notifications/unsubscribe-auth/ADWD9_rPUmSDF_bz8Mg2DAxAYHtsGvkvks5rF5ejgaJpZM4K9W-D.

[mehersam]

Done.