The Medusa Manual

Table of Contents

Next:   [Contents]

The Medusa Manual

This document describes Medusa. In addition to this manual, you may find useful information on Toolkit’s home page.

Copyright © 2014-2019 Okayama University, Last modified: 2021-07-25 10:05 by tkk </Users/tkk/xtreeml/doc/medusa.texi>


Next: , Previous: , Up: Top   [Contents]

1 Tutorial

1.1 Browse demo site by PC

On demo site https://dream.misasa.okayama-u.ac.jp/demo (username=admin, password=admin), please do anything crazy. No worry since original datasets will be restored every morning. If you access to the demo site on dairy maintenance period, you may see error message. Access again after a while.

First operation besides record browsing is to create a record. Click ‘stone’ tab and scroll till the end of table. Type name ‘My great sample’ and click ‘enter’ icon. Then click the new ‘My great sample’. You see sub-tabs on your right. By click of sub-tab ‘file’, you can upload corresponding image file. To edit a record, click “edit” or “system-gear” icon. This allows to update most of properties.

Soon you will find the operation to be hustle although to keep track samples, those steps are minimum already. In other word, even with minimum steps, people in lab complain and refuse extra tasks. It is them who want to keep to track samples. Now is the time to download our Android App.

1.2 Work in lab with Android

By Android App ‘Browser’, download our Android App ‘Sisyphus for Android’ from https://dream.misasa.okayama-u.ac.jp/documentation/Archives/client-Android.apk medusa-figures/code_App. You have to trust us on installation.

The App is already configured for the demo site. Push ‘New stone’ button, type any name, then push ‘enter’ icon. Check if the stone was created on web browser on PC.

Next try to create a record with photo. Push ‘New stone’ button, type any name, then push ‘clip’ icon followed by ‘add snap shot’. Creation of a record with photo is easy.

To be practical, you want to create a record in a certain box. Let’s assume you are sitting in front of ‘Clean bench 1270’. First set current working box. Push ‘reload’ icon on the top, then scan label for ‘Clean bench 1270medusa-figures/code_CleanBench1270.

With this configuration, any new records will be created in ‘Clean bench 1270’.

The most frequent operation is to update location of stone. You wan to locate ‘RA-QD02-0116’ in ‘Clean bench 1270’. Let’s assume you have the stone ‘RA-QD02-0116’ in your hand with label. Push ‘Scan barcode’ button and scan the code for ‘RA-QD02-0116medusa-figures/code_RA-QD02-0116. To update location is that easy.

When you move the stone to ‘Yachi's Office’, change current working box first. Push ‘reload’ icon then scan ‘Yachi's Officemedusa-figures/code_YachisOffice. Push ‘Scan barcode’ button then scan ‘RA-QD02-0116medusa-figures/code_RA-QD02-0116 for re-location.

If you decide to divide ‘RA-QD02-0116’ and create daughter, change current working box first. Push ‘reload’ icon then scan ‘RA-QD02-0116medusa-figures/code_RA-QD02-0116. With this configuration, any new records are ‘RA-QD02-0116’’s daughter.

1.3 Printer setup

With label option enable on ‘Configuration’ tab, the App tries to print label on record creation. First, setup PC paired with label printer following instruction ‘Label printer and barcode reader’, then set label-printer URL on ‘Configuration’ tab. The URL will look like https://192.168.11.103:8889. As of March 22, 2015, we only support label printer by King Jim.

1.4 Next step

As of March 22 (2015), several labs show interest but no one besides us really is using Medusa. The datasets managed by Medusa are important and should be maintained seriously. Even success on installation of Medusa by yourself, support to modify Medusa to fit your circumstance, setup client hardware/software, and build backup system. We are looking for the first lab besides us to utilize Medusa. Contact us when necessary.


Next: , Previous: , Up: Top   [Contents]

2 Changelog

2018-06-12

Add QR code to download Sisyphus without typing.

2018-02-20

Release Medusa 9.4 with visualization of location. Search not only name and ID but also classification. Support absolute age as well as relative age. See Update a stone. Link between minerals in a mount can be sticky using flag fixed in box. See Make a box. Add documentation for setting up the public server. Implement a button to change public flag of records that are link to a bib.

2017-03-31

Medusa 9.3 is released. Medusa keeps track of weight history. Medusa has an interface to sub-divide a stone. Medusa can tell total weight in a box. A stone record is with flags that can tell if a stone is discarded or lost. A stone record is shown with status icon. Tenant hierarchy is shown by dynamic tree. Items to be shown is list can be customized.

2016-06-12

The manual is converted to Texinfo format. Operation and backup guides are merged to this manual.

2016-03-31

Medusa 9.2 is released. Medusa can keep track of how stones are boxes are moved. Support information of relative age. Support tables in bib record to emulate table in a paper. Support registration at SESAR from Medusa. Support any additional properties. Support two authorization including Google and Shibboleth.

2015-07-14

Add instruction to open port for CentOS by Damian Ulbricht.

2015-07-02

Medusa 9.1 was released to fit on Helmholtz Centre Potsdam.

2014-03-31

Medusa 9.0 was released with assistant by Probizmo.

2013-03-31

The manual is converted to LaTeX format.

2012-03-31

The first manual was written.


Next: , Previous: , Up: Top   [Contents]

3 Requirements

Medusa is developed based on an open-source web-application-framework ‘Ruby on Rails’ (6.1). Core code of Medusa is written in ‘Ruby’ (2.7). Some codes are sensitive to version of related software.

To run Medusa, ‘Ruby on Rails’, a web server ‘Apache’, and a database system ‘PostgreSQL’ need to be installed. Although Medusa runs on any platform as long as related components are installed, we recommend to run on Linux (CentOS 7) as of January, 2020.


Next: , Previous: , Up: Top   [Contents]

4 Setup


Next: , Up: Setup   [Contents]

4.1 Install

  1. Install required packages.
    $ sudo yum -y install wget # `tmpwatch' when necessary
    $ sudo wget -O /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-6\
    > https://www.fedoraproject.org/static/0608B895.txt
    $ sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-6
    $ sudo rpm -Uvh \
    > https://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
    $ cat <<'EOF' > PUIAS_6_computational.repo
    [PUIAS_6_computational]
    name=PUIAS computational Base $releasever - $basearch
    mirrorlist=http://puias.math.ias.edu/data/puias/computational/$releasever/$basearch/mirrorlist
    #baseurl=http://puias.math.ias.edu/data/puias/computational/$releasever/$basearch
    gpgcheck=1
    gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-puias
    EOF
    $ sudo mv PUIAS_6_computational.repo /etc/yum.repos.d/
    $ sudo wget -O /etc/pki/rpm-gpg/RPM-GPG-KEY-puias\
    > http://springdale.math.ias.edu/data/puias/6/x86_64/os/RPM-GPG-KEY-puias
    $ sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-puias
    $ sudo rpm -Uvh\
    > http://yum.postgresql.org/9.3/redhat/rhel-6-x86_64/pgdg-centos93-9.3-1.noarch.rpm
    $ sudo yum -y update
    $ sudo yum -y groupinstall 'Development Tools'
    $ sudo yum -y install zlib-devel openssl-devel readline-devel ncurses-devel\
    > gdbm-devel db4-devel libffi-devel tk-devel libyaml-devel git postgresql93-devel\
    > postgresql93-server httpd ImageMagick
    
  2. Create a system user.
    $ sudo adduser --system --shell /bin/bash --comment 'Medusa' \
    > --create-home --home-dir /home/medusa/ medusa
    $ sudo passwd medusa
    
  3. Configure PostgreSQL.
    $ sudo chkconfig postgresql-9.3 on
    $ sudo service postgresql-9.3 initdb
    $ sudo -u postgres vi /var/lib/pgsql/9.3/data/pg_hba.conf
    
    # !! modify in editor !!
    # "local" is for Unix domain socket connections only
    local   medusa             medusa                                  password
    local   all                all                                     peer
    # IPv4 local connections:
    host    medusa             medusa          127.0.0.1/32            password
    host    all                all             127.0.0.1/32            ident
    # IPv6 local connections:
    host    medusa             medusa          ::1/128                 password
    host    all                all             ::1/128                 ident
    
    $ sudo service postgresql-9.3 start
    
  4. Install Ruby program.
    $ sudo -su medusa
    $ cd ~
    $ git clone https://github.com/sstephenson/rbenv.git ~/.rbenv
    $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile
    $ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
    $ source ~/.bash_profile
    $ type rbenv
    $ mkdir ~/.rbenv/plugins
    $ git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build
    $ git clone https://github.com/sstephenson/rbenv-default-gems.git \
    > ~/.rbenv/plugins/rbenv-default-gems
    $ cat <<EOF > ~/.rbenv/default-gems
    bundler
    rbenv-rehash
    EOF
    
    $ rbenv install 2.1.0
    $ rbenv global 2.1.0
    $ bundle config build.pg --with-pg-dir=/usr/pgsql-9.3 --with-pg-lib=/usr/pgsql-9.3/lib
    $ exit
    
  5. Download Medusa software.

    Download Medusa from repository (or archive) and locate it to /srv/medusa.

    $ sudo mkdir -p /srv/medusa
    $ sudo chown medusa:medusa /srv/medusa
    $ cd /srv/medusa
    $ wget https://dream.misasa.okayama-u.ac.jp/documentation/Archives/medusa-9.2.zip
    $ unzip medusa-9.2.zip
    $ mv medusa.git current
    
  6. Install gem packages.
    $ cd /srv/medusa/current
    $ bundle install --path vendor/bundler --without test development
    
  7. Create a database and an user.

    For example, create a database medusa and an user ‘medusa’ with a password ‘my_password’. “Ruby on Rails" will access to the database as this user.

    $ sudo -u postgres psql
    # !! modify in psql ""
    CREATE USER medusa WITH SUPERUSER PASSWORD 'my_password';
    CREATE DATABASE medusa OWNER medusa;
    \q
    
  8. Have a configuration file.

    Copy config/database.yml.example to config/database.yml and revise ‘production’ part in the file.

    production:
      adapter: postgresql
      encoding: unicode
      database: medusa
      pool: 5
      username: medusa
      password: my_password
    
  9. Have another configuration file.

    Copy config/application.yml.example to config/application.yml and configure the ‘defaults’ part of the file.

    Medusa create name-card-size PDF file with name, ID, image, and barcode. The barcode can be 1D (Code128B) or 2D (QR-code). The barcode is an encoded string that is defined by prefix + ID.

    defaults: &defaults
      site_name: "Medusa"
      help_url: https://dream.misasa.okayama-u.ac.jp/documentation/
      admin:
        email: medusa@example.com
        initial_password: vQxPIFMZ
      barcode:
        prefix:
        type: 2D
      backup:
        files:
          dir_path: "/tmp/medusa/backup/files"
        db:
          dir_path: "/tmp/medusa/backup/db"
    
  10. Condition the database.

    Condition the database and compile assets by following commands.

    It will create tables in the database, initialize it with the seed data, and create pre-existing administrator-account (username: admin, password: vQxPIFMZ). Note that the commands should be issued at the application root directory.

    $ bundle exec rake db:migrate RAILS_ENV=production
    $ bundle exec rake db:seed RAILS_ENV=production
    $ bundle exec rake search_column:create RAILS_ENV=production
    $ bundle exec rake assets:precompile RAILS_ENV=production
    
  11. Install init scripts.

    Install init script and config file by following commands.

    $ sudo cp config/init.sh /etc/init.d/medusa
    $ sudo cp config/apache.conf /etc/httpd/conf.d/medusa.conf
    $ sudo chkconfig medusa on
    $ sudo chkconfig httpd on
    $ sudo setsebool -P httpd_can_network_connect on
    
  12. Start application.

    Start application by following commands. Then access to http://localhost/medusa and log-in with pre-existing administrator-account.

    $ sudo service medusa start
    $ sudo service httpd start
    
  13. Tweak operating system.

    A www-port of CentOS is filtered by the operating system and can be opened this way, when run as server.

    $ iptables -I INPUT -p tcp --dport 80 -j ACCEPT
    $ service iptables save
    

Next: , Previous: , Up: Setup   [Contents]

4.2 Backup

You have to store two kinds of datasets. One is the database and other is uploaded files that are NOT in the database. The uploaded (or attached) files are stored in the public/system/attachment_files directory.

An example shell-script for daily backup for the data in the database is shown bellow. This example is for a case using PostgreSQL database with database-name ‘medusa’ and user-name ‘medusa’.

#!/bin/bash
SNAPSHOT_Rw=/path/to/backup/db-dump;
DB=medusa
DB_USER=medusa
PROGRESS=$SNAPSHOT_Rw/inProgress;
LATEST=$SNAPSHOT_Rw/Latest;
pg_dump -i -U $DB $DB_USER > $PROGRESS

if [ $? = 0 ] ; then
	DATE=`date +%Y-%m-%d`;
	NEW_BACKUP=$SNAPSHOT_Rw/$DATE.pg_dump;
	mv $PROGRESS $NEW_BACKUP;
	if [ -e $LATEST ] ; then
		rm $LATEST;
	fi;
	ln -s $NEW_BACKUP $LATEST;
fi;

An example shell-script for daily backup for the attachment files linked to the database is also shown bellow.

#!/bin/bash
SNAPSHOT_Rw=/path/to/backup/db-linked-files;
RSYNC_SRC="/srv/medusa/current/public/system";
PROGRESS=$SNAPSHOT_Rw/inProgress;
LATEST=$SNAPSHOT_Rw/Latest;
RSYNC_CMD="rsync -av --delete --link-dest=$LATEST $RSYNC_SRC $PROGRESS";

if [ -d $PROGRESS ] ; then
	rm -r $PROGRESS;
fi;
mkdir $PROGRESS
$RSYNC_CMD
if [ $? = 0 ] ; then
  DATE_DIR=`date +%Y-%m-%d`;
  NEW_BACKUP=$SNAPSHOT_Rw/$DATE_DIR;
  mv $PROGRESS $NEW_BACKUP;
  if [ -d $LATEST ] ; then
  	rm $LATEST;
  fi;
  ln -s $NEW_BACKUP $LATEST;
fi;

Next: , Previous: , Up: Setup   [Contents]

4.3 Restore

First, setup a Medusa site. Follow step by step instruction that is located somewhere else if necessary. We assume Medusa to be expanded to /srv/medusa_restore and you are using PostgreSQL. Do not forget to create a database ‘medusa_restore’ and an user ‘medusa’.

Then, restore database from the recent dumpfile by a following command.

$ psql -U medusa medusa_restore < /path/to/backup/db-dump/Latest

Restore attachments from backup by a following command.

$ rsync -a /path/to/backup/db-linked-files/Latest /srv/medusa_restore/current/public/system

Check if restore was made correctly by a built-in web-server in ‘Ruby on Rails.’ To run the build-in web-server, issue a following command. Once web server has started, access http://localhost:3000 to see a login page. Log in using the administrator account.

$ rails server -e production

Next: , Previous: , Up: Setup   [Contents]

4.4 Export/Import

You may want to have a public Medusa for open access. To do so, set public flag of certain records. Then export the records, then export the public Medusa. To make the records public requires attention. Handle with care.

We suppose there are three servers, that are the development server, the master server, and the public server.

To copy public records from the master server to the public server is carried out by six steps as described below.

  1. Update Medusa code for the master and the public servers.
  2. Copy the master database to the development database.
  3. Erase records in the development database that are not flagged.
  4. Create lists of attachment-files to be copied.
  5. Copy the development database to the public database.
  6. Copy attachment-files to the public server.

Issue following main-script to do all. Sub-scripts are described on following sections.

$ cat /home/medusa/scripts/publish_stone.sh
#!/bin/bash
medusa_root=/home/medusa/devel-godigo/medusa
cd $medusa_root
## 1 Update Medusa code for the master and the public servers
# 1.1 Update the master code
bundle exec cap stone_master deploy
# 1.2 Update the public code
bundle exec cap stone_public deploy
# 1.3 Restart the master and the public server
bundle exec cap stone_master unicorn:stop
bundle exec cap stone_master unicorn:start
bundle exec cap stone_master sidekiq:stop
bundle exec cap stone_master sidekiq:start
bundle exec cap stone_public unicorn:stop
bundle exec cap stone_public unicorn:start
bundle exec cap stone_public sidekiq:stop
bundle exec cap stone_public sidekiq:start
## 2 Copy the master database to the development database (Synchronize
the master server with db and db-linked-files)
bundle exec cap stone_master app:pull
## 3 Erase records in the development database that are not flagged
(Delete all records besides ones to be opened)
bundle exec rails runner scripts/delete_unpublished_record.rb
## 4 Create lists of attachment-files to be copied (Make a list of
files to be opened) 
bundle exec rails runner scripts/list_uploaded_files.rb --base=$medusa_root/public/system/ > sync_list
## 5 Copy the development database to the public database (Synchlonize
the public datebase with the master datebase)
bundle exec cap stone_public db:push
## 6 Copy attachment-files to the public server
# 6.1 Synchlonize db-linked-files of the public server in the files to be opened
bundle exec cap stone_public uploaded_file:push SYNC_LIST=sync_list
# 6.2 Restart the public server
bundle exec cap stone_public unicorn:stop
bundle exec cap stone_public unicorn:start
bundle exec cap stone_public sidekiq:stop
bundle exec cap stone_public sidekiq:start

4.4.1 Update Medusa code for the master and the public servers

After test on the development server, using capistrano, you will both deploy the master server and the public server from the depository. Configuration for the development server to deploy both the master and the public code is described as below.

location of Medusa

The server should be configured to develop Medusa. We suppose you clone Medusa as /home/medusa/devel-godigo/medusa/.

configuration to deploy the master server (ex., 172.24.1.36)
$ cat /home/medusa/devel-godigo/medusa/config/deploy/stone_master.rb
role :app, %w{medusa@database.misasa.okayama-u.ac.jp}
role :web, %w{medusa@database.misasa.okayama-u.ac.jp}
role :db,  %w{medusa@database.misasa.okayama-u.ac.jp}
server 'database.misasa.okayama-u.ac.jp', user: 'medusa', roles: %w{web app db}, my_property: :my_value
set :deploy_to, '/srv/stone_master'
set :relative_url_root, '/stone'
set :rails_env, 'production'
configuration to deploy the public server (ex., 150.46.245.23)
$ cat /home/medusa/devel-godigo/medusa/config/deploy/stone_public.rb
role :app, %w{medusa@devel.misasa.okayama-u.ac.jp}
role :web, %w{medusa@devel.misasa.okayama-u.ac.jp}
role :db,  %w{medusa@devel.misasa.okayama-u.ac.jp}
server 'devel.misasa.okayama-u.ac.jp', user: 'medusa', roles: %w{web app db}, my_property: :my_value
set :deploy_to, '/srv/apps/stone_public'
set :relative_url_root, '/stone_public'
set :rails_env, 'production'
set :unicorn_port, 3030

4.4.2 Copy the master database to the development database

After you deploy the newest code to the master server and the public server, you want to copy the datasets (records and attachment-files) on the master server to the development server, filter records out on the development server, then copy the datasets on the development server to the public server. Two copying are carried out by task provided by capistrano.

Configuration for the synchronization
$ tail -5 /home/medusa/devel-godigo/medusa/config/deploy.rb
# Setting for db-tasks.
set :skip_data_sync_confirm, true
set :assets_dir, "public/system"
set :uploaded_files_dir, "public/system"
set :local_uploaded_files_dir, "public/system"
Load library capistrano-db-tasks to sync files on file system (that are not records)
$ tail -2 /home/medusa/devel-godigo/medusa/Capfile
# Task to synchronize the site between db and db-linked-files
require "capistrano-db-tasks"
Extend functionality to extract only records with public flag
$ cat /home/medusa/devel-godigo/medusa/lib/capistrano/tasks/uploaded_file.cap
namespace :uploaded_file do
  desc 'Synchronize your remote uploaded_files using local files'
  task :push do
    if fetch(:skip_data_sync_confirm) || Util.prompt('Are you sure you want to erase your server uploaded_files with local files?')
      servers = Capistrano::Configuration.env.send(:servers)
      server = servers.detect {|s| s.roles.include?(:app)}
      port = server.netssh_options[:port] || 22
      user = server.netssh_options[:user] || server.properties.fetch(:user)
      dirs = [fetch(:uploaded_files_dir)].flatten
      local_dirs = [fetch(:local_uploaded_files_dir)].flatten
      dirs.each_index do |idx|
        cmd = "rsync -arv --del"
        cmd = "#{cmd} --files-from=#{ENV['SYNC_LIST']}" if ENV['SYNC_LIST']
        cmd = "#{cmd} --rsh='ssh -p #{port}' ./#{dirs[idx]} #{user}@#{server}:#{current_path}/#{local_dirs[idx]}"
        system(cmd)
      end
    end
  end
end

4.4.3 Erase records in the development database that are not flagged

On the development server, all records besides ones to be opened should be deleted. The records to be opened should be accompanied with attachment-files.

After all records are copied from the master server to the development server, following script will be called to delete records that should not be opened to the public on the development server.

$ cat /home/medusa/devel-godigo/medusa/scripts/delete_unpublished_record.rb
klasses = [Specimen, Box, Place, Analysis, Bib, Table, AttachmentFile, Surface, Spot]
count = 0
klasses.each do |klass|
  klass.joins(:record_property).where.not('record_properties.published' => true).delete_all
  puts "#{klass.to_s} #{klass.count}"
  count += klass.count
end
RecordProperty.where.not(published: true).delete_all
GlobalQr.where.not(record_property_id:RecordProperty.pluck(:id)).delete_all
admin = User.find_by_username("admin")
admin.password = "admin"
admin.save
RecordProperty.update_all(user_id: admin.id)
User.where.not(:id => admin.id).destroy_all
group_ids = RecordProperty.pluck(:group_id).compact.uniq
Group.where.not(id: group_ids).destroy_all

To copy attachment-files from the development server to the pubkic server, following script would be called to create a list of attachment-files of to be copied from the development server to the public server.

$ cat /home/medusa/devel-godigo/medusa/scripts/list_uploaded_files.rb
require 'optparse'

options = {:base => nil}
OptionParser.new {|o|
  o.banner = "Usage: #{$0} [options]"
  o.on("--base=base", "base" ){|v| options[:base] = v}
}.parse!(ARGV.dup)

base_path = Rails.root
base_path = Pathname.new(options[:base]) if options[:base]
apaths = []
apaths.concat(AttachmentFile.all.map{|obj| File.dirname(obj.data.path) })
apaths.concat(Surface.all.map{|obj| obj.map_dir})
apaths.each do |apath|
  rpath = Pathname.new(apath).relative_path_from(base_path)
  puts rpath.to_s
end

4.4.4 Create lists of attachment-files to be copied

See Erase records in the development database that are not flagged.

4.4.5 Copy the development database to the public database

See Copy the master database to the development database.

4.4.6 Copy attachment-files to the public server

See Copy the master database to the development database.


Previous: , Up: Setup   [Contents]

4.5 Authorization

From Medusa 9.2, not only local authorization but also those by Google and Shibboleth are supported.

Each user should configure the authorization individually. Login using local authorization first. Then open page via “Medusa / account icon”. You see Link to Google button and/or Link to Shibboleth button. If you do not see none of the button, ask administrator to reconfigure Medusa.


Next: , Previous: , Up: Top   [Contents]

5 Daily operation


Next: , Up: Daily operation   [Contents]

5.1 First login

We assume that Medusa has been installed already. See Setup. Before start daily operation, you have to create user accounts and groups as Unixy system has. Login with pre-existing administrator-account. See Setup. Then click “pref” icon for configuration.

Create users (or members) and groups (or projects) by following appropriate links. Update information of members whenever necessary. User’s info can be updated by individual user also. If an user is with administration privilege, he can update anyone’s info including password. Note that one user can belong to several groups. To change members in a group, change affiliation of each user.

You also have to create several items. Create classifications and physical forms of stone, box types, and categories for analysis. Examples of items to be added are shown below.

After you login as a normal user first time, click your account name shown on top right in a window, then update your personal information.


Next: , Previous: , Up: Daily operation   [Contents]

5.2 Primer

5.2.1 Record browsing

Medusa keeps track genetic and tenant relationship of “stone” and “box”, with links to other records such for “place”, “analysis”, “bib”, and “file.” On each tab, records of certain type are listed. By certain search criteria, records of interest are listed. To click title of property such as parent, box, or, physiform, will sort the list.

The columns to be shown on list of ‘stone’ sub-tab is configured in page via “Medusa / system preference icon / view”.

5.2.2 Search records

Put keyword on search box on the top of the browser and hit enter to see records with name, ID, or classification that match the keyword. Engine of pattern matching is ‘SQL LIKE Operator’.

%

Any 0 or 1 letter.

_

Any 1 letter, which corresponds to ‘.’ in regular expression.

5.2.3 Label or name card

We suggest Medusa users to keep stones with label or name card. Select a stone or box then click “label” or “PDF.” icon. A CSV file to be fed into label printer or a card-size PDF file will be downloaded. The name card contains name, ID, a thumbnail image, and a barcode. The ID such as 20110523203903-158-715 can be encoded by QR-code (Denso-wave) or Code128B. See document ‘Label printer and barcode reader’ to setup label printer.

5.2.4 Export a list

To export a list, (1) have a list of stones and (2) click “check all” icon on the bottom of the list, then (3) click “select” icon at the bottom of the list. A stone browser switches into a stone editor. Then (4) click “csv”, “label”, or “card” icon on the top. Download starts soon and you will have records in a format of CSV (Comma Separated Values), label with barcode on (if configured appropriately), or name-card-sized PDF.

5.2.5 Other basic operations

Major operations besides record browsing are ‘create a record’, ‘edit a record’, ‘upload a file’, and ‘make a link’.

To create a record of certain class, click appropriate tab then scroll till the end of a table. Type name ‘My great record’ and click ‘enter’ icon.

To edit a record, select a record of concern, then click “edit” or “system-gear” icon. This allows to update most of info. We do not recommend to modify ID assigned by Medusa.

To upload a file that is relevant to a record, first select the record. You see sub-tabs on your right. By click of sub-tab “file” then upload any file. On image file, a thumbnail image is created and shown with the record. When a record is with multiple images, edit priority list on “file” sub-tab.

Although to make a link can be a subset of edit, it is described in detail on the next section.

5.2.6 Batch edition

Sometimes you want to edit information on multiple records at once. For example, you want to set “project” (or group) of 100 stones.

Click stone tab and list stones that you want to edit by certain search criteria. Check stones located at the left edge in the list. You can select all immediately by click “check all” at the bottom of the list. Then click “select” icon that is located at the bottom of the list. A stone browser switches into a stone editor. Set parameter by choosing pull-down menu or by typing. For example, if you want to change lithology of stone, choose “ordinary chondrite” from pull-down menu. Then click update button.

In a similar way, system info such like owner and group, can be revised at once for different type of records using this batch edition. If you want to change it one-by-one, choose a record and click system-gear icon.


Next: , Previous: , Up: Daily operation   [Contents]

5.3 Make a box

A mount for probe analyses contain multiple minerals. The mount and the minerals should be stored in Medusa as box and stones. Since the stones never get out of the box, check ‘fixed in box’ of stone records. Once stones are fixed in the box, to update ‘checked-date’ of the box updates those of stones.

Total weight of stones in a box is automatically calculated by Medusa.

The tenant hierarchy of a stone in recursive boxes are shown by navigation tree on the left column. The sub-boxes can be hide and unhide in the tree.


Next: , Previous: , Up: Daily operation   [Contents]

5.4 Update a stone

Medusa can not only record weight of a stone but also history of weight. When you subdivide a stone into several pieces, try to describe the status on page via “Medusa / specimen tab / daughter sub-tab”.

A stone can be with absolute or relative ages. Medusa 9.2 can store information of age of a stone. The age in geology is ‘relative age’, not ‘absolute age’. Thus Medusa 9.4 was improve to accept absolute age.

Medusa can keep track of a stone that does not exist. Set status of a stone to be ‘discarded’ or ‘lost’ when necessary. The status is shown by icon.

From Medusa 9.2 trip history of each stone is kept track by Medusa. When you move a stone to other box, the move is appended to history automatically. No extra work is necessary. See page via “Medusa / specimen tab / select a specimen record / history sub-tab”.

From Medusa 9.2, an user can add any extra properties of information related with specimen. See page via “Medusa / system preference button / custom”.


Next: , Previous: , Up: Daily operation   [Contents]

5.5 Make a link

There are several links between records. The most significant ones are genetic link between stones, and tenant link between box and stone (or box). There is other one between spot and analyses. Those are detailed on this section.

5.5.1 Manual link

When you make a link from the parent, choose parent record. You see several sub-tabs and click “daughter”. Fill in daughter’s ID then click “link” icon. You have to know daughter’s ID. Medusa owns in-situ search capability.

You can make link from daughter, too. After choosing daughter’s record, click “edit” icon that is located above thumbnail image. With this record-info editor, you can make a link to parent.

In this manner, link can be created between stone record and something else. Choose stone record then click certain sub-tab. Fill the record ID in a form then click “link” icon.

You can make tenant link between a stone and a box in a similar way. Note in this relation, you have to read the first paragraph on this section by replacing daughter and parent to be stone and box, respectively. Also tenant relationship, such for “box” contains another “box”, can be described in similar fashion.

5.5.2 Auto link

There is a quick way to create a daughter stone. Choose pre-existing parent-record and click “daughter” sub-tab. Type in appropriate name at the end of list and click “enter” icon. Medusa will make a daughter record that is genetically linked to the parent.

In a similar way, you can make a box record with a tenant link. Also under “box” tab and “stone” sub-tab, you can make a stone record with a tenant link.

5.5.3 Spot link

As inferred already, a record of stone and box is usually linked to an image file. Medusa can make a link between a spot within the image and any records.

As an example, 8 minerals on 1-inch mount are considered. Each mineral is independent and you create 8 stone records in a box. To have a visual on each mineral, one tedious approach is to take 8 pictures and make links between the 8 pictures and 8 stones. Using spot link, you make links between 8 spots and 8 stones using single picture that is linked to a box.

Let’s assume that you have created 8 records and know IDs of them already. Take only single picture of the mount with 8 minerals, and upload and correlated with the box. Click “file” tab, then you choose the image record. The image in shown on the left-hand side of a window. Using zoom and double click, locate one target mineral under cross-line. Type ID of the target mineral (stone) into “link ID” field, then click “new spot”. Now the spot in the image is linked to the stone. By repeating this 8 times, all 8 mineral records have visuals.

Stroke of a spot may not be appropriate. For example, the diameter of the circle could be too small. Click “edit” on “spot” sub-tab and optimize parameters.

In this example, a link was made between a stone record and a spot record. Technically, a spot record is also linked to a file record. Note that you can make a link from a spot record to any type of record.


Next: , Previous: , Up: Daily operation   [Contents]

5.6 Analysis

Medusa stores chemical properties of a stone in “analysis” record. Let’s think about a situation you analyze number of stones N using instrument ICPMS and estimate M trace-element abundances. In this case, analysis records of N are created, and each record has measured items of M.

There are two steps to store your data. First you create N analysis records. Then you port M measured items (or trace-element abundances) into corresponding analysis record. The operational flow to store an analysis is described on this section.

5.6.1 Creation of an analysis record

Click “analysis” tab, then you see a list. At the bottom of the list, you will find a form for a new analysis record. Fill in appropriate acquisition name (run number such like ‘ref-ol-sc1-1024’), instrument used for the acquisition, and stone ID. When you click “create” button, (1) an analysis record is created, and (2) it is linked stone record.

5.6.2 Load datasets into an analysis record

You have created analysis records of N successfully. Choose one of the analysis records to load trace-element abundances of M. Click “at-a-glance” sub-tab, then you see a data table. There would be forms for a new data entry. Choose a chemical parameter (or trace-element abundance) that you want to load from pull-down menu, fill data fields, and click “create”. By repeating this operation M times, the analysis record will have M trace-element abundances in it.

You can save time by using templates. At the bottom of the data table, you see template strings such as EPMA, XRF, oxygen-isotope ratio. By clicking one of them, Medusa gives you a multi-items input-forms. The templates are hard coded on Medusa as of July 2011. Check the source code if necessary. A list of chemical parameters that you see at the pull-down menu can be updated by administrators. Log on as an administrator and follow “pref” menu, then go under “analysis” tab.

5.6.3 Creation of analysis records and fill chemical parameters at once

You can create analysis records M and chemical parameters N at once with a help of an external spreadsheet program such as MS Excel.

Click “analysis” tab, you see an analysis list. At the bottom of the list, you will find a list of batch-port templates. Click appropriate one, download the template, then fill your data using a spreadsheet program. Note that Medusa is strict in grammar. Do not forget to fill “session” column. You do not have to fill error columns. As mentioned already, the templates are hard coded as of July 2011; we are working on it to make template handling dynamic. As of May 2012, you can add column of element (or isotope) items to the template if they are already defined on Medusa. You can delete columns of element item from the template if unnecessary.

After the edition upload it using an interface that also is located at the bottom of the list. Medusa only accepts MIME type of text/csv, text/plain, and application/csv. If your browser uploads with MIME type application/octet-stream, use a different computer.

You can do same thing “analysis” sub-tab on a stone record. Using this interface, Medusa ignores embedded IDs in a CSV file and force to assign the current record.

There is a way of uploading analysis records by locally installed utilities.


Previous: , Up: Daily operation   [Contents]

5.7 Publicize

Medusa can show records to guests. To do so, you have to set “published?” flag of records.

As a first step, records to be opened to public should have been linked to a bibliography record. Make a bibliography record, select it, then click “stone” sub-tab. Make a link to individual stone records. You have to know IDs of the stone records in advance. This step really should have been done soon after you publish your data regardless you make these open to public or not.

Next, click “stone” sub-tab and check records that you want to be opened to public. After the selection on check boxes at the left-hand side, click “publish” button located at the top of the list. Now the records can be accessed at $(medusa-root)/published. On March 31, 2018, a button to set flags of all records that are linked to a bib record was implemented. The button will set the flags of stone, box, place, analysis, and table.

Medusa tries to emulate tables in a published article. To do so, Medusa 9.2 can have tables in bib records using analyses already stored in Medusa. See page via “Medusa / bib tab / select a bib record / table sub-tab”.

To be useful to communities, Medusa 9.2 support synchronization to SESAR. Once you decided to open your specimen, upload information of a specimen to SESAR. See “Medusa / specimen tab / select a specimen record / detail edit button”.


Next: , Previous: , Up: Top   [Contents]

6 Refer to records

From Medusa, you will be able to download stone, box, and bib records in a format of BibTeX. As of March 26 (2017), implementation is still in the alpha stage. We wrote a script as shown below and run it by cron on a server with our Medusa.

#!/usr/bin/env bash
cd /srv/OurMedusa/current
RAILS_ENV=production bundle exec rake record:dump:list output_path=/tmp/auto-OurMedusa-list
RAILS_ENV=production bundle exec rake record:dump:bib output_path=/tmp/ref_OurMedusa.bib

Say you have ref_OurMedusa.bib and report.tex, then you will have report.pdf as shown below.

ref_OurMedusa.bib
@article{20110416134955-320-347,
  author={{RA-QD02-0095}},
  title={Grain at \nolinkurl{/IPM/main/1270/Hayabusa 1/Heaven on the Itokawa/}},
  journal={\href{https://dream.misasa.okayama-u.ac.jp/?q=20110416134955-320-347}{DREAM}},
  volume={16},
  pages={20110416134955-320-347},
  year={2011},
 url={https://dream.misasa.okayama-u.ac.jp/?q=20110416134955-320-347},
}
@article{20151104080528-151493,
  author={{126}},
  title={Room at \nolinkurl{/IPM/main/}},
  journal={\href{https://dream.misasa.okayama-u.ac.jp/?q=20151104080528-151493}{DREAM}},
  volume={15},
  pages={20151104080528-151493},
  year={2015},
  url={https://dream.misasa.okayama-u.ac.jp/?q=20151104080528-151493},
}
@article{20130209100246-493-546,
  author = "Nakamura, E. and Kunihiro, T. and Kitagawa, H. and Yachi, Y.",
  title = "Software Dedicated for the Curation of Geochemical Data Sets in Analytical Laboratories",
  journal = "Geostandards and Geoanalytical Research",
  year = "2013",
  number = "1",
  volume = "38",
  pages = "95--102",
doi = "10.1111/j.1751-908X.2013.00205.x",
}
report.tex
\documentclass[12pt]{article}
\usepackage{natbib}
\usepackage{hyperref}
\begin{document}
A stone \cite{20110416134955-320-347} was not located at
\cite{20151104080528-151493}.  Needless to say, this is not mentioned
in \cite{20130209100246-493-546}.
\bibliographystyle{abbrvnat} % (gca_like, apalike-url, abbrvnat, unsrtnat, plainnat, Science, pnas2011)
\bibliography{ref_geochem,ref_pml,ref_dream}
\end{document}
report.pdf

A stone RA-QD02-0095 [2011] was not located at 126 [2015]. Needless to say, this is not mentioned in Nakamura et al. [2013].

References

126

Room at /IPM/main/. DREAM, 15:20151104080528-151493, 2015. URL https://dream.misasa.okayama-u.ac.jp/?q=20151104080528-151493.

E. Nakamura, T. Kunihiro, H. Kitagawa, and Y. Yachi.

Software dedicated for the curation of geochemical data sets in analytical laboratories. Geostandards and Geoanalytical Research, 38(1):95-102, 2013. doi: 10.1111/j.1751-908X.2013.00205.x.

RA-QD02-0095.

Grain at /IPM/main/1270/Hayabusa1/HeavenontheItokawa/. DREAM, 16:20110416134955-320-347, 2011. URL https://dream.misasa.okayama-u.ac.jp/?q=20110416134955-320-347.


Previous: , Up: Top   [Contents]

7 Command index