Untuk mengirimkan data ke National Institute of Mental Health Data Archives (NDA), pengguna harus memvalidasi datanya untuk memastikan data tersebut sesuai dengan format yang disyaratkan. Hal ini dilakukan dengan menggunakan alat Validasi dan Unggah NDA. Selain itu, pengguna juga dapat mengemas dan mengunduh data dari NDA. Jika data terkait diunduh dari S3, token AWS gabungan sementara diperlukan. Paket Python dan klien baris perintah telah dikembangkan untuk memungkinkan pengguna memvalidasi, mengemas, mengirimkan, dan/atau mengunduh data secara terprogram. Layanan web Validasi, Pengiriman Paket, dan Pengiriman Data.
Pengguna memerlukan distribusi Python untuk menggunakan klien. Jalankan perintah berikut dari terminal/command prompt untuk menentukan apakah Python sudah terinstal:
python3 --version
Catatan:
Jika Python sudah terinstal, pengguna akan melihat informasi versi. Jika tidak, Anda perlu mengunduh dan menginstalnya dari Python.org.
Pengguna mungkin memerlukan hak administratif, root, atau sudo untuk menginstal distribusi Python.
Python mungkin diinstal tetapi tidak tersedia di jalur sistem. Silakan baca dokumentasi instalasi dan penggunaan Python: Python3
Sejak Python 3.4, pip disertakan secara default dengan biner Python. Anda dapat memeriksa versinya dengan:
pip3 --version
Jika pip diinstal, Anda akan melihat informasi versi. Jika tidak, Anda harus menginstal pip. Pertama, unduh dari https://bootstrap.pypa.io/get-pip.py, lalu jalankan perintah berikut untuk menginstal bagi pengguna Anda.
python3 get-pip.py --user
Catatan:
Pip mungkin diinstal tetapi tidak tersedia di jalur sistem. Silakan baca dokumentasi instalasi dan penggunaan Python.
Petunjuk ini akan membantu Anda menyiapkan untuk menjalankan klien.
Cukup masukkan perintah berikut ke terminal atau command prompt Anda untuk menginstal nda-tools:
pip install nda-tools
Ini secara otomatis akan menginstal paket nda-tools, termasuk skrip baris perintah dan paket yang diperlukan.
Catatan:
Jika nda-tools memerlukan izin khusus, coba:
pip install nda-tools --user
Jika ada beberapa versi python atau pip di mesin operasi, command prompt tidak akan mengenali skrip nda-tools. Coba perintah berikut sebagai gantinya:
python -m NDATools.clientscripts.[NDAtoolcommand]
Jika versi alat yang tidak digunakan lagi telah diinstal, pengguna akan diminta untuk melakukan upgrade. Untuk memperbarui, ikuti perintah prompt.
Meskipun tidak hanya diperlukan untuk validasi, jika Anda ingin membuat paket dan mengirimkan data Anda ke NDA, Anda harus memiliki akun aktif dengan kami. Ini dapat diminta dari situs web NDA. Anda dapat membaca lebih lanjut tentang apa yang diperlukan untuk menyumbangkan data ke dalam NDA di sini.
Keyring adalah paket Python yang memanfaatkan manajer kredensial sistem operasi untuk menyimpan dan mengambil kredensial pengguna dengan aman.
Untuk pengguna sistem operasi apa pun, kata sandi dapat diperbarui dengan:
keyring.set_password('nda-tools', USERNAME, NEW_PASSWORD)
Pengguna Mac dan Windows masing-masing dapat menggunakan Rantai Kunci dan Manajer Kredensial untuk memperbarui kata sandi mereka.
Untuk memperbarui kata sandi Anda dengan keyring, jalankan:
keyring.set_password('nda-tools', 'YOUR_USERNAME', 'NEW_PASSWORD') ,
mengganti YOUR_USERNAME dan NEW_PASSWORD dengan nama pengguna NDA dan kata sandi baru Anda. Anda dapat membaca lebih lanjut dari Dokumentasi Keyring.
Jika Anda tidak memiliki entri apa pun yang disimpan melalui gantungan kunci, Anda akan diminta memasukkan kata sandi. Jika otentikasi berhasil, nda-tools akan menyimpan kata sandi Anda melalui keyring. Penggunaan alat nda selanjutnya akan mengambil kata sandi secara otomatis dan aman dari gantungan kunci.
Pengguna Linux mungkin perlu menginstal implementasi keyring backend karena mereka mungkin tidak memiliki pengelola kredensial asli seperti yang disertakan dengan sistem operasi Mac dan Windows. Jika backend keyring hilang, nda-tools akan mencetak pesan berikut:
If there is no backend set up for keyring, you may try pip install secretstorage --upgrade keyrings.alt
Untuk pengguna Ubuntu,
apt-get install -y gnome-keyring
Harap dicatat bahwa jika Anda mengalami kesalahan SSL saat menjalankan klien, Anda mungkin perlu menjalankan kembali permintaan instalasi pip, dengan pip install pip install requests[secure] yang akan menginstal beberapa paket tambahan dengan lebih banyak dukungan untuk koneksi SSL.
Untuk melihat opsi yang tersedia untuk klien Alat Validasi Python, masukkan perintah berikut:
vtcmd -h
atau untuk melihat opsi yang tersedia untuk klien Unduh Python, masukkan:
downloadcmd -h
Jika input baris perintah Anda memiliki karakter khusus (misalnya kata sandi) atau spasi (misalnya dalam direktori/nama file), Anda mungkin perlu mengapitnya dalam tanda kutip.
Jika Anda menggunakan Windows, gunakan tanda kutip ganda: " "
Jika Anda menggunakan Mac OSX atau Linux, gunakan tanda kutip tunggal: ' '
Saat pertama kali dijalankan, klien akan meminta Anda memasukkan nama pengguna dan kata sandi, yang akan disimpan di manajer kredensial sistem operasi Anda. Anda dapat kembali dan mengedit kredensial Anda kapan saja.
File ~.NDAToolssettings.cfg yang disediakan bersama klien berisi opsi yang dapat dikonfigurasi untuk Titik Akhir, File, dan informasi Pengguna.
Biasanya, Anda tidak perlu mengubah entri di bagian 'Titik Akhir'; namun, Anda mungkin ingin mengubah bagian 'File' dan 'Pengguna' dengan lokasi pilihan untuk hasil validasi, login pengguna, dan informasi kredensial AWS.
Meskipun argumen tidak bersifat posisional, argumen pertama harus berupa daftar file yang akan divalidasi.
vtcmd -l "Users/[youruser]/Documents/MultipleDataTypes" "Users/[youruser]/Documents/MultipleDataTypes/Stage_Testing_BigFiles_genomics_sample03.csv"
Daftar file tidak memiliki saklar baris perintah sehingga dapat ditafsirkan sebagai bagian dari argumen sebelumnya.
Misalnya, tidak ada cara untuk membedakan apakah file csv merupakan bagian dari argumen -l atau argumen kedua:
Anda harus mengetahui path lengkap ke file csv yang akan divalidasi. Selain itu, jika data Anda mencakup manifes dan/atau file terkait (yaitu, file genomik, file pencitraan, dll.), Anda juga harus mengetahui jalur lengkap ke file tersebut, yang harus dimasukkan sebagai argumen baris perintah opsional. Jika tidak, klien akan meminta Anda memasukkan daftar direktori tempat file tambahan disimpan. Anda juga dapat mencantumkan bucket, awalan opsional, dan kredensial AWS Anda jika file terkait ada di AWS.
Harap Dicatat: Saat mencantumkan direktori untuk file terkait, sertakan folder hingga namun tidak menyertakan nama file yang tercantum dalam file csv.
Jika nama file terkait ada di Users/[youruser]/Documents/MultipleDataTypes/data/1G_file.fastq dan terdaftar di file csv Anda sebagai:
data/1G_file.fastq
maka direktori yang akan anda masuki adalah:
Pengguna/[pengguna Anda]/Dokumen/MultipleDataTypes
Anda tidak boleh menyertakan folder 'data/' sebagai bagian dari nama direktori.
Periksa semua properti file dan pastikan pengguna memiliki semua Izin yang diizinkan.
Untuk memulai validasi, Anda harus memasukkan daftar file (atau jalur file jika tidak ada di direktori saat ini), dipisahkan dengan spasi:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv
Jika data Anda menyertakan file manifes, Anda harus memasukkan direktori tempat file manifes berada, dipisahkan dengan spasi:
vtcmd submission_data/sample_imagingcollection01.csv -m submission_data/Manifests
Jika ada file terkait, masukkan direktori tempat file tersebut ditemukan, dipisahkan dengan spasi:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l MultipleDataTypes testdata/with_associated_files
Jika file terletak di tempat lain selain direktori kerja saat ini, maka Anda harus memasukkan path lengkap ke file tersebut:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l Users/[youruser]/Downloads/SubmissionData testdata/with_associated_files
Jika file terkait Anda berada di S3, Anda harus menyertakan nama bucket, kunci akses, dan kunci rahasia.
Akses dan kunci rahasia juga dapat disimpan di file settings.cfg.
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -s3 my_bucket -ak XXXXXXXXXXXXXX -sk XXXXXXXXXXXXXX
Catatan: Anda juga dapat mengunggah file terkait yang disimpan secara lokal dan di s3. Pastikan untuk menyertakan direktori tempat file lokal disimpan (-l path/to/local/associated/files)
Untuk membuat paket, masukkan "-b" di akhir argumen baris perintah Anda. Anda juga dapat memasukkan nama pengguna, kredensial AWS, ID Koleksi, serta judul dan deskripsi kiriman Anda, atau Anda dapat memasukkan informasi ini nanti saat diminta oleh klien. Klien tidak akan mulai membuat paket pengiriman sampai:
Semua file Anda divalidasi
Semua file terkait telah ditempatkan di drive lokal Anda atau di S3
Setelah pengiriman dan pengunggahan paket selesai, Anda akan menerima email di kotak masuk Anda dari NDA yang mengonfirmasi bahwa pengiriman Anda berhasil. Versi lokal paket akan disimpan secara otomatis ke folder ~nda-toolsvtcmdsubmission_package dan dapat ditemukan di tab pengiriman koleksi di situs NDA.
Pemeriksaan QA dilakukan pada semua data setelah diserahkan ke NDA untuk mengetahui ketidakkonsistenan dalam poin data termasuk jenis kelamin, subjek, usia wawancara, dan tanggal wawancara. Jika ditemukan masalah pada data, email akan dikirimkan ke pengguna yang membuat penyerahan beserta laporan kesalahan yang ditemukan oleh NDA.
Untuk memperbaiki data dalam NDA kiriman Anda, Anda perlu mengganti semua file csv yang berisi kesalahan pada kiriman asli Anda. Untuk melakukan ini, Anda harus:
Ambil file csv yang digunakan untuk membuat kiriman asli dan berisi data yang perlu diperbaiki. Ini mencakup semua file csv yang datanya perlu ditambahkan, dihapus, atau diperbarui.
Perbaiki file dengan menambahkan, menghapus, atau memperbarui informasi sesuai kebutuhan.
Jalankan vtcmd dengan argumen baris perintah -rs. Tentukan nilai penyerahan yang datanya perlu Anda koreksi. Kemudian daftar semua file csv yang telah Anda koreksi. Jika ada file csv dari kiriman asli yang tidak mengandung perubahan apa pun, file tersebut tidak perlu disertakan sebagai argumen saat ini.
Misalnya, jika penyerahan asli dengan id 123456 terdiri dari file1.csv, file2.csv dan file3.csv, dan perlu dilakukan koreksi pada file1.csv dan file2.csv, perintah untuk memperbaiki kesalahan qa akan terlihat seperti:
vtcmd -b -rs 123456 corrected-file1.csv corrected-file2.csv
Perhatikan bahwa file3.csv dikecualikan dari perintah karena tidak ada perubahan yang perlu dilakukan pada file tersebut.
Harap dicatat perintah ini harus dijalankan sekali untuk pengiriman dan harus mencakup semua file yang berisi koreksi data . yaitu jangan menjalankan vtcmd sekali untuk file1.csv yang dikoreksi dan lain kali untuk file2.csv yang dikoreksi. Jika Anda secara tidak sengaja menghilangkan file yang berisi perubahan yang diperlukan saat menjalankan perintah, silakan hubungi HelpDesk di [email protected].
Perhatikan juga bahwa file csv harus berisi semua data yang dikirimkan aslinya. yaitu jika sebuah csv awalnya memiliki 800 baris dan hanya 3 baris yang perlu diubah, semua 800 baris tersebut harus ada di csv saat menjalankan vtcmd , bukan hanya 3 baris yang berisi perubahan. Data apa pun yang tidak disertakan dalam csv akan tercermin dalam jumlah data yang diharapkan untuk pengumpulan.
Skrip tidak akan mengunggah file terkait apa pun yang diunggah selama pengiriman asli. File terkait hanya perlu diunggah jika file tersebut muncul di file csv yang telah diperbaiki, namun tidak di file csv mana pun dari kiriman asli. Hal ini menghemat waktu selama pengiriman genomik dan pencitraan karena file terkait memerlukan waktu berhari-hari untuk diunggah.
Untuk mendownload data, Anda harus menggunakan perintah downloadcmd. Ini memberikan beberapa opsi untuk mengunduh data paket NDA Anda atau subkumpulan data. Semua file diunduh secara otomatis ke folder ~nda-toolsdownloadcmdpackages , tetapi Anda dapat mengubahnya dengan menunjukkan direktori baru di baris perintah untuk menyimpan file. Harap diperhatikan: batas maksimum transfer data adalah 20TB per bulan.
Pengguna dapat menghubungi NDA Help Desk di [email protected] dan meminta batas unduhan mereka untuk [sementara] diperpanjang.
Semua data paket dapat diunduh dengan meneruskan ID paket:
downloadcmd -dp <packageID>
Catatan: ini TIDAK akan mengunduh file terkait kecuali Anda membuat paket NDA dengan file terkait . Langkah-langkah untuk mengunduh file terkait ada di bawah.
Perintah downloadcmd memiliki dua opsi untuk mengunduh data di dalam file .txt. Jika Anda mengunduh paket NDA, Anda akan menemukan file meta-data .txt, banyak di antaranya mewakili ukuran data. Genomik, pencitraan, dan data terkait lainnya akan dicantumkan dalam file .txt ini sebagai tautan s3. Jika Anda ingin mengunduh semua tautan s3 di file .txt, Anda dapat mengindikasikannya dengan meneruskan tanda -ds.
downloadcmd -dp <packageID> -ds path/to/data/structure/file/image03.txt
Jika Anda ingin mengunduh paket NDA dan semua genomik, pencitraan, dan data terkait lainnya sebagai daftar tautan s3 yang disimpan dalam file .txt khusus, Anda dapat melakukannya dengan menggunakan tanda -t.
downloadcmd -dp <packageID> -t path/to/all/s3/txt/file/alls3.txt
Perintah downloadcmd dapat mengunduh paket NDA Anda ke dalam bucket S3 Anda secara langsung.
downloadcmd -dp <packageID> -s3 <s3 bucket>
Ini adalah cara yang lebih disukai untuk mengunduh data dari NDA karena dua alasan:
Mengunduh ke bucket S3 lain jauh lebih cepat karena data tidak keluar dari AWS.
Ini memungkinkan kami mengunduh data dalam jumlah tak terbatas dari NDA ke bucket Anda secara langsung.
Agar operasi penyalinan S3-ke-S3 berhasil, bucket S3 yang disediakan sebagai argumen program harus dikonfigurasi untuk mengizinkan operasi objek PUT untuk arn:aws:sts::618523879050:federated-user/<username> , dengan <username> adalah nama pengguna NDA Anda.
Untuk bucket non-publik, hal ini memerlukan pembaruan pada kebijakan bucket. Pernyataan berikut harus ditambahkan untuk memberikan izin yang diperlukan setelah mengganti <your-s3-bucket> dengan nama bucket:
{
"Sid": "AllowNDAUpload",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:federated-user/<username>"
},
"Action": "s3:PutObject*",
"Resource": "arn:aws:s3:::<your-s3-bucket>/*"
}Anda mungkin perlu mengirim email ke departemen TI perusahaan/institusi Anda agar ini ditambahkan untuk Anda.
Catatan: Jika bucket S3 Anda dienkripsi dengan kunci KMS yang dikelola pelanggan, Anda juga perlu memperbarui kebijakan kunci yang digunakan untuk mengenkripsi bucket.
Pernyataan berikut harus ditambahkan ke kebijakan kunci Anda:
{
"Sid": "EnableUseForFederatedNDA",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:user/DownloadManager"
},
"Action": ["kms:GenerateDataKey","kms:Decrypt"],
"Resource": "*"
}Jika Anda memiliki masalah dengan klien Alat Validasi Python ini atau ingin memberikan umpan balik/komentar, silakan kirim email kepada kami di [email protected].
