LIMS*Nucleus characterizes two types of users, regular users and administrators. LIMS*Nucleus users are unique to LIMS*Nucleus and not shared with the operating system nor database. Administrative functionality is listed in the table below.

This page discusses the guidelines for writing an Artanis application such as LIMS*Nucleus that is suitable for Guix packaging. If you are looking for modifications needed in the Artanis source code, look here.

Write a Guix packageable Artanis application

First read the discussion on modifications required to the Artanis source code so you are aware that all temporary files created by your application must be moved to a directory outside the application directory. In addition, Artanis’ cache must be move outside the application directory, as well as artanis.conf so it remains editable. These activities can be handled with a post installation initialization file.

One time initialization

Because your artanis app needs some directories outside of the application directory to work with temporary files, configuration files etc., a one time initialization script can be run to set up your server. The overall process would look like:

1. guix package -i limsn
2. init-limsn.sh
3. install-pg-aws.sh
4. start-limsn.sh

The initialization file would create required directories and copy over the artanis.conf file. Note that the placeholder PATH_INTO_STORE is replaced on installation by the path into the store.

1
2
3
4
5
6
7
8
9
10

#! /bin/bash
export LC_ALL="C"
echo export LC_ALL=\"C\" >> $HOME/.bashrc
echo export GUIX_PROFILE=$HOME/.guix-profile >> $HOME/.bashrc
echo . $HOME/.guix-profile/etc/profile >> $HOME/.bashrc
echo export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale >> $HOME/.bashrc

sudo mkdir -p $HOME/.config/limsn
sudo cp PATH_INTO_STORE/share/guile/site/3.0/limsn/conf/artanis.conf $HOME/.config/limsn

artanis.conf

Because a configuration file outside the project directory is being used, you can use a startup script to launch your application:

1
2
3
4
5
6

#!/bin/bash
!#
export LC_ALL="C"
mkdir -p /var/tmp/limsn/tmp/cache
cd PATH_INTO_STORE/share/guile/site/3.0/limsn
art work -h0.0.0.0  --config=$HOME/.config/limsn/artanis.conf

In this example -h0.0.0.0 is needed for running on Amazon Web Services

GNUPLOT

With regular Artanis Gnuplot can be run on the server and generate *.png files in the ../pub directory that are accessible to the .html.tpl file via:

1

<image src= <%= myplot %>>

Where in the above snippet the variable myplot == “../pub/myplot.png”. With guix modified Artanis, the .png file would have to go into /tmp/limsn and would become inaccessible due to security restrictions. To get around this, load the myplot variable with svg commands. This is accomplished by first creating the gnuplot script with the following commands:

1
2
3
4
5
6

reset session
set terminal svg size 800,500
save '-' 
set key box ins vert right top
set grid
...etc.

The ‘save’-’’ statement will save to standard output so that you can pipe into your variable. Here is a helper function that will collect the svg commands:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

(use-modules (ice-9 regex) ;;list-matches
             (ice-9 textual-ports)
             (ice-9 rdelim)  ;;read-line
             (ice-9 popen))

(define (get-svg-content gnuplot-script-file)
  ;;requires:   set terminal svg size 600,400
  ;;            save '-'
  ;;in the script
  ;;gnuplot-script-file is the script as a text variable
  (let* ((port (open-input-pipe (string-append "gnuplot " gnuplot-script-file)))
	 (a "")	 
	 (dummy (let loop ((line (read-line port)))
		  (if (not (eof-object? line))
		      (begin
			(set! a (string-append a line))
			(loop (read-line port))))))	 	 
	 (dummy (close-pipe port))
	 (dummy (pretty-print a))
	 (coord-start (string-match "<svg  width=" a ))
	 (coord-end (string-match "</g></svg>" a)))
    (xsubstring a (match:start coord-start) (match:end coord-end))
  ))

Then in your controller:

1
2

(let* ((myplot-svg (get-svg-content gnuplot-script-file))
       etc....

And in the web page template:

1

<%= myplot-svg %>

Now in the above snippet myplot-svg == ’<svg width=“600” height=“350” viewBox=“0 0 600 350” xmlns=“http://www.w3.org/2000/svg” xmlns:xlink=“http://www…etc….”

Application specific variables

Application specific variables are defined in ENTRY such as:

1
2
3

...
(conf-set! 'maxnumplates 100)
...

Since ENTRY is in the store, this will only work for variables that are not available to the end user for (re)setting. To provide editable application specific variables, put them in artanis.conf. Variables are grouped in artanis.conf. LIMS*Nucleus specific variable ‘maxnumplates’ is placed in the ‘cookie’ group for convenience, even though it is not a cookie.

1

cookie.maxnumplates = 100

artanis/config.scm must be patched appropriately:

1
2
3
4
5
6
7
8

(substitute* "artanis/config.scm"		
		       ((" \\(else \\(error parse-namespace-cache \"Config: Invalid item\" item\\)\\)\\)\\)")
			"(else (error parse-namespace-cache \"Config: Invalid item\" item))))\n\n(define (parse-namespace-cookie item)\n  (match item\n    (('expire expire) (conf-set! '(cookie expire) (->integer expire)))\n    (('maxplates maxplates) (conf-set! '(cookie maxplates) (->integer maxplates)))\n    (else (error parse-namespace-cookie \"Config: Invalid item\" item))))"))

	   (substitute* "artanis/config.scm"
	   	       (("debug.monitor = <PATHs>\")")
	   		"debug.monitor = <PATHs>\")\n ((cookie expire)\n       3600\n      \"Cookie expiration time in seconds.\n       1 hour is 3600\n       6 hours 21600\n       1 month 2592000\n cookie.expire = <integer>\")\n\n ((cookie maxplates)\n       10\n      \"Maximum number of plates per plate-set.\n cookie.maxplates = <integer>\")"))

Modify controller syntax

Controllers as they are written will generate a warning:

guix package: warning: failed to load ‘(limsn app controllers plates)’: no code for module (lims app controllers plates) /home/mbc/.guix-profile/share/guile/site/3.0/myapp/app/controllers/pages.scm:4:0: warning: module name (app controllers plates) does not match file name ‘limsn/app/controllers/plates.scm’ hint: File `/home/mbc/.guix-profile/share/guile/site/3.0/limsn/app/controllers/plates.scm’ should probably start with: (define-module (limsn app controllers plates))

Guix expects the first statement in a module to begin with (define-module ()….)
Artanis wants modules to (use-modules (artanis mvc controller))
Satisfy both requirements with:

1
2
3
4
5
6
7
8
9
10
11
12
13

(define-module (limsn app controllers plates)
  #:use-module (artanis artanis)
  #:use-module (artanis mvc controller)) ;;to eliminate error

;;error: define-artanis-controller: unbound variable
;;hint: Did you forget `(use-modules (artanis mvc controller))'?

(define-artanis-controller pages) ; DO NOT REMOVE THIS LINE!!!
;;libraries must be imported after define-artanis-controller
(use-modules (myapp lib mylib) )

(pages-define plates
	      (lambda (rc)......etc.

Be sure to import libraries after (define-artanis-controller )

Make Libraries accessible

Artanis provides the …./lib directory to hold libraries. This directory is placed on the GUILE_LOAD_PATH for you. To avoid warnings, you may wish to write your library as a module e.g. (define-module (limsn lib mylib)…) in which case you need to place your project directory on GUILE_LOAD_PATH with a statment in ENTRY such as:

(add-to-load-path (string-append (find-ENTRY-path identity #t) “/..”))

Another option is to create a separate package for your library, package separately, and make it available as an input.

Prerequisites

• AWS username/password
• EC2 key pair
• (Static IP address) A transient IP is adequate and will be used in the video tutorial. Consider a static IP for production. A static IP address is free upon request, but must be used on a running instance. You will be charged for a static IP that is requested but not used.
• Credit card number - a valid credit card is required to register. Note that these are Amazon requirements.

Installation

Note: the video tutorial of AWS EC2 installation of LIMS*Nucleus describes installation of an older version of LIMS*Nucleus. Though still useful to watch as the overall process and many details are the same, details discussed below supercede what is in the video. The main changes are different names for scripts are being used, LIMS*Nucleus is now packaged as a guix module and so is installed in the store, and because a guix pull must be performed the free tier t2.micro may not provide enough memory. Use t2.medium.

Local: download the archive of install scripts and transfer to AWS with scp:

1

home@HP8300:~$scp -i labsolns.pem $HOME/temp/limsn-ec2.tar.xz  admin@ec2-18-191-151-165.us-east-2.compute.amazonaws.com:.

You must modify the above command with your own keys and the connection address provided to you by Amazon.

AWS: decompress and run the install script:

1
2

admin@ip-172-31-23-11:~$tar -xvf ./limsn-ec2.tar.xz
admin@ip-172-31-23-11:~$./install-limsn-ec2.sh

install-limsn-ec2.sh and guix-install-mod.sh must be in the same directory. Multiple files described below are loaded into the store at PATH_INTO_STORE/limsn/scripts

Supplied Scripts

Scripts available on this website or in /gnu/store are described on the scripts page.

Useful commands

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

## start the database server
admin@ip-172-31-25-179:~$ pg_ctl -D /home/admin/lndata -l logfile start
 
## start the application in detached mode
admin@ip-172-31-25-179:~$ nohup ~/start-limsn.sh

## find the application PID
admin@ip-172-31-25-179:~$ps aux | grep art
 admin     1219  1.3  5.5 153504 56172 ?        Sl   12:25   0:00 /gnu/store/18hp7flyb3yid3yp49i6qcdq0sbi5l1n-guile-3.0.2/bin/guile \ /gnu/store/imh84i7rcckxd55nndhrnr0j7jr64ffv-artanis-0.5.1/bin/.art-real work -h 0.0.0.0

## kill the application
admin@ip-172-31-25-179:~$kill -9 1219


## delete the database
admin@ip-172-31-25-179:~$ rm -r lndata


## reinstall the database
admin@ip-172-31-25-179:~$ ./install-pg-aws.sh

LIMS*Nucleus defines a hierarchy of 5 entities.

A project contains plate sets, each of which contains plates etc. Projects can only be created by an administrator. Plate Sets can be created by users. Other entities are created automatically as needed. Plates, wells, samples are created at the time of plate set creation.
Plates and wells are created automatically during rearraying operations.

LIMS*Nucleus example database contains plate sets, plates, hit list, assay runs and data. The various projects are at different stages of completion to demonstrate the functionality of the application.

### Files for import

Provide your own import files or use the supplied data below:

Statistics for example assay data files

Error message upon launching the server: ?

1
2
3

sudo mkdir /sys/fs/cgroup/systemd
sudo mount -t cgroup -o none,name=systemd cgroup /sys/fs/cgroup/systemd

Error message when loading a page from AWS:

View the channels video for details on how to set up a Guix channel.

• Installation

labsolns can be installed as a Guix channel. To do so, add it to ~/.config/guix/channels.scm:

1
2
3
4
5
6
7
8
9
10
11

(cons* (channel
        (name 'labsolns)
        (url "https://github.com/mbcladwell/labsolns")
        (branch "master")
        ;; Enable signature verification:
        (introduction
         (make-channel-introduction
          "74b2041a467ce3e35fd989f2d66a08e5697f980b"
          (openpgp-fingerprint
           "E709 94D1 9CB0 FE2B CAC4  9E54 0BF8 F292 4D2B 1944"))))
       %default-channels)

Then run guix pull.

If you receive error messages like “…commit nnnn is not a descendant of nnnnn …” use

guix pull –allow-downgrades.

Hit identification can be accomplished using one of three different methods:

1. Select an algorithm during data import

Select an algorithm from the drop down during data import. Hits will be identified and the Hit List name and description text fields will be enabled so you can register the hit list.

2. In the scatterplot/replot view, view and generate a hit list

When plotting or replotting, the tool icon provides the option to view a hit list. The hit list view provides the option to register and save the hit list.

3. Export data and use external data analysis to identify hits. Import the hit list.

Post data import, annotated data can be exported for visualization using other software. A hit list can be compiled external to LIMS*Nucleus and then imported.

Scroll down to the hit list and import under the tools icon:

A Guix pack installation is a simple installation suitable for users not interested in the Guix package manager. The detailed instructions below follow the same process automated by the install script found on the evaluate page, but provides additional diagnostic information.

The first step in the install script is setting up the database. Manually install the database using instructions on the postgres page.

If you are using the install script and it is not executable, change permissions:

1

chmod 777 install-limsn-pack.sh

Download and unzip the archive

1
2

wget https://github.com/limsn/labsolns/releases/download/v0.1.0p/limsn-0.1.0-pack.tar.gz
tar xf ./limsn-0.1.0-pack.tar.gz

Look at the contents of the bin directory

1
2
3
4
5
6
7

$ls ./bin
art         dropuser  guile-config           initdb                 oid2name           pg_controldata  pg_receivewal   pg_standby       pg_waldump  reindexdb
clusterdb   ecpg      guile-snarf            install-pg-aws-ec2.sh  pg_archivecleanup  pg_ctl          pg_recvlogical  pg_test_fsync    pgbench     start-limsn.sh
createdb    gnuplot   guile-tools            install-pg-aws-rds.sh  pg_basebackup      pg_dump         pg_resetwal     pg_test_timing   postgres    vacuumdb
createuser  guild     init-limsn-channel.sh  lnpg.sh                pg_checksums       pg_dumpall      pg_restore      pg_upgrade       postmaster  vacuumlo
dropdb      guile     init-limsn-pack.sh     load-pg.sh             pg_config          pg_isready      pg_rewind       pg_verifybackup  psql

Various *limsn*.sh scripts are needed to configure and start up LIMS*Nucleus. You can also use psql to diagnose the database.

Place $HOME/bin on $PATH

1
2
3

$export PATH="$HOME/bin${PATH:+:}$PATH"
$echo $PATH
/home/admin/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games

Note that in the above example I am using the admin account on AWS so $HOME == /home/admin

Initialize LIMS*Nucleus

Initialize by executing ./bin/init-limsn-pack.sh. The function of the various scripts is described on the scripts page. Check that the $HOME/.config/limsn directory has been created and artanis.conf has been copied into the directory:

1
2

$ ls $HOME/.config/limsn
artanis.conf

Check that $HOME/.bashrc has been modified to include exports for LC_ALL, PATH, GUILE_LOAD_PATH, and GUILE_DBD_PATH.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

...
$cat $HOME/.bashrc
/# sources /etc/bash.bashrc).
if ! shopt -oq posix; then
  if [ -f /usr/share/bash-completion/bash_completion ]; then
    . /usr/share/bash-completion/bash_completion
  elif [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
  fi
fi
export LC_ALL="C"
export PATH=/home/admin/bin:/gnu/store/2rl49lcanmqn26s660dd85lv7pfn0ykb-limsn-0.1.0/bin:/home/admin/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games
export GUILE_LOAD_PATH=/home/admin/gnu/store/rj0pzbki1m5hpcshs614mhkrgs2b3i9d-artanis-0.5.2/share/guile/site/3.0:/home/admin/gnu/store/780bll8lp0xvj7rnazb2qdnrnb329lbw-guile-json-3.5.0/share/guile/site/3.0:/home/admin/gnu/store/jmn100gjcpqbfpxrhrna6gzab8hxkc86-guile-redis-2.1.1/share/guile/site/3.0:/home/admin/gnu/store/3f0lv3m4vlzqc86750025arbskfrq05p-guile-dbi-2.1.8/share/guile/site/2.2
export GUILE_DBD_PATH=/home/admin/gnu/store/z5kilafxayw2kdvn3anw1shkqij17dqb-guile-dbd-postgresql-2.1.8/lib

source .bashrc to make certain that all environment variables have been properly set:

1

$source $HOME/.bashrc

Modify the artanis.conf configuration file

Critical parameters are described on the configuration page. You must have in hand IP addresses for the database and client.

1

sudo nano $HOME/.config/limsn/artanis.conf

Make sure the database is available and loaded

The psql command below will work on a local database - modify accordingly. You should find 10 preloaded projects. Projects 4-9 are empty and can be used for experimentation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

$psql -U ln_admin -h 127.0.0.1 lndb
psql (13.4, server 11.14 (Debian 11.14-0+deb10u1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

lndb==>select * from project;

id | project_sys_name |                  descr                   |     project_name     | sessions_id |            updated            
----+------------------+------------------------------------------+----------------------+-------------+-------------------------------
  1 | PRJ-1            | 3 plate sets with 2 96 well plates each  | With AR, HL          | 9999999999  | 2022-04-06 11:07:05.854606+00
  2 | PRJ-2            | 1 plate set with 2 384 well plates each  | With AR              | 9999999999  | 2022-04-06 11:07:06.825439+00
  3 | PRJ-3            | 1 plate set with 1 1536 well plate       | With AR              | 9999999999  | 2022-04-06 11:07:08.32809+00
  4 | PRJ-4            | description 4                            | MyTestProj4          | 9999999999  | 2022-04-06 11:07:13.364018+00
  5 | PRJ-5            | description 5                            | MyTestProj5          | 9999999999  | 2022-04-06 11:07:13.365426+00
  6 | PRJ-6            | description 6                            | MyTestProj6          | 9999999999  | 2022-04-06 11:07:13.367082+00
  7 | PRJ-7            | description 7                            | MyTestProj7          | 9999999999  | 2022-04-06 11:07:13.368542+00
  8 | PRJ-8            | description 8                            | MyTestProj8          | 9999999999  | 2022-04-06 11:07:13.370008+00
  9 | PRJ-9            | description 9                            | MyTestProj9          | 9999999999  | 2022-04-06 11:07:13.371613+00
 10 | PRJ-10           | 2 plate sets with 10 96 well plates each | Plates only, no data | 9999999999  | 2022-04-06 11:07:13.372956+00
(10 rows)

lndb=> 

Start LIMS*Nucleus

Start in detached mode so you can close the terminal. To kill the process you will need to look up the PID and kill. Start in regular mode to monitor any error messages.

1

$nohup start-limsn.sh &

to kill Ctrl-C in interactive mode or in detached mode:

1
2
3
4
5

$ ps aux | grep artanis
admin    12479  2.9  6.0 154628 60944 pts/0    Sl   13:22   0:00 /gnu/store/cnfsv9ywaacyafkqdqsv2ry8f01yr7a9-guile-3.0.7/bin/guile \ /gnu/store/dfa7p2zvk4xlhaq1y3hsqkzpqd73ggni-artanis-0.5.2/bin/.art-real work -h0.0.0.0 --config=/home/admin/.config/limsn/artanis.conf
admin    12494  0.0  0.0   3084   880 pts/0    S+   13:22   0:00 grep artanis

$ kill -15 12479

View a schematic of the LIMS*Nucleus architecture here. If you have experience with PostgreSQL, you may wish to install the LIMS*Nucleus database independent of the client utilizing resources you already control e.g. an AWS instance of Postgres or Postgres running in your internal datacenter. This archive provides the necessary scripts for database installation/configuration. LIMS*Nucleus is agnostic with respect to the location of the database - all that is needed is a valid connection string. Once the database has been configured, the artanis configuration file must be modified.

Scripts included are:

Once the database is up and running, install the client.

Postgres Install script

The postgres install script can be used to install a data directory under the current user, \(HOME/lndata, or to modify the database installed by <code>sudo apt-get install postgres</code> in the default data directory at /etc/postgresql/\)PGMAJOR/main

User directory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

#!/bin/sh

mkdir lndata

echo "export PGDATA=\"$HOME/lndata\"" >> $HOME/.bashrc
export PGDATA="$HOME/lndata"
export LC_ALL="C"

sudo mkdir -p /var/run/postgresql
sudo chown -R admin:admin /var/run/postgresql
initdb -D $HOME/lndata
    
sed -i 's/\#listen_addresses =/listen_addresses =/'  $HOME/lndata/postgresql.conf

pg_ctl -D $HOME/lndata -l logfile start
 
 psql -U postgres -h 127.0.0.1 postgres -a -f initdba.sql
 psql -U ln_admin -h 127.0.0.1 postgres -a -f initdbb.sql
 psql -U ln_admin -h 127.0.0.1 -d lndb -a -f initdbc.sql
 psql -U ln_admin -h 127.0.0.1 -d lndb -a -f create-db.sql
 psql -U ln_admin -h 127.0.0.1 -d lndb -a -f example-data.sql

Take ownership with sudo chown -R admin:admin /var/run/postgresql where admin:admin is the user id

Default postgres directory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

PGMAJOR=$(eval "ls /etc/postgresql")
PGHBACONF="/etc/postgresql/$PGMAJOR/main/pg_hba.conf"
sudo sed -i 's/host[ ]*all[ ]*all[ ]*127.0.0.1\/32[ ]*md5/host    all        all             127.0.0.1\/32        trust/' $PGHBACONF

PGCONF="/etc/postgresql/$PGMAJOR/main/postgresql.conf"
sudo sed -i 's/\#listen_addresses =/listen_addresses =/' $PGCONF
	
eval "sudo pg_ctlcluster $PGMAJOR main restart"

 psql -U postgres -h 127.0.0.1 postgres -a -f initdba.sql
 psql -U ln_admin -h 127.0.0.1 postgres -a -f initdbb.sql
 psql -U ln_admin -h 127.0.0.1 -d lndb -a -f initdbc.sql
 psql -U ln_admin -h 127.0.0.1 -d lndb -a -f create-db.sql
 psql -U ln_admin -h 127.0.0.1 -d lndb -a -f example-data.sql