Para enviar datos al Instituto Nacional de Archivos de Datos de Salud Mental (NDA), los usuarios deben validar sus datos para garantizar que cumplan con el formato requerido. Esto se hace utilizando la herramienta de carga y validación de NDA. Además, los usuarios también pueden empaquetar y descargar datos de NDA. Si los datos asociados se descargan de S3, se requieren tokens de AWS federados temporales. Se han desarrollado un paquete Python y clientes de línea de comandos para permitir a los usuarios validar, empaquetar, enviar y/o descargar datos mediante programación. Servicios web de validación, paquete de envío y envío de datos.
El usuario necesitará una distribución de Python para utilizar el cliente. Ejecute lo siguiente desde una terminal/símbolo del sistema para determinar si Python ya está instalado:
python3 --version
Notas:
Si Python ya está instalado, los usuarios deberían ver la información de la versión. De lo contrario, deberá descargarlo e instalarlo desde Python.org.
Es posible que el usuario necesite derechos administrativos, privilegios de root o sudo para instalar una distribución de Python.
Es posible que Python esté instalado pero no disponible en la ruta del sistema. Consulte la documentación de instalación y uso de Python: Python3
Desde Python 3.4, pip se incluye de forma predeterminada con el binario de Python. Puedes consultar la versión con:
pip3 --version
Si pip está instalado, debería ver la información de la versión. Si no, deberías instalar pip. Primero, descárguelo de https://bootstrap.pypa.io/get-pip.py, luego ejecute lo siguiente para instalarlo para su usuario.
python3 get-pip.py --user
Notas:
Es posible que Pip esté instalado pero no disponible en la ruta del sistema. Consulte la documentación de instalación y uso de Python.
Estas instrucciones lo ayudarán a configurar para ejecutar el cliente.
Simplemente ingrese el siguiente comando en su terminal o símbolo del sistema para instalar nda-tools:
pip install nda-tools
Esto instalará automáticamente el paquete nda-tools, incluidos los scripts de la línea de comandos y los paquetes necesarios.
Notas:
Si nda-tools necesita un permiso especial, intente:
pip install nda-tools --user
Si existen varias versiones de python o pip en la máquina operativa, el símbolo del sistema no reconocerá el script nda-tools. Pruebe el siguiente comando en su lugar:
python -m NDATools.clientscripts.[NDAtoolcommand]
Si ya está instalada una versión obsoleta de la herramienta, le pedirá al usuario que la actualice. Para actualizar, siga el comando.
Si bien no es necesario únicamente para la validación, si desea crear un paquete y enviar sus datos a la NDA, debe tener una cuenta activa con nosotros. Esto se puede solicitar desde el sitio web de la NDA. Puede leer más sobre lo que se necesita para aportar datos a la NDA aquí.
Keyring es un paquete de Python que aprovecha el administrador de credenciales del sistema operativo para almacenar y recuperar de forma segura las credenciales de usuario.
Para usuarios de cualquier sistema operativo, la contraseña se puede actualizar con:
keyring.set_password('nda-tools', USERNAME, NEW_PASSWORD)
Los usuarios de Mac y Windows pueden utilizar Keychain y Credentials Manager, respectivamente, para actualizar sus contraseñas.
Para actualizar su contraseña con llavero, ejecute:
keyring.set_password('nda-tools', 'YOUR_USERNAME', 'NEW_PASSWORD') ,
reemplazando YOUR_USERNAME y NEW_PASSWORD con su nombre de usuario NDA y nueva contraseña. Puede leer más en la documentación del llavero.
Si no tiene ninguna entrada almacenada a través del llavero, se le pedirá que ingrese la contraseña. Si la autenticación es exitosa, nda-tools almacenará su contraseña mediante un llavero. El uso posterior de nda-tools recuperará la contraseña de forma automática y segura del llavero.
Es posible que los usuarios de Linux necesiten instalar una implementación backend de llavero, ya que es posible que no tengan un administrador de credenciales nativo como los incluidos en los sistemas operativos Mac y Windows. Si falta el backend del llavero, nda-tools imprimirá el siguiente mensaje:
If there is no backend set up for keyring, you may try pip install secretstorage --upgrade keyrings.alt
Para usuarios de Ubuntu,
apt-get install -y gnome-keyring
Tenga en cuenta que si encuentra errores de SSL al ejecutar el cliente, es posible que deba volver a ejecutar la instalación de solicitudes de pip, con pip install pip install requests[secure] que instalará algunos paquetes adicionales con más soporte para conexiones SSL.
Para ver las opciones disponibles para el cliente Python de la herramienta de validación, ingrese el siguiente comando:
vtcmd -h
o para ver las opciones disponibles para el cliente Descargar Python, ingrese:
downloadcmd -h
Si las entradas de su línea de comandos tienen caracteres especiales (es decir, contraseñas) o espacios (es decir, en directorios/nombres de archivos), es posible que deba encerrarlos entre comillas.
Si utiliza Windows, utilice comillas dobles: " "
Si utiliza Mac OSX o Linux, utilice comillas simples: ' '
Tras su primera ejecución, el cliente le pedirá que ingrese su nombre de usuario y contraseña, que almacenará en el administrador de credenciales de su sistema operativo. Puede regresar y editar sus credenciales en cualquier momento.
El archivo ~.NDAToolssettings.cfg proporcionado con el cliente contiene opciones configurables para puntos finales, archivos e información de usuario.
Normalmente, no necesitará cambiar las entradas en la sección "Puntos finales"; sin embargo, es posible que desee modificar las secciones "Archivos" y "Usuario" con ubicaciones preferidas para los resultados de la validación, el inicio de sesión del usuario y la información de las credenciales de AWS.
Si bien los argumentos no son posicionales, el primer argumento debe ser la lista de archivos a validar.
vtcmd -l "Users/[youruser]/Documents/MultipleDataTypes" "Users/[youruser]/Documents/MultipleDataTypes/Stage_Testing_BigFiles_genomics_sample03.csv"
La lista de archivos no tiene ningún modificador de línea de comandos, por lo que puede interpretarse como parte de un argumento anterior.
Por ejemplo, no hay forma de diferenciar si el archivo csv es parte del argumento -l o un segundo argumento:
Es necesario que conozca la ruta completa a los archivos csv que se van a validar. Además, si sus datos incluyen manifiestos y/o archivos asociados (es decir, archivos genómicos, archivos de imágenes, etc.), también debe conocer la ruta completa a estos archivos, que debe ingresarse como un argumento opcional de la línea de comandos. De lo contrario, el cliente le pedirá que ingrese una lista de directorios donde se almacenan los archivos adicionales. También puede enumerar un depósito, un prefijo opcional y sus credenciales de AWS si los archivos asociados están en AWS.
Tenga en cuenta: al enumerar el directorio de archivos asociados, incluya la carpeta hasta , pero sin incluir, el nombre del archivo que figura en el archivo csv.
Si el nombre del archivo asociado está en Usuarios/[su usuario]/Documentos/MultipleDataTypes/data/1G_file.fastq y aparece en su archivo csv como:
datos/archivo_1G.fastq
entonces el directorio al que ingresarás es:
Usuarios/[suusuario]/Documentos/Múltiples tipos de datos
No debe incluir la carpeta 'datos/' como parte del nombre del directorio.
Verifique todas las propiedades de los archivos y asegúrese de que el usuario tenga todos los permisos permitidos.
Para iniciar la validación, debe ingresar una lista de archivos (o una ruta de archivo si no está en el directorio actual), separados por un espacio:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv
Si tus datos incluyen archivos de manifiesto, debes ingresar los directorios donde se encuentran los archivos de manifiesto, separados por un espacio:
vtcmd submission_data/sample_imagingcollection01.csv -m submission_data/Manifests
Si hay archivos asociados, ingrese los directorios donde se encuentran, separados por un espacio:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l MultipleDataTypes testdata/with_associated_files
Si los archivos están ubicados en algún lugar distinto al directorio de trabajo actual, debe ingresar la ruta completa a los archivos:
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -l Users/[youruser]/Downloads/SubmissionData testdata/with_associated_files
Si sus archivos asociados están en S3, debe incluir el nombre del depósito, la clave de acceso y la clave secreta.
La clave secreta y de acceso también se puede almacenar en el archivo settings.cfg.
vtcmd MultipleDataTypes/genomics_sample03.csv testdata/with_associated_files/genomics_sample03.csv -s3 my_bucket -ak XXXXXXXXXXXXXX -sk XXXXXXXXXXXXXX
Nota: También puede cargar archivos asociados guardados localmente y en s3. Solo asegúrese de incluir el directorio donde se guardan los archivos locales (-l ruta/a/local/asociado/archivos)
Para crear un paquete, ingrese "-b" al final del argumento de su línea de comando. También puede ingresar su nombre de usuario, credenciales de AWS, ID de colección y el título y descripción de su envío, o puede ingresar esta información más tarde cuando el cliente se lo solicite. El cliente no comenzará a crear el paquete de envío hasta que:
Todos tus archivos están validados.
Todos los archivos asociados se han ubicado en su disco local o en S3
Una vez que se complete el envío y la carga del paquete, recibirá un correo electrónico en su bandeja de entrada de NDA confirmando que su envío fue exitoso. Una versión local del paquete se guardará automáticamente en la carpeta ~nda-toolsvtcmdsubmission_package y se puede encontrar en la pestaña de envío de colección en el sitio de NDA.
Se realiza una verificación de calidad de todos los datos después de que se hayan enviado a la NDA para detectar inconsistencias en los puntos de datos, incluidos el sexo, el sujeto, la edad de la entrevista y la fecha de la entrevista. Si se encuentra algún problema con los datos, se enviará un correo electrónico a los usuarios que crearon el envío junto con un informe de los errores encontrados por la NDA.
Para corregir los datos en NDA para su envío, debe reemplazar todos los archivos csv que contenían errores en su envío original. Para hacer esto debes:
Recupere los archivos csv que se utilizaron para crear el envío original y que contienen datos que deben corregirse. Esto incluye todos los archivos csv donde es necesario agregar, eliminar o actualizar datos.
Corrija los archivos agregando, eliminando o actualizando información según sea necesario.
Ejecute vtcmd con el argumento de línea de comando -rs. Especifique el valor del envío cuyos datos necesita corregir. Luego, enumere todos los archivos csv a los que realizó correcciones. Si había un archivo csv del envío original que no contenía ningún cambio, no es necesario proporcionar el archivo como argumento en este momento.
Por ejemplo, si el envío original con ID 123456 constaba de file1.csv, file2.csv y file3.csv, y era necesario realizar correcciones en file1.csv y file2.csv, el comando para corregir errores de qa se verá así:
vtcmd -b -rs 123456 corrected-file1.csv corrected-file2.csv
Observe que file3.csv está excluido del comando porque no es necesario realizar cambios en ese archivo en particular.
Tenga en cuenta que este comando debe ejecutarse una vez para un envío y debe incluir todos los archivos que contienen correcciones a los datos . es decir, no ejecute vtcmd una vez para el archivo corregido1.csv y otra vez para el archivo corregido2.csv. Si accidentalmente omite archivos que contienen cambios necesarios al ejecutar el comando, comuníquese con el servicio de asistencia técnica en [email protected].
También tenga en cuenta que los archivos csv deben contener todos los datos enviados originalmente. es decir , si un csv originalmente tenía 800 filas y solo era necesario cambiar 3 filas, todas las 800 filas deberían estar presentes en el csv cuando se ejecuta vtcmd , no solo las 3 filas que contienen cambios. Cualquier dato que quede fuera del csv se reflejará en los números de datos esperados para la recopilación.
El script no cargará ningún archivo asociado que se haya cargado durante el envío original. Sólo será necesario subir los archivos asociados si aparecen en archivos csv corregidos pero no en ninguno de los archivos csv del envío original. Esto ahorra tiempo durante los envíos de imágenes y genómicas, donde los archivos asociados pueden tardar días en cargarse.
Para descargar datos, debe utilizar el comando downloadcmd. Esto proporciona varias opciones para descargar los datos empaquetados de su NDA o un subconjunto de los datos. Todos los archivos se descargan automáticamente a la carpeta ~nda-toolsdownloadcmdpackages , pero puede cambiar esto indicando un nuevo directorio en la línea de comando para guardar archivos. Tenga en cuenta: el límite máximo de transferencia de datos es de 20 TB por mes.
Los usuarios pueden comunicarse con la mesa de ayuda de la NDA en [email protected] y solicitar que se extienda [temporalmente] su umbral de descarga.
Todos los datos empaquetados se pueden descargar pasando el ID del paquete:
downloadcmd -dp <packageID>
Nota: NO descargará archivos asociados a menos que haya creado su paquete NDA con archivos asociados . Los pasos para descargar los archivos asociados se encuentran a continuación.
El comando downloadcmd tiene dos opciones para descargar datos dentro de archivos .txt. Si descargó su paquete NDA, encontrará archivos .txt de metadatos, muchos de los cuales representan medidas de datos. La genómica, las imágenes y otros datos asociados se enumerarán en estos archivos .txt como enlaces s3. Si desea descargar todos los enlaces s3 en su archivo .txt, puede indicarlo pasando el indicador -ds.
downloadcmd -dp <packageID> -ds path/to/data/structure/file/image03.txt
Si desea descargar su paquete NDA y todos los datos genómicos, de imágenes y otros datos asociados como una lista de enlaces s3 almacenados en un archivo .txt personalizado, puede hacerlo usando el indicador -t.
downloadcmd -dp <packageID> -t path/to/all/s3/txt/file/alls3.txt
El comando downloadcmd puede descargar su paquete NDA directamente en su depósito S3.
downloadcmd -dp <packageID> -s3 <s3 bucket>
Esta es la forma preferida de descargar datos de NDA por dos motivos:
La descarga a otro depósito de S3 es considerablemente más rápida porque los datos no salen de AWS.
Nos permite descargar una cantidad ilimitada de datos de NDA a su depósito directamente.
Para que las operaciones de copia de S3 a S3 sean exitosas, el depósito de S3 proporcionado como argumento del programa debe configurarse para permitir operaciones de objetos PUT para arn:aws:sts::618523879050:federated-user/<username> , donde <username> es su nombre de usuario de NDA.
Para depósitos no públicos, esto requerirá una actualización de la política del depósito. Se debe agregar la siguiente declaración para permitir los permisos necesarios después de reemplazar <your-s3-bucket> con el nombre del depósito:
{
"Sid": "AllowNDAUpload",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:federated-user/<username>"
},
"Action": "s3:PutObject*",
"Resource": "arn:aws:s3:::<your-s3-bucket>/*"
}Es posible que deba enviar un correo electrónico al departamento de TI de su empresa/institución para que se agregue esto.
Nota: Si su depósito de S3 está cifrado con una clave KMS administrada por el cliente, también deberá actualizar la política de la clave que se utiliza para cifrar el depósito.
Se debe agregar la siguiente declaración a la política de su clave:
{
"Sid": "EnableUseForFederatedNDA",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::618523879050:user/DownloadManager"
},
"Action": ["kms:GenerateDataKey","kms:Decrypt"],
"Resource": "*"
}Si tiene algún problema con este cliente Python de la herramienta de validación o desea enviar comentarios, envíenos un correo electrónico a [email protected].
