DataONE R Client の使い方メモ
=================================

DataONE は、米NSF の支援のもとで開発されている
研究データ分散リポジトリシステムである。

DataONE R Client は、オープンソース統計解析ソフト R 上から
DataONE に格納されているデータにアクセスするための R パッケージである。

以下の記述は FreeBSD 9.1-RELEASE 上で DataONE R Client 1.0.0 を
試験的に使用した時の備忘録である（2013年7月）。


感想
--------
* まだ完成度が低い。クライアント証明書の設定に openssl を使う必要があり、
  それがマニュアルに記載されていないなど、
  素人には初期設定すら不可能なレベル。

* 使い勝手が悪い。

    * 現状では検索機能が貧弱な上、R から DataONE 上のパッケージの
      ResourceMap ID が見えないので ONEMercury 上で検索する必要がある。

    * 大きなテーブルだとターミナル画面上で全体を視認するのは難しい。
      一旦エクセル等に読み込ませて全体像を把握したくなる。

* データのダウンロードも含めて一連のワークフローを R スクリプトにできる
  のは利点かも。解析に使用したデータがどのデータだったのか分からなくなる
  とかいう事故が防止出来る？

公式サイト等
----------------
`DataONE <https://www.dataone.org/>`_

`DataONE R Client <https://releases.dataone.org/online/dataone_r/>`_


準備
---------

JDK をインストール::

    # cd /usr/ports/java/openjdk7; make; make install


R のインストール::

    # cd /usr/ports/math/R; make; make install


DataONE R Client のインストール
----------------------------------
環境変数の設定::

    $ R CMD javareconf -e
    $ export MAKE=gmake

..    export LD_LIBRARY_PATH=/usr/local/openjdk7/jre/lib/amd64/server

R パッケージのインストール。 R 上で::

    > install.packages("dataonelibs")
    > install.packages("dataone")

d1IdentifierSearch() は R コードにバグがあって動かない。
どうしても使いたければコードを修正してコマンドラインからインストールする。


クライアント証明書の入手
----------------------------
DataONE R Client を使用するには DataONE システムにログインするための
クライアント証明書が必要。

そのクライアント証明書は cilogin.org から入手する。
cilogin.org には google アカウントでログインできる。

    * （もし google アカウントを持っていないなら）
      google アカウントを作成する。

    * ウェブブラウザで https://cilogin.org/?skin=DataONE にアクセスする。

    * Identity Provider に Google を選び、 LOG ON ボタンを押す。

    * Google の認証ページが出てくるので、Google アカウント情報を入力する

    * クライアント証明書発行ページが表示される。
      12文字以上のパスワードを入力すると証明書がダウンロード可能になる。
   
    * ダウンロードした証明書は PKCS#12 形式になっているが、
      DataONE R Client で使用するには pem 形式に変換する必要がある。
      （DataONE R Client が利用している
      暗号ライブラリ Bouncy Castle が pem 形式しか読めないため）

      変換には openssl を使用する::

        $ openssl pkcs12 -in P12FILE -nodes -out PEMFILE

    * pem ファイルを掃除する。
      DataONE R Client 1.0.0 に同梱の Bouncy Castle ver 1.46 は
      pem ファイル内に余計なテキストがあると正常に動かない。
      余計なテキストというのは::

        Bag Attributes
            localKeyID: xx xx xx xx xx xx xx xx xx xx
        subject=/DC=org/DC=cilogon/C=US/O=Google/CN=xxxxx
        issuer=/DC=org/DC=cilogon/C=US/O=CILogon/CN=CILogon OpenID CA 1

      というような部分のこと。

    * pem ファイルを配備する。/tmp/x509up_u{UID} がデフォルトの位置。::

        $ cp PEMFILE /tmp/x509up_u`id -u`

    * 証明書が読めるかどうか試す::

        $ R
        > library("dataone")
        > cm <- CertificateManager()
        > getCertExpires(cm)

      証明書の有効期限が表示されたら正常。

..    別解
      最新の Bouncy Castle jar と入れ替えるとゴミ付き pem でも読める
      削除    bcprov-jdk16-146.jar
      追加    bcpkix-jdk15on-149.jar
      追加    bcprov-jdk15on-149.jar
      でも jar 入れ替えるより pem を編集する方が楽だよね



DataONE R Client の使い方
----------------------------
    * D1Client インスタンス作成::

        > d1c <- D1Client()

    * DataONE R Client のデータ検索機能は貧弱でほとんど使い物にならないので、
      ONEMercury でデータを探す。

        `ONEMercury <https://cn.dataone.org/onemercury/>`_

      検索結果画面上で、各エントリの download ボタンをクリックすると、
      画面にそのパッケージの ResourceMap ID が表示される（resourceMap_* という文字列）ので、
      ダウンロードしたいパッケージの ResourceMap ID をコピーしておく。

      下図の赤丸部分に表示されているのが ResourceMap ID である。

    .. image:: d1resourcemap.jpg


    * パッケージをダウンロードする。::

        > package1 <- getPackage(d1c, rmid)

      ここで、 rmid はダウンロードしたいパッケージの ResourceMap ID である。
      
      （メンバーノードによってはうまくダウンロードできないようだ。
      台湾林試 (TFRI) のパッケージを取得しようとすると
      認証エラーで途中で止まってしまう。）

    * そのパッケージに含まれているオブジェクトの ID を取り出す。::

        > data_ids <- getIdentifier(package1)

    * データオブジェクトを取り出す。例えば 1番目のオブジェクトを取り出すには、::

        > data_obj <- getMember(package1, data_ids[1])

    * データオブジェクトからデータ内容を取り出す。::

        > data <- getData(data_obj)

    * 一時ファイルを使用してデータ内容を data.frame に変換する。::

        > tf <- tempfile()
        > writeLines(data, tf)
        > dataframe1 <- read.csv(tf)

      読み込みコマンドはデータのフォーマットに合わせて適切に選ぶこと。

      （dataone パッケージには asDataFrame() という関数が定義されているが、
      エラーが出て正常に動作しない。正常な動作では、EML メタデータを
      自動的に解析して区切り文字を取得し、データファイルを自動的に
      パースしてくれるようなのだが。）