CajalLab

Procedures

The preferred option is that you host Dokuwiki on a NAS running in your lab network. The procedure will vary depending on the server available. The only requirement is that it can host DokuWiki. For practical purposes, this protocol assumes that you are using a Synology server running the latest version of Diskstation Manager (DSM), which automatically hosts Dokuwiki as a third-party application, but this is not required. Note that setting up and routinely using a Synology server running DSM is rather simple. It will also provide the lab with many other capabilities: For example, chat for lab communication (like Slack or Teams), a cloud for file access anywhere (like OneDrive or Google drive), and many other useful utilities are provided. If you don’t have access to a NAS, skip to Host DokuWiki on a hosting website. Several things must be setup on the NAS:

1. Add users. The simplest approach is to create one username for all members of the lab if they should all have equal access rights. We will call this general lab member, “LabUser”. On the DSM, go to Control Panel and select Users. Add LabUser as the common username for all lab members and include a strong password. Note that having a common username is simpler but is less secure; all lab members will have equal access to the server. This username/password should also exist, as a User, on the lab computers that will access the system.
2. Add a Labmember group. On DSM Control Panel, select Groups and add a group called, “Labmember”. Include in this group LabUser or the individual lab member user accounts you defined above. This group will allow you to define common permissions to shared folders defined below.
3. Create one or more data Shared folders for primary processed data. The folders you create will vary depending on your lab needs. These folders can hold files that contain initially processed data that you would like to have readily accessible for analyses or other purposes. In Control Panel, go to SharedFolders and make DATA a shared folder.
4. Include ACL permissions for each of these folders. The simplest option is to give the LabMember group full access. Alternatively, you may give the LabMember group full permissions except Delete.
5. Install other utilities included with your NAS. For example, install Drive, which will allow you to run a cloud, and Chat, which will allow seamless lab communication.
6. Logon to DSM, click on Package Center, and scroll down to the Third Party section. Find DokuWiki and click Install. This will guide you through the process of setting up your Dokuwiki.
7. If you selected this hosting option, jump to Create your DokuWiki.

Contract a hosting website that includes Dokuwiki in its offerings or have your institutional IT host DokuWiki for you on their servers. This is acceptable but may be impractical. If you selected this option, jump to Create your DokuWiki.

This option provides a way to set up the system for evaluation but is only a short-term solution.

1. Before you start this step, make sure to turn off the example wiki by selecting the command prompt window and pressing any key. The example and the Apache server should not be running.
2. The steps provided in this protocol are optimized for PCs running Windows. MAC users should additionally follow the steps described in: https://www.dokuwiki.org/install:macosx and https://www.dokuwiki.org/php_build-in_webserver.
3. Go to https://download.dokuwiki.org/, select the stable version and the option for “Include Web-server”.
4. Unzip the downloaded file to a particular folder on your computer or USB drive (Documents or Desktop). Open the DokuWikiStick folder and click Run. Make sure you are opening the unzipped folder (not the downloaded, unzipped folder). The first time you run this you should allow firewall access if prompted.
5. The DokuWiki installer will appear in your browser (use Chrome preferably).

The previous steps should lead to the DokuWiki installer page open in your browser. Once you complete this and the following steps, the wiki system will look identical to the example provided (see step B) but without metadata.

1. Give your wiki a name in the Wiki Name field (e.g., MyLab, where My is the PI’s surname).
2. Make sure that “enable ACL” is selected.
3. Add yourself as the SuperUser by filling in your details including a password.
4. For security, select the ACL policy to be a Closed wiki. Then press Save.
5. The next page will show a Login; add your username and password to enter your wiki.

1. On the Dokuwiki Start page, select Admin and Extension Manager. You will find that many plugins are installed by default. Install the following plugins if they are not already installed: Add New Page, Bureaucracy, Imgpaste, Smtp, Sqlite, Struct, Templatepagename. Installation is simple, search for the plugin in the Search and Install tab, and once the plugin appears (make sure the plugin name matches exactly), click Install on the right side.
2. Optional. If you are interested in sending emails directly from the wiki, make sure to set up the SMTP configuration. Go to the Admin, click on Configuration Settings, and select SMTP. Setup the server you want to use to relay your emails. If using your institution email, it may be required to contact IT to enable email relay from your server IP. Otherwise use some settings that you know work, such as commonly used Microsoft or Goggle SMTPs.

In our example, we will setup a typical biomedical research lab that works with subjects (mice). However, subjects can be anything you work with, but it should be the highest-level identifiable entity from which other samples (e.g., organs, cells, etc.) are generated. Lower-level samples that originate from identified subjects will share the subject code. It is important to select a logical, simple rule that serves as a unique identifier within your lab. This identifier will be used to label all data related to a subject. The scheme in the example shown below works well, but you are free to select your own code definitions.

• In our example, the subjects (mice) are named using a unique identifier code structure consisting of 2 letters that identify the strain and a consecutive number that increases by an integer for every new subject in the lab. For instance, vg1234 is the 1234th mouse used in the lab and it is a Vgat-Cre strain since vg was defined in the system as Vgat-Cre strain (as described below). If you plan on using more than 325 strains, you should employ 3 letters instead of 2. You are free to choose your own scheme but it must have an ascending unique number. For example, you can simply use the ascending integer without the strain code.
• Filenames are named starting always with the subject’s unique identifier followed by a few parameters that identify the file. This may include a session code, a file number within the session, and a procedure code. For example, vg1234a2.dat refers to file number 2 in session a. The parameter code logic in your files is up to you but must contain the unique identifier.

Schemas are tables inside a database that will contain the metadata that is amenable to a database. Additional metadata can go within the wiki pages. Several basic (essential) schemas are required for our example, but many other schemas can be created depending on your needs. Our example contains the following basic schemas:

1. Animals are the subjects of the lab experiments (mice in our example).
2. Strains are the strains of animals used in the lab.
3. Subgroups are used to group Animals that belong to the same experiment.
4. Procedures define the methods (protocols) performed in the lab.
5. Surgeries define the details of surgical methods performed on animals.
6. Surgrecovery serves to track post-surgery recoveries.
7. Sessions define the details of file recording methods performed on animals.
8. Histology defines the details of histological samples obtained from animals.
9. Chemicals are the chemicals used in the lab.
10. Solutions are combinations of chemicals.
11. Solutionmake are the steps to make solutions.
12. Materials are all the materials used in the lab.
13. Probes are devices created with materials that are used to measure biological variables.
14. Electrodes are a type of probe.
15. Computers are the computers used in the lab for data acquisition.
16. Drives are the external hard drives connected to computers and used for data storage.
17. Equipment are all the equipment used in the lab.
18. Setups are combinations of equipment, computers and drives where data are generated.
19. Vendors are the vendors from where materials, chemicals, equipment, etc. are purchased.
20. Orders track all orders from vendors.
21. IACUC are the lab IACUC protocols.
22. DEA are bottles of DEA-controlled drugs.
23. DEAuse is the use of DEA drugs.
24. Breeders are pairs (or other combinations) of animals used for breeding.
25. Born are the animals born from the breeders.

You can make as many schemas as are required to account for your needs. Anything that is relevant to your experiments that can be listed and defined should be a schema or part of a schema. Here are some cases (not included in the example):

1. Groups is useful to combine subgroups into coherent studies or papers.
2. Cages is useful to define where the animals are housed. This may be required by your institution to maintain a census. It is easy to set up a way to notify your animal facility via email directly from the system once a cage is empty (using the SMTP plugin).
3. Programs is useful to list specialized programs employed for data acquisition in your lab. For example, if you do behavioral experiments, you may use software definitions to run those experiments. A schema would store details about these programs, including code definitions that are useful to run specific analyses. By including these in the wiki database they can be accessed directly by scripts for execution and analyses.
4. Scripts is useful to list and track your programming language scripts (Matlab, Originlab, Python, R, etc.).

The details that need to be added for each basic schema are listed in Table 1. These are the steps to add each schema to the wiki:

1. In the Admin page, click on Struct Schema Editor in the Additional Plugins section.
2. Add the schema name in the schema field and click Save. The schema name, fields, type, and the changes to be made from default are listed in Table 1. In general, you should use contiguous lowercase letters and integers only to name your schemas. Fields can have more complex text but when making your own, keep it simple.
3. Begin filling each schema field (i.e., table column) one by one using the values in Table 1. You will need to click Save to add each field. Note that sort value (10’s) sets the order of the columns in your aggregations but not in the database (this allows insertion of other fields later, if desired, without changing all sort values). The SQLite database incorporates the field columns in the order you add them.
4. Once you are finished adding all the fields and schemas you can try exporting one of them to see its format. Click on the Import/Export tab, select Page, and click Export. If you have Excel installed, or some other CSV program, open the exported CSV file to see the table. Note that the table is an empty sheet with your field headings per column. Once there are values, they will appear in the CSV (use the completed example to see values). Pid refers to the Page ID for Page schemas (fixed name of a page in the wiki). The Page ID is different from the Page Title. The Page Title is the first heading in a page and can be easily changed (if a page has no headings, the Page ID becomes the Page Title). Rid refers to the row ID for Global and Serial schemas. Each row of a Page schema corresponds to a page in the wiki. Serial schemas have multiple rows that are all associated with specific pages in the wiki (multiple different rows can be associated with each page). Global schemas have no association with any page on the wiki.

If the schema is a Page schema, this step is required to associate the schema with a namespace in the wiki; a namespace is a folder within the wiki and has this format, namespace:pageid. Pages allow extensive content (text, images, etc.) to be associated with the values defined in the Page schema (e.g., include details about a protocol with extensive images, video, tables, etc. in the Procedures pages). To associate the Page schemas with their namespaces, follow these steps:

1. In the Admin page, click on Struct Schema Assignments and navigate to the bottom of the page to add the contents listed in each row of Table 2 one at a time.
2. Select and copy the full content of the first cell under Page/Namespace in Table 2. Paste the content into the open field at the bottom of the wiki page (under Page/Namespace column) and change the Schema selection column to the value in the Schema column in Table 2. Check that the values align with the row in Table 2 and press Add.
   • Repeat the previous step for each row in Table 2.
   • At the end, there should be 16 rows indicating 16 associations between schemas and namespaces, as shown in Figure 2 below. The Regular Expressions used in these lines exclude certain pages inside the namespace from being included in the schema.

After the schema assignments have been made, the namespaces and a few pages need to be created inside each namespace. This involves creating the pages and adding the required syntax into them. In this step, we will create the namespaces, the main pages that are used within each namespace to create other pages, and the template pages that are called upon each time a new page is created by a Page schema. Follow these steps for each namespace listed in Table 3:

1. In the Search field located in the top right, search for the namespace:pageid listed in Table 3 (e.g., animals:animals) and press Enter. This will show a message indicating that the page does not exist.
2. Create it by clicking on the red text. When the page appears, click on Edit this page (pencil symbol on the right hand side).
3. Paste the syntax text for this page located in Table 3, and press Save. At this point, you have created your first page in the wiki. Since there is no data in the schema, it will report “Nothing found”. Note that Table 3 is provided also as a .txt file, which makes copying the syntax simpler.
4. For each namespace, Table 3 lists both the main pages and the c_template page. The c_template page provides the syntax to be added to pages created by the assigned schema.
5. Repeat these steps for all rows listed in Table 3. Note that the last row in Table 3 includes the start page.

So far, the Superuser is the only one with access to the wiki. Lab members should be added to a Labmember group following these steps:

1. Go to the Admin page and select User Manager.
2. In the section Add user, fill the fields for each user with their password and include the user in a new Labmember group.
3. Click Add for each addition. If successful, each lab member will appear in the list above.

Set pages that are accessible to the Labmembers group. By default, the Superuser has access to the whole wiki and has the ability to delete. There are 6 levels of permissions for each namespace or page (None, Read, Edit, Create, Upload, Delete).

1. Go to the Admin page and select Access Control List Management. Select Group in Permissions for and type labmembers. This will display the permissions for this group for the namespace or page selected on the left window.
2. On the left window select each namespace starting with Animals. Change Add new Entry to Upload and click Save. Repeat this for the all the existing namespaces except: Wiki. This will allow lab members to upload images and other content to these namespaces. If there is a reason to exclude this access level for any namespace, set it only with permission to Edit or Read.
   • However, existing pages (created above), such as the c_template and main pages (e.g., animals, create, breeders, chemicals, etc.) inside each namespace, should probably not be modifiable by lab members since there is no reason for those not involved in managing the wiki to change any of these existing pages (before new pages are added). To avoid this problem, click on each of the existing pages inside each namespace and set the currently existing pages to Read for the labmembers group. This step is not necessary but will eliminate the possibility that someone inadvertently changes the syntax on one of these essential pages. This step was not done in the example provided.
   • Once the above steps have been performed, the Current ACL Rules for each namespace will be visible in the table at the bottom of the page.

At this point, the wiki is ready for use. There are two ways to start using it. One is to begin using it by manually adding metadata. Alternatively, you can upload your existing old metadata to the schemas. If you select the latter option, it is best to look at the format of the schema tables by exporting the schemas from the example provided with this protocol. This will show the format necessary to upload your metadata in the correct format. For example, the date field must follow the wiki format, which is set by default to yyyy-mm-dd (as per Excel date nomenclature). So be sure to adjust your dates in the CSV prior to import or it will not work (yyyy-mm-dd hh:mm for Date/Time fields). When exporting or importing into schemas, it is important to specify if your schemas are Page or Serial schemas. The following are Serial schemas: born, deause, electrodes, orders, sessions, solutionmake, surgeries, surgrecovery. All the others are Page schemas. To export the schemas from the example provided follow these steps:

1. Go to Admin page and select Struct Schema Editor, at the bottom.
2. Select a schema by clicking on it on the right-side list. For example, click on Animals.
3. Select the Import/Export tab.
4. Navigate down to the section Export raw data to CSV file. Since Animals is a Page schema, select page and press Export. If Excel is installed and Chrome includes an extension to “enable local file links”, the schema table will be opened in Excel. Note the format for each field. Pages are referred by their namespace:pageid. Dates will be displayed in Excel default format but should be uploaded as indicated above.
5. If you decide to upload your existing metadata, it is best to begin uploading the schemas that do not depend on other schemas, and then incorporate the other schemas. For example, Vendors, Strains, Subgroups, IACUC, etc. should be imported before Animals, since Animals includes the other schemas.