Team:Bielefeld-CeBiTec/Notebook/LabnotesGenerator

Labnotes Generator
To reduce the time and energy spend on writing your notebook, we developed the labnotes generator (LNG). This dedicated python script parses multiple text files and generates HTML code ready to use for the final wiki page.
The tool takes data from all provided files and sorts them by given date. Afterwards, a HTML file with the correct HTML classes is created. To include the desired style the user can provide a customized CSS file, which recognizes and styles the given classes. To add images, you have to write the HTML code into the procedure section. The provided java script file is necessary to expand and collapse the singe boxes. If provided, the tool will also recognize special keywords and connects these with a link. This is especially useful to refer to standard protocols. The python script, the JavaScript file and a CSS file are freely available to the whole iGEM community. You can download a zip file containing the script, templates and example data here. Please acknowledge iGEM team Bielefeld-CeBiTec 2017 when using this tool and feel free to tell your friends about it.

We say thank you to the teams TU-Darmstadt and Cologne-Duesseldorf for testing the beta versions of our gift for the iGEM community!

Preparation

To run the script, you have to install python on your device. The next step is to create the input files. These have to look like this:
>YYYY-MM-DD
Team
Experiment (Aim/superior experimental context)
Investigators
Title (Title or main task of the experiment)
Procedure
Alternative date formats are DD.MM.YYYY and MM/DD/YYYY. The “Team” information can be used to show the dependency of this experiment to a certain sub team working on your project. The “Experiment” line shows the superior experimental context, since usually multiple experiments are connected. The “Investigators” line sets the names of all involved investigators, where it is also possible to write just the initials and replace them later automatically. The “Title” sets the title of this experiment and is the only information visible in the collapsed format.
The “Procedure” part consists of multiple lines starting right after the “Title” line. You can write just text or add also a minus at the beginning of each line to add bullet points. Multiple minuses for building up a hierarchy are possible, too. Be sure to save these files with a coding in “UTF-8”, otherwise you cannot display characters like “µ” in “µl”.
Next to the main input you can provide optional dictionaries for automatic replacement of short names with full names of the investigators and recognize keywords and create a link to your protocols. A dictionary text file is structured like this:
{"key1" : "substitution1",
"key2" : "substitution2",
"key3" : "substitution3"}
You can find more information in case of problems in the README file which comes with the other files in the ZIP file. You can find it also here in the wiki.

Usage

To run the script, open a console and navigate via the command line into the desired folder. Then call the script. If you are not familiar with command line tools, look in the internet how to open and use a console on your operating system. The basic call of the script is
python labnotes_creator.py <input file/folder>
The input can whether be a single file or a folder. In case of a folder all files within this folder must be a text file containing labnotes. To import the dictionaries for name replacement and linking keywords to uploaded protocols use the parameters
-names <names dict> -protocols <protocols dict>
These parameters and all following ones are optional and do not have to be added to the call of the script, if not needed. The order of the parameters is not important. For preview purpose or easier copying into the wiki it is often very useful to add some HTML code before and after the generated HTML code. You can achieve this by specifying a top and a bottom HTML file with the parameters
-top <html top insert>
-bottom <html bottom insert>
Next to the HTML output you get also a JavaScript file for expanding and collapsing the notes. A default CSS is also created and linked to final HTML file. To suppress the generation of these files, use the parameters
-nojs -nocss
Both parameters do not require additional attributes. They are especially useful, if you already added the function to your own JavaScript file or use another styling sheet. In the latter case, you have to keep the four class names. Anything else is up to you and should not affect the functionality. The last parameter is
-out <output folder/path>
which can be used to specify an output folder. Without using this parameter, all generated files are saved in the actual working directory.

README

Use the *_example.txt files to test the script and its output.
Use the *_template.txt files to create your own files.

labnotes file:
Following date formats are accepted:
YYYY-MM-DD
DD.MM.YYYY
MM/DD/YYYY

You can use "-" at the beginning of each line in the procedure to create bullet points. Use multiple minuses in a row to create lower levels of the list.
After each entry you have to place an empty line.
Using HTML code for formating, like "<i>italic text</i>" is possible.
The order of the entries does not matter. Entries are sorted automatically by the date.
If you do not want to show an information, you can write "?" or "???" into this line. You cannot hide the procedure, date or the experiment title.

names-dict:
Use the initials as key and the full names as values for the dictionary format. New entries are seperated by commas. The last entry is not followed by a comma. The file has to be saved with the ANSI coding, otherwise it cannot be imported into python as a dictionary!

protocols-dict:
Same rules for this dictionary as for the names-dict. The template contains in the value also a placeholder for a link. The keywords can consist of multiple words. All letters MUST be written in lower case! Otherwise it wont work.

command line input:
example call:
-python labnotes_generator.py labnotes_example.txt -names names_dict_example.txt -protocols protocols_example.txt -out output
-> creates HTML, JS and CSS files in new folder "output"
simle use:
python labnotes_generator.py <input file/folder>
-> in case of refer to a folder ALL files within this folder have to be labnote files!
single parameters:
-names <txt file> specifies file containing names directory
-protocols <txt file> specifies file containing protocol directory
-top <HTML file> specifies HTML file to which the new generated content is appended to
-bottom <HTML file> specifies HTML file which is appended to the generated content
-out <name of output folder> specify existing or not existing folder/path to which all generated content is saved to
-nocss suppress generating a CSS file
-nojs suppress generating a JS file
-h or -help get info to all commands
Troubleshooting:
Some characters are not displayed, why?
-> Be sure to use the coding "UTF-8" for you labnotes.txt. To do this click on "save as" and choose the correct coding.

The first entry is not generated?
-> Sometimes it seems, like a wrong coding adds additional characters to the begining of the file, which are not visible. Add some empty lines before the first entry and it should be recognized in the next run.

The information of procedure, inveestigators and more in a single entry is messed up, why?
-> Check your entry in the labnotes.txt, you probably forgot one line. Remember: Even if you do not want to show one information, do not leave this line out! Use "?" or "???" instead!

Changelog

2017-10-23
Release of the first puclic version