datalad add-sibling-dataverse
Synopsis
datalad add-sibling-dataverse [-h] [-d DATASET] [-s NAME] [--storage-name NAME] [--mode {annex,filetree,annex-only,filetree-only,git-only}] [--credential NAME] [--existing {skip,reconfigure,error}] [--root-path PATH] [--version] URL PID
Description
Add a Dataverse dataset as a sibling(-tandem)
Dataverse is a web application to share and cite research data.
This command registers an existing Dataverse dataset as a sibling of a
DataLad dataset. Both dataset version history and file content can then be
deposited at a Dataverse site via the standard push command.
Dataverse imposes strict limits on directory names (and to some degree also file name). Therefore, names of files that conflict with these rules (e.g., a directory name with any character not found in the English alphabet) are mangled on-push. This mangling does not impact file names in the DataLad dataset (also not for clones from Dataverse). See the package documentation for details.
If a DataLad's dataset version history was deposited on Dataverse, a
dataset can also be cloned from Dataverse again, via the standard clone
command.
In order to be able to use this command, a personal access token has to be generated on the Dataverse platform. You can find it by clicking on your name at the top right corner, and then clicking on API Token>Create Token.
Examples
Add a dataverse dataset sibling for sharing and citing:
% datalad add-sibling-dataverse \
-s dataverse \
https://demo.dataverse.org doi:10.5072/FK2/PMPMZM \
Options
URL
URL identifying the dataverse instance to connect to (e.g., https://demo.dataverse.org).
PID
Persistent identifier of the dataverse dataset to use as a sibling. This PID can be found on the dataset's landing page on Dataverse. Either right at the top underneath the title of the dataset as an URL or in the dataset's metadata. Both formats (doi:10.5072/FK2/PMPMZM and https://doi.org/10.5072/FK2/PMPMZM) are supported for this parameter.
-h, --help, --help-np
show this help message. --help-np forcefully disables the use of a pager for displaying the help message
-d DATASET, --dataset DATASET
specify the dataset to add the sibling to. If no dataset is given, an attempt is made to identify the dataset based on the current working directory.
-s NAME, --name NAME
name of the sibling. If none is given, the hostname-part of the URL will be used. [Default: 'dataverse']
--storage-name NAME
name of the storage sibling (git-annex special remote). Must not be identical to the sibling name. If not specified, defaults to the sibling name plus '-storage' suffix. If only a storage sibling is created, this setting is ignored, and the primary sibling name is used.
--mode {annex,filetree,annex-only,filetree-only,git-only}
Different sibling setups with varying ability to accept file content and dataset versions are supported: 'annex' for a sibling tandem, one for a dataset's Git history and one storage sibling to host any number of file versions; 'git-only' for a single sibling for the Git history only; 'annex-only' for a single annex sibling for multi-version file storage, but no dataset Git history; 'filetree' for a human-readable data organization on the dataverse end that matches the file tree of a dataset branch. This mode is useful for depositing a single dataset snapshot for consumption without DataLad. A dataset's Git history is included in the export and enabled cloning from Dataverse. 'filetree-only' disables the Git history export, and removes the ability to clone from Dataverse. When both a storage sibling and a regular sibling are created together, a publication dependency on the storage sibling is configured for the regular sibling in the local dataset clone. [Default: 'annex']
--credential NAME
name of the credential providing an API token for the dataverse installation of your choice, to be used for authorization. If no credential is given or known, a credential discovery will attempted based on the Dataverse URL. If no credential can be found, a token is prompted for.
--existing {skip,reconfigure,error}
action to perform, if a (storage) sibling is already configured under the given name. In this case, sibling creation can be skipped ('skip') or the sibling (re-)configured ('reconfigure') in the dataset, or the command be instructed to fail ('error'). [Default: 'error']
--root-path PATH
optional alternative root path for the sibling inside the Dataverse dataset. This can be used to represent multiple DataLad datasets within a single Dataverse dataset without conflict. Must be given in POSIX notation.
--version
show the module and its version which provides the command