Mercurial > hg > LGDataverses
view DVN-web/installer/dvninstall/doc/guides/dataverse-user-main.html @ 6:1b2188262ae9
adding the installer.
| author | "jurzua <jurzua@mpiwg-berlin.mpg.de>" |
|---|---|
| date | Wed, 13 May 2015 11:50:21 +0200 |
| parents | |
| children |
line wrap: on
line source
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>User Guide — The Harvard Dataverse Network 3.6.1 documentation</title> <link rel="stylesheet" href="_static/agogo.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: './', VERSION: '3.6.1', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> <link rel="top" title="The Harvard Dataverse Network 3.6.1 documentation" href="index.html" /> <link rel="next" title="Installers Guide" href="dataverse-installer-main.html" /> <link rel="prev" title="Dataverse Network Guides" href="index.html" /> </head> <body> <div class="header-wrapper"> <div class="header"> <div class="headertitle"><a href="index.html">The Harvard Dataverse Network 3.6.1 documentation</a></div> <div class="rel"> <a href="index.html" title="Dataverse Network Guides" accesskey="P">previous</a> | <a href="dataverse-installer-main.html" title="Installers Guide" accesskey="N">next</a> | <a href="genindex.html" title="General Index" accesskey="I">index</a> </div> </div> </div> <div class="content-wrapper"> <div class="content"> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="user-guide"> <h1>User Guide<a class="headerlink" href="#user-guide" title="Permalink to this headline">¶</a></h1> <div class="section" id="common-tasks"> <h2>Common Tasks<a class="headerlink" href="#common-tasks" title="Permalink to this headline">¶</a></h2> <p>Here is a list of the most common ways people use the Dataverse Network. Activities can be grouped into finding and using data or publishing data. A brief description of each activity follows with more detailed information available in the Users Guide.</p> <div class="section" id="finding-data"> <h3>Finding Data<a class="headerlink" href="#finding-data" title="Permalink to this headline">¶</a></h3> <p>Visitors to the site can browse dataverses looking for data of interest or they can search by keywords. There are Basic and Advanced Searches.</p> <p><strong>Browsing the Site</strong></p> <p>The Network Homepage presents a list of recently released dataverses on the left side of the page. A dataverse is a container for studies that can be managed as a group by the dataverse administrator. Most often a dataverse represents a single organization or scholar and so their studies are often related. On the right side of the page there are lists of both recently released studies and studies that have been downloaded most often. At the bottom of these lists, the View More link brings the user to a complete list of released dataverses or studies as applicable. The home page also includes a scrolling list of datverse collections called subnetworks, if applicable.</p> <p>Clicking on the name of a dataverse, study or subnetwork displays its home page.</p> <p><strong>Browsing Dataverses</strong></p> <p>If you click the View More link under the recently released dataverse list on the Network Homepage you’ll be brought to the Browse Dataverses page. Here you can sort the dataverses by Name, Affiliation, Release Date and Download Count. You may also filter the dataverses by typing a filter term in the “filter” text box. The filter will only display those dataverses whose name or affiliation matches the filter term. Clicking on the name of a dataverse displays its home page.</p> <p><strong>Search</strong></p> <p>For many purposes, Basic Search is sufficient. On the center top of the network homepage enter keywords or complete sentences and click <strong>Search</strong>. A resulting list of studies is displayed. Further refinement can be made by clicking facets such as “Original Dataverse” or “Author” under “Refine Results” on the left side of the page. After a facet has been clicked, it will appear at the top of the page under “Search Results for” and clicking the selected facet will remove it, restoring the previous results. In addition to the network homepage, Basic Search can be found on the upper right of the dataverse home pages as well as on the search results and Advanced Search pages. Be aware that searching from a dataverse limits the scope of search to studies within that dataverse while searching from the network home page searches all released studies.</p> <p>When a more specific search is needed, use Advanced Search. Advanced Search allows searching on keywords found in specific cataloging information fields, in particular collections in a dataverse where available, or by variable name. The link to Advanced Search is next to the Basic Search feature on the network and dataverse home pages and the search results page.</p> </div> <div class="section" id="using-data"> <h3>Using Data<a class="headerlink" href="#using-data" title="Permalink to this headline">¶</a></h3> <p>Data in the Dataverse Network is stored in files. Files of any type are allowed but some types of tabular and network data files are supported by additional functionality, including downloading in different formats, downloading subsets of variables, and analytical tools.</p> <p><strong>Download Files</strong></p> <p>To download files, click on a study of interest, then select the data tab. Individual files can be downloaded or groups of files by checking files of interest or entire file categories and clicking Download All Selected Files. Groups of files are packaged into a single <tt class="docutils literal"><span class="pre">.zip</span></tt> file. Group downloads have a download size limit and any selected files not downloaded will be indicated in the <tt class="docutils literal"><span class="pre">.zip</span></tt> file.</p> <p>Downloading individual files in an alternate format where available is straightforward. Choose the format from the Download As select box next to the file and the file will download.</p> <p><strong>Subset or Analyze Files</strong></p> <p>Tabular and Network data files of recognized formats (Stata, SPSS, RData, Graphml) can be further manipulated through downloading subsets of variables and by performing various statistical analyses. Where available these options appear as an additional link, Access Subset/Analysis, below the Download As format select box next to each file. The functionality is quite different for tabular versus network data files so refer to the Users Guide for additional information.</p> </div> <div class="section" id="publishing-data"> <h3>Publishing Data<a class="headerlink" href="#publishing-data" title="Permalink to this headline">¶</a></h3> <p>Publishing data through the Dataverse Network is straightforward: create an account and a place to store your data, organize your data, upload files, and release your data for public access.</p> <p><strong>Create a Dataverse and Account</strong></p> <p>The first step to publishing your data is to create a place to store it that can be managed by you. To do this you need an account. Create a dataverse and account by clicking on the Create a Dataverse link on the upper right side of the network homepage. This leads you through a series of steps at the end of which you will have a dataverse and user account to manage it.</p> <p>Newly created dataverses are unreleased and not available for browsing. Make note of the link to your dataverse at the end of the process so you can return to it until it becomes released. Another way to access your unreleased dataverse is to log in, click on your user name in the upper right of the page, dataverses tab, then the name of your dataverse.</p> <p><strong>Create Studies</strong></p> <p>Once you have a user account and a place to store your data, you need to take the first step toward organizing your data into studies. Many data have been or will be used to publish a study so this step may be clear. If not, a study should represent a particular thesis or inquiry with accompanying data. First, log in with your new user account and navigate to your dataverse home page. Next, click Options in the upper right of the page. From there click Create a Study and complete the form. Most of the fields on the study form are optional -only the title is required. If you are unsure of what these values should be, enter a title and these fields can be completed later before releasing the study.</p> <p>Be aware that a newly created study is unreleased and not available for browsing. To access an unreleased study for further editing, click on Options->Manage Studies and click on your study’s name. You can also click on your username, studies tab, then the study name.</p> <p><strong>Upload Files</strong></p> <p>Now that you have a place to store and manage your data and a study to associate it with, you can upload your data and documentation files. Files are uploaded to a study. Navigate to the study you want to upload particular files to and click on Add Files on the upper right side of the page. The add files page requires you to first select a file type, then browse for the file on your local system. Some file types undergo additional processing to support extended functionality but if you are unsure which type to choose, select Other. At this time you can enter a descriptive Category which can be used to group related files and a file description. If you are unsure of these values they can be added later.</p> <p>Though files are selected individually, several files can be added to this page at one time. It is recommended to upload only a few files at a time since this can take some time to complete, depending on file type.</p> <p>An alternative to selecting files individually is to first create an archive of files in <tt class="docutils literal"><span class="pre">.zip</span></tt> or <tt class="docutils literal"><span class="pre">.tar</span></tt> format and then select the appropriate “multiple files” Data Type when uploading your archive. The zip file or tarball will be unpacked so that the individual files will be added to the page.</p> <p>If you upload an SPSS (<tt class="docutils literal"><span class="pre">.por</span></tt>, <tt class="docutils literal"><span class="pre">.sav</span></tt>), Stata (<tt class="docutils literal"><span class="pre">.dta</span></tt>) or R (<tt class="docutils literal"><span class="pre">.RData</span></tt>) file, your study will be temporarily unavailable for editing until the additional processing on the file is completed. This can be brief or take some time depending on the size and complexity of the file. A message at the top of the file indicates it is unavailable for editing and an email will be sent when finished to the address you indicate on the add files page.</p> <p><strong>Release Studies</strong></p> <p>Once your study is in a state where it’s ready to be published or shared with others, it should be released. This is done either by clicking Release on the upper right of the study page or by navigating to your dataverse, clicking Options, Manage Studies, then clicking release next to the study you want released. Note that releasing a study fixes the version number. Additional changes to the study will create a new draft version. The draft can be repeatedly edited without changing the version number until it is released. At this point your study is visible within your dataverse. If your dataverse is also released it will be searchable and viewable by others. If your dataverse is not yet released, it will only be visible to people with access to your dataverse.</p> <p><strong>Release Dataverse</strong></p> <p>Releasing a dataverse makes it appear in the list of dataverses on the network home page and makes it viewable by others. This may require adding a study or other details to your dataverse depending on site policy. By default, releasing a dataverse requires nothing but changing the Dataverse Release Settings to Released on the Manage Permissions page. To release your dataverse, navigate to the dataverse home page, choose Options from the upper right of the page, click on Dataverse Settings, then Manage Permissions. At the top of the page, change Dataverse Release Settiings to Released and click Save Changes.</p> <p>Any studies that are released are now visible to others. Those that are unreleased do not appear in the list of studies on the dataverse home page.</p> <p>At this point you have published one or more studies and their data and made them available for browsing or searching.</p> </div> <div class="section" id="things-to-consider-next-steps"> <h3>Things to Consider, Next Steps<a class="headerlink" href="#things-to-consider-next-steps" title="Permalink to this headline">¶</a></h3> <p>The above tasks are fundamental activities and may be all that is needed for most users. Some situations are more complex and require additional consideration. These include publishing and organizing data for large organizations, shared research between scholars, and enabling contributions by a geographically diverse team while keeping data private until ready for publication.</p> <p>For <strong>large organizations</strong>, a single dataverse may suffice. Collections within a dataverse can further organize studies by sub unit or topic. The dataverse itself can be <strong>customized</strong> with the organizations own website header and footer. In some cases, sub units or organizations want to maintain their own distinct branding. In such cases each can create and maintain their own dataverse and the parent dataverse can link to their studies through a link collection.</p> <p>For <strong>shared research</strong>, the model is similar: a single dataverse based on the research project can be created to which both researchers have administration rights. Additionally, researchers can maintain their own dataverses for other work and link back to the studies in the shared project dataverse.</p> <p><strong>Allowing a diverse team to contribute</strong> to an unreleased dataverse is simply a matter of granting the appropriate level of <strong>permissions</strong> to each team member. At minimum, each team member would need to be added as a contributor to the dataverse. By default, they can only contribute to studies they themselves have created. However, this can be expanded from the dataverse Manage Permissions page to allow contributors to edit all studies in the dataverse. Changes made by contributors need to be approved by a curator or admin before a study can be released.</p> </div> <div class="section" id="how-the-guides-are-organized"> <h3>How the Guides Are Organized<a class="headerlink" href="#how-the-guides-are-organized" title="Permalink to this headline">¶</a></h3> <p>The guides are reference documents that explain how to use the Dataverse Network functionality: Installers Guide, Developers Guide, APIs Guide, and Users Guide. The Users Guide is further divided into primary activities: using data, creating studies, administering dataverses or the network. Details on all of the above tasks can be found in the Users Guide. The Installers Guide is for people or organizations who want to host their own Dataverse Network. The Developers Guide contains instructions for people who want to contribute to the Open Source Dataverse Network project or who want to modify the code to suit their own needs. Finally, the APIs Guide is for people who would like to use our APIs in order to build apps that can work with the Dataverse Network web application. This <a class="reference external" href="http://thedata.org/book/apps">page</a> lists some current apps which have been developed with our APIs.</p> </div> <div class="section" id="other-resources"> <h3>Other Resources<a class="headerlink" href="#other-resources" title="Permalink to this headline">¶</a></h3> <p><strong>Dataverse Network Project Site</strong></p> <p>Additional information about the Dataverse Network project itself including presentations, information about upcoming releases, data management and citation, and announcements can be found at <a class="reference external" href="http://thedata.org/">http://thedata.org</a></p> <p><strong>User Group</strong></p> <p>As the user community grows we encourage people to shares ideas, ask questions, or offer suggestions for improvement. Go to <a class="reference external" href="https://groups.google.com/group/dataverse-community">https://groups.google.com/group/dataverse-community</a> to register to our dataverse community group.</p> <p><strong>Follow Us on Twitter</strong></p> <p>For up to date news, information and developments, follow our twitter account: <a class="reference external" href="https://twitter.com/thedataorg">https://twitter.com/thedataorg</a></p> <p><strong>Support</strong></p> <p>We maintain an email based support service that’s free of charge. We attempt to respond within one business day to all questions and if it cannot be resolved immediately, we’ll let you know what to expect.</p> </div> <div class="section" id="contact-us"> <h3>Contact Us<a class="headerlink" href="#contact-us" title="Permalink to this headline">¶</a></h3> <p>The support email address is <a class="reference external" href="mailto:support%40thedata.org">support<span>@</span>thedata<span>.</span>org</a>.</p> <p>This is the same address as the Report Issue link. We try to respond within one business day.</p> </div> </div> <div class="section" id="finding-and-using-data"> <span id="id1"></span><h2>Finding and Using Data<a class="headerlink" href="#finding-and-using-data" title="Permalink to this headline">¶</a></h2> <p>Ends users, without need to login to the Dataverse Network, can browse dataverses, search studies, view study description and data files for public studies, and subset, analyze and visualize data for public data files. If entire studies or individual data files are restricted, end users need to be given permission from the dataverse administrator to access the data.</p> <div class="section" id="search"> <h3>Search<a class="headerlink" href="#search" title="Permalink to this headline">¶</a></h3> <p>To find a study or data set, you can search or browse studies offered in any released dataverse on the Network homepage. Each dataverse offers a hierarchical organization comprising one or more collections of data sets with a particular theme. Most dataverses allow you to search for data within their files, or you can start browsing through the dataverse classifications that are closest to your substantive interests.</p> <p><strong>Browse Collections</strong></p> <p>You can browse all public dataverses from the Network homepage. Click the title of a dataverse to browse that dataverse’s collections and studies. Click the title of a collection to view a list of studies and subcollections for that selection. Click the title of a study to view the Cataloging Information and study files for that selection.</p> <p>When you select a dataverse to view its contents, the homepage opens to the <em>root collection</em>, and the dataverse’s studies are displayed directly under the root collection name. If the root collection contains other collections, then those collections are listed and not the studies within them. You must select a collection title to view the studies contained within it.</p> <p>Note: If a dataverse includes links to collections from another dataverse and the root collection does not contain other collections, the homepage opens to a list of the root and linked collections.</p> <p><strong>Search - Basic</strong></p> <p>You can search for studies across the entire Dataverse Network from the Network homepage, or search within a dataverse from the dataverse homepage. When you search across the Network, studies from restricted dataverses are not included in the search. Restricted studies are included in search results, and a lock icon appears beside those studies in the results list. After your search is complete, you can further narrow your list of data by searching again in the results. See Search Tips for search examples and guidelines.</p> <p>When you enter more than one term in the search text field, the results list contains studies that have these terms near each other within the study fields searched. For example, if you enter <tt class="docutils literal"><span class="pre">United</span> <span class="pre">Nations</span></tt>, the results include studies where the words <em>United</em> and <em>Nations</em> are separated by no more than four words in the same study field, such as abstract or title.</p> <p>It supports a search in any field of the studies’ Cataloging Information, which includes citation information, abstract and other scope-related information, methodology, and Terms of Use. In addition, file descriptions also are searched.</p> <p><strong>Search - Advanced</strong></p> <p>In an advanced search, you can refine your criteria by choosing which Cataloging Information fields to search. You also can apply logic to the field search. For text fields, you can specify that the field searched either <em>contains</em> or <em>does not containthe text that you enter. For date fields, you can specify that the field searched is either *later than</em> nor <em>earlier than</em> the date that you enter. Refer to the <a class="reference external" href="http://lucene.apache.org/java/docs/">Documentation</a> page for the latest version at the Lucene website and look for <em>Query Syntax</em> for full details.</p> <p>To perform an advanced search, click the Advanced Search link at the top-right of the Search panel. You can search the following study metadata fields by using the Search Scope drop-down list:</p> <ul class="simple"> <li>Title - Title field of studies’ Cataloging Information.</li> <li>Author - Author fields of studies’ Cataloging Information.</li> <li>(Study) Global ID - ID assigned to studies.</li> <li>Other ID - A different ID previously given to the study by another archive.</li> <li>Abstract - Any words in the abstract of the study.</li> <li>Keyword - A term that defines the nature or scope of a study. For example, <tt class="docutils literal"><span class="pre">elections</span></tt>.</li> <li>Keyword Vocabulary - Reference to the standard used to define the keywords.</li> <li>Topic Classification - One or more words that help to categorize the study.</li> <li>Topic Classification Vocabulary - Reference used to define the Topic Classifications.</li> <li>Producer - Institution, group, or person who produced the study.</li> <li>Distributor - Institution that is responsible for distributing the study.</li> <li>Funding Agency - Agency that funded the study.</li> <li>Production Date - Date on which the study was created or completed.</li> <li>Distribution Date - Date on which the study was distributed to the public.</li> <li>Date of Deposit - Date on which the study was uploaded to the Network.</li> <li>Time Period Cover Start - The beginning of the period covered by the study.</li> <li>Time Period Cover End - The end of the period covered by the study.</li> <li>Country/Nation - The country or countries where the study took place.</li> <li>Geographic Coverage - The geographical area covered by the study. For example, <tt class="docutils literal"><span class="pre">North</span> <span class="pre">America</span></tt>.</li> <li>Geographic Unit - The smallest geographic unit in which the study took place, such as <tt class="docutils literal"><span class="pre">state</span></tt>.</li> <li>Universe - Universe of interest, population of interest, or target population.</li> <li>Kind of Data - The type of data included in the file, such as <tt class="docutils literal"><span class="pre">survey</span> <span class="pre">data</span></tt>, <tt class="docutils literal"><span class="pre">census/enumeration</span> <span class="pre">data</span></tt>, or <tt class="docutils literal"><span class="pre">aggregate</span> <span class="pre">data</span></tt>.</li> <li>Variable Information - The variable name and description in the studies’ data files, given that the data file is subsettable and contains tabular data. It returns the studies that contain the file and the variable name where the search term was found.</li> </ul> <p><strong>Sort Results</strong></p> <p>When your search is complete, the results page lists studies that met the search criteria in order of relevance. For example, a study that includes your search term within the Cataloging Information in ten places appears before a study that includes your search term in the Cataloging Information in only one place.</p> <p>You can sort search results by title, study ID, last updated, or number of downloads (that is, the number of times users downloaded any file belonging to that study). Click the Sort By drop-down list to choose your sort order.</p> <p><strong>Search Tips</strong></p> <p>Use the following guidelines to search effectively within a Network or a dataverse:</p> <ul> <li><p class="first">The default search syntax uses <tt class="docutils literal"><span class="pre">AND</span></tt> logic within individual fields. That is, if you enter more than one term, the search engine looks for all terms within a single field, such as title or abstract. For example, if you enter <tt class="docutils literal"><span class="pre">United</span> <span class="pre">Nations</span> <span class="pre">report</span></tt>, the results list any studies that include the terms <em>United</em>, <em>Nations</em>, and <em>report</em> within a single metadata field.</p> </li> <li><p class="first">The search logic looks for multiple terms within a specific proximity to one another, and in the same field. The current proximity criteria is four words. That is, if you enter two search terms, both terms must be within four words of each other in the same field to be returned as a result. For example, you might enter <tt class="docutils literal"><span class="pre">10</span> <span class="pre">year</span></tt> in a basic search. If a study includes the string <em>10 millions deaths per year</em> within a metadata field, such as abstract, that study is not included in the search results. A study that contains the string <em>10 per year</em> within the abstract field is included in the search results.</p> </li> <li><p class="first">During the index process that supports searches, periods are removed in strings and each term between periods is indexed individually. If you perform a basic search for a term that contains one or more periods, the search works because the analyzer applies the <em>AND</em> logic. If you search on a specific field, though, note that you should specify individually each component of the string between periods to return your results.</p> </li> <li><p class="first">You can enter one term in the search field, and then search within those results for another term to narrow the results further. This might be more effective than searching for both terms at one time, if those terms do not meet the proximity and field limits specified previously. You could search first for an author’s name, and then search those results for a specific term in the title. If you try searching for both terms in the author and title fields together, you might not find the study for which you are looking. For example, you can search the Harvard Dataverse Network for the following study:</p> <blockquote> <div><p><em>Gary King; Will Lowe, 2003, “10 Million International Dyadic Events”, hdl:1902.1/FYXLAWZRIA UNF:3:um06qkr/1tAwpS4roUqAiw== Murray Research Archive [Distributor]</em></p> </div></blockquote> <p>If you type <tt class="docutils literal"><span class="pre">King,</span> <span class="pre">10</span> <span class="pre">Million</span></tt> in the Search field and click Search, you see <tt class="docutils literal"><span class="pre">0</span> <span class="pre">matches</span> <span class="pre">were</span> <span class="pre">found</span></tt> in the Results field. If you type <tt class="docutils literal"><span class="pre">10</span></tt> in the Search field and click Search, you see something like <tt class="docutils literal"><span class="pre">1621</span> <span class="pre">matches</span> <span class="pre">were</span> <span class="pre">found</span></tt> in the Results field. But if you first type <tt class="docutils literal"><span class="pre">King</span></tt> in the Search field and click Search, then type <tt class="docutils literal"><span class="pre">10</span> <span class="pre">Million</span></tt> in the Search field and click Search again, you see something like <tt class="docutils literal"><span class="pre">4</span> <span class="pre">matches</span> <span class="pre">were</span> <span class="pre">found</span></tt> in the Results field.</p> </li> </ul> </div> <div class="section" id="view-studies-download-data"> <h3>View Studies / Download Data<a class="headerlink" href="#view-studies-download-data" title="Permalink to this headline">¶</a></h3> <p><strong>Cataloging Information</strong></p> <p>When a study is created, a set of <em>metadata</em> is associated with that study. This metadata is called the <em>Cataloging Information</em> for the study. When you select a study to view it, you first see the Cataloging Information tab listing the metadata associated with that study. This is the default view of a study.</p> <p>Cataloging Information contains numerous fields that help to describe the study. The amount of information you find for each study varies, based on what was entered by the author (Contributor) or Curator of that study. For example, one study might display the distributor, related material, and geographic coverage. Another study might display only the authors and the abstract. Every study includes the <em>Citation Information</em> fields in the Cataloging Information.</p> <p>Note: A comprehensive list of all Cataloging Information fields is provided in the <a class="reference internal" href="#metadata-references"><em>List of Metadata References</em></a></p> <p>Cataloging Information is divided into four sections. These sections and their details are displayed only when the author (Contributor) or Curator provides the information when creating the study. Sections consist of the following:</p> <ul class="simple"> <li>Citation Information - These fields comprise the <a class="reference external" href="http://thedata.org/citation">citation</a> for the study, consisting of a global identifier for all studies and a UNF, or Universal Numerical Fingerprint, for studies that contain subsettable data files. It also can include information about authors, producers and distributors, and references to related studies or papers.</li> <li>Abstract and Scope - This section describes the research study, lists the study’s data sets, and defines the study’s geographical scope.</li> <li>Data Collection/Methodology - This section includes the technical details of how the author obtained the data.</li> <li>Terms of Use - This information explains that the study requires users to accept a set of conditions or agreements before downloading or analyzing the data. If any <em>Terms of Use</em> text is displayed in the Cataloging Information section, you are prompted to accept the conditions when you click the download or analyze icons in the Files page. Note: A study might not contain Terms of Use, but in some cases the original parent dataverse might have set conditions for all studies owned by that dataverse. In that case, the conditions are inherited by the study and you must accept these conditions before downloading files or analyzing the data.</li> </ul> <p>Study metadata can be downloaded in XML format using a link at the bottom of the study Cataloging Information tab: <a class="reference external" href="https://thedata.harvard.edu/dvn/api/metadata/91148?partialExclude=codeBook/dataDscr">DDI (without variables)</a> / <a class="reference external" href="https://thedata.harvard.edu/dvn/api/metadata/91148">DDI (full)</a>. These links appear for released studies whose metadata has been exported. Studies are typically exported on a daily basis.</p> <p><strong>List of Study Files</strong></p> <p>When you view a study, click the Documentation, Data and Analysis tab to view a list of all electronic files associated with the study that were provided by the author or Curator.</p> <p>A study might contain documentation, data, or other files. When the study contributor uploads data files of the type <tt class="docutils literal"><span class="pre">.dta</span></tt>, <tt class="docutils literal"><span class="pre">.sav</span></tt>, or <tt class="docutils literal"><span class="pre">.por</span></tt> to the Network, those files are converted to <tt class="docutils literal"><span class="pre">.tab</span></tt> tab-delimited files. These <tt class="docutils literal"><span class="pre">.tab</span></tt> files are subsettable, and can be subsetted and analyzed online by using the Dataverse Network application.</p> <p>Data files of the type <tt class="docutils literal"><span class="pre">.xml</span></tt> also are considered to be subsettable, and can be subsetted and analyzed to a minimal degree online. An <tt class="docutils literal"><span class="pre">.xml</span></tt> type file indicates social network data that complies with the <a class="reference external" href="http://graphml.graphdrawing.org/">GraphML</a> file format.</p> <p>You can identify a subsettable data file by the <em>Subsetting</em> label and the number of cases and variables listed next to the file name. Other files that also contain data might be associated with a study, but the Dataverse Network application does not recognize them as data (or subsettable) files.</p> <p><strong>Download Study Files</strong></p> <p>You can download any of the following within a study:</p> <ul class="simple"> <li>All or selected data files within a <em>study</em> or a <em>category</em> (type of files)</li> <li>Individual <em>data files</em></li> <li>Individual subsets within a data file (see <a class="reference internal" href="#tabular-data"><em>Subset and Analyze Tabular Data Sets</em></a> or <a class="reference internal" href="#network-data"><em>Subset and Analyze Network Data Sets</em></a> for details)</li> </ul> <p>The default format for subsettable tabular data file downloads is <em>tab-delimited</em>. When you download one or more subsettable files in tab-delimited format, the file contains a header row. When you download one subsettable file, you can select from the following formats in addition to tab-delimited:</p> <ul class="simple"> <li>Original file</li> <li>Splus</li> <li>Stata</li> <li>R</li> </ul> <p>The default format for subsettable network data file downloads is <em>Original file</em>. In addition, you can choose to download network data files in <em>GraphML</em> format.</p> <p>If you select any other format for a tabular data file, the file is downloaded in a zipped archive. You must unzip the archive to view or use the individual data file.</p> <p>If you download all or a selection of data files within a study, the files are downloaded in a zipped archive, and the individual files are in tab-delimited or network format. You must unzip the archive to view or use the individual data files.</p> <p>Note: Studies and data files often have user restrictions applied. If prompted to accept Terms of Use for a study or file, check the <em>I Accept</em> box and then click the Continue button to view or download the file.</p> <p><strong>User Comments</strong></p> <p>If the User Comment feature is enabled within a dataverse, users are able to add comments about a study within that dataverse.</p> <p>When you view a study, click the User Comments tab to view all comments associated with the study. Comments can be monitored and abuse reported to the Network admin, who has permission to remove any comments deemed inappropriate. Note that the dataverse admin does not have permission to remove comments, to prevent bias.</p> <p>If you choose, you also can add your own comments to a study from the User Comments tab. See <a class="reference internal" href="#edit-study-comments-settings"><em>Comment on Studies or Data</em></a> for detailed information.</p> <p>Note: To add a comment to a study, you must register and create an account in the dataverse that owns the study about which you choose to comment. This helps to prevent abuse and SPAM issues.</p> <p><strong>Versions</strong></p> <p>Upon creating a study, a version is created. This is a way to archive the <em>metadata</em> and <em>data files</em> associated with the study citation or UNF.</p> <p><strong>View Citations</strong></p> <p>You can view a formatted citation for any of the following entities within the Dataverse Network application:</p> <ul class="simple"> <li>Studies - For every study, you can view a citation for that study. Go to the Cataloging Information tab for a study and view the <em>How to Cite</em> field.</li> <li>Data sets - For any data set, you can view a citation for that set. Go to the Documentation, Data and Analysis tab for a study to see the list of study files. To view the citation for any data set click the <em>View Data Citation</em> link associated with that subsettable file.</li> <li>Data subsets - If you subset and analyze a data set, you can view a citation for each subset. See <a class="reference internal" href="#apply-descriptive-statistics"><em>Apply Descriptive Statistics</em></a> or <a class="reference internal" href="#perform-advanced-analysis"><em>Perform Advanced Analysis</em></a> for detailed information. Also, when you download a workspace file, a copy of the citation information for that subset is provided in the download.</li> </ul> <p>Note: For individual variables within a subsettable data subset, you can view the <a class="reference external" href="http://thedata.org/citation/tech">UNF</a> for that variable. This is not a full citation for the variable, but it is one component of that citation. Note also that this does not apply to <tt class="docutils literal"><span class="pre">.xml</span></tt> data.</p> </div> <div class="section" id="subset-and-analysis"> <h3>Subset and Analysis<a class="headerlink" href="#subset-and-analysis" title="Permalink to this headline">¶</a></h3> <p>Subsetting and analysis can be performed on tabular and network data files. Refer to the appropriate section for more details.</p> <div class="section" id="tabular-data"> <span id="id2"></span><h4>Tabular Data<a class="headerlink" href="#tabular-data" title="Permalink to this headline">¶</a></h4> <p>Tabular data files (subsettable files) can be subsetted and analyzed online by using the Dataverse Network application. For analysis, the Dataverse Network offers a user interface to Zelig, a powerful, R-based statistical computing tool. A comprehensive set of Statistical Analysis Models are provided.</p> <p>After you find the tablular data set that you want, access the Subset and Analysis options to use the online tools. Then, you can <em>subset data by variables or observations</em>, translate it into a convenient format, download subsets, and apply statistics and analysis.</p> <p>Network data files (also subsettable) can be subsetted online, and then downloaded as a subset. Note that network data files cannot be analyzed online.</p> <p>Review the Tabular Data Subset and Recode Tips before you start.</p> <p><strong>Access Subset and Analysis Options</strong></p> <p>You can subset and analyze tabular data files before you download the file or your subsets.</p> <p>To access the Subset and Analysis options for a data set:</p> <ol class="arabic simple"> <li>Click the title of the study from which you choose to analyze or download a file or subset.</li> <li>Click the Documentation, Data and Analysis tab for the study.</li> <li>In the list of study files, locate the data file that you choose to download, subset, or analyze. You can download data sets for a file only if the file entry includes the subset icon.</li> <li>Click the <em>Access Subset/Analysis</em> link associated with the selected file. If prompted, check the <em>I accept</em> box and click Continue to accept the Terms of Use. You see the Data File page listing data for the file that you choose to subset or analyze.</li> </ol> <p><strong>View Variable Quick Summary</strong></p> <p>When a subsettable data file is uploaded for a study, the Dataverse Network code calculates summary statistics for each variable within that data file. On any tab of the Data File page, you can view the summary statistics for each variable in the data file. Information listed comprises the following:</p> <ul class="simple"> <li>For continuous variables, the application calculates summary statistics that are listed in the DDI schema.</li> <li>For discrete variables, the application tabulates values and their labels as a frequency table. Note, however, that if the number of categories is more than 50, the values are not tabulated.</li> <li>The UNF value for each variable is included.</li> </ul> <p>To view summary statistics for a variable:</p> <ol class="arabic simple"> <li>In the Data File page, click any tab.</li> <li>In the variable list on the bottom of the page, the right column is labeled <em>Quick Summary</em>. locate a variable for which you choose to view summary statistics. Then, click the Quick Summary icon for that variable to toggle the statistic’s information on and off. You see a small chart that lists information about that variable. The information provided depends upon the variable selected.</li> </ol> <p><strong>Download Tabular Subsets</strong></p> <p>You can download a subset of variables within a tabular-data study file. You also can recode a subset of those variables and download the recoded subset, if you choose.</p> <p>To download a subset of variables in tabular data:</p> <ol class="arabic simple"> <li>In the Data File page, click the Download Subset tab.</li> <li>Click the radio button for the appropriate File Format in which to download the variables: Text, R Data, S plus, or Stata.</li> <li>On the right side of the tab, use the Show drop-down list to select the quantities of variables to list at one time: 10, 20, 50, or All.</li> <li>Scroll down the screen and click the check boxes to select variables from the table of available values. When you select a variable, it is added to the Selected Variables box at the top of the tab. To remove a variable from this box, deselect it from the Variable Type list at the bottom of the screen. To select all variables, click the check box beside the column name, Variable Type.</li> <li>Click the <em>Create Zip File</em> button. The <em>Create Zip File</em> button label changes the following format: <tt class="docutils literal"><span class="pre">zipFile_<number>.zip</span></tt>.</li> <li>Click the <tt class="docutils literal"><span class="pre">zipFile_<number>.zip</span></tt> button and follow your browser’s prompts to open or save the data file to your computer’s disk drive</li> </ol> <p id="apply-descriptive-statistics"><strong>Apply Descriptive Statistics</strong></p> <p>When you run descriptive statistics for data, you can do any of the following with the analysis results:</p> <ul class="simple"> <li>Open the results in a new window to save or print the results.</li> <li>Download the R workspace in which the statistics were analyzed, for replication of the analysis. See Replicate Analysis for more information.</li> <li>View citation information for the data analyzed, and for the full data set from which you selected variables to analyze. See View Citations for more information.</li> </ul> <p>To apply descriptive statistics to a data set or subset:</p> <ol class="arabic simple"> <li>In the Data File page, click the Descriptive Statistics tab.</li> <li>Click one or both of the Descriptive Statistics options: Univariate Numeric Summaries and Univariate Graphic Summaries.</li> <li>On the right side of the tab, use the Show drop-down list to select one of the following options to show variables in predefined quantities: 10, 20, 50, or All.</li> <li>Scroll down the screen and click the check boxes to select variables from the table of available values. When you select a variable, it is added to the Selected Variables box at the top of the tab. To remove a variable from this box, deselect it from the Variable Type list at the bottom of the screen. To select all variables, click the check box beside the column name, Variable Type.</li> <li>Click the Run Statistics button. You see the Dataverse Analysis page.</li> <li>To save or print the results, scroll to the Descriptive Statistics section and click the link <em>Open results in a new window</em>. You then can print or save the window contents. To save the analysis, scroll to the Replication section and click the button <em>zipFile_<number>.zip</em>. Review the Citation Information for the data set and for the subset that you analyzed.</li> <li>Click the link <em>Back to Analysis and Subsetting</em> to return the previous page and continue analysis of the data.</li> </ol> <p><strong>Recode and Case-Subset Tabular Data</strong></p> <p>Review the Tabular Data Recode and Subset Tips before you start work with a study’s files.</p> <p>To recode and subset variables within a tabular data set:</p> <ol class="arabic simple"> <li>In the Data File page, click the Recode and Case-Subsetting tab.</li> <li>One the right side of the variable list, use the Show drop-down list and select one of the following options to show variables in predefined quantities: 10, 20, 50, or All.</li> <li>Scroll down the screen and click the check boxes to select variables from the table of available values. When you select a variable, it is added to the Selected Variables box at the top of the tab. To remove a variable from this box, deselect it from the Variable Type list at the bottom of the screen. To select all variables, click the check box beside the column name, Variable Type.</li> <li>Select one variable in the Selected Variables box, and then click <em>Start</em>. The existing name and label of the variable appear in the New Variable Name and New Variable Label boxes.</li> <li>In the New Variable Label field, change the variable name to a unique value that is not used in the data file. The new variable label is optional.</li> <li>In the table below the Variable Name fields, you can check one or more values to drop them from the subset, or enter new values, labels, or ranges (as a condition) as needed. Click the Add Value/Range button to create more entries in the value table. Note: Click the <tt class="docutils literal"><span class="pre">?</span></tt> Info buttons to view tips on how to use the Recode and Subset table. Also, See Tabular Data Recode and Subset Tips for more information about adding values and ranges.</li> <li>Click the Apply Recodes button. Your renamed variables appear at the bottom of the page in the List of Recode Variables.</li> <li>Select another variable in the Selected Variables box, click the Start button, and repeat the recode action. Repeat this process for each variable that you choose to recode.</li> <li>To remove a recoded variable, scroll to the List of Recode Variables at the bottom of the page and click the Remove link for the recoded variable that you choose to delete from your subset.</li> </ol> <p id="perform-advanced-analysis"><strong>Perform Advanced Analysis</strong></p> <p>When you run advanced statistical analysis for data, you can do any of the following with the analysis results:</p> <ul class="simple"> <li>Open the results in a new window to save or print the results.</li> <li>Download the R workspace in which the statistics were analyzed, for replication of the analysis. See Replicate Analysis for more information.</li> <li>View citation information for the data analyzed, and for the full data set from which you selected variables to analyze. See View Citations for more information.</li> </ul> <p>To run statistical models for selected variables:</p> <ol class="arabic simple"> <li>In the Data File page, click the Advanced Statistical Analysis tab.</li> <li>Scroll down the screen and click the check boxes to select variables from the table of available values. When you select a variable, it is added to the Selected Variables box at the top of the tab. To remove a variable from this box, deselect it from the Variable Type list at the bottom of the screen. To select all variables, click the check box beside the column name, Variable Type.</li> <li>Select a model from the Choose a Statistical Model drop-down list.</li> <li>Select one variable in the Selected Variables box, and then click the applicable arrow button to assign a function to that variable from within the analysis model. You see the name of the variables in the appropriate function box. Note: Some functions allow a specific type of variable only, while other functions allow multiple variable types. Types include Character, Continuous, and Discrete. If you assign an incorrect variable type to a function, you see an <tt class="docutils literal"><span class="pre">Incompatible</span> <span class="pre">type</span></tt> error message.</li> <li>Repeat the variable and function assignments until your model is complete.</li> <li>Select your Output options.</li> <li>Click the Run Model button. If the statistical model that you defined is incomplete, you first are prompted to correct the definition. Correct your model, and then click Run Model again. You see the Dataverse Analysis page.</li> <li>To save or print the results, scroll to the Advanced Statistical Analysis section and click the link <em>Open results in a new window</em>. You then can print or save the window contents. To save the analysis, scroll to the Replication section and click the button <tt class="docutils literal"><span class="pre">zipFile_<number>.zip</span></tt>. Review the Citation Information for the data set and for the subset that you analyzed.</li> <li>Click the link <em>Back to Analysis and Subsetting</em> to return the previous page and continue analysis of the data.</li> </ol> <p><strong>Replicate Analysis</strong></p> <p>You can save the R workspace in which the Dataverse Network performed an analysis. You can download the workspace as a zipped archive that contains four files. Together, these files enable you to recreate the subset analysis in another R environment:</p> <ul class="simple"> <li><tt class="docutils literal"><span class="pre">citationFile.<identifier>.txt</span></tt> - The citation for the subset that you analyzed.</li> <li><tt class="docutils literal"><span class="pre">rhistoryFile.<identifier>.R</span></tt> - The R code used to perform the analysis.</li> <li><tt class="docutils literal"><span class="pre">tempsubsetfile.<identifier>.tab</span></tt> - The R object file used to perform the analysis.</li> <li><tt class="docutils literal"><span class="pre">tmpRWSfile.<identifier>.RData</span></tt> - The subset data that you analyzed.</li> </ul> <p>To download this workspace for your analysis:</p> <ol class="arabic simple"> <li>For any subset, Apply Descriptive Statistics or Perform Advanced Analysis.</li> <li>On the Dataverse Analysis or Advanced Statistical Analysis page, scroll to the Replication section and click the button <tt class="docutils literal"><span class="pre">zipFile_<number>.zip</span></tt>.</li> <li>Follow your browser’s prompts to save the zipped archive. When the archive file is saved to your local storage, extract the contents to use the four files that compose the R workspace.</li> </ol> <p><strong>Statistical Analysis Models</strong></p> <p>You can apply any of the following advanced statistical models to all or some variables in a tabular data set:</p> <p>Categorical data analysis: Cross tabulation</p> <p>Ecological inference model: Hierarchical mulitnomial-direct ecological inference for R x C tables</p> <p>Event count models, for event count dependent variables:</p> <ul class="simple"> <li>Negative binomial regression</li> <li>Poisson regression</li> </ul> <p>Models for continuous bounded dependent variables:</p> <ul class="simple"> <li>Exponential regression for duration</li> <li>Gamma regression for continuous positives</li> <li>Log-normal regression for duration</li> <li>Weibull regression for duration</li> </ul> <p>Models for continuous dependent variables:</p> <ul class="simple"> <li>Least squares regression</li> <li>Linear regression for left-censoreds</li> </ul> <p>Models for dichotomous dependent variables:</p> <ul class="simple"> <li>Logistic regression for binaries</li> <li>Probit regression for binaries</li> <li>Rare events logistic regression for binaries</li> </ul> <p>Models for ordinal dependent variables:</p> <ul class="simple"> <li>Ordinal logistic regression for ordered categoricals</li> <li>Ordinal probit regression for ordered categoricals</li> </ul> <p><strong>Tabular Data Recode and Subset Tips</strong></p> <p>Use the following guidelines when working with tabular data files:</p> <ul class="simple"> <li>Recoding:<ul> <li>You must fill at least the first (new value) and last (condition) columns of the table; the second column is optional and for a new value label.</li> <li>If the old variable you chose for recoding has information about its value labels, you can prefill the table with these data for convenience, and then modify these prefilled data.</li> <li>To exclude a value from your recoding scheme, click the Drop check box in the row for that value.</li> </ul> </li> <li>Subsetting:<ul> <li>If the variable you chose for subsetting has information about its value labels, you can prefill the table with these data for convenience.</li> <li>To exclude a value in the last column of the table, click the Drop check box in row for that value.</li> <li>To include a particular value or range, enter it in the last column whose header shows the name of the variable for subsetting.</li> </ul> </li> <li>Entering a value or range as a condition for subsetting or recoding:<ul> <li>Suppose the variable you chose for recoding is x. If your condition is x==3, enter <tt class="docutils literal"><span class="pre">3</span></tt>. If your condition is x < -3, enter <tt class="docutils literal"><span class="pre">(--3</span></tt>. If your condition is x > -3, enter <tt class="docutils literal"><span class="pre">-3-)</span></tt>. If your condition is -3 < x < 3, enter <tt class="docutils literal"><span class="pre">(-3,</span> <span class="pre">3)</span></tt>.</li> <li>Use square brackets (<tt class="docutils literal"><span class="pre">[]</span></tt>) for closed ranges.</li> <li>You can enter non-overlapping values and ranges separated by a comma, such as <tt class="docutils literal"><span class="pre">0,[7-9]</span></tt>.</li> </ul> </li> </ul> </div> <div class="section" id="network-data"> <span id="id3"></span><h4>Network Data<a class="headerlink" href="#network-data" title="Permalink to this headline">¶</a></h4> <p>Network data files (subsettable files) can be subsetted and analyzed online by using the Dataverse Network application. For analysis, the Dataverse Network offers generic network data analysis. A list of Network Analysis Models are provided.</p> <p>Note: All subsetting and analysis options for network data assume a network with undirected edges.</p> <p>After you find the network data set that you want, access the Subset and Analysis options to use the online tools. Then, you can subset data by <em>vertices</em> or <em>edges</em>, download subsets, and apply network measures.</p> <p><strong>Access Network Subset and Analyze Options</strong></p> <p>You can subset and analyze network data files before you download the file or your subsets. To access the Subset and Analysis options for a network data set:</p> <ol class="arabic simple"> <li>Click the title of the study from which you choose to analyze or download a file or subset.</li> <li>Click the Documentation, Data and Analysis tab for the study.</li> <li>In the list of study files, locate the network data file that you choose to download, subset, or analyze. You can download data sets for a file only if the file entry includes the subset icon.</li> <li>Click the <em>Access Subset/Analysis</em> link associated with the selected file. If prompted, check the <em>I accept</em> box and click Continue to accept the Terms of Use. You see the Data File page listing data for the file that you choose to subset or analyze.</li> </ol> <p><strong>Subset Network Data</strong></p> <p>There are two ways in which you can subset network data. First, you can run a manual query, and build a query of specific values for edge or vertex data with which to subset the data. Or, you can select from among three automatically generated queries with which to subset the data:</p> <ul class="simple"> <li>Largest graph - Subset the <nth> largest connected component of the network. That is, the largest group of nodes that can reach one another by walking across edges.</li> <li>Neighborhood - Subset the <nth> neighborhood of the selected vertices. That is, generate a subgraph of the original network composed of all vertices that are positioned at most <n> steps away from the currently selected vertices in the original network, plus all of the edges that connect them.</li> </ul> <p>You also can successively subset data to isolate specific values progressively.</p> <p>Continue to the next topics for detailed information about subsetting a network data set.</p> <p><strong>Subset Manually</strong></p> <p>Perform a manual query to slice a graph based on the attributes of its vertices or edges. You choose whether to subset the graph based on vertices or edges, then use the Manual Query Builder or free-text Query Workspace fields to construct a query based on that element’s attributes. A single query can pertain only to vertices or only to edges, never both. You can perform separate, sequential vertex or edge queries.</p> <p>When you perform a vertex query, all vertices whose attributes do not satisfy the query are dropped from the graph, in addition to all edges that touch them. When you perform an edge query, all edges whose attributes do not satisfy the criteria are dropped, but all vertices remain <em>unless</em> you enable the <em>Eliminate disconnected vertices</em> check box. Note that enabling this option drops all disconnected vertices whether or not they were disconnected before the edge query.</p> <p>Review the Network Data Tips before you start work with a study’s files.</p> <p>To subset variables within a network data set by using a manually defined query:</p> <ol class="arabic"> <li><p class="first">In the Data File page, click the Manual Query radio button near the top of the page.</p> </li> <li><p class="first">Use the Attribute Set drop-down list and select Vertex to subset by node or vertex values. Select Edge to subset by edge values.</p> </li> <li><p class="first">Build the first attribute selection value in the Manual Query Builder panel:</p> <ol class="arabic simple"> <li>Select a value in the Attributes list to assign values on which to subset.</li> <li>Use the Operators drop-down list to choose the function by which to define attributes for selection in this query.</li> <li>In the Values field, type the specific values to use for selection of the attribute.</li> <li>Click <em>Add to Query</em> to complete the attribute definition for selection. You see the query string for this attribute in the Query Workspace field.</li> </ol> <p>Alternatively, you can enter your query directly by typing it into the Query Workspace field.</p> </li> <li><p class="first">Continue to add selection values to your query by using the Manual Query Builder tools.</p> </li> <li><p class="first">To remove any verticies that do not connect with other data in the set, check the <em>Eliminate disconnected vertices</em> check box.</p> </li> <li><p class="first">When you complete construction of your query string, click <em>Run</em> to perform the query.</p> </li> <li><p class="first">Scroll to the bottom of the window, and when the query is processed you see a new entry in the Subset History panel that defines your query.</p> </li> </ol> <p>Continue to build a successive subset or download a subset.</p> <p><strong>Subset Automatically</strong></p> <p>Peform an Automatic Query to select a subgraph of the nextwork based on structural properties of the network. Remember to review the Network Data Tips before you start work with a study’s files.</p> <p>To subset variables within a network data set by using an automatically generated query:</p> <ol class="arabic simple"> <li>In the Data File page, click the Automatic Query radio button near the middle of the page.</li> <li>Use the Function drop-down list and select the type of function with which to select your subset:<ul> <li>Largest graph - Subset the <nth> largest group of nodes that can reach one another by walking across edges.</li> <li>Neighborhood - Generate a subgraph of the original network composed of all vertices that are positioned at most <n> steps away from the currently selected vertices in the original network, plus all of the edges that connect them. This is the only query that can (and generally does) increase the number of vertices and edges selected.</li> </ul> </li> <li>In the Nth field, enter the <nth> degree with which to select data using that function.</li> <li>Click <em>Run</em> to perform the query.</li> <li>Scroll to the bottom of the window, and when the query is processed you see a new entry in the Subset History panel that defines your query.</li> </ol> <p>Continue to build a successive subset or download a subset.</p> <p><strong>Build or Restart Subsets</strong></p> <p><strong>Build a Subset</strong></p> <p>To build successive subsets and narrow your data selection progressively:</p> <ol class="arabic simple"> <li>Perform a manual or automatic subset query on a selected data set.</li> <li>Perform a second query to further narrow the results of your previous subset activity.</li> <li>When you arrive at the subset with which you choose to work, continue to analyze or download that subset.</li> </ol> <p><strong>Undo Previous Subset</strong></p> <p>You can reset, or undo, the most recent subsetting action for a data set. Note that you can do this only one time, and only to the most recent subset.</p> <p>Scroll to the Subset History panel at the bottom of the page and click <em>Undo</em> in the last row of the list of successive subsets. The last subset is removed, and the previous subset is available for downloading, further subsetting, or analysis.</p> <p><strong>Restart Subsetting</strong></p> <p>You can remove all subsetting activity and restore data to the original set.</p> <p>Scroll to the Subset History panel at the bottom of the page and click <em>Restart</em> in the row labeled <em>Initial State</em>. The data set is restored to the original condition, and is available for downloading, subsetting, or analysis.</p> <p><strong>Run Network Measures</strong></p> <p>When you finish selecting the specific data that you choose to analyze, run a Network Measure analysis on that data. Review the Network Data Tips before you start your analysis.</p> <ol class="arabic simple"> <li>In the Data File page, click the Network Measure radio button near the bottom of the page.</li> <li>Use the Attributes drop-down list and select the type of analysis to perform:<ul> <li>Page Rank - Determine how much influence comes from a specific actor or node.</li> <li>Degree - Determine the number of relationships or collaborations exist within a network data set.</li> <li>Unique Degree - Determine the number of collaborators that exist.</li> <li>In Largest Component - Determine the largest component of a network.</li> <li>Bonacich Centrality - Determine the importance of a main actor or node.</li> </ul> </li> <li>In the Parameters field, enter the specific value with which to subset data using that function:<ul> <li>Page Rank - Enter a value for the parameter <d>, a proportion, between 0 and 1.</li> <li>Degree - Enter the number of relationships to extract from a network data set.</li> <li>Unique Degree - Enter the number of unique relationships to extract.</li> <li>In Largest Component - Enter the number of components to extract from a network data set, starting with the largest.</li> </ul> </li> <li>Click <em>Run</em> to perform the analysis.</li> <li>Scroll to the bottom of the window, and when the analysis is processed you see a new entry in the Subset History panel that contains your analyzed data.</li> </ol> <p>Continue to download the analyzed subset.</p> <p><strong>Download Network Subsets or Measures</strong></p> <p>When you complete subsetting and analysis of a network data set, you can download the final set of data. Network data subsets are downloaded in a zip archive, which has the name <tt class="docutils literal"><span class="pre">subset_<original</span> <span class="pre">file</span> <span class="pre">name>.zip</span></tt>. This archive contains three files:</p> <ul class="simple"> <li><tt class="docutils literal"><span class="pre">subset.xml</span></tt> - A GraphML formatted file that contains the final subsetted or analyzed data.</li> <li><tt class="docutils literal"><span class="pre">verticies.tab</span></tt> - A tabular file that contains all node data for the final set.</li> <li><tt class="docutils literal"><span class="pre">edges.tab</span></tt> - A tabular file that contains all relationship data for the final set.</li> </ul> <p>Note: Each time you download a subset of a specific network data set, a zip archive is downloaded that has the same name. All three zipped files within that archive also have the same names. Be careful not to overwrite a downloaded data set that you choose to keep when you perform sucessive downloads.</p> <p>To download a final set of data:</p> <ol class="arabic simple"> <li>Scroll to the Subset History panel on the Data File page.</li> <li>Click <em>Download Latest Results</em> at the bottom of the history list.</li> <li>Follow your browser’s prompts to open or save the data file to your computer’s disk drive. Be sure to save the file in a unique location to prevent overwritting an existing downloaded data file.</li> </ol> <p><strong>Network Data Tips</strong></p> <p>Use these guidelines when subsetting or analyzing network data:</p> <ul class="simple"> <li>For a Page rank network measure, the value for the parameter <d> is a proportion and must be between 0 and 1. Higher values of <d> increase dispersion, while values of <d> closer to zero produce a more uniform distribution. PageRank is normalized so that all of the PageRanks sum to 1.</li> <li>For a Bonacich Centrality network measure, the alpha parameter is a proportion that must be between -1 and +1. It is normalized so that all alpha centralities sum to 1.</li> <li>For a Bonacich Centrality network measure, the exo parameter must be greater than 0. A higher value of exo produces a more uniform distribution of centrality, while a lower value allows more variation.</li> <li>For a Bonacich Centrality network measure, the original alpha parameter of alpha centrality takes values only from -1/lambda to 1/lambda, where lambda is the largest eigenvalue of the adjacency matrix. In this Dataverse Network implementation, the alpha parameter is rescaled to be between -1 and 1 and represents the proportion of 1/lambda to be used in the calculation. Thus, entering alpha=1 sets alpha to be 1/lambda. Entering alpha=0.5 sets alpha to be 1/(2*lambda).</li> </ul> </div> </div> <div class="section" id="data-visualization"> <h3>Data Visualization<a class="headerlink" href="#data-visualization" title="Permalink to this headline">¶</a></h3> <p>Data Visualization allows contributors to make time series visualizations available to end users. These visualizations may be viewable and downloadable as graphs or data tables. Please see the appropriate guide for more information on setting up a visualization or viewing one.</p> <div class="section" id="explore-data"> <h4>Explore Data<a class="headerlink" href="#explore-data" title="Permalink to this headline">¶</a></h4> <p>The study owner may make a data visualization interface available to those who can view a study. This will allow you to select various data variables and see a time series graph or data table. You will also be able to download your custom graph for use in your own reports or articles.</p> <p>The study owner will at least provide a list of data measures from which to choose. These measures may be divided into types. If they are you will be able to narrow the list of measures by first selecting a measure type. Once you have selected a measure, if there are multiple variables associated with the measure you will be able to select one or more filters to uniquely identify a variable. By default any filter assigned to a variable will become the label associated with the variable in the graph or table. By pressing the Add Line button you will add the selected variable to your custom graph.</p> <p> <img alt="image0" src="_images/measure_selected.png" /></p> <p>Once you have added data to your graph you will be able to customize it further. You will be given a choice of display options made available by the study owner. These may include an interactive flash graph, a static image graph and a numerical data table. You will also be allowed to edit the graph title, which by default is the name of the measure or measures selected. You may also edit the Source Label. Other customizable features are the height and the legend location of the image graph. You may also select a subset of the data by selecting the start and end points of the time series. Finally, on the display tab you may opt to display the series as indices in which case a single data point known as the reference period will be designated as 100 and all other points of the series will be calculated relative to the reference period. If you select data points that do not have units in common (i.e. one is in percent while the other is in dollars) then the display will automatically be set to indices with the earliest common data point as the default reference period.</p> <p><img alt="image1" src="_images/complex_graph_screenshot.png" /></p> <p>On the Line Details tab you will see additional information on the data you have selected. This may include links to outside web pages that further explain the data. On this tab you will also be able to edit the label or delete the line from your custom graph.</p> <p>On the Export tab you will be given the opportunity to export your custom graph and/or data table. If you select multiple files for download they will be bound together in a single zip file.</p> <p>The Refresh button clears any data that you have added to your custom graph and resets all of the display options to their default values.</p> </div> <div class="section" id="set-up"> <h4>Set Up<a class="headerlink" href="#set-up" title="Permalink to this headline">¶</a></h4> <p>This feature allows you to make time series visualizations available to your end users. These visualizations may be viewable and downloadable as graphs or data tables. In the current beta version of the feature your data file must be subsettable and must contain at least one date field and one or more measures. You will be able to associate data fields from your file to a time variable and multiple measures and filters.</p> <p>When you select Set Up Exploration from within a study, you must first select the file for which you would like to set up the exploration. The list of files will include all subsettable data files within the study.</p> <p>Once you have selected a file you will go to a screen that has 5 tabs to guide you through the data visualization set-up. (In general, changes made to a visualization on the individual tabs are not saved to the database until the form’s Save button is pressed. When you are in add or edit mode on a tab, the tab will have an update or cancel button to update the “working copy” of a visualization or cancel the current update.)</p> <p>If you have a previously set up an exploration for a data file you may copy that exploration to a new file. When you select a file for set up you will be asked if you want to copy an exploration from another data file and will be presented a list of files from which to choose. Please note that the data variable names must be identical in both files for this migration to work properly.</p> <p><strong>Time Variable</strong></p> <p>On the first tab you select the time variable of your data file. The variable list will only include those variables that are date or time variables. These variables must contain a date in each row. You may also enter a label in the box labeled Units. This label will be displayed under the x-axis of the graph created by the end user.</p> <p><img alt="image2" src="_images/edittimevariablescreenshot.png" /></p> <p><strong>Measures</strong></p> <p>On the Measures tab you may assign measures to the variables in your data file. First you may customize the label that the end user will see for measures. Next you may add measures by clicking the “Add Measure” link. Once you click that link you must give your measure a unique name. Then you may assign Units to it. Units will be displayed as the y-axis label of any graph produced containing that measure. In order to assist in the organizing of the measures you may create measure types and assign your measures to one or more measure types. Finally, the list of variables for measures will include all those variables that are entered as numeric in your data file. If you assign multiple variables to the same measure you will have to distinguish between them by assigning appropriate filters. For the end user, the measure will be the default graph name.</p> <p><img alt="image3" src="_images/editmeasuresscreenshot.png" /></p> <p><strong>Filters</strong></p> <p>On the filters tab you may assign filters to the variables in your data file. Generally filters contain demographic, geographic or other identifying information about the variables. For a given group of filters only one filter may be assigned to a single variable. The filters assigned to a variable must be sufficient to distinguish among the variables assigned to a single measure. Similar to measures, filters may be assigned to one or more types. For the end user the filter name will be the default label of the line of data added to a graph.</p> <p><img alt="image4" src="_images/editfiltersscreenshot.png" /></p> <div class="line-block"> <div class="line"><br /></div> </div> <p><strong>Sources</strong></p> <p>On the Sources tab you can indicate the source of each of the variables in your data file. By default, the source will be displayed as a note below the x-axis labels. You may assign a single source to any or all of your data variables. You may also assign multiple sources to any of your data variables.</p> <p><img alt="image5" src="_images/sourcetabscreenshot.png" /></p> <div class="line-block"> <div class="line"><br /></div> </div> <p><strong>Display</strong></p> <p>On the Display tab you may customize what the end user sees in the Data Visualization interface. Options include the data visualization formats made available to the end user and default view, the Measure Type label, and the Variable Info Label.</p> <div class="line-block"> <div class="line"><br /></div> <div class="line-block"> <div class="line"><img alt="image6" src="_images/displaytabscreenshot.png" /></div> </div> </div> <p><strong>Validate Button</strong></p> <p>When you press the “Validate” button the current state of your visualization data will be validated. In order to pass validation your data must have one time variable defined. There must also be at least one measure variable assigned. If more than one variable is assigned to a given measure then filters must be assigned such that each single variable is defined by the measure and one or more filters. If the data visualization does not pass validation a detailed error message enumerating the errors will be displayed.</p> <p><strong>Release Button</strong></p> <p>Once the data visualization has been validated you may release it to end users by pressing the “Release” button. The release button will also perform a validation. Invalid visualizations will not be released, but a detailed error message will not be produced.</p> <p><strong>Save Button</strong></p> <p>The “Save” button will save any changes made to a visualization on the tabs to the database. If a visualization has been released and changes are saved that would make it invalid the visualization will be set to “Unreleased”.</p> <p><strong>Exit Button</strong></p> <p>To exit the form press the “Exit” button. You will be warned if you have made any unsaved changes.</p> <p><strong>Examples</strong></p> <p>Simplest case – a single measure associated with a single variable.</p> <p>Data variable contains information on average family income for all Americans. The end user of the visualization will see an interface as below:</p> <p><img alt="image7" src="_images/simple_explore_data.png" /></p> <p>Complex case - multiple measures and types along with multiple filters and filter types. If you have measures related to both income and poverty rates you can set them up as measure types and associate the appropriate measures with each type. Then, if you have variables associated with multiple demographic groups you can set them up as filters. You can set up filter types such as age, gender, race and state of residence. Some of your filters may belong to multiple types such as males age 18-34.</p> <p><img alt="image8" src="_images/complex_exploration.png" /></p> </div> </div> </div> <div class="section" id="dataverse-administration"> <h2>Dataverse Administration<a class="headerlink" href="#dataverse-administration" title="Permalink to this headline">¶</a></h2> <p>Once a user creates a dataverse becomes its owner and therefore is the administrator of that dataverse. The dataverse administrator has access to manage the settings described in this guide.</p> <div class="section" id="create-a-dataverse"> <h3>Create a Dataverse<a class="headerlink" href="#create-a-dataverse" title="Permalink to this headline">¶</a></h3> <p>A dataverse is a container for studies and is the home for an individual scholar’s or organization’s data.</p> <p>Creating a dataverse is easy but first you must be a registered user. Depending on site policy, there may be a “Create a Dataverse” link on the Network home page. This first walks you through creating an account, then a dataverse.</p> <ol class="arabic simple"> <li>Fill in the required information:</li> </ol> <blockquote> <div><ul class="simple"> <li><strong>Type of Dataverse</strong>: Choose Scholar if it represents an individual’s work otherwise choose Basic.</li> <li><strong>Dataverse Name</strong>: This will be displayed on the network and dataverse home pages. If this is a Scholar dataverse it will automatically be filled in with the scholar’s first and last name.</li> <li><strong>Dataverse Alias</strong>: This is an abbreviation, usually lower-case, that becomes part of the URL for the new dataverse.</li> </ul> <blockquote> <div>The required fields to create a dataverse are configurable in the Network Options, so fields that are required may also include Affiliation, Network Home Page Description, and Classification.</div></blockquote> </div></blockquote> <ol class="arabic simple" start="2"> <li>Click “Save” and you’re done! An email will be sent to you with more information, including the URL to access you new dataverse.</li> </ol> <p>*Required information can vary depending on site policy. Required fields are noted with a <strong>red asterisk</strong>.</p> </div> <div class="section" id="edit-general-settings"> <h3>Edit General Settings<a class="headerlink" href="#edit-general-settings" title="Permalink to this headline">¶</a></h3> <p>Use the General Settings tab on the Options page to release your dataverse, change the name, alias, and classification of your dataverse. The classifications are used to browse to your dataverse from the Network home page.</p> <p>Navigate to the General Settings from the Options page:</p> <p>Dataverse home page > Options page > Settings tab > General subtab</p> <p>To edit release your dataverse:</p> <p>Select <em>Released</em> from the drop-down list when your dataverse is ready to go public. Select <em>Not Released</em> if you wish to block public access to your dataverse.</p> <p>Your dataverse cannot be released if it does not contain any released studies. Create a study or define a collection with studies from other dataverses before you attempt to make your dataverse public.</p> <p>To edit the affiliation, name, or alias settings of your dataverse:</p> <p>If you edit a Scholar dataverse type, you can edit the following fields:</p> <ul class="simple"> <li>First Name - Edit your first name, which appears with your last name on the Network home page in the Scholar Dataverse group.</li> <li>Last Name - Edit your last name, which appears with your first name on the Network home page in the Scholar Dataverse group.</li> </ul> <p>If you edit either Scholar or basic types, you can edit any of the following fields:</p> <ul class="simple"> <li>Affiliation - Edit your institutional identity.</li> <li>Dataverse Name - Edit the title for your dataverse, which appears on your dataverse home page. There are no naming restrictions.</li> <li>Dataverse Alias - Edit your dataverse’s URL. Special characters (~,`, !, @, #, $, %, ^, &, and *) and spaces are not allowed. <strong>Note</strong>: if you change the Dataverse Alias field, the URL for your Dataverse changes (http//.../dv/’alias’), which affects links to this page.</li> <li>Network Home Page Description - Edit the text that appears beside the name of your dataverse on the Network home page.</li> <li>Classification - Check the classifications, or groups, in which you choose to include your dataverse. Remove the check for any classifications that you choose not to join.</li> </ul> </div> <div class="section" id="edit-layout-branding"> <span id="id4"></span><h3>Edit Layout Branding<a class="headerlink" href="#edit-layout-branding" title="Permalink to this headline">¶</a></h3> <p><strong>Customize Layout Branding (header/footer) to match your website</strong></p> <p>The Layout Branding allows you to customize your dataverse, by <strong>adding HTML to the default banner and footer</strong>, such as that used on your personal website. If your website has such layout elements as a navigation menu or images, you can add them here. Each dataverse is created with a default customization added, which you can leave as is, edit to change the background color, or add your own customization.</p> <p>Navigate to the Layout Branding from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Customization</span> <span class="pre">subtab</span></tt></p> <p>To edit the banner and footer of your dataverse:</p> <ol class="arabic simple"> <li>In the Custom Banner field, enter your plain text, and HTML to define your custom banner.</li> <li>In the Custom Footer field, enter your plain text, and HTML to define your custom footer.</li> </ol> <p><strong>Embed your Dataverse into your website (iframes)</strong></p> <p>Want to embed your Dataverse on an OpenScholar site? Follow <a class="reference internal" href="#openscholar"><em>these special instructions</em></a>.</p> <p>For dataverse admins that are more advanced HTML developers, or that have HTML developers available to assist them, you can create a page on your site and add the dataverse with an iframe.</p> <ol class="arabic simple"> <li>Create a new page, that you will host on your site.</li> <li>Add the following HTML code to the content area of that new page.</li> </ol> <blockquote> <div><div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre"><script</span> <span class="pre">type="text/javascript"></span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">var</span> <span class="pre">dvn_url</span> <span class="pre">=</span> <span class="pre">"[SAMPLE_ONLY_http://dvn.iq.harvard.edu/dvn/dv/sampleURL]";</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">var</span> <span class="pre">regexS</span> <span class="pre">=</span> <span class="pre">"[\\?&]dvn_subpage=([^&#]*)";</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">var</span> <span class="pre">regex</span> <span class="pre">=</span> <span class="pre">new</span> <span class="pre">RegExp(</span> <span class="pre">regexS</span> <span class="pre">);</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">var</span> <span class="pre">results</span> <span class="pre">=</span> <span class="pre">regex.exec(</span> <span class="pre">window.location.href</span> <span class="pre">);</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">if(</span> <span class="pre">results</span> <span class="pre">!=</span> <span class="pre">null</span> <span class="pre">)</span> <span class="pre">dvn_url</span> <span class="pre">=</span> <span class="pre">dvn_url</span> <span class="pre">+</span> <span class="pre">results[1];document.write('<iframe</span> <span class="pre">src="'</span> <span class="pre">+</span> <span class="pre">dvn_url</span> <span class="pre">+</span> <span class="pre">'"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">onLoad="set_dvn_url(this)"</span> <span class="pre">width="100%"</span> <span class="pre">height="600px"</span> <span class="pre">frameborder="0"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">style="background-color:#FFFFFF;"></iframe>');</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre"></script></span></tt></div> </div> </div></blockquote> <ol class="arabic simple" start="3"> <li>Edit that code by adding the URL of your dataverse (replace the SAMPLE_ONLY URL in the example, including the brackets “[ ]”), and adjusting the height. We suggest you keep the height at or under 600px in order to fit the iframe into browser windows on computer monitor of all sizes, with various screen resolutions.</li> <li>The dataverse is set to have a min-width of 724px, so try give the page a width closer to 800px.</li> <li>Once you have the page created on your site, with the iframe code, go to the Setting tab, then the Customization subtab on your dataverse Options page, and click the checkbox that disables customization for your dataverse.</li> <li>Then enter the URL of the new page on your site. That will redirect all users to the new page on your site.</li> </ol> <p><strong>Layout Branding Tips</strong></p> <ul class="simple"> <li>HTML markup, including <tt class="docutils literal"><span class="pre">script</span></tt> tags for JavaScript, and <tt class="docutils literal"><span class="pre">style</span></tt> tags for an internal style sheet, are permitted. The <tt class="docutils literal"><span class="pre">html,</span></tt> <tt class="docutils literal"><span class="pre">head</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element tags are not allowed.</li> <li>When you use an internal style sheet to insert CSS into your customization, it is important to avoid using universal (“<tt class="docutils literal"><span class="pre">*</span></tt>”) and type (“<tt class="docutils literal"><span class="pre">h1</span></tt>”) selectors, because these can overwrite the external style sheets that the dataverse is using, which can break the layout, navigation or functionality in the app.</li> <li>When you link to files, such as images or pages on a web server outside the network, be sure to use the full URL (e.g. <tt class="docutils literal"><span class="pre">http://www.mypage.com/images/image.jpg</span></tt>).</li> <li>If you recreate content from a website that uses frames to combine content on the sides, top, or bottom, then you must substitute the frames with <tt class="docutils literal"><span class="pre">table</span></tt> or <tt class="docutils literal"><span class="pre">div</span></tt> element types. You can open such an element in the banner field and close it in the footer field.</li> <li>Each time you click “Save”, your banner and footer automatically are validated for HTML and other code errors. If an error message is displayed, correct the error and then click “Save” again.</li> <li>You can use the banner or footer to house a link from your homepage to your personal website. Be sure to wait until you release your dataverse to the public before you add any links to another website. And, be sure to link back from your website to your homepage.</li> <li>If you are using an OpenScholar or iframe site and the redirect is not working, you can edit your branding settings by adding a flag to your dataverse URL: disableCustomization=true. For example: <tt class="docutils literal"><span class="pre">dvn.iq.harvard.edu/dvn/dv/mydv?disableCustomization=true</span></tt>. To reenable: <tt class="docutils literal"><span class="pre">dvn.iq.harvard.edu/dvn/dv/mydv?disableCustomization=false</span></tt>. Disabling the customization lasts for the length of the user session.</li> </ul> </div> <div class="section" id="edit-description"> <h3>Edit Description<a class="headerlink" href="#edit-description" title="Permalink to this headline">¶</a></h3> <p>The Description is displayed on your dataverse Home page. Utilize this field to display announcements or messaging.</p> <p>Navigate to the Description from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">General</span> <span class="pre">subtab</span> <span class="pre">>Home</span> <span class="pre">Page</span> <span class="pre">Description</span></tt></p> <p>To change the content of this description:</p> <ul class="simple"> <li>Enter your description or announcement text in the field provided. Note: A light blue background in any form field indicates HTML, JavaScript, and style tags are permitted. The <tt class="docutils literal"><span class="pre">html,</span></tt>, <tt class="docutils literal"><span class="pre">head</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types are not allowed.</li> </ul> <p>Previous to the Version 3.0 release of the Dataverse Network, the Description had a character limit set at 1000, which would truncate longer description with a <strong>more >></strong> link. This functionality has been removed, so that you can add as much text or code to that field as you wish. If you would like to add the character limit and truncate functionality back to your dataverse, just add this snippet of Javascript to the end of your description.</p> <blockquote> <div><div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre"><script</span> <span class="pre">type="text/javascript"></span></tt></div> <div class="line"> <tt class="docutils literal"><span class="pre">jQuery(document).ready(function(){</span></tt></div> <div class="line"> <tt class="docutils literal"><span class="pre">jQuery(".dvn\_hmpgMainMessage</span> <span class="pre">span").truncate({max\_length:1000});</span></tt></div> <div class="line"> <tt class="docutils literal"><span class="pre">});</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre"></script></span></tt></div> </div> </div></blockquote> </div> <div class="section" id="edit-study-comments-settings"> <span id="id5"></span><h3>Edit Study Comments Settings<a class="headerlink" href="#edit-study-comments-settings" title="Permalink to this headline">¶</a></h3> <p>You can enable or disable the Study User Comments feature in your dataverse. If you enable Study User Comments, any user has the option to add a comment to a study in this dataverse. By default, this feature is enabled in all new dataverses. Note that you should ensure there are terms of use at the network or dataverse level that define acceptable use of this feature if it is enabled.</p> <p>Navigate to the Study User Comments from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">General</span> <span class="pre">subtab</span> <span class="pre">>Allow</span> <span class="pre">Study</span> <span class="pre">Comments</span></tt></p> <p>A user must create an account in your dataverse to use the comment feature. When you enable this feature, be aware that new accounts will be created in your dataverse when users add comments to studies. In addition, the Report Abuse function in the comment feature is managed by the network admin. If a user reads a comment that might be inappropriate, that user can log in or register an account and access the Report Abuse option. Comments are reported as abuse to the network admin.</p> <p>To manage the Study User Comments feature in your dataverse:</p> <ul class="simple"> <li>Click the “Allow Study Comments” check box to enable comments.</li> <li>Click the checked box to remove the check and disable comments.</li> </ul> </div> <div class="section" id="manage-e-mail-notifications"> <h3>Manage E-Mail Notifications<a class="headerlink" href="#manage-e-mail-notifications" title="Permalink to this headline">¶</a></h3> <p>You can edit the e-mail address used on your dataverse’s Contact Us page and by the network when sending notifications on processes and errors. By default, the e-mail address used is from the user account of the dataverse creator.</p> <p>Navigate to the E-Mail Notifications from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">General</span> <span class="pre">subtab</span> <span class="pre">>E-Mail</span> <span class="pre">Address(es)</span></tt></p> <p>To edit the contact and notification e-mail address for your dataverse:</p> <ul class="simple"> <li>Enter one or more e-mail addresses in the <strong>E-Mail Address</strong> field. Provide the addresses of users who you choose to receive notification when contacted from this dataverse. Any time a user submits a request through your dataverse, including the Request to Contribute link and the Contact Us page, e-mail is sent to all addresses that you enter in this field. Separate each address from others with a comma. Do not add any spaces between addresses.</li> </ul> </div> <div class="section" id="add-fields-to-search-results"> <h3>Add Fields to Search Results<a class="headerlink" href="#add-fields-to-search-results" title="Permalink to this headline">¶</a></h3> <p>Your dataverse includes the network’s search and browse features to assist your visitors in locating the data that they need. By default, the Cataloging Information fields that appear in the search results or in studies’ listings include the following: study title, authors, ID, production date, and abstract. You can customize other Cataloging Information fields to appear in search result listings after the default fields. Additional fields appear only if they are populated for the study.</p> <p>Navigate to the Search Results Fields from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Customization</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Search</span> <span class="pre">Results</span> <span class="pre">Fields</span></tt></p> <p>To add more Cataloging Information fields listed in the Search or Browse panels:</p> <ul class="simple"> <li>Click the check box beside any of the following Cataloging Information fields to include them in your results pages: Production Date, Producer, Distribution Date, Distributor, Replication For, Related Publications, Related Material, and Related Studies.</li> </ul> <p>Note: These settings apply to your dataverse only.</p> </div> <div class="section" id="set-default-study-listing-sort-order"> <h3>Set Default Study Listing Sort Order<a class="headerlink" href="#set-default-study-listing-sort-order" title="Permalink to this headline">¶</a></h3> <p>Use the drop-down menu to set the default sort order of studies on the Study Listing page. By default, they are sorted by Global ID, but you can also sort by Title, Last Released, Production Date, or Download Count.</p> <p>Navigate to the Default Study Listing Sort Order from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Customization</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Default</span> <span class="pre">Sort</span> <span class="pre">Order</span></tt></p> </div> <div class="section" id="enable-twitter"> <h3>Enable Twitter<a class="headerlink" href="#enable-twitter" title="Permalink to this headline">¶</a></h3> <p>If your Dataverse Network has been configured for Automatic Tweeting, you will see an option listed as “Enable Twitter.” When you click this, you will be redirected to Twtter to authorize the Dataverse Network application to send tweets for you.</p> <p>Once authorized, tweets will be sent for each new study or study version that is released.</p> <p>To disable Automatic Tweeting, go to the Options page, and click “Disable Twitter.”</p> <p>Navigate to Enable Twitter from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">> Promote</span> <span class="pre">Your</span> <span class="pre">Dataverse</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Sync</span> <span class="pre">Dataverse</span> <span class="pre">With</span> <span class="pre">Twitter</span></tt></p> </div> <div class="section" id="get-code-for-dataverse-link-or-search-box"> <h3>Get Code for Dataverse Link or Search Box<a class="headerlink" href="#get-code-for-dataverse-link-or-search-box" title="Permalink to this headline">¶</a></h3> <p>Add a dataverse promotional link or dataverse search box on your personal website by copying the code for one of the sample links on this page, and then pasting it anywhere on your website to create the link.</p> <p>Navigate to the Code for Dataverse Link or Search Box from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Promote</span> <span class="pre">Your</span> <span class="pre">Dataverse</span> <span class="pre">subtab</span></tt></p> </div> <div class="section" id="edit-terms-for-study-creation"> <h3>Edit Terms for Study Creation<a class="headerlink" href="#edit-terms-for-study-creation" title="Permalink to this headline">¶</a></h3> <p>You can set up Terms of Use for the dataverse that require users to acknowledge your terms and click “Accept” before they can contribute to the dataverse.</p> <p>Navigate to the Terms for Study Creation from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Terms</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Deposit</span> <span class="pre">Terms</span> <span class="pre">of</span> <span class="pre">Use</span></tt></p> <p>To set Terms of Use for creating or uploading to the dataverse:</p> <ol class="arabic simple"> <li>Click the Enable Terms of Use check box.</li> <li>Enter a description of your terms to which visitors must agree before they can create a study or upload a file to an existing study. Note: A light blue background in any form field indicates HTML, JavaScript, and style tags are permitted. The <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types are not allowed.</li> </ol> </div> <div class="section" id="edit-terms-for-file-download"> <h3>Edit Terms for File Download<a class="headerlink" href="#edit-terms-for-file-download" title="Permalink to this headline">¶</a></h3> <p>You can set up Terms of Use for the network that require users to acknowledge your terms and click “Accept” before they can download or subset contents from the network.</p> <p>Navigate to the Terms for File Download from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">> Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Terms</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Download</span> <span class="pre">Terms</span> <span class="pre">of</span> <span class="pre">Use</span></tt></p> <p>To set Terms of Use for downloading or subsetting contents from any dataverse in the network:</p> <ol class="arabic simple"> <li>Click the Enable Terms of Use check box.</li> <li>Enter a description of your terms to which visitors must agree before they can download or analyze any file. Note: A light blue background in any form field indicates HTML, JavaScript, and style tags are permitted. The <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types are not allowed.</li> </ol> </div> <div class="section" id="manage-permissions"> <h3>Manage Permissions<a class="headerlink" href="#manage-permissions" title="Permalink to this headline">¶</a></h3> <p>Enable contribution invitation, grant permissions to users and groups, and manage dataverse file permissions.</p> <p>Navigate to Manage Permissions from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">subtab</span></tt></p> <p><strong>Contribution Settings</strong></p> <p>Choose the access level contributors have to your dataverse. Whether they are allowed to edit only their own studies, all studies, or whether all registered users can edit their own studies (Open dataverse) or all studies (Wiki dataverse). In an Open dataverse, users can add studies by simply creating an account, and can edit their own studies any time, even after the study is released. In a Wiki dataverse, users cannot only add studies by creating an account, but also edit any study in that dataverse. Contributors cannot, however, release a study directly. After their edits, they submit it for review and a dataverse administrator or curator will release it.</p> <p><strong>User Permission Settings</strong></p> <p>There are several roles defined for users of a Dataverse Network installation:</p> <ul class="simple"> <li>Data Users - Download and analyze all types of data</li> <li>Contributors - Distribute data and receive recognition and citations to it</li> <li>Curators - Summarize related data, organize data, or manage multiple sets of data</li> <li>Administrators - Set up and manage contributions to your dataverse, manage the appearance of your dataverse, organize your dataverse collections</li> </ul> <p><strong>Privileged Groups</strong></p> <p>Enter group name to allow a group access to the dataverse. Groups are created by network administrators.</p> <p><strong>Dataverse File Permission Settings</strong></p> <p>Choose ‘Yes’ to restrict ALL files in this dataverse. To restrict files individually, go to the Study Permissions page of the study containing the file.</p> </div> <div class="section" id="create-user-account"> <h3>Create User Account<a class="headerlink" href="#create-user-account" title="Permalink to this headline">¶</a></h3> <p>As a registered user, you can:</p> <ul class="simple"> <li>Add studies to open and wiki dataverses, if available</li> <li>Contribute to existing studies in wiki dataverses, if available</li> <li>Add user comments to studies that have this option</li> <li>Create your own dataverse</li> </ul> <p><strong>Network Admin Level</strong></p> <p>Navigate to Create User Account from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Users</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Create</span> <span class="pre">User</span> <span class="pre">link</span></tt></p> <p>To create an account for a new user in your Network:</p> <ol class="arabic"> <li><dl class="first docutils"> <dt>Complete the account information page.</dt> <dd><p class="first last">Enter values in all required fields. Note: an email address can also be used as a username</p> </dd> </dl> </li> <li><p class="first">Click Create Account to save your entries.</p> </li> <li><p class="first">Go to the Permissions tab on the Options page to give the user Contributor, Curator or Admin access to your dataverse.</p> </li> </ol> <p><strong>Dataverse Admin Level</strong></p> <p>Navigate to Create User Account from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">> Permissions</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Create</span> <span class="pre">User</span> <span class="pre">link</span></tt></p> <p>To create an account for a new user in your Dataverse:</p> <ol class="arabic"> <li><dl class="first docutils"> <dt>Complete the account information page.</dt> <dd><p class="first last">Enter values in all required fields. Note: an email address can also be used as a username</p> </dd> </dl> </li> <li><p class="first">Click Create Account to save your entries.</p> </li> <li><p class="first">Go to the Permissions tab on the Options page to give the user Contributor, Curator or Admin access to your dataverse.</p> </li> </ol> <p><strong>New User: Network Homepage</strong></p> <p>As a new user, to create an account at the <strong>Dataverse Network homepage</strong>, select “Create Account” at the top-right hand side of the page.</p> <p>Complete the required information denoted by the red asterisk and save.</p> <p><strong>New User: Dataverse Level</strong></p> <p>As a new user, to create an account at the <strong>Dataverse level</strong>, select “Create Account” at the top-right hand side of the page. Note: For Open Dataverses select “Create Account” in the orange box on the top right hand side of the page labelled: “OPEN DATAVERSE”.</p> <p>Complete the required information denoted by the red asterisk and save.</p> </div> <div class="section" id="download-tracking-data"> <h3>Download Tracking Data<a class="headerlink" href="#download-tracking-data" title="Permalink to this headline">¶</a></h3> <p>You can view any guestbook responses that have been made in your dataverse. Beginning with version 3.2 of Dataverse Network, if the guestbook is not enabled, data will be collected silently based on the logged-in user or anonymously. The data displayed includes user account data or the session ID of an anonymous user, the global ID, study title and file name of the file downloaded, the time of the download, the type of download and any custom questions that have been answered. The username/session ID and download type were not collected in the 3.1 version of Dataverse Network. A comma separated values file of all download tracking data may be downloaded by clicking the Export Results button.</p> <p>Navigate to the Download Tracking Data from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Download</span> <span class="pre">Tracking</span> <span class="pre">Data</span> <span class="pre">subtab</span></tt></p> </div> <div class="section" id="edit-file-download-guestbook"> <h3>Edit File Download Guestbook<a class="headerlink" href="#edit-file-download-guestbook" title="Permalink to this headline">¶</a></h3> <p>You can set up a guestbook for your dataverse to collect information on all users before they can download or subset contents from the dataverse. The guestbook is independent of Terms of Use. Once it has been enabled it will be shown to any user for the first file a user downloads from a given study within a single session. If the user downloads additional files from the study in the same session a record will be created in the guestbook response table using data previously entered. Beginning with version 3.2 of Dataverse Network, if the dataverse guestbook is not enabled in your dataverse, download information will be collected silently based on logged-in user information or session ID.</p> <p>Navigate to the File Download Guestbook from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Guestbook</span> <span class="pre">subtab</span></tt></p> <p>To set up a Guestbook for downloading or subsetting contents from any study in the dataverse:</p> <ol class="arabic simple"> <li>Click the Enable File Download Guestbook check box.</li> <li>Select or unselect required for any of the user account identifying data points (First and last name, E-Mail address, etc.)</li> <li>Add any custom questions to collect additional data. These questions may be marked as required and set up as free text responses or multiple choice. For multiple choice responses select Radio Buttons as the Custom Field Type and enter the possible answers.</li> <li>Any custom question may be removed at any time, so that it won’t show for the end user. If there are any responses associated with question that has been removed they will continue to appear in the Guestbook Response data table.</li> </ol> </div> <div class="section" id="openscholar"> <span id="id6"></span><h3>OpenScholar<a class="headerlink" href="#openscholar" title="Permalink to this headline">¶</a></h3> <p><strong>Embed your Dataverse easily on an OpenScholar site</strong></p> <p>Dataverse integrates seamlessly with <a class="reference external" href="http://openscholar.harvard.edu/">OpenScholar</a>, a self-service site builder for higher education.</p> <p>To embed your dataverse on an OpenScholar site:</p> <ol class="arabic simple"> <li>On your Dataverse Options page, Go to the Setting tab</li> <li>Go to the Customization subtab</li> <li>Click the checkbox that disables customization for your dataverse</li> <li>Make note of your Dataverse alias URL (i.e. <a class="reference external" href="http://thedata.harvard.edu/dvn/dv/myvalue">http://thedata.harvard.edu/dvn/dv/myvalue</a>)</li> <li>Follow the <a class="reference external" href="http://support.openscholar.harvard.edu/customer/portal/articles/1215076-apps-dataverse">OpenScholar Support Center instructions</a> to enable the Dataverse App</li> </ol> </div> <div class="section" id="enabling-lockss-access-to-the-dataverse"> <span id="id7"></span><h3>Enabling LOCKSS access to the Dataverse<a class="headerlink" href="#enabling-lockss-access-to-the-dataverse" title="Permalink to this headline">¶</a></h3> <p><strong>Summary:</strong></p> <p><a class="reference external" href="http://lockss.stanford.edu/lockss/Home">LOCKSS Project</a> or <em>Lots of Copies Keeps Stuff Safe</em> is an international initiative based at Stanford University Libraries that provides a way to inexpensively collect and preserve copies of authorized e-content. It does so using an open source, peer-to-peer, decentralized server infrastructure. In order to make a LOCKSS server crawl, collect and preserve content from a DVN, both the server (the LOCKSS daemon) and the client (the DVN) sides must be properly configured. In simple terms, the LOCKSS server needs to be pointed at the DVN, given its location and instructions on what to crawl, the entire network, or a particular Dataverse; on the DVN side, access to the data must be authorized for the LOCKSS daemon. The section below describes the configuration tasks that the administrator of a Dataverse will need to do on the client side. It does not describe how LOCKSS works and what it does in general; it’s a fairly complex system, so please refer to the documentation on the <a class="reference external" href="http://lockss.stanford.edu/lockss/Home">LOCKSS Project</a> site for more information. Some information intended to a LOCKSS server administrator is available in the <a class="reference internal" href="dataverse-installer-main.html#using-lockss-with-dvn"><em>“Using LOCKSS with DVN”</em></a> of the <a class="reference internal" href="dataverse-installer-main.html#introduction"><em>DVN Installers Guide</em></a> (our primary sysadmin-level manual).</p> <p><strong>Configuration Tasks:</strong></p> <p>In order for a LOCKSS server to access, crawl and preserve any data on a given Dataverse Network, it needs to be granted an authorization by the network administrator. (In other words, an owner of a dataverse cannot authorize LOCKSS access to its files, unless LOCKSS access is configured on the Dataverse Network level). By default, LOCKSS crawling of the Dataverse Network is not allowed; check with the administrator of your Dataverse Network for details.</p> <p>But if enabled on the Dataverse Network level, the dataverse owner can further restrict LOCKSS access. For example, if on the network level all LOCKSS servers are allowed to crawl all publicly available data, the owner can limit access to the materials published in his or her dataverse to select servers only; specified by network address or domain.</p> <p>In order to configure LOCKSS access, navigate to the Advanced tab on the Options page:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Advanced</span> <span class="pre">subtab</span></tt></p> <p>It’s important to understand that when a LOCKSS daemon is authorized to “crawl restricted files”, this does not by itself grant the actual access to the materials! This setting only specifies that the daemon should not be skipping such restricted materials outright. If it is indeed desired to have non-public materials collected and preserved by LOCKSS, in addition to selecting this option, it will be the responsibility of the DV Administrator to give the LOCKSS daemon permission to actually access the files. As of DVN version 3.3, this can only be done based on the IP address of the LOCKSS server (by creating an IP-based user group with the appropriate permissions).</p> <p>Once LOCKSS crawling of the Dataverse is enabled, the Manifest page URL will be</p> <p><tt class="docutils literal"><span class="pre">http</span></tt><tt class="docutils literal"><span class="pre">://<YOUR</span> <span class="pre">SERVER>/dvn/dv/<DV</span> <span class="pre">ALIAS>/faces/ManifestPage.xhtml</span></tt>.</p> </div> </div> <div class="section" id="study-and-data-administration"> <h2>Study and Data Administration<a class="headerlink" href="#study-and-data-administration" title="Permalink to this headline">¶</a></h2> <p>Study Options are available for Contributors, Curators, and Administrators of a Dataverse.</p> <div class="section" id="create-new-study"> <h3>Create New Study<a class="headerlink" href="#create-new-study" title="Permalink to this headline">¶</a></h3> <p>Brief instructions for creating a study:</p> <p>Navigate to the dataverse in which you want to create a study, then click Options->Create New Study.</p> <p>Enter at minimum a study title and click Save. Your draft study is now created. Add additional cataloging information and upload files as needed. Release the study when ready to make it viewable by others.</p> <p><strong>Data Citation widget</strong></p> <p>At the top of the edit study form, there is a data citation widget that allows a user to quickly enter fields that appear in the data citation, ie. title, author, date, distributor Otherwise, the information can be entered as the fields appear in the data entry form.</p> <p>See the information below for more details and recommendations for creating a study.</p> <p><strong>Steps to Create a Study</strong></p> <ol class="arabic simple"> <li>Enter Cataloging Information, including an abstract of the study. Set Terms of Use for the study in the Cataloging fields, if you choose.</li> <li>Upload files associated with the study.</li> <li>Set permissions to access the study, all of the study files, or some of the study files.</li> <li>Delete your study if you choose, before you submit it for review.</li> <li>Submit your study for review, to make it available to the public.</li> </ol> <p>There are several guidelines to creating a study:</p> <ul class="simple"> <li>You must create a study by performing steps in the specified order.</li> <li>If multiple users edit a study at one time, the first user to click Save assumes control of the file. Only that user’s changes are effective.</li> <li>When you save the study, any changes that you make after that do not effect the study’s citation.</li> </ul> <p><strong>Enter Cataloging Information</strong></p> <p>To enter the Cataloging Information for a new study:</p> <ol class="arabic"> <li><p class="first">Prepopulate Cataloging Information fields based on a study template (if a template is available), use the Select Study Template pull-down list to select the appropriate template.</p> <p>A template provides default values for basic fields in the Cataloging Information fields. The default template prepopulates the Deposit Date field only.</p> </li> <li><p class="first">Enter a title in the Title field.</p> </li> <li><p class="first">Enter data in the remaining Cataloging Information fields. To list all fields, including the Terms of Use fields, click the Show All Fields button after you enter a title. Use the following guidelines to complete these fields:</p> <ul class="simple"> <li>A light blue background in any form field indicates that HTML, JavaScript, and style tags are permitted. You cannot use the <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types.</li> <li>To use the inline help and view information about a field, roll your cursor over the field title.</li> <li>Be sure to complete the Abstract field.</li> <li>To set Terms of Use for your study, scroll to the bottom of the Cataloging Information tab. Eight fields appear under the Terms of Use label. You must complete at least one of these fields to enable Terms for this study.</li> </ul> </li> <li><p class="first">Click the <em>Save</em> button and then add comments or a brief description in the Study Version Notes popup. Then click the <em>Continue</em> button and your study draft version is saved.</p> </li> </ol> <p><strong>Upload Study Files</strong></p> <p>To upload files associated with a new study:</p> <ol class="arabic"> <li><p class="first">For each file that you choose to upload to your study, first select the Data Type from the drop-down list. Then click the Browse button to select the file, and then click Upload to add each file at a time.</p> <p>When selecting a CSV (character-separated values) data type, an SPSS Control Card file is first required.</p> <p>When selecting a TAB (tab-delimited) data type, a DDI Control Card file is first required. There is no restriction to the number or types of files that you can upload to the Dataverse Network.</p> <p>There is a maximum file size of 2 gigabytes for each file that you upload.</p> </li> <li><p class="first">After you upload one file, enter the type of file in the <em>Category</em> field and then click Save. If you do not enter a category and click Save, the Category drop-down list does not have any value. You can create any category to add to this list.</p> </li> <li><p class="first">For each file that you upload, first click the check box in front of the file’s entry in the list, and then use the Category drop-down list to select the type of file that you uploaded.</p> <p>Every checked file is assigned the category that you select. Be sure to click the checked box to remove the check before you select a new value in the Category list for another file.</p> </li> <li><p class="first">In the Description field, enter a brief message that identifies the contents of your file.</p> </li> <li><p class="first">Click Save when you are finished uploading files. <strong>Note:</strong> If you upload a subsettable file, that process takes a few moments to complete. During the upload, the study is not available for editing. When you receive e-mail notification that the subsettable file upload is complete, click <em>Refresh</em> to continue editing the study.</p> <p>You see the Documentation, Data and Analysis tab of the study page with a list of the uploaded files. For each <em>subsettable tabular</em> data set file that you upload, the number of cases and variables and a link to the Data Citation information for that data set are displayed. If you uploaded an SPSS (<tt class="docutils literal"><span class="pre">.sav</span></tt> or <tt class="docutils literal"><span class="pre">.por</span></tt>) file, the Type for that file is changed to <em>Tab delimited</em> and the file extension is changed to <tt class="docutils literal"><span class="pre">.tab</span></tt> when you click Save.</p> <p>For each <em>subsettable network</em> data set file that you upload, the number of edges and verticies and a link to the Data Citation information for that data set are displayed.</p> </li> <li><p class="first">Continue to the next step and set file permissions for the study or its files.</p> </li> </ol> <p><strong>Study File Tips</strong></p> <p>Keep in mind these tips when uploading study files to your dataverse:</p> <ul class="simple"> <li>The following subsettable file types are supported:<ul> <li>SPSS <tt class="docutils literal"><span class="pre">sav</span></tt> and <tt class="docutils literal"><span class="pre">por</span></tt> - Versions 7.x to 20.x (See the <a class="reference internal" href="#spss-datafile-ingest"><em>Note on SPSS ingest</em></a> in the Appendix)</li> <li>STATA <tt class="docutils literal"><span class="pre">dta</span></tt> - Versions 4 to 12</li> <li>R <tt class="docutils literal"><span class="pre">RData</span></tt> - All versions (NEW as of DVN v.3.5! See <a class="reference internal" href="#r-datafile-ingest"><em>Ingest of R data files</em></a> in the Appendix)</li> <li>GraphML <tt class="docutils literal"><span class="pre">xml</span></tt> - All versions</li> <li>CSV data file with a <a class="reference internal" href="#controlcard-datafile-ingest"><em>control card</em></a></li> <li>TAB-delimited data file with a <a class="reference internal" href="#ddixml-datafile-ingest"><em>DDI XML control card</em></a></li> </ul> </li> <li>A custom ingest for FITS Astronomical data files has been added in v.3.4. (see <a class="reference internal" href="#fits-datafile-ingest"><em>FITS File format Ingest</em></a> in the Appendix)</li> <li>You can add information for each file, including:<ul> <li>File name</li> <li>Category (documentation or data)</li> <li>Description</li> </ul> </li> <li>If you upload the wrong file, click the Remove link before you click Save. To replace a file after you upload it and save the study, first remove the file and then upload a new one.</li> <li>If you upload a STATA (<tt class="docutils literal"><span class="pre">.dta</span></tt>), SPSS (<tt class="docutils literal"><span class="pre">.sav</span></tt> or <tt class="docutils literal"><span class="pre">.por</span></tt>), or network (<tt class="docutils literal"><span class="pre">.xml</span></tt>) file, the file automatically becomes subsettable (that is, subset and analysis tools are available for that file in the Network). In this case, processing the file might take some time and you will not see the file listed immediately after you click Save.</li> <li>When you upload a <em>subsettable</em> data file, you are prompted to provide or confirm your e-mail address for notifications. One e-mail lets you know that the file upload is in progress; a second e-mail notifies you when the file upload is complete.</li> <li>While the upload of the files takes place, your study is not available for editing. When you receive e-mail notification that the upload is completed, click <em>Refresh</em> to continue editing the study.</li> </ul> <p><strong>Set Study and File Permissions</strong></p> <p>You can restrict access to a study, all of its files, or some of its files. This restriction extends to the search and browse functions.</p> <p>To permit or restrict access:</p> <ol class="arabic"> <li><p class="first">On the study page, click the Permissions link.</p> </li> <li><p class="first">To set permissions for the study:</p> <ol class="upperalpha simple"> <li>Scroll to the Entire Study Permission Settings panel, and click the drop-down list to change the study to Restricted or Public.</li> <li>In the <em>User Restricted Study Settings</em> field, enter a user or group to whom you choose to grant access to the study, then click Add.</li> </ol> <p>To enable a request for access to restricted files in the study, scroll to the File Permission Settings panel, and click the Restricted File Settings check box. This supplies a request link on the Data, Documentation and Analysis tab for users to request access to restricted files by creating an account.</p> <p>To set permission for individual files in the study:</p> <ol class="upperalpha simple"> <li>Scroll to the Individual File Permission Settings panel, and enter a user or group in the Restricted File User Access <em>Username</em> field to grant permissions to one or more individual files.</li> <li>Use the File Permission pull-down list and select the permission level that you choose to apply to selected files: Restricted or Public.</li> <li>In the list of files, click the check box for each file to which you choose to apply permissions. To select all files, click the check box at the top of the list.</li> <li>Click Update. The users or groups to which you granted access privileges appear in the File Permissions list after the selected files.</li> </ol> </li> </ol> <p>Note: You can edit or delete your study if you choose, but only until you submit the study for reveiw. After you submit your study for review, you cannot edit or delete it from the dataverse.</p> <p><strong>Delete Studies</strong></p> <p>You can delete a study that you contribute, but only until you submit that study for review. After you submit your study for review, you cannot delete it from the dataverse.</p> <p>If a study is no longer valid, it can now be deaccessioned so it’s unavailable to users but still has a working citation. A reference to a new study can be provided when deaccessioning a study. Only Network Administrators can now permanently delete a study once it has been released.</p> <p>To delete a draft version:</p> <ol class="arabic"> <li><p class="first">Click the Delete Draft Version link in the top-right area of the study page.</p> <p>You see the Delete Draft Study Version popup.</p> </li> <li><p class="first">Click the Delete button to remove the draft study version from the dataverse.</p> </li> </ol> <p>To deaccession a study:</p> <ol class="arabic"> <li><dl class="first docutils"> <dt>Click the Deaccession link in the top-right area of the study page.</dt> <dd><p class="first last">You see the Deaccession Study page.</p> </dd> </dl> </li> <li><p class="first">You have the option to add your comments about why the study was deaccessioned, and a link reference to a new study by including the Global ID of the study.</p> </li> <li><p class="first">Click the Deaccession button to remove your study from the dataverse.</p> </li> </ol> <p><strong>Submit Study for Review</strong></p> <p>When you finish setting options for your study, click <em>Submit For Review</em> in the top-right corner of the study page. The page study version changes to show <em>In Review</em>.</p> <p>You receive e-mail after you click <em>Submit For Review</em>, notifying you that your study was submitted for review by the Curator or Dataverse Admin. When a study is in review, it is not available to the public. You receive another e-mail notifying you when your study is released for public use.</p> <p>After your study is reviewed and released, it is made available to the public, and it is included in the search and browse functions. The Cataloging Information tab for your study contains the Citation Information for the complete study. The Documentation, Data and Analysis tab lists the files associated with the study. For each subsettable file in the study, a link is available to show the Data Citation for that specific data set.</p> <p><strong>UNF Calculation</strong></p> <p>When a study is created, a UNF is calculated for each subsettable file uploaded to that study. All subsettable file UNFs then are combined to create another UNF for the study. If you edit a study and upload new subsettable files, a new UNF is calculated for the new files and for the study.</p> <p>If the original study was created before version 2.0 of the Dataverse Network software, the UNF calculations were performed using version 3 of that standard. If you upload new subsettable files to an existing study after implementation of version 2.0 of the software, the UNFs are recalculated for all subsettable files and for the study using version 5 of that standard. This prevents incompatibility of UNF version numbers within a study.</p> </div> <div class="section" id="manage-studies"> <h3>Manage Studies<a class="headerlink" href="#manage-studies" title="Permalink to this headline">¶</a></h3> <p>You can find all studies that you uploaded to the dataverse, or that were submitted by a Contributor for review. Giving you access to view, edit, release, or delete studies.</p> <p><strong>View, Edit, and Delete/Deaccession Studies</strong></p> <p>To view and edit studies that you uploaded:</p> <ol class="arabic simple"> <li>Click a study Global ID, title, or <em>Edit</em> link to go to the study page.</li> <li>From the study page, do any of the following:<ul> <li>Edit Cataloging Information</li> <li>Edit/Delete File + Information</li> <li>Add File(s)</li> <li>Edit Study Version Notes</li> <li>Permissions</li> <li>Create Study Template</li> <li>Release</li> <li>Deaccession</li> <li>Destroy Study</li> </ul> </li> </ol> <p>To delete or deaccession studies that you uploaded:</p> <ol class="arabic simple"> <li>If the study has not been released, click the <em>Delete</em> link to open the Delete Draft Study Version popup.</li> <li>If the study has been released, click the <em>Deaccession</em> link to open the Deaccession Study page.</li> <li>Add your comments about why the study was deaccessioned, and a reference link to another study by including the Global ID, then click the <em>Deaccession</em> button.</li> </ol> <p><strong>Release Studies</strong></p> <p>When you release a study, you make it available to the public. Users can browse it or search for it from the dataverse or Network homepage.</p> <p>You receive e-mail notification when a Contributor submits a study for review. You must review each study submitted to you and release that study to the public. You receive a second e-mail notification after you release a study.</p> <p>To release a study draft version:</p> <ol class="arabic simple"> <li>Review the study draft version by clicking the Global ID, or title, to go to the Study Page, then click Release in the upper right corner. For a quick release, click <em>Release</em> from the Manage Studies page.</li> <li>If the study draft version is an edit of an existing study, you will see the Study Version Differences page. The table allows you to view the changes compared to the current public version of the study. Click the <em>Release</em> button to continue.</li> <li>Add comments or a brief description in the Study Version Notes popup. Then click the <em>Continue</em> button and your study is now public.</li> </ol> </div> <div class="section" id="manage-study-templates"> <h3>Manage Study Templates<a class="headerlink" href="#manage-study-templates" title="Permalink to this headline">¶</a></h3> <p>You can set up study templates for a dataverse to prepopulate any of the Cataloging Information fields of a new study with default values. When a user adds a new study, that user can select a template to fill in the defaults.</p> <p><strong>Create Template</strong></p> <p>Study templates help to reduce the work needed to add a study, and to apply consistency to studies within a dataverse. For example, you can create a template to include the Distributor and Contact details so that every study has the same values for that metadata.</p> <p>To create a new study template:</p> <ol class="arabic simple"> <li>Click Clone on any Template.</li> <li>You see the Study Template page.</li> <li>In the Template Name field, enter a descriptive name for this template.</li> <li>Enter generic information in any of the Cataloging Information metadata fields. You may also change the input level of any field to make a certain field required, recommended, optional or hidden. Hidden fields will not be visible to the user creating studies from the template.</li> <li>After you complete entry of generic details in the fields that you choose to prepopulate for new studies, click Save to create the template.</li> </ol> <p>Note: You also can create a template directly from the study page to use that study’s Cataloging Information in the template.</p> <p><strong>Enable a template</strong></p> <p>Click the Enabled link for the given template. Enabled templates are available to end users for creating studies.</p> <p><strong>Edit Template</strong></p> <p>To edit an existing study template:</p> <ol class="arabic simple"> <li>In the list of templates, click the Edit link for the template that you choose to edit.</li> <li>You see the Study Template page, with the template setup that you selected.</li> <li>Edit the template fields that you choose to change, add, or remove.</li> </ol> <p>Note: You cannot edit any Network Level Template.</p> <p><strong>Make a Template the Default</strong></p> <p>To set any study template as the default template that applies automatically to new studies: In the list of templates, click the Make Default link next to the name of the template that you choose to set as the default. | The Current Default Template label is displayed next to the name of the template that you set as the default.</p> <div class="line-block"> <div class="line"><strong>Remove Template</strong></div> <div class="line">To delete a study template from a dataverse:</div> </div> <ol class="arabic simple"> <li>In the list of templates, click the Delete link for the template that you choose to remove from the dataverse.</li> <li>You see the Delete Template page.</li> <li>Click Delete to remove the template from the dataverse.</li> </ol> <p>Note: You cannot delete any network template, default template or template in use by any study.</p> </div> <div class="section" id="data-uploads"> <h3>Data Uploads<a class="headerlink" href="#data-uploads" title="Permalink to this headline">¶</a></h3> <p><strong>Troubleshooting Data Uploads:</strong></p> <p>Though the add files page works for the majority of our users, there can be situations where uploading files does not work. Below are some troubleshooting tips, including situations where uploading a file might fail and things to try.</p> <p><strong>Situations where uploading a file might fail:</strong></p> <ol class="arabic simple"> <li>File is too large, larger than the maximum size, should fail immediately with an error.</li> <li>File takes too long and connection times out (currently this seems to happen after 5 mins) Failure behavior is vague, depends on browser. This is probably an IceFaces issue.</li> <li>User is going through a web proxy or firewall that is not passing through partial submit headers. There is specific failure behavior here that can be checked and it would also affect other web site functionality such as create account link. See redmine ticket <a class="reference external" href="https://redmine.hmdc.harvard.edu/issues/2532">#2352</a>.</li> <li>AddFilesPage times out, user begins adding files and just sits there idle for a long while until the page times out, should see the red circle slash.</li> <li>For subsettable files, there is something wrong with the file itself and so is not ingested. In these cases they should upload as other and we can test here.</li> <li>For subsettable files, there is something wrong with our ingest code that can’t process something about that particular file, format, version.</li> <li>There is a browser specific issue that is either a bug in our software that hasn’t been discovered or it is something unique to their browser such as security settings or a conflict with a browser plugin like developer tools. Trying a different browser such as Firefox or Chrome would be a good step.</li> <li>There is a computer or network specific issue that we can’t determine such as a firewall, proxy, NAT, upload versus download speed, etc. Trying a different computer at a different location might be a good step.</li> <li>They are uploading a really large subsettable file or many files and it is taking a really long time to upload.</li> <li>There is something wrong with our server such as it not responding.</li> <li>Using IE 8, if you add 2 text or pdf files in a row it won’t upload but if you add singly or also add a subsettable file they all work. Known issue, reported previously, <a class="reference external" href="https://redmine.hmdc.harvard.edu/issues/2367">#2367</a></li> </ol> <p><strong>So, general information that would be good to get and things to try would be:</strong></p> <ol class="arabic simple"> <li>Have you ever been able to upload a file?</li> <li>Does a small text file work?</li> <li>Which browser and operating system are you using? Can you try Firefox or Chrome?</li> <li>Does the problem affect some files or all files? If some files, do they work one at a time? Are they all the same type such as Stata or SPSS? Which version? Can they be saved as a supported version, e.g. Stata 12 or SPSS 20? Upload them as type “other” and we’ll test here.</li> <li>Can you try a different computer at a different location?</li> <li>Last, we’ll try uploading it for you (may need DropBox to facilitate upload).</li> </ol> </div> <div class="section" id="manage-collections"> <span id="id8"></span><h3>Manage Collections<a class="headerlink" href="#manage-collections" title="Permalink to this headline">¶</a></h3> <p>Collections can contain studies from your own dataverse or another, public dataverse in the Network.</p> <p><strong>Create Collection</strong></p> <p>You can create new collections in your dataverse, but any new collection is a child of the root collection except for Collection Links. When you create a child in the root collection, you also can create a child within that child to make a nested organization of collections. The root collection remains the top-level parent to all collections that are not linked from another dataverse.</p> <p>There are three ways in which you can create a collection:</p> <ul class="simple"> <li>Static collection - You assign specific studies to this type of collection.</li> <li>Dynamic collection - You can create a query that gathers studies into a collection based on matching criteria, and keep the contents current. If a study matches the query selection criteria one week, then is changed and no longer matches the criteria, that study is only a member of the collection as long as it’s criteria matches the query.</li> <li>Linked collection - You can link an existing collection from another dataverse to your dataverse homepage. Note that the contents of that collection can be edited only in the originating dataverse.</li> </ul> <p><strong>Create Static Collection by Assigning Studies</strong></p> <p>To create a collection by assigning studies directly to it:</p> <ol class="arabic"> <li><p class="first">Locate the root collection to create a direct subcollection in the root, or locate any other existing collection in which you choose create a new collection. Then, click the <em>Create</em> link in the Create Child field for that collection.</p> <p>You see the Study Collection page.</p> </li> <li><p class="first">In the Type field, click the Static option.</p> </li> <li><p class="first">Enter your collection Name.</p> </li> <li><p class="first">Select the Parent in which you choose to create the collection. The default is the collection in which you started on the <em>Manage Collections</em> page. You cannot create a collection in another dataverse unless you have permission to do so.</p> </li> <li><p class="first">Populate the Selected Studies box:</p> <ul class="simple"> <li>Click the <em>Browse</em> link to use the Dataverse and Collection pull-down lists to create a list of studies.</li> <li>Click the <em>Search</em> link to select a query field and search for specific studies, enter a term to search for in that query field, and then click Search.</li> </ul> <p>A list of available studies is displayed in the Studies to Choose from box.</p> </li> <li><p class="first">In the Studies to Choose from box, click a study to assign it to your collection.</p> <p>You see the study you clicked in the Selected Studies box.</p> </li> <li><p class="first">To remove studies from the list of Selected Studies, click the study in that box.</p> <p>The study is remove from the Selected Studies box.</p> </li> <li><p class="first">If needed, repopulate the Studies to Choose from box with new studies, and add additional studies to the Studies Selected list.</p> </li> </ol> <p><strong>Create Linked Collection</strong></p> <p>You can create a collection as a link to one or more collections from other dataverses, thereby defining your own collections for users to browse in your dataverse.</p> <p>Note: A collection created as a link to a collection from another dataverse is editable only in the originating dataverse. Also, collections created by use of this option might not adhere to the policies for adding Cataloging Information and study files that you require in your own dataverse.</p> <p>To create a collection as a link to another collection:</p> <ol class="arabic"> <li><p class="first">In the Linked Collections field, click Add Collection Link.</p> <p>You see the Add Collection Link window.</p> </li> <li><p class="first">Use the Dataverse pull-down list to select the dataverse from which you choose to link a collection.</p> </li> <li><p class="first">Use the Collection pull-down list to select a collection from your selected dataverse to add a link to that collection in your dataverse.</p> <p>The collection you select will be displayed in your dataverse homepage, and will be included in your dataverse searches.</p> </li> </ol> <p><strong>Create Dynamic Collection as a Query</strong></p> <p>When you create a collection by assigning the results of a query to it, that collection is dynamic and is updated regularly based on the query results.</p> <p>To create a collection by assigning the results of a query:</p> <ol class="arabic"> <li><p class="first">Locate the root collection to create a direct subcollection in the root, or locate any other existing collection in which you choose create a new collection. Then, click the <em>Create</em> link in the Create Child field for that collection.</p> <p>You see the Study Collection page.</p> </li> <li><p class="first">In the Type field, click the Dynamic option.</p> </li> <li><p class="first">Enter your collection Name.</p> </li> <li><p class="first">Select the Parent in which you choose to create the collection.</p> <p>The default is the collection in which you started on the <em>Manage Collections</em> page. You cannot create a collection in another dataverse unless you have permission to do so.</p> </li> <li><p class="first">Enter a Description of this collection.</p> </li> <li><p class="first">In the Enter query field, enter the study field terms for which to search to assign studies with those terms to this collection. Use the following guidelines:</p> <ul> <li><p class="first">Almost all study fields can be used to build a collection query.</p> <p>The study fields must be entered in the appropriate format to search the fields’ contents.</p> </li> <li><p class="first">Use the following format for your query: <tt class="docutils literal"><span class="pre">title:Elections</span> <span class="pre">AND</span> <span class="pre">keywordValue:world</span></tt>.</p> <p>For more information on query syntax, refer to the <a class="reference external" href="http://lucene.apache.org/java/docs/">Documentation</a> page at the Lucene website and look for <em>Query Syntax</em>. See the <a class="reference external" href="http://guides.thedata.org/files/thedatanew_guides/files/catalogingfields11apr08.pdf">cataloging fields</a> document for field query names.</p> </li> <li><p class="first">For each study in a dataverse, the Study Global Id field in the Cataloging Information consists of three query terms: <tt class="docutils literal"><span class="pre">protocol</span></tt>, <tt class="docutils literal"><span class="pre">authority</span></tt>, and <tt class="docutils literal"><span class="pre">globalID</span></tt>.</p> <p>If you build a query using <tt class="docutils literal"><span class="pre">protocol</span></tt>, your collection can return any study that uses the <tt class="docutils literal"><span class="pre">protocol</span></tt> you specified.</p> <p>If you build a query using all three terms, you collection returns only one study.</p> </li> </ul> </li> <li><p class="first">To limit this collection to search for results in your own dataverse, click the <em>Only your dataverse</em> check box.</p> </li> </ol> <p><strong>Edit Collections</strong></p> <ol class="arabic"> <li><p class="first">Click a collection title to edit the contents or setup of that collection.</p> <p>You see the Collection page, with the current collection settings applied.</p> </li> <li><p class="first">Change, add, or delete any settings that you choose, and then click Save Collection to save your edits.</p> </li> </ol> <p><strong>Delete Collections or Remove Links</strong></p> <p>To delete existing static or dynamic collections:</p> <ol class="arabic simple"> <li>For the collection that you choose to delete, click the Delete link.</li> <li>Confirm the delete action to remove the collection from your dataverse.</li> </ol> <p>To remove existing linked collections:</p> <ol class="arabic simple"> <li>For the linked collection that you choose to remove, click the <em>Remove</em> link. (Note: There is no confirmation for a Remove action. When you click the Remove link, the Dataverse Network removes the linked collection immediately.)</li> </ol> </div> <div class="section" id="managing-user-file-access"> <h3>Managing User File Access<a class="headerlink" href="#managing-user-file-access" title="Permalink to this headline">¶</a></h3> <p>User file access is managed through a set of access permissions that together determines whether or not a user can access a particular file, study, or dataverse. Generally speaking, there are three places where access permissions can be configured: at the dataverse level, at the study level, and at the file level. Think of each of these as a security perimeter or lock with dataverse being the outer most perimeter, study the next, and finally the file level. When configuring user file access, it might be helpful to approach this from the dataverse access level first and so on.</p> <p>For example, a user would like access to a particular file. Since files belong to studies and studies belong to dataverses, first determine whether the user has access to the dataverse. If the dataverse is released, all users have access to it. If it is unreleased, the user must appear in the User Permissions section on the dataverse permissions page.</p> <p>Next, they would need access to the study. If the study is public, then everyone has access. If it is restricted, the user must appear in the User Restricted Study Settings section on the study permissions page.</p> <p>Last, they would need access to the file. If the file is public, everyone has access. If the file is restricted, then the user must be granted access.</p> <p><strong>There are two ways a file can be restricted.</strong></p> <p>First, on the dataverse permissions page, all files in the dataverse could be restricted using Restrict ALL files in this Dataverse. To enable user access in this case, add the username to the Restricted File User Access section on this page.</p> <p>Second, individual files can be restricted at the study level on the study permissions page in the “Files” subtab. These can be restricted on a file-by-file basis. If this is the case, the file(s) will be displayed as restricted in the Individual File Permission Settings section. To enable user access to a particular file in this case, check the file to grant access to, type the username in the Restricted File User Access section, click update so their name appears next to the file, then click save.</p> <p>Another option at the study level when restricting files is to allow users the ability to request access to restricted files. This can be done in the study Permissions page in the “Files” subtab where you must first select the files you want to restrict, click on “update permissions” to restrict, and then under “File Permission Settings” check off the box to “Allow users to request access...” and click on Save at the bottom of the page. The contact(s) set for the Dataverse (<tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">Options</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">></span> <span class="pre">General</span></tt>) will get an email notification each time a user sends a request. The request access email will displays a list of the file(s) requested and a DOI or Handle for the study. To approve or deny access to these file(s) go back to the study permissions page under the “Files” subtab and Approve or Deny the specific files that were requested. If you choose to deny any files you will have the option to add a reason why. Be sure to remember to click on the “update” button and then select Save so that your selections are saved and an email is sent to the requestor granting or denying them access. The email then sent to the requestor will list out which files were approved with a DOI or Handle URL, and any files which were denied along with any reasons that may have been provided.</p> <p>Finally, a somewhat unusual configuration could exist where both Restrict all files in a dataverse is set and an individual file is restricted. In this case access would need to be granted in both places -think of it as two locks. This last situation is an artifact of integrating these two features and will be simplified in a future release.</p> </div> </div> <div class="section" id="network-administration"> <h2>Network Administration<a class="headerlink" href="#network-administration" title="Permalink to this headline">¶</a></h2> <p>The Dataverse Network provides several options for configuring and customizing your application. To access these options, login to the Dataverse Network application with an account that has Network Administrator privileges. By default, a brand new installation of the application will include an account of this type - the username and password is ‘networkAdmin’.</p> <p>After you login, the Dataverse Network home page links to the Options page from the “Options” gear icon, in the menu bar. Click on the icon to view all the options available for customizing and configuring the applications, as well as some network adminstrator utilities.</p> <p>The following tasks can be performed from the Options page:</p> <ul class="simple"> <li>Manage dataverses, harvesting, exporting, and OAI sets - Create, edit, and manage standard and harvesting dataverses, manage harvesting schedules, set study export schedules, and manage OAI harvesting sets.</li> <li>Manage subnetworks - Create, edit, and manage subnetworks, manage network and subnetwork level study templates.</li> <li>Customize the Network pages and description - Brand your Network and set up your Network e-mail contact.</li> <li>Set and edit Terms of Use - Apply Terms of Use at the Network level for accounts, uploads, and downloads.</li> <li>Create and manage user accounts and groups and Network privileges, and enable option to create a dataverse - Manage logins, permissions, and affiliate access to the Network.</li> <li>Use utilities and view software information - Use the administrative utilities and track the current Network installation.</li> </ul> <div class="section" id="dataverses-section"> <h3>Dataverses Section<a class="headerlink" href="#dataverses-section" title="Permalink to this headline">¶</a></h3> <div class="section" id="create-a-new-dataverse"> <h4>Create a New Dataverse<a class="headerlink" href="#create-a-new-dataverse" title="Permalink to this headline">¶</a></h4> <p>A dataverse is a container for studies and is the home for an individual scholar’s or organization’s data.</p> <p>Creating a dataverse is easy but first you must be a registered user. Depending on site policy, there may be a link on the Network home page, entitled “Create a Dataverse”. This first walks you through creating an account, then a dataverse. If this is not the case on your site, log in, then navigate to the Create a New Dataverse page and complete the required information. That’s it!</p> <ol class="arabic"> <li><dl class="first docutils"> <dt>Navigate to the Create a New Dataverse page:</dt> <dd><p class="first last">Network home page > Options page >Dataverses tab > Dataverse subtab > “Create Dataverse” link.</p> </dd> </dl> </li> <li><p class="first">Fill in the required information:</p> <blockquote> <div><p><strong>Type of Dataverse</strong></p> <p>Choose Scholar if it represents an individual’s work otherwise choose Basic.</p> <p><strong>Dataverse Name</strong></p> <p>This will be displayed on the network and dataverse home pages. If this is a Scholar dataverse it will automatically be filled in with the scholar’s first and last name.</p> <p><strong>Dataverse Alias</strong></p> <p>This is an abbreviation, usually lower-case, that becomes part of the URL for the new dataverse.</p> </div></blockquote> </li> <li><p class="first">Click Save and you’re done!</p> <p>An email will be sent to you with more information, including the url to access you new dataverse.</p> </li> </ol> <p><strong>Required information</strong> can vary depending on site policy. Required fields are noted with a red asterisk.</p> <p>Note: If “Allow users to create a new Dataverse when they create an account” is enabled, there is a Create a Dataverse link on the Network home page.</p> </div> <div class="section" id="manage-dataverses"> <h4>Manage Dataverses<a class="headerlink" href="#manage-dataverses" title="Permalink to this headline">¶</a></h4> <p>As dataverses increase in number it’s useful to view summary information in table form and quickly locate a dataverse of interest. The Manage Dataverse table does just that.</p> <p>Navigate to Network home page > Options page > Dataverses tab > Dataverses subtab > Manage Dataverse table:</p> <ul class="simple"> <li>Dataverses are listed in order of most recently created.</li> <li>Clicking on a column name sorts the list by that column such as Name or Affiliation.</li> <li>Clicking on a letter in the alpha selector displays only those dataverses beginning with that letter.</li> <li>Move through the list of dataverses by clicking a page number or the forward and back buttons.</li> <li>Click Delete to remove a dataverse.</li> </ul> </div> </div> <div class="section" id="subnetwork-section"> <h3>Subnetwork Section<a class="headerlink" href="#subnetwork-section" title="Permalink to this headline">¶</a></h3> <p>A subnetwork is a container for a group of dataverses. Users will be able to create their dataverses in a particular subnetwork. It may include its own branding and its own custom study templates.</p> <div class="section" id="create-a-new-subnetwork"> <h4>Create a New Subnetwork<a class="headerlink" href="#create-a-new-subnetwork" title="Permalink to this headline">¶</a></h4> <p>You must be a network admin in order to create a subnetwork. These are the steps to create a subnetwork:</p> <ol class="arabic"> <li><dl class="first docutils"> <dt>Navigate to Create a New Subnetwork Page:</dt> <dd><p class="first last">Network home page > Options page > Subnetworks tab> Create Subnetwork Link</p> </dd> </dl> </li> <li><p class="first">Fill in required information:</p> <blockquote> <div><p><strong>Subnetwork Name</strong></p> <p>The name to be displayed in the menubar. Please use a short name.</p> <p><strong>Subnetwork Alias</strong></p> <p>Short name used to build the URL for this Subnetwork. It is case sensitive.</p> <p><strong>Subnetwork Short Description</strong></p> <p>This short description is displayed on the Network Home page</p> </div></blockquote> </li> <li><dl class="first docutils"> <dt>Fill in Optional Branding</dt> <dd><p class="first last">These fields include a logo file, Subnetwork affiliation, description, and custom banner and footer.</p> </dd> </dl> </li> <li><p class="first">Click Save and you’re done!</p> </li> </ol> </div> <div class="section" id="manage-subnetworks"> <h4>Manage Subnetworks<a class="headerlink" href="#manage-subnetworks" title="Permalink to this headline">¶</a></h4> <p>The Manage Subnetworks page gives summary information about all of the subnetworks in your installation.</p> <p>Navigate to Network home page > Options Page > Subnetworks tab:</p> <ul class="simple"> <li>Subnetworks are listed alphabetically</li> <li>Clicking on a column name sorts the list by that column</li> <li>Click Edit to edit the subnetwork’s information or branding</li> <li>Click Delete to remove a subnetwork. Note: this will not remove the dataverses assigned to the subnetwork. The dataverses will remain and may be reassigned to another subnetwork.</li> </ul> </div> <div class="section" id="manage-classifications"> <h4>Manage Classifications<a class="headerlink" href="#manage-classifications" title="Permalink to this headline">¶</a></h4> <p>Classifications are a way to organize dataverses on the network home page so they are more easily located. They appear on the left side of the page and clicking on a classification causes corresponding dataverses to be displayed. An example classification might be Organization, Government.</p> <p>Classifications typically form a hierarchy defined by the network administrator to be what makes sense for a particular site. A top level classification could be Organization, the next level Association, Business, Government, and School.</p> <p>The classification structure is first created on the Options page, from the Manage Classifications table. Once a classification is created, dataverses can be assigned to it either when the dataverse is first created or later from the Options page: Network home page > (Your) Dataverse home page > Options page > Settings tab > General subtab.</p> <p>To manage classifications, navigate to the Manage Classifications table:</p> <p>Network home page > Options page > Classifications tab > Manage Classifications table</p> <p>From here you can view the current classification hierarchy, create a classification, edit an existing classification including changing its place in the hierarchy, and delete a classification.</p> </div> <div class="section" id="manage-study-comments-notifications"> <h4>Manage Study Comments Notifications<a class="headerlink" href="#manage-study-comments-notifications" title="Permalink to this headline">¶</a></h4> <p>Dataverse admins can enable or disable a User Comment feature within their dataverses. If this feature is enabled, users are able to add comments to studies within that dataverse. Part of the User Comment feature is the ability for users to report comments as abuse if they deem that comment to be inappropriate in some way.</p> <p>Note that it is a best practice to explicitly define terms of use regarding comments when the User Comments feature is enabled. If you define those terms at the Network level, then any study to which comments are added include those terms.</p> <p>When a user reports another’s comment as abuse, that comment is listed on the Manage Study Comment Notifications table on the Options page. For each comment reported as abuse, you see the study’s Global ID, the comment reported, the user who posted the comment, and the user who reported the comment as abuse.</p> <p>There are two ways to manage abuse reports: In the Manage Study Comment Notifications table on the Options page, and on the study page User Comments tab. In both cases, you have the options to remove the comment or to ignore the abuse report.</p> <p>The Manage Study Comments Notifications table can be found here:</p> <p>Network home page > Options page > Dataverses tab > Study Comments subtab > Manage Study Comment Notifications table</p> </div> <div class="section" id="manage-controlled-vocabulary"> <h4>Manage Controlled Vocabulary<a class="headerlink" href="#manage-controlled-vocabulary" title="Permalink to this headline">¶</a></h4> <p>You can set up controlled vocabulary for a dataverse network to give the end user a set list of choices to select from for most fields in a study template. Study fields which do not allow controlled vocabulary include the study title and subtitle, certain date fields and geographic boundaries.</p> <p>To <strong>manage controlled vocabulary</strong>, navigate to the Manage Controlled Vocabulary table:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Vocabulary</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Manage</span> <span class="pre">Controlled</span> <span class="pre">Vocabulary</span> <span class="pre">table</span></tt></p> <p><strong>To create a new controlled vocabulary:</strong></p> <ol class="arabic simple"> <li>Click Create New Controlled Vocabulary.</li> <li>You see the Edit Controlled Vocabulary page.</li> <li>In the Name field, enter a descriptive name for this Controlled Vocabulary. In the Description field enter any additional information that will make it easier to identify a particular controlled vocabulary item to assign to a given custom field. In the Values field enter the controlled vocabulary values that you want to make available to users for a study field. Here you can submit an entire list of terms at once. Use the “add” and “remove” buttons to add or subtract values from the list. You may also copy and paste a list of values separated by carriage returns.</li> <li>After you complete entry of values, click Save to create the controlled vocabulary.</li> </ol> <p><strong>Edit Controlled Vocabulary</strong></p> <p>To edit an existing controlled vocabulary:</p> <ol class="arabic simple"> <li>In the list of controlled vocabulary, click the Edit link for the controlled vocabulary that you choose to edit. You see the Edit Controlled Vocabulary page, with the controlled vocabulary setup that you selected.</li> <li>Edit the controlled vocabulary items that you choose to change, add, or remove. You may also copy and paste a list of values separated by carriage returns.</li> </ol> </div> <div class="section" id="manage-network-study-templates"> <h4>Manage Network Study Templates<a class="headerlink" href="#manage-network-study-templates" title="Permalink to this headline">¶</a></h4> <p>You can set up study templates for a dataverse network to prepopulate any of the Cataloging Information fields of a new study with default values. Dataverse administrators may clone a Network template and modify it for users of that dataverse. You may also change the input level of any field to make a certain field required, recommended, optional, hidden or disabled. Hidden fields will not be available to the user, but will be available to the dataverse administrator for update in cloned templates. Disabled field will not be available to the dataverse administrator for update. You may also add your own custom fields. When a user adds a new study, that user can select a template to fill in the defaults.</p> <p>To manage study templates, navigate to the Manage Study Templates table:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Templates</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Manage</span> <span class="pre">Study</span> <span class="pre">Templates</span> <span class="pre">table</span></tt></p> <p><strong>Create Template</strong></p> <p>Study templates help to reduce the work needed to add a study, and to apply consistency to studies across a dataverse network. For example, you can create a template to include the Distributor and Contact details so that every study has the same values for that metadata.</p> <p>To create a new study template:</p> <ol class="arabic simple"> <li>Click Create New Network Template.</li> <li>You see the Study Template page.</li> <li>In the Template Name field, enter a descriptive name for this template.</li> <li>Enter generic information in any of the Cataloging Information metadata fields. You can also add your own custom fields to the Data Collection/Methodology section of the template. Each custom field must be assigned a Name, Description and Field Type. You may also apply controlled vocabulary to any of the custom fields that are set to Plain Text Input as Field Type.</li> <li>After you complete entry of generic details in the fields that you choose to prepopulate for new studies, click Save to create the template.</li> </ol> <p><strong>Enable a template</strong></p> <p>Click the Enabled link for the given template. Enabled templates are available to database administrators for cloning and end users for creating studies.</p> <p><strong>Edit Template</strong></p> <p>To edit an existing study template:</p> <ol class="arabic simple"> <li>In the list of templates, click the Edit link for the template that you choose to edit.</li> <li>You see the Study Template page, with the template setup that you selected.</li> <li>Edit the template fields that you choose to change, add, or remove.</li> </ol> <p><strong>Make a Template the Default</strong></p> <p>To set any study template as the default template that applies automatically to the creation of new network templates:</p> <p>In the list of templates, click the Make Default Selection link next to the name of the template that you choose to set as the default for a subnetwork(s). A pop-up window with the names of the subnetworks will appear and you may select the appropriate subnetworks. The subnetwork name(s) is displayed in the Default column of the template that you set as the default for each given subnetwork.</p> <p><strong>Remove Template</strong></p> <p>To delete a study template from a dataverse:</p> <ol class="arabic simple"> <li>In the list of templates, click the Delete link for the template that you choose to remove from the network.</li> <li>You see the Delete Template page.</li> <li>Click Delete to remove the template from the network. Note that you cannot delete any template that is in use or is a default template at the network or dataverse level.</li> </ol> </div> </div> <div class="section" id="harvesting-section"> <h3>Harvesting Section<a class="headerlink" href="#harvesting-section" title="Permalink to this headline">¶</a></h3> <div class="section" id="create-a-new-harvesting-dataverse"> <h4>Create a New Harvesting Dataverse<a class="headerlink" href="#create-a-new-harvesting-dataverse" title="Permalink to this headline">¶</a></h4> <p>A harvesting dataverse allows studies from another site to be imported so they appear to be local, though data files remain on the remote site. This makes it possible to access content from data repositories and other sites with interesting content as long as they support the OAI or Nesstar protocols.</p> <p>Harvesting dataverses differ from ordinary dataverses in that study content cannot be edited since it is provided by a remote source. Most dataverse functions still apply including editing the dataverse name, branding, and setting permissions.</p> <p>Aside from providing the usual name, alias, and affiliation information, Creating a harvesting dataverse involves specifying the harvest protocol, OAI or Nesstar, the remote server URL, possibly format and set information, whether or how to register incoming studies, an optional harvest schedule, and permissions settings.</p> <p>To create a harvesting dataverse navigate to the Create a New Harvesting Dataverse page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">> Harvesting</span> <span class="pre">tab</span> <span class="pre">> Harvesting</span> <span class="pre">Dataverses</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">"Create</span> <span class="pre">Harvesting</span> <span class="pre">Dataverse"</span> <span class="pre">link</span></tt></p> <p>Complete the form by entering required information and click Save.</p> <p>An example dataverse to harvest studies native to the Harvard dataverse:</p> <ul class="simple"> <li><strong>Harvesting Type:</strong> OAI Server</li> <li><strong>Dataverse Name:</strong> Test IQSS Harvest</li> <li><strong>Dataverse Alias:</strong> testiqss</li> <li><strong>Dataverse Affiliation:</strong> Our Organization</li> <li><strong>Server URL:</strong> <a class="reference external" href="http://dvn.iq.harvard.edu/dvn/OAIHandler">http://dvn.iq.harvard.edu/dvn/OAIHandler</a></li> <li><strong>Harvesting Set:</strong> No Set (harvest all)</li> <li><strong>Harvesting Format:</strong> DDI</li> <li><strong>Handle Registration:</strong> Do not register harvested studies (studies must already have a handle)</li> </ul> </div> <div class="section" id="manage-harvesting"> <h4>Manage Harvesting<a class="headerlink" href="#manage-harvesting" title="Permalink to this headline">¶</a></h4> <p>Harvesting is a background process meaning once initiated, either directly or via a timer, it conducts a transaction with a remote server and exists without user intervention. Depending on site policy and considering the update frequency of remote content this could happen daily, weekly, or on-demand. How does one determine what happened? By using the Manage Harvesting Dataverses table on the Options page.</p> <p>To manage harvesting dataverses, navigate to the <strong>Manage Harvesting Dataverses</strong> table:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Harvesting</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Harvesting</span> <span class="pre">Dataverses</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Manage</span> <span class="pre">Harvesting</span> <span class="pre">Dataverses</span> <span class="pre">table</span></tt></p> <p>The Manage Harvesting table displays all harvesting dataverses, their schedules, and harvest results in table form. The name of each harvesting dataverse is a link to that harvesting dataverse’s configuration page. The schedule, if configured, is displayed along with a button to enable or disable the schedule. The last attempt and result is displayed along with the last non-zero result. It is possible for the harvest to check for updates and there are none. A Run Now button provides on-demand harvesting and a Remove link deletes the harvesting dataverse.</p> <p>Note: the first time a dataverse is harvested the entire catalog is harvested. This may take some time to complete depending on size. Subsequent harvests check for additions and changes or updates.</p> <p>Harvest failures can be investigated by examining the import and server logs for the timeframe and dataverse in question.</p> </div> <div class="section" id="schedule-study-exports"> <h4>Schedule Study Exports<a class="headerlink" href="#schedule-study-exports" title="Permalink to this headline">¶</a></h4> <p>Sharing studies programmatically or in batch such as by harvesting requires information about the study or metadata to be exported in a commonly understood format. As this is a background process requiring no user intervention, it is common practice to schedule this to capture updated information.</p> <p>Our export process generates DDI, Dublin Core, Marc, and FGDC formats though DDI and Dublin Core are most commonly used. Be aware that different formats contain different amounts of information with DDI being most complete because it is our native format.</p> <p>To schedule study exports, navigate to the Harvesting Settings subtab:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Harvesting</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Export</span> <span class="pre">Schedule</span></tt></p> <p>First enable export then choose frequency: daily using hour of day or weekly using day of week. Click Save and you are finished.</p> <p>To disable, just choose Disable export and Save.</p> </div> <div class="section" id="manage-oai-harvesting-sets"> <h4>Manage OAI Harvesting Sets<a class="headerlink" href="#manage-oai-harvesting-sets" title="Permalink to this headline">¶</a></h4> <p>By default, a client harvesting from the Dataverse Network that does not specify a set would fetch all unrestricted, locally owned studies - in other words public studies that were not harvested from elsewhere. For various reasons it might be desirable to define sets of studies for harvest such as by owner, or to include a set that was harvested from elsewhere. This is accomplished using the Manage OAI Harvesting Sets table on the Options page.</p> <p>The Manage OAI Harvesting Sets table lists all currently defined OAI sets, their specifications, and edit, create, and delete functionality.</p> <p>To manage OAI harvesting sets, navigate to the Manage OAI Harvesting Sets table:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Harvesting</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">OAI</span> <span class="pre">Harvesting</span> <span class="pre">Sets</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Manage OAI</span> <span class="pre">Harvesting</span> <span class="pre">Sets</span> <span class="pre">table</span></tt></p> <p>To create an OAI set, click Create OAI Harvesting Set, complete the required fields and Save. The essential parameter that defines the set is the Query Definition. This is a search query using <a class="reference external" href="http://lucene.apache.org/java/3_0_0/queryparsersyntax.html">Lucene syntax</a> whose results populate the set.</p> <p>Once created, a set can later be edited by clicking on its name.</p> <p>To delete a set, click the appropriately named Delete Set link.</p> <p>To test the query results before creating an OAI set, a recommended approach is to create a <a class="reference internal" href="#manage-collections"><em>dynamic study collection</em></a> using the proposed query and view the collection contents. Both features use the same <a class="reference external" href="http://lucene.apache.org/java/3_0_0/queryparsersyntax.html">Lucene syntax</a> but a study collection provides a convenient way to confirm the results.</p> <p>Generally speaking, basic queries take the form of study metadata field:value. Examples include:</p> <ul class="simple"> <li><tt class="docutils literal"><span class="pre">globalId:"hdl</span> <span class="pre">1902</span> <span class="pre">1</span> <span class="pre">10684"</span> <span class="pre">OR</span> <span class="pre">globalId:"hdl</span> <span class="pre">1902</span> <span class="pre">1</span> <span class="pre">11155"</span></tt>: Include studies with global ids <a class="reference external" href="hdl:1902.1/10684">hdl:1902.1/10684</a> and <a class="reference external" href="hdl:1902.1/11155">hdl:1902.1/11155</a></li> <li><tt class="docutils literal"><span class="pre">authority:1902.2</span></tt>: Include studies whose authority is 1902.2. Different authorities usually represent different sources such as IQSS, ICPSR, etc.</li> <li><tt class="docutils literal"><span class="pre">dvOwnerId:184</span></tt>: Include all studies belonging to dataverse with database id 184</li> <li><tt class="docutils literal"><span class="pre">studyNoteType:"DATAPASS"</span></tt>: Include all studies that were tagged with or include the text DATAPASS in their study note field.</li> </ul> <p><strong>Study Metadata Search Terms:</strong></p> <div class="line-block"> <div class="line">title</div> <div class="line">subtitle</div> <div class="line">studyId</div> <div class="line">otherId</div> <div class="line">authorName</div> <div class="line">authorAffiliation</div> <div class="line">producerName</div> <div class="line">productionDate</div> <div class="line">fundingAgency</div> <div class="line">distributorName</div> <div class="line">distributorContact</div> <div class="line">distributorContactAffiliation</div> <div class="line">distributorContactEmail</div> <div class="line">distributionDate</div> <div class="line">depositor</div> <div class="line">dateOfDeposit</div> <div class="line">seriesName</div> <div class="line">seriesInformation</div> <div class="line">studyVersion</div> <div class="line">relatedPublications</div> <div class="line">relatedMaterial</div> <div class="line">relatedStudy</div> <div class="line">otherReferences</div> <div class="line">keywordValue</div> <div class="line">keywordVocabulary</div> <div class="line">topicClassValue</div> <div class="line">topicClassVocabulary</div> <div class="line">abstractText</div> <div class="line">abstractDate</div> <div class="line">timePeriodCoveredStart</div> <div class="line">timePeriodCoveredEnd</div> <div class="line">dateOfCollection</div> <div class="line">dateOfCollectionEnd</div> <div class="line">country</div> <div class="line">geographicCoverage</div> <div class="line">geographicUnit</div> <div class="line">unitOfAnalysis</div> <div class="line">universe</div> <div class="line">kindOfData</div> <div class="line">timeMethod</div> <div class="line">dataCollector</div> <div class="line">frequencyOfDataCollection</div> <div class="line">samplingProcedure</div> <div class="line">deviationsFromSampleDesign</div> <div class="line">collectionMode</div> <div class="line">researchInstrument</div> <div class="line">dataSources</div> <div class="line">originOfSources</div> <div class="line">characteristicOfSources</div> <div class="line">accessToSources</div> <div class="line">dataCollectionSituation</div> <div class="line">actionsToMinimizeLoss</div> <div class="line">controlOperations</div> <div class="line">weighting</div> <div class="line">cleaningOperations</div> <div class="line">studyLevelErrorNotes</div> <div class="line">responseRate</div> <div class="line">samplingErrorEstimate</div> <div class="line">otherDataAppraisal</div> <div class="line">placeOfAccess</div> <div class="line">originalArchive</div> <div class="line">availabilityStatus</div> <div class="line">collectionSize</div> <div class="line">studyCompletion</div> <div class="line">confidentialityDeclaration</div> <div class="line">specialPermissions</div> <div class="line">restrictions</div> <div class="line">contact</div> <div class="line">citationRequirements</div> <div class="line">depositorRequirements</div> <div class="line">conditions</div> <div class="line">disclaimer</div> <div class="line">studyNoteType</div> <div class="line">studyNoteSubject</div> <div class="line">studyNoteText</div> </div> </div> <div class="section" id="edit-lockss-harvest-settings"> <span id="id9"></span><h4>Edit LOCKSS Harvest Settings<a class="headerlink" href="#edit-lockss-harvest-settings" title="Permalink to this headline">¶</a></h4> <p><strong>Summary:</strong></p> <p><a class="reference external" href="http://lockss.stanford.edu/lockss/Home">LOCKSS Project</a> or <em>Lots of Copies Keeps Stuff Safe</em> is an international initiative based at Stanford University Libraries that provides a way to inexpensively collect and preserve copies of authorized e-content. It does so using an open source, peer-to-peer, decentralized server infrastructure. In order to make a LOCKSS server crawl, collect and preserve content from a Dataverse Network, both the server (the LOCKSS daemon) and the client (the Dataverse Network) sides must be properly configured. In simple terms, the LOCKSS server needs to be pointed at the Dataverse Network, given its location and instructions on what to crawl; the Dataverse Network needs to be configured to allow the LOCKSS daemon to access the data. The section below describes the configuration tasks that the Dataverse Network administrator will need to do on the client side. It does not describe how LOCKSS works and what it does in general; it’s a fairly complex system, so please refer to the documentation on the <a class="reference external" href="http://lockss.stanford.edu/lockss/Home">LOCKSS Project</a> site for more information. Some information intended to a LOCKSS server administrator is available in the <a class="reference external" href="http://guides.thedata.org/book/h-using-lockss-dvn">“Using LOCKSS with Dataverse Network (DVN)”</a> of the <a class="reference external" href="http://guides.thedata.org/book/installers-guides">Dataverse Network Installers Guide</a></p> <blockquote> <div>(our primary sysadmin-level manual).</div></blockquote> <p><strong>Configuration Tasks:</strong></p> <p>Note that neither the standard LOCKSS Web Crawler, nor the OAI plugin can properly harvest materials from a Dataverse Network. A custom LOCKSS plugin developed and maintained by the Dataverse Network project is available here: <a class="reference external" href="http://lockss.hmdc.harvard.edu/lockss/plugin/DVNOAIPlugin.jar">http://lockss.hmdc.harvard.edu/lockss/plugin/DVNOAIPlugin.jar</a>. For more information on the plugin, please see the <a class="reference external" href="http://guides.thedata.org/book/h-using-lockss-dvn">“Using LOCKSS with Dataverse Network (DVN)”</a> section of the Dataverse Network Installers Guide. In order for a LOCKSS daemon to collect DVN content designated for preservation, an Archival Unit must be created with the plugin above. On the Dataverse Network side, a Manifest must be created that gives the LOCKSS daemon permission to collect the data. This is done by completing the “LOCKSS Settings” section of the: <tt class="docutils literal"><span class="pre">Network</span> <span class="pre">Options</span> <span class="pre">-></span> <span class="pre">Harvesting</span> <span class="pre">-></span> <span class="pre">Settings</span> <span class="pre">tab.</span></tt></p> <p>For the Dataverse Network, LOCKSS can be configured at the network level for the entire site and also locally at the dataverse level. The network level enables LOCKSS harvesting but more restrictive policies, including disabling harvesting, can be configured by each dataverse. A dataverse cannot enable LOCKSS harvesting if it has not first been enabled at the network level.</p> <p>This “Edit LOCKSS Harvest Settings” section refers to the network level LOCKSS configuration.</p> <p>To enable LOCKSS harvesting at the network level do the following:</p> <ul class="simple"> <li>Navigate to the LOCKSS Settings page: <tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">-></span> <span class="pre">Network</span> <span class="pre">Options</span> <span class="pre">-></span> <span class="pre">Harvesting</span> <span class="pre">-></span> <span class="pre">Settings</span></tt>.</li> <li>Fill in the harvest information including the level of harvesting allowed (Harvesting Type, Restricted Data Files), the scope of harvest by choosing a predefined OAI set, then if necessary a list of servers or domains allowed to harvest.</li> <li>It’s important to understand that when a LOCKSS daemon is authorized to “crawl restricted files”, this does not by itself grant the actual access to the materials! This setting only specifies that the daemon should not be skipping such restricted materials outright. (The idea behind this is that in an archive with large amounts of access-restricted materials, if only public materials are to be preserved by LOCKSS, lots of crawling time can be saved by instructing the daemon to skip non-public files, instead of having it try to access them and get 403/Permission Denied). If it is indeed desired to have non-public materials collected and preserved by LOCKSS, it is the responsibility of the DVN Administrator to give the LOCKSS daemon permission to access the files. As of DVN version 3.3, this can only be done based on the IP address of the LOCKSS server (by creating an IP-based user group with the appropriate permissions).</li> <li>Next select any licensing options or enter additional terms, and click “Save Changes”.</li> <li>Once LOCKSS harvesting has been enabled, the LOCKSS Manifest page will be provided by the application. This manifest is read by LOCKSS servers and constitutes agreement to the specified terms. The URL for the network-level LOCKSS manifest is <tt class="docutils literal"><span class="pre">http</span></tt><tt class="docutils literal"><span class="pre">://<YOUR</span> <span class="pre">SERVER>/dvn/faces/ManifestPage.xhtml</span></tt> (it will be needed by the LOCKSS server administrator in order to configure an <em>Archive Unit</em> for crawling and preserving the DVN).</li> </ul> </div> </div> <div class="section" id="settings-section"> <h3>Settings Section<a class="headerlink" href="#settings-section" title="Permalink to this headline">¶</a></h3> <div class="section" id="edit-name"> <h4>Edit Name<a class="headerlink" href="#edit-name" title="Permalink to this headline">¶</a></h4> <p>The name of your Dataverse Network installation is displayed at the top of the Network homepage, and as a link at the top of each dataverse homepage in your Network.</p> <p>To create or change the name of your Network, navigate to the Settings tab on the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">General</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Network</span> <span class="pre">Name</span></tt></p> <p>Enter a descriptive title for your Network. There are no naming restrictions, but it appears in the heading of every dataverse in your Network, so a short name works best.</p> <p>Click Save and you are done!</p> </div> <div class="section" id="id10"> <h4>Edit Layout Branding<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h4> <p>When you install a Network, there is no banner or footer on any page in the Network. You can apply any style to the Network pages, such as that used on your organization’s website. You can use plain text, HTML, JavaScript, and style tags to define your custom banner and footer. If your website has such elements as a navigation menu or images, you can add them to your Network pages.</p> <p>To customize the layout branding of your Network, navigate to the Customization subtab on the Options page:</p> <p>Network home page > Options page > Settings tab > Customization subtab > Edit Layout Branding</p> <p>Enter your banner and footer content in the Custom Banner and Custom Footer fields and Save.</p> <p>See <a class="reference internal" href="#edit-layout-branding"><em>Layout Branding Tips</em></a> for guidelines.</p> </div> <div class="section" id="id11"> <h4>Edit Description<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h4> <p>By default your Network homepage has the following description: <tt class="docutils literal"><span class="pre">A</span> <span class="pre">description</span> <span class="pre">of</span> <span class="pre">your</span> <span class="pre">Dataverse</span> <span class="pre">Network</span> <span class="pre">or</span> <span class="pre">announcements</span> <span class="pre">may</span> <span class="pre">be</span> <span class="pre">added</span> <span class="pre">here.</span> <span class="pre">Use</span> <span class="pre">Network</span> <span class="pre">Options</span> <span class="pre">to</span> <span class="pre">edit</span> <span class="pre">or</span> <span class="pre">remove</span> <span class="pre">this</span> <span class="pre">text.</span></tt> You can edit that text to describe or announce such things as new Network features, new dataverses, or maintenance activities. You also can disable the description to not appear on the homepage.</p> <p>To manage the Network description, navigate to:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">General</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Network</span> <span class="pre">Description</span></tt></p> <p>Create a description by entering your desired content in the text box. HTML, JavaScript, and style tags are permitted. The <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types are not allowed. Next enable the description display by checking the Enable Description in Homepage checkbox. Click Save and you’re done. You can disable the display of the description but keep the content by unchecking and saving.</p> </div> <div class="section" id="edit-dataverse-requirements"> <h4>Edit Dataverse Requirements<a class="headerlink" href="#edit-dataverse-requirements" title="Permalink to this headline">¶</a></h4> <p>Enforcing a minimum set of requirements can help ensure content consistency.</p> <p>When you enable dataverse requirements, newly created dataverses cannot be made public or released until the selected requirements are met. Existing dataverses are not affected until they are edited. Edits to existing dataverses cannot be saved until requirements are met.</p> <p>To manage the requirements, navigate to:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Advanced</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Release</span> <span class="pre">Dataverse</span> <span class="pre">Requirements</span></tt></p> <p>Available requirements include:</p> <ul class="simple"> <li>Require Network Homepage Dataverse Description</li> <li>Require Dataverse Affiliation</li> <li>Require Dataverse Classification</li> <li>Require Dataverse Studies included prior to release</li> </ul> </div> <div class="section" id="id12"> <h4>Manage E-Mail Notifications<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h4> <p>The Dataverse Network sends notifications via email for a number of events on the site, including workflow events such as creating a dataverse, uploading files, releasing a study, etc. Many of these notifications are sent to the user initiating the action as well as to the network administrator. Additionally, the Report Issue link on the network home page sends email to the network administrator. By default, this email is sent to <cite>support@thedata.org <mailto:support@thedata.org></cite>.</p> <p>To change this email address navigate to the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">General</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">E-Mail</span> <span class="pre">Address(es)</span></tt></p> <p>Enter the address of network administrators who should receive these notifications and Save.</p> <p>Please note the Report Issue link when accessed within a dataverse gives the option of sending notification to the network or dataverse administrator. Configuring the dataverse administrator address is done at the dataverse level: <tt class="docutils literal"><span class="pre">(Your)</span> <span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">General</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">E-Mail</span> <span class="pre">Address(es)</span></tt></p> </div> <div class="section" id="id13"> <h4>Enable Twitter<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h4> <p>If your Dataverse Network has been configured for Automatic Tweeting, you will see an option listed as “Enable Twitter.” When you click this, you will be redirected to Twitter to authorize the Dataverse Network application to send tweets for you.</p> <p>To manage the Dataverse Twitter configuration, navigate to:</p> <p><tt class="docutils literal"><span class="pre">Dataverse</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Settings</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Promote</span> <span class="pre">Your</span> <span class="pre">Dataverse</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Sync</span> <span class="pre">Dataverse</span> <span class="pre">With</span> <span class="pre">Twitter</span></tt></p> <p>Once authorized, tweets will be sent for each new dataverse that is released.</p> <p>To disable Automatic Tweeting, go to the options page, and click “Disable Twitter.”</p> </div> </div> <div class="section" id="terms-section"> <h3>Terms Section<a class="headerlink" href="#terms-section" title="Permalink to this headline">¶</a></h3> <div class="section" id="edit-terms-for-account-creation"> <h4>Edit Terms for Account Creation<a class="headerlink" href="#edit-terms-for-account-creation" title="Permalink to this headline">¶</a></h4> <p>You can set up Terms of Use that require users with new accounts to accept your terms before logging in for the first time.</p> <p>To configure these terms navigate to the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Terms</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Account</span> <span class="pre">Term</span> <span class="pre">of</span> <span class="pre">Use</span></tt></p> <p>Enter your required terms as you would like them to appear to users. HTML, JavaScript, and style tags are permitted. The <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types are not allowed. Check Enable Terms of Use to display these terms. Click Save and you are finished. To disable but preserve your current terms, uncheck the Enable checkbox and save.</p> </div> <div class="section" id="id14"> <h4>Edit Terms for Study Creation<a class="headerlink" href="#id14" title="Permalink to this headline">¶</a></h4> <p>You can set up Terms of Use for the Network that require users to accept your terms before they can create or modify studies, including adding data files. These terms are defined at the network level so they apply across all dataverses. Users will be presented with these terms the first time they attempt to modify or create a study during each session.</p> <p>To configure these terms of use navigate to the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Terms</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Deposit</span> <span class="pre">Term</span> <span class="pre">of</span> <span class="pre">Use</span></tt></p> <p>Enter your terms as you would like to display them to the user. HTML, JavaScript, and style tags are permitted. The <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types are not allowed. Check Enable Terms of Use and save. Uncheck Enable Terms of Use and save to disable but preserve existing terms of use.</p> </div> <div class="section" id="id15"> <h4>Edit Terms for File Download<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h4> <p>You can set up Terms of Use for the Network that require users to accept your terms before they can download or subset files from the Network. Since this is defined at the network level it applies to all dataverses. Users will be presented with these terms the first time they attempt to download a file or access the subsetting and analysis page each session.</p> <p>To configure these terms, navigate to the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Terms</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Download</span> <span class="pre">Term</span> <span class="pre">of</span> <span class="pre">Use</span></tt></p> <p>Enter the terms as you want them to appear to the user. HTML, JavaScript, and style tags are permitted. The <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">body</span></tt> element types are not allowed. Check Enable Terms of Use and save. Unchecking the checkbox and saving disables the display of the terms but preserves the current content.</p> </div> <div class="section" id="id16"> <h4>Download Tracking Data<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h4> <p>You can view any guestbook responses that have been made in all dataverses. Beginning with version 3.2 of Dataverse Network, for any dataverse where the guestbook is not enabled data will be collected silently based on the logged in user or anonymously. The data displayed includes user account data or the session id of an anonymous user, the global ID, study title and filename of the file downloaded, the time of the download, the type of download and any custom questions that have been answered. The username/session ID and download type were not collected in the 3.1 version of DVN. A comma separated values file of all download tracking data may be downloaded by clicking the Export Results button.</p> <p>To manage the Network download tracking data, navigate to:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Download</span> <span class="pre">Tracking</span> <span class="pre">Data</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Manage</span> <span class="pre">Download</span> <span class="pre">Tracking</span> <span class="pre">Data</span> <span class="pre">table</span></tt></p> </div> </div> <div class="section" id="permissions-and-users-section"> <h3>Permissions and Users Section<a class="headerlink" href="#permissions-and-users-section" title="Permalink to this headline">¶</a></h3> <div class="section" id="manage-network-permissions"> <h4>Manage Network Permissions<a class="headerlink" href="#manage-network-permissions" title="Permalink to this headline">¶</a></h4> <p>Permissions that are configured at the network level include:</p> <ul class="simple"> <li>Enabling users to create an account when they create a dataverse.</li> <li>Granting privileged roles to existing users including network administrator and dataverse creator.</li> <li>Changing and revoking privileged roles of existing users.</li> </ul> <p>Enabling users to create an account when they create a dataverse displays a “Create a Dataverse” link on the network home page. New and unregistered users coming to the site can click on this link, create an account and a dataverse in one workflow rather than taking two separate steps involving the network administrator.</p> <p>Granting a user account network administrator status gives that user full control over the application as managed through the UI.</p> <p>Granting a user account dataverse creator status is somewhat a legacy function since any user who creates a dataverse has this role.</p> <p>To manage these permissions, navigate to the Manage Network Permissions table on the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Manage</span> <span class="pre">Network</span> <span class="pre">Permissions</span> <span class="pre">table</span></tt></p> <p>Enable account with dataverse creation by checking that option and saving.</p> <p>Granting privileged status to a user requires entering a valid, existing user name, clicking add, choosing the role, then saving changes.</p> </div> <div class="section" id="roles-by-version-state-table"> <h4>Roles by Version State Table<a class="headerlink" href="#roles-by-version-state-table" title="Permalink to this headline">¶</a></h4> <table border="1" class="docutils"> <colgroup> <col width="20%" /> <col width="11%" /> <col width="15%" /> <col width="3%" /> <col width="13%" /> <col width="17%" /> <col width="20%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head"> </th> <th class="head"><strong>Role</strong></th> <th class="head"> </th> <th class="head" colspan="2"> </th> <th class="head"> </th> <th class="head"> </th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><strong>Version State</strong></td> <td>None</td> <td>Contributor +, ++</td> <td colspan="2">Curator</td> <td>Admin</td> <td>Network Admin**</td> </tr> <tr class="row-odd"><td>Draft</td> <td> </td> <td>E,E2,D3,S,V</td> <td colspan="2">E,E2,P,T,D3,R,V</td> <td>E,E2,P,T,D3,R,V</td> <td>E,E2,P,T,D3,D2,R,V</td> </tr> <tr class="row-even"><td>In Review</td> <td> </td> <td>E,E2,D3,V</td> <td colspan="2">E,E2,P,T,D3,R,V</td> <td>E,E2,P,T,D3,R,V</td> <td>E,E2,P,T,D3,R,D2,V</td> </tr> <tr class="row-odd"><td>Released</td> <td>V</td> <td>E,V</td> <td colspan="2">E,P,T,D1,V</td> <td>E,P,T,D1,V</td> <td>E,P,T,D2,D1,V</td> </tr> <tr class="row-even"><td>Archived</td> <td>V</td> <td>V</td> <td colspan="2">P,T,V</td> <td>P,T,V</td> <td>P,T,D2,V</td> </tr> <tr class="row-odd"><td>Deaccessioned</td> <td> </td> <td> </td> <td colspan="2">P,T,R2,V</td> <td>P,T,R2,V</td> <td>P,T,R2,D2,V</td> </tr> </tbody> </table> <p><strong>Legend:</strong></p> <p>E = Edit (Cataloging info, File meta data, Add files)</p> <p>E2 = Edit Study Version Notes</p> <p>D1 = Deaccession</p> <p>P = Permission</p> <p>T = Create Template</p> <p>D2 = Destroy</p> <p>D3 = Delete Draft, Delete Review Version</p> <p>S = Submit for Review</p> <p>R = Release</p> <p>R2 = Restore</p> <p>V = View</p> <p><strong>Notes:</strong></p> <p><a href="#id17"><span class="problematic" id="id18">*</span></a>Same as Curator</p> <p><a href="#id19"><span class="problematic" id="id20">**</span></a>Same as Curator + D2</p> <p>+Contributor actions (E,D3,S,V) depend on new DV permission settings. A contributor role can act on their own studies (default) or all studies in a dv, and registered users can become contributors and act on their own studies or all studies in a dv.</p> <p>++ A contributor is defined either as a contributor role or as any registered user in a DV that allows all registered users to contribute.</p> </div> <div class="section" id="authorization-to-access-terms-protected-files-via-the-api"> <h4>Authorization to access Terms-protected files via the API<a class="headerlink" href="#authorization-to-access-terms-protected-files-via-the-api" title="Permalink to this headline">¶</a></h4> <p>As of DVN v. 3.2, a programmatic API has been provided for accessing DVN materials. It supports Basic HTTP Auth where the client authenticates itself as an existing DVN (or anonymous) user. Based on this, the API determines whether the client has permission to access the requested files or metadata. It is important to remember however, that in addition to access permissions, DVN files may also be subject to “Terms of Use” agreements. When access to such files is attempted through the Web Download or Subsetting interfaces, the user is presented with an agreement form. The API however is intended for automated clients, so the remote party’s compliance with the Terms of Use must be established beforehand. <strong>We advise you to have a written agreement with authorized parties before allowing them to access data sets, bypassing the Terms of Use. The authorized party should be responsible for enforcing the Terms of Use to their end users.</strong>Once such an agreement has been established, you can grant the specified user unrestricted access to Terms-protected materials on the Network home page > Options page > PERMISSIONS tab > Permissions subtab, in the “Authorize Users to bypass Terms of Use” section.</p> <p>Please consult the Data Sharing section of the Guide for additional information on the <a class="reference internal" href="dataverse-api-main.html#data-sharing-api"><em>Data Sharing API</em></a>.</p> </div> <div class="section" id="create-account"> <h4>Create Account<a class="headerlink" href="#create-account" title="Permalink to this headline">¶</a></h4> <p>There are several ways to create accounts: at the network level by the network administrator, at the dataverse level by the dataverse administrator, and by the new user themselves if the option to create an account when creating a dataverse is enabled.</p> <p>Accounts created by all methods are equivalent with the exception of granting dataverse creator status during the create a dataverse workflow. That status can be granted afterwards by the network administrator if necessary.</p> <p>To create an account at the <strong>network admin level</strong>, navigate to the Create Account page from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Users</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Create</span> <span class="pre">User</span> <span class="pre">link</span> <span class="pre">></span> <span class="pre">Create</span> <span class="pre">Account</span> <span class="pre">page</span></tt></p> <p>Complete the required information denoted by the red asterisk and save. Note: an email address can also be used as a username.</p> </div> <div class="section" id="manage-users"> <h4>Manage Users<a class="headerlink" href="#manage-users" title="Permalink to this headline">¶</a></h4> <p>The Manage Users table gives the network administrator a list of all user accounts in table form. It lists username, full name, roles including at which dataverse the role is granted, and the current status whether active or deactivated.</p> <p>Usernames are listed alphabetically and clicking on a username takes you to the account page that contains detailed information on that account. It also provides the ability to update personal details and change passwords.</p> <p>The Manage Users table also provides the ability to deactivate a user account.</p> <p>To view the Manage Users table navigate to the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Users</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Manage</span> <span class="pre">Users</span> <span class="pre">table</span></tt></p> </div> <div class="section" id="manage-groups"> <h4>Manage Groups<a class="headerlink" href="#manage-groups" title="Permalink to this headline">¶</a></h4> <p>Groups in the Dataverse Network are a way to identify collections of users so permissions can be applied collectively rather than individually. This allows controlling permissions for individuals by altering membership in the group without affecting permissions of other members. Groups can be defined by user names or IP addresses.</p> <p>The Manage Groups table lists information about existing groups in table form including name, display or friendly name, and group membership.</p> <p>Clicking on the name takes you to the Edit Group page where the group’s configuration can be changed. It is also possible to create and delete groups from the Manage Groups table.</p> <p>To view the Manage Groups table, navigate to the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Permissions</span> <span class="pre">tab</span> <span class="pre">></span> <span class="pre">Groups</span> <span class="pre">subtab</span> <span class="pre">></span> <span class="pre">Manage</span> <span class="pre">Groups</span> <span class="pre">table</span></tt></p> <p>Once on the Groups subtab, viewing the Manage Groups table, you can create or delete a group.</p> <p>When creating a group you must choose whether to identify users by username or by IP address with a Username Group or IP User Group.</p> <p>With a Username Group, enter an existing username into the edit box, click the “+” symbol to enter additional users, then save.</p> <p>With an IP User Group, enter an IP address or domain name into the edit box. Wildcards can be used by specifying an asterisk (*) in place of an IP address octet (eg. 10.20.30.*), or for the sub-domain or host portion of the domain name (eg. *.mydomain.edu).</p> <p>Last, an optional special feature of the IP User Group is to allow for an Affiliate Login Service. Effectively this allows for the use of a proxy to access the Dataverse Network on behalf of a group such as a University Library where identification and authorization of users is managed by their proxy service. To enable this feature, enter IP addresses of any proxy servers that will access Dataverse Network, check This IP group has an affiliate login service, enter the Affiliate Name as it will appear on the Dataverse Network Login page, and the Affiliate URL which would go to the proxy server. Save and you are finished.</p> </div> </div> <div class="section" id="utilities"> <h3>Utilities<a class="headerlink" href="#utilities" title="Permalink to this headline">¶</a></h3> <p>The Dataverse Network provides the network administrator with tools to manually execute background processes, perform functions in batch, and resolve occasional operational issues.</p> <p>Navigate to the Utilities from the Options page:</p> <p><tt class="docutils literal"><span class="pre">Network</span> <span class="pre">home</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Options</span> <span class="pre">page</span> <span class="pre">></span> <span class="pre">Utilities</span> <span class="pre">tab</span></tt></p> <p>Available tools include:</p> <ul class="simple"> <li><strong>Study Utilities</strong> - Create draft versions of studies, release file locks and delete multiple studies by inputting ID’s.</li> <li><strong>Index Utilities</strong> - Create a search index.</li> <li><strong>Export Utilities</strong> - Select files and export them.</li> <li><strong>Harvest Utilities</strong> - Harvest selected studies from another Network.</li> <li><strong>File Utilities</strong> - Select files and apply the JHOVE file validation process to them.</li> <li><strong>Import Utilities</strong> - Import multiple study files by using this custom batch process.</li> <li><strong>Handle Utilities</strong> - Register and re-register study handles.</li> </ul> <p><strong>Study Utilities</strong></p> <p>Curating a large group of studies sometimes requires direct database changes affecting a large number of studies that may belong to different dataverses. An example might be changing the distributor name and logo or the parent dataverse. Since the Dataverse Network employs study versioning, it was decided that any such backend changes should increment the affected studies’ version. However, incrementing a study’s version is nontrivial as a database update. So, this utility to create a draft of an existing study was created.</p> <p>The practice would involve generating a list of study database ID’s that need changing, use the utility to create drafts of those studies, then run the database update scripts. The result is new, unreleased draft versions of studies with modifications made directly through the database. These studies would then need to be reviewed and released manually.</p> <p>Due to the transactional nature of study updates, particularly when uploading large files, it is possible a study update is interrupted such as during a system restart. When this occurs, the study lock, created to prevent simultaneous updates while one is already in progress, remains and the study cannot be edited until it is cleared.</p> <p>Checking for this condition and clearing it is easy. Open this utility, check if any locks are listed and remove them. The user should once again be able to edit their study.</p> <p>The user interface provides a convenient way to delete individual studies but when faced with deleting a large number of studies that do not conveniently belong to a single dataverse, use the Delete utility.</p> <p>Specify studies by their database id single, as a comma-separated list (1,7,200, etc.), or as a hyphen-separated range (1-1000, 2005, 2500-2700).</p> <p><strong>Index Utilities</strong></p> <p>Indexing is the process of making study metadata searchable. The Lucence search engine used by the Dataverse Network uses file-based indexes. Normally, any time a study or new study version is released the study information is automatically indexed. Harvesting also indexes studies in small batches as they are harvested. Sometimes this does not occur, such as when the harvest process is interrupted. The index could also become corrupt for some reason though this would be extremely rare.</p> <p>The index utility allows for reindexing of studies, dataverses, and the entire site. Studies and dataverses can be specified by their database id’s alone, in a comma separated list, or in a hyphenated range: 1-1000. Use index all sparingly, particularly if you have a large site. This is a single transaction and should not be interrupted or you will need to start again. A more flexible approach is to determine the lowest and highest study ID’s and index in smaller ranges: 1-1000, 1001-2000, etc.</p> <p>Note: if for some reason a study change was not indexed, there is an automatic background process that will detect this, inform the administrator and will be reindexed once every 24 hours so manually reindexing is not required.</p> <p><strong>Export Utilities</strong></p> <p>Export is a background process that normally runs once every 24 hours. Its purpose is to produce study metadata files in well known formats such as DDI, DC, MIF, and FGDC that can be used to import studies to other systems such as through harvesting.</p> <p>Sometimes it’s useful to manually export a study, dataverse, any updated studies, or all studies. Studies and dataverses are specified by database id rather than global id or handle.</p> <p>Export is tied to OAI set creation and Harvesting. To enable harvesting of a subset of studies by another site, first an OAI set is created that defines the group of studies. Next, the scheduled export runs and creates the export files if they’re not already available. It also associates those studies defined by the set with the set name so future requests for the set receive updates — additions or deletions from the set. This way remote sites harvesting the set maintain an updated study list.</p> <p>If you do not want to wait 24 hours to test harvest a newly created set, use the export utility. Click “Run Export” to export any changed studies and associate studies to the set. Exporting studies or dataverses alone will not associate studies to a set, in those cases Update Harvest Studies must also be run.</p> <p><strong>Harvest Utilities</strong></p> <p>The Harvest utility allows for on-demand harvesting of a single study. First select one of the predefined harvesting dataverses which provide remote server connection information as well as the local dataverse where the study will be harvested to. Specify the harvest ID of the study to be harvested. The harvest id is particular to the study and server being harvested from. It can be obtained from the OAI protocol ListIdentifiers command, from the harvest log if previously harvested, or if from another DVN it takes the form: <OAI set alias>//<global id>. A Dataverse Network study with <tt class="docutils literal"><span class="pre">globalID:</span> <span class="pre">hdl:1902.1/10004</span></tt>, from the OAI set “My Set”, having alias “myset”, would have a harvest identifier of: <tt class="docutils literal"><span class="pre">myset//hdl:1902.1/10004</span></tt></p> <p><strong>File Utilities</strong></p> <p>The Dataverse Network attempts to identify file types on upload to provide more information to an end user. It does this by calling a file type identification library called JHOVE. Though JHOVE is a very comprehensive library, sometimes a file type may not be recognized or is similar to another type and misidentified. For these cases we provide an override mechanism — a list of file extensions and a brief text description. Since these are created after the files have been uploaded, this file utility provides a way to re-identify the file types and furthermore limits this process to specific file types or to studies, specified by database ID singly, as a comma separated, or as a hype-separated range.</p> <p><strong>Import Utilities</strong></p> <p>Importing studies usually is done by harvesting study metadata from a remote site via the OAI protocol. This causes study metadata to be hosted locally but files are served by the remote server. The Import utility is provided for cases where an OAI server is unavailable or where the intent is to relocate studies and their files to the Dataverse Network.</p> <p>At present this requires the help of the network administrator and can be manually intensive. First, study metadata may need to be modified slightly then saved in a specific directory structure on the server file system. Next, the study metadata import format and destination dataverse is chosen. Last, the top level directory where the study metadata and files are stored and “Batch Import” is clicked. Because the DDI input format can be quite complex and usage varies, verify the results are what’s intended.</p> <p>A single study import function is also provided as a test for importing your study’s metadata syntax but is not meant for actual import. It will not import associated files.</p> <p>Before performing a batch import, you must organize your files in the following manner:</p> <ol class="arabic simple"> <li>If you plan to import multiple files or studies, create a master directory to hold all content that you choose to import.</li> <li>Create a separate subdirectory for each study that you choose to import. The directory name is not important.</li> <li>In each directory, place a file called <tt class="docutils literal"><span class="pre">study.xml</span></tt> and use that file to hold the XML-formatted record for one study. Note: Do not include file description elements in the <tt class="docutils literal"><span class="pre">study.xml</span></tt> file. Including those fields results in the addition of multiple blank files to that study.</li> <li>Also place in the directory any additional files that you choose to upload for that study.</li> </ol> <p>For an example of a simple study DDI, refer to the <a class="reference internal" href="#metadata-references"><em>Metadata References</em></a> section.</p> <p><strong>Handle Utilities</strong></p> <p>When a study is created, the global ID is first assigned, then registered with handle.net as a persistent identifier. This identifier becomes part of the study’s citation and is guaranteed to always resolve to the study. For the study with global ID, <a class="reference external" href="hdl:1902.1/16598">hdl:1902.1/16598</a> or handle 1902.1/16596, the URL in the citation would be: <a class="reference external" href="http://hdl.handle.net/1902.1/16598">http://hdl.handle.net/1902.1/16598</a>.</p> <p>If for any reason a study is created and not registered or is registered in a way that needs to be changed, use the Handle utility to either register currently unregistered studies or to re-register all registered studies.</p> </div> <div class="section" id="web-statistics"> <h3>Web Statistics<a class="headerlink" href="#web-statistics" title="Permalink to this headline">¶</a></h3> <p>The Dataverse Network provides the capability to compile and analyze site usage through Google Analytics. A small amount of code is embedded in each page so when enabled, any page access along with associated browser and user information is recorded by Google. Later analysis of this compiled access data can be performed using the <a class="reference external" href="http://www.google.com/analytics/">Google Analytics</a> utility.</p> <p>Note: Access to Google Analytics is optional. If access to this utility is not configured for your network, in place of the Manage Web Usage menu option is a message stating: <tt class="docutils literal"><span class="pre">Google</span> <span class="pre">Analytics</span> <span class="pre">are</span> <span class="pre">not</span> <span class="pre">configured</span> <span class="pre">for</span> <span class="pre">this</span> <span class="pre">Network.</span></tt></p> <p><strong>To enable Google Analytics:</strong></p> <ol class="arabic simple"> <li>Create a Gmail account.</li> <li>Go to <a class="reference external" href="http://www.google.com/analytics/">Google Analytics</a> and create a profile for the server or website domain. You will be assigned a Web Property ID.</li> <li>Using the Glassfish Admin console, add a JVM option and assign it the value of the newly assigned Web Property ID: <tt class="docutils literal"><span class="pre">Ddvn.googleanalytics.key=</span></tt></li> <li>Restart Glassfish.</li> <li>It takes about 24 hours after installation and set up of this option for tracking data to become available for use.</li> </ol> <p>Note: Google provides the code necessary for tracking. This has already been embedded into the Dataverse Network but not the Web Property ID. That is configured as a JVM option by the network admin when enabling this feature.</p> <p><strong>To view Web Statistics, navigate to:</strong></p> <ul class="simple"> <li>Network home page > Options page > Settings tab > General subtab > Web Statistics</li> <li>You will be redirected to <a class="reference external" href="http://www.google.com/analytics/">Google Analytics</a>. Log in using your Gmail account used to create the profile.</li> </ul> </div> </div> <div class="section" id="appendix"> <h2>Appendix<a class="headerlink" href="#appendix" title="Permalink to this headline">¶</a></h2> <p>Additional documentation complementary to Users Guides.</p> <div class="section" id="control-card-based-data-ingest"> <h3>Control Card-Based Data Ingest<a class="headerlink" href="#control-card-based-data-ingest" title="Permalink to this headline">¶</a></h3> <p>As of version 2.2 the DVN supports ingesting plain text data files, in addition to SPSS and STATA formats. This allows users and institutions to ingest raw data into Dataverse Networks without having to purchase and maintain proprietary, commercial software packages.</p> <p>Tab-delimited and CSV files are supported. In order to ingest a plain data file, an additional file containing the variable metadata needs to be supplied.</p> <p><strong>Two Metadata Types Are Supported</strong></p> <ol class="arabic simple"> <li>A simplified format based on the classic SPSS control card syntax; this appears as “CSV/SPSS” in the menu on the Add Files page.</li> <li>DDI, an xml format from the Data Documentation Inititative consortium. Choose “TAB/DDI” to ingest a tab file with a DDI metadata sheet.</li> </ol> <p>The specifics of the formats are documented in the 2 sections below.</p> <div class="section" id="csv-data-spss-style-control-card"> <span id="controlcard-datafile-ingest"></span><h4>CSV Data, SPSS-style Control Card<a class="headerlink" href="#csv-data-spss-style-control-card" title="Permalink to this headline">¶</a></h4> <p>Unlike other supported “subsettable” formats, this ingest mechanism requires 2 files: the CSV raw data file proper and an SPSS Setup file (“control card”) with the data set metadata. In the future, support for other data definition formats may be added (STATA, SAS, etc.). As always, user feedback is welcome.</p> <p><strong>The supported SPSS command syntax:</strong></p> <p>Please note that it is not our goal to attempt to support any set of arbitrary SPSS commands and/or syntax variations. The goal is to enable users who do not own proprietary statistical software to prepare their raw data for DVN ingest, using a select subset of SPSS data definitional syntax.</p> <p>(In addition to its simplicity and popularity, we chose to use the SPSS command syntax because Dataverse Network already has support for the SPSS <tt class="docutils literal"><span class="pre">.SAV</span></tt> and <tt class="docutils literal"><span class="pre">.POR</span></tt> formats, so we have a good working knowledge of the SPSS formatting conventions.)</p> <p>The following SPSS commands are supported:</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">DATA</span> <span class="pre">LIST </span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">VARIABLE</span> <span class="pre">LABELS </span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">NUMBER</span> <span class="pre">OF</span> <span class="pre">CASES</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">VALUE</span> <span class="pre">LABELS</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">FORMATS</span></tt> (actually, not supported as of now – see below)</div> <div class="line"><tt class="docutils literal"><span class="pre">MISSING</span> <span class="pre">VALUES</span></tt></div> </div> <p>We support mixed cases and all the abbreviations of the above commands that are valid under SPSS. For example, both “var labels” and “Var Lab” are acceptable commands.</p> <p>Individual command syntax.</p> <p><strong>1. DATA LIST</strong></p> <p>An explicit delimiter definition is required. For example:</p> <p><tt class="docutils literal"><span class="pre">DATA</span> <span class="pre">LIST</span> <span class="pre">LIST(',')</span></tt></p> <p>specifies <tt class="docutils literal"><span class="pre">','</span></tt> as the delimiter. This line is followed by the <tt class="docutils literal"><span class="pre">'/'</span></tt> separator and variable definitions. Explicit type definitions are required. Each variable is defined by a name/value pair <tt class="docutils literal"><span class="pre">VARNAME</span></tt></p> <p><tt class="docutils literal"><span class="pre">(VARTYPE)</span></tt> where <tt class="docutils literal"><span class="pre">VARTYPE</span></tt> is a standard SPSS fortran-type definition.</p> <p><strong>Note</strong> that this is the only <strong>required</strong> section. The minimum amount of metadata required to ingest a raw data file is the delimiter character, the names of the variables and their data type. All of these are defined in the <tt class="docutils literal"><span class="pre">DATA</span> <span class="pre">LIST</span></tt> section. Here’s an example of a complete, valid control card:</p> <p><tt class="docutils literal"><span class="pre">DATA</span> <span class="pre">LIST</span> <span class="pre">LIST(’,’)</span></tt> <tt class="docutils literal"><span class="pre">CASEID</span> <span class="pre">(f)</span> <span class="pre">NAME</span> <span class="pre">(A)</span> <span class="pre">RATIO</span> <span class="pre">(f)</span></tt> <tt class="docutils literal"><span class="pre">.</span></tt></p> <p>It defines a comma-separated file with 3 variables named <tt class="docutils literal"><span class="pre">CASEID</span></tt>, <tt class="docutils literal"><span class="pre">NAME</span></tt> and <tt class="docutils literal"><span class="pre">RATIO</span></tt>, two of them of the types numeric and one character string.</p> <p>Examples of valid type definitions:</p> <div class="line-block"> <div class="line"><strong>A8</strong> 8 byte character string;</div> <div class="line"><strong>A</strong> character string;</div> <div class="line"><strong>f10.2</strong> numeric value, 10 decimal digits, with 2 fractional digits;</div> <div class="line"><strong>f8</strong> defaults to F8.0</div> <div class="line"><strong>F</strong> defaults to F.0, i.e., numeric integer value</div> <div class="line"><strong>2</strong> defaults to F.2, i.e., numeric float value with 2 fractional digits.</div> </div> <p>The following SPSS date/time types are supported:</p> <p>type format</p> <p><tt class="docutils literal"><span class="pre">DATE`` ``yyyy-MM-dd</span></tt></p> <p><tt class="docutils literal"><span class="pre">DATETIME`` ``yyyy-MM-dd</span> <span class="pre">HH:mm:ss</span></tt></p> <p>The variable definition pairs may be separated by any combination of white space characters and newlines. <strong>Wrapped-around lines must start with white spaces</strong> (i.e., newlines must be followed by spaces). The list must be terminated by a line containing a single dot.</p> <p>Please note, that the actual date values should be stored in the CSV file as strings, in the format above. As opposed to how SPSS stores the types of the same name (as integer numbers of seconds).</p> <p><strong>2. VARIABLE LABELS</strong></p> <p>Simple name/value pairs, separated by any combination of white space characters and newlines (as described in section 1 above). The list is terminated by a single dot.</p> <p>For example:</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">VARIABLE</span> <span class="pre">LABELS</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">CELLS</span> <span class="pre">"Subgroups</span> <span class="pre">for</span> <span class="pre">sample-see</span> <span class="pre">documentation"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">STRATA</span> <span class="pre">"Cell</span> <span class="pre">aggregates</span> <span class="pre">for</span> <span class="pre">sample”</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">.</span></tt></div> </div> <p><strong>3. NUMBER OF CASES (optional)</strong></p> <p>The number of cases may be explicitly specified. For example:</p> <p><tt class="docutils literal"><span class="pre">num</span> <span class="pre">of</span> <span class="pre">cases</span> <span class="pre">1000</span></tt></p> <p>When the number of cases is specified, it will be checked against the number of observations actually found in the CSV file, and a mismatch would result in an ingest error.</p> <p><strong>4. VALUE LABELS</strong></p> <p>Each value label section is a variable name followed by a list of value/label pairs, terminated by a single “/” character. The list of value label sections is terminated by a single dot.</p> <p>For example,</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">VALUE</span> <span class="pre">labels</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">FOO</span> <span class="pre">0</span> <span class="pre">"NADA"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">1</span> <span class="pre">"NOT</span> <span class="pre">MUCH"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">99999999</span> <span class="pre">"A</span> <span class="pre">LOT"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">/</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">BAR</span> <span class="pre">97</span> <span class="pre">"REFUSAL"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">98</span> <span class="pre">"DONT</span> <span class="pre">KNOW"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">99</span> <span class="pre">"MISSING"</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">/</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">.</span></tt></div> </div> <p><strong>5. FORMATS</strong></p> <p>This command is actually redundant if you explicitly supply the variable formats in the <a href="#id21"><span class="problematic" id="id22">``</span></a>DATA LIST`` section above.</p> <p><strong>NOTE:</strong> It appears that the only reason the``FORMATS`` command exists is that <tt class="docutils literal"><span class="pre">DATA</span> <span class="pre">LIST</span></tt> syntax does not support explicit fortran-style format definitions when fixed-field data is defined. So it is in fact redundant when we’re dealing with delimited files only.</p> <p>Please supply valid, fortran-style variable formats in the <a href="#id23"><span class="problematic" id="id24">``</span></a>DATA LIST`` section, as described above.</p> <p><strong>6. MISSING VALUES</strong></p> <p>This is a space/newline-separate list of variable names followed by a comma-separated list of missing values definition, in parentheses. For example:</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">INTVU4</span> <span class="pre">(97,</span> <span class="pre">98,</span> <span class="pre">99)</span></tt></div> <div class="line">The list is terminated with a single dot.</div> </div> <p>An example of a valid <a href="#id25"><span class="problematic" id="id26">``</span></a>MISSING VALUES`` control card section:</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">MISSING</span> <span class="pre">VALUES</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">INTVU4</span> <span class="pre">(97,</span> <span class="pre">98,</span> <span class="pre">99)</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">INTVU4A</span> <span class="pre">('97',</span> <span class="pre">'98',</span> <span class="pre">'99')</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">.</span></tt></div> </div> <div class="line-block"> <div class="line"><strong>An example of a control card ready for ingest:</strong></div> </div> <div class="highlight-guess"><div class="highlight"><pre><span class="n">data</span> <span class="n">list</span> <span class="n">list</span><span class="p">(</span><span class="sc">','</span><span class="p">)</span> <span class="o">/</span> <span class="n">CELLS</span> <span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="n">STRATA</span> <span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="n">WT2517</span> <span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="n">SCRNRID</span> <span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="n">CASEID</span> <span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="n">INTVU1</span> <span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="n">INTVU2</span> <span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="n">INTVU3</span> <span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="n">INTVU4</span> <span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="n">INTVU4A</span> <span class="p">(</span><span class="n">A</span><span class="p">)</span> <span class="p">.</span> <span class="n">VARIABLE</span> <span class="n">LABELS</span> <span class="n">CELLS</span> <span class="s">"Subgroups for sample-see documentation"</span> <span class="n">STRATA</span> <span class="s">"Cell aggregates for sample-see documenta"</span> <span class="n">WT2517</span> <span class="s">"weight for rep. sample-see documentation"</span> <span class="n">SCRNRID</span> <span class="s">"SCREENER-ID"</span> <span class="n">CASEID</span> <span class="s">"RESPONDENT'S CASE ID NUMBER"</span> <span class="n">INTVU1</span> <span class="s">"MONTH RESPONDENT BEGAN INTERVIEW"</span> <span class="n">INTVU2</span> <span class="s">"DAY RESPONDENT BEGAN INTERVIEW"</span> <span class="n">INTVU3</span> <span class="s">"HOUR RESPONDENT BEGAN INTERVIEW"</span> <span class="n">INTVU4</span> <span class="s">"MINUTE RESPONDENT BEGAN INTERVIEW"</span> <span class="n">INTVU4A</span> <span class="s">"RESPONDENT INTERVIEW BEGAN AM OR PM"</span> <span class="p">.</span> <span class="n">VALUE</span> <span class="n">labels</span> <span class="n">CASEID</span> <span class="mi">99999997</span> <span class="s">"REFUSAL"</span> <span class="mi">99999998</span> <span class="s">"DONT KNOW"</span> <span class="mi">99999999</span> <span class="s">"MISSING"</span> <span class="o">/</span> <span class="n">INTVU1</span> <span class="mi">97</span> <span class="s">"REFUSAL"</span> <span class="mi">98</span> <span class="s">"DONT KNOW"</span> <span class="mi">99</span> <span class="s">"MISSING"</span> <span class="o">/</span> <span class="n">INTVU2</span> <span class="mi">97</span> <span class="s">"REFUSAL"</span> <span class="mi">98</span> <span class="s">"DONT KNOW"</span> <span class="mi">99</span> <span class="s">"MISSING"</span> <span class="o">/</span> <span class="n">INTVU3</span> <span class="mi">97</span> <span class="s">"REFUSAL"</span> <span class="mi">98</span> <span class="s">"DONT KNOW"</span> <span class="mi">99</span> <span class="s">"MISSING"</span> <span class="o">/</span> <span class="n">INTVU4</span> <span class="mi">97</span> <span class="s">"REFUSAL"</span> <span class="mi">98</span> <span class="s">"DONT KNOW"</span> <span class="mi">99</span> <span class="s">"MISSING"</span> <span class="o">/</span> <span class="n">INTVU4A</span> <span class="s">"97"</span> <span class="s">"REFUSAL"</span> <span class="s">"98"</span> <span class="s">"DONT KNOW"</span> <span class="s">"99"</span> <span class="s">"MISSING"</span> <span class="s">"AM"</span> <span class="s">"MORNING"</span> <span class="s">"PM"</span> <span class="s">"EVENING"</span> <span class="p">.</span> <span class="n">MISSING</span> <span class="n">VALUES</span> <span class="n">CASEID</span> <span class="p">(</span><span class="mi">99999997</span><span class="p">,</span> <span class="mi">99999998</span><span class="p">,</span> <span class="mi">99999999</span><span class="p">)</span> <span class="n">INTVU1</span> <span class="p">(</span><span class="mi">97</span><span class="p">,</span> <span class="mi">98</span><span class="p">,</span> <span class="mi">99</span><span class="p">)</span> <span class="n">INTVU2</span> <span class="p">(</span><span class="mi">97</span><span class="p">,</span> <span class="mi">98</span><span class="p">,</span> <span class="mi">99</span><span class="p">)</span> <span class="n">INTVU3</span> <span class="p">(</span><span class="mi">97</span><span class="p">,</span> <span class="mi">98</span><span class="p">,</span> <span class="mi">99</span><span class="p">)</span> <span class="n">INTVU4</span> <span class="p">(</span><span class="mi">97</span><span class="p">,</span> <span class="mi">98</span><span class="p">,</span> <span class="mi">99</span><span class="p">)</span> <span class="n">INTVU4A</span> <span class="p">(</span><span class="err">'</span><span class="mi">97</span><span class="err">'</span><span class="p">,</span> <span class="err">'</span><span class="mi">98</span><span class="err">'</span><span class="p">,</span> <span class="err">'</span><span class="mi">99</span><span class="err">'</span><span class="p">)</span> <span class="p">.</span> <span class="n">NUMBER</span> <span class="n">of</span> <span class="n">CASES</span> <span class="mi">2517</span> </pre></div> </div> <p><strong>DATA FILE.</strong></p> <p>Data must be stored in a text file, one observation per line. Both DOS and Unix new line characters are supported as line separators. On each line, individual values must be separated by the delimiter character defined in the DATA LISTsection. There may only be exactly (<tt class="docutils literal"><span class="pre">NUMBER</span> <span class="pre">OF</span> <span class="pre">VARIABLES</span> <span class="pre">-</span> <span class="pre">1</span></tt>) delimiter characters per line; i.e. character values must not contain the delimiter character.</p> <p><strong>QUESTIONS, TODOS:</strong></p> <p>Is there any reason we may want to support <tt class="docutils literal"><span class="pre">RECODE</span></tt> command also?</p> <p>— comments, suggestions are welcome! —</p> </div> <div class="section" id="tab-data-with-ddi-metadata"> <span id="ddixml-datafile-ingest"></span><h4>Tab Data, with DDI Metadata<a class="headerlink" href="#tab-data-with-ddi-metadata" title="Permalink to this headline">¶</a></h4> <p>As of version 2.2, another method of ingesting raw TAB-delimited data files has been added to the Dataverse Network. Similarly to the SPSS control card-based ingest (also added in this release), this ingest mechanism requires 2 files: the TAB raw data file itself and the data set metadata in the DDI/XML format.</p> <p><strong>Intended use case:</strong></p> <p>Similarly to the SPSS syntax-based ingest, the goal is to provide another method of ingesting raw quantitative data into the DVN, without having to first convert it into one of the proprietary, commercial formats, such as SPSS or STATA. Pleaes note, that in our design scenario, the DDI files supplying the ingest metadata will be somehow machine-generated; by some software tool, script, etc. In other words, this design method is targeted towards more of an institutional user, perhaps another data archive with large quantities of data and some institutional knowledge of its structure, and with some resources to invest into developing an automated tool to generate the metadata describing the datasets. With the final goal of ingesting all the data into a DVN by another automated, batch process. The DVN project is also considering developing a standalone tool of our own that would guide users through the process of gathering the information describing their data sets and producing properly formatted DDIs ready to be ingested.</p> <p>For now, if you are merely looking for a way to ingest a single “subsettable” data set, you should definitely be able to create a working DDI by hand to achieve this goal. However, we strongly recommend that you instead consider the CSV/SPSS control card method, which was designed with this use case in mind. If anything, it will take considerably fewer keystrokes to create an SPSS-syntax control card than a DDI encoding the same amount of information.</p> <p><strong>The supported DDI syntax:</strong></p> <p>You can consult the DDI project for complete information on the DDI metadata (<a class="reference external" href="http://icpsr.umich.edu/DDI">http://icpsr.umich.edu/DDI</a>). However, only a small subset of the published format syntax is used for ingesting individual data sets. Of the 7 main DDI sections, only 2, fileDscr and dataDscr are used. Inside these sections, only a select set of fields, those that have direct equivalents in the DVN data set structure, are supported.</p> <p>These fields are outlined below. All the fields are mandatory, unless specified otherwise. An XSD schema of the format subset is also provided, for automated validation of machine-generated XML.</p> <div class="highlight-guess"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> <span class="nt"><codeBook</span> <span class="na">xmlns=</span><span class="s">"http://www.icpsr.umich.edu/DDI"</span><span class="err">\</span><span class="nt">></span> <span class="nt"><fileDscr></span> <span class="nt"><fileTxt</span> <span class="na">ID=</span><span class="s">"file1"</span><span class="nt">></span> <span class="nt"><dimensns></span> <span class="nt"><caseQnty></span>NUMBER OF OBSERVATIONS<span class="nt"></caseQnty></span> <span class="nt"><varQnty></span>NUMBER OF VARIABLES<span class="nt"></varQnty></span> <span class="nt"></dimensns></span> <span class="nt"></fileTxt></span> <span class="nt"></fileDscr></span> <span class="nt"><dataDscr></span> <span class="c"><!-- var section for a discrete numeric variable: --></span> <span class="nt"><var</span> <span class="na">ID=</span><span class="s">"v1.1"</span> <span class="na">name=</span><span class="s">"VARIABLE NAME"</span> <span class="na">intrvl=</span><span class="s">"discrete"</span> <span class="nt">></span> <span class="nt"><location</span> <span class="na">fileid=</span><span class="s">"file1"</span><span class="nt">/></span> <span class="nt"><labl</span> <span class="na">level=</span><span class="s">"variable"</span><span class="nt">></span>VARIABLE LABEL<span class="nt"></labl></span> <span class="nt"><catgry></span> <span class="nt"><catValu></span>CATEGORY VALUE<span class="nt"></catValu></span> <span class="nt"></catgry></span> … <span class="c"><!-- 1 or more category sections are allowed for discrete variables --></span> <span class="nt"><varFormat</span> <span class="na">type=</span><span class="s">"numeric"</span> <span class="nt">/></span> <span class="nt"></var></span> <span class="c"><!-- var section for a continuous numeric variable: --></span> <span class="nt"><var</span> <span class="na">ID=</span><span class="s">"v1.2"</span> <span class="na">name=</span><span class="s">"VARIABLE NAME"</span> <span class="na">intrvl=</span><span class="s">"contin"</span> <span class="nt">></span> <span class="nt"><location</span> <span class="na">fileid=</span><span class="s">"file1"</span><span class="nt">/></span> <span class="nt"><labl</span> <span class="na">level=</span><span class="s">"variable"</span><span class="nt">></span>VARIABLE LABEL<span class="nt"></labl></span> <span class="nt"><varFormat</span> <span class="na">type=</span><span class="s">"numeric"</span> <span class="nt">/></span> <span class="nt"></var></span> <span class="c"><!-- var section for a character (string) variable: --></span> <span class="nt"><var</span> <span class="na">ID=</span><span class="s">"v1.10"</span> <span class="na">name=</span><span class="s">"VARIABLE NAME"</span> <span class="na">intrvl=</span><span class="s">"discrete"</span> <span class="nt">></span> <span class="nt"><location</span> <span class="na">fileid=</span><span class="s">"file1"</span><span class="nt">/></span> <span class="nt"><labl</span> <span class="na">level=</span><span class="s">"variable"</span><span class="nt">></span>VARIABLE LABEL<span class="nt"></labl></span> <span class="nt"><varFormat</span> <span class="na">type=</span><span class="s">"character"</span> <span class="nt">/></span> <span class="nt"></var></span> <span class="c"><!-- a discrete variable with missing values defined: --></span> <span class="nt"></dataDscr></span> <span class="nt"></codeBook></span> </pre></div> </div> <p>— comments, suggestions are welcome! —</p> </div> </div> <div class="section" id="spss-data-file-ingest"> <span id="spss-datafile-ingest"></span><h3>SPSS Data File Ingest<a class="headerlink" href="#spss-data-file-ingest" title="Permalink to this headline">¶</a></h3> <div class="section" id="ingesting-spss-por-files-with-extended-labels"> <h4>Ingesting SPSS (.por) files with extended labels<a class="headerlink" href="#ingesting-spss-por-files-with-extended-labels" title="Permalink to this headline">¶</a></h4> <p>This feature has been added to work around the limit on the length of variable labels in SPSS Portable (.por) files. To use this feature, select “SPSS/POR,(w/labels)” from the list of file types on the AddFiles page. You will be prompted to first upload a text file containing the extended, “long” versions of the labels, and then upload the .por file. The label text file should contain one TAB-separated variable name/variable label pair per line.</p> </div> </div> <div class="section" id="ingest-of-r-rdata-files"> <span id="r-datafile-ingest"></span><h3>Ingest of R (.RData) files<a class="headerlink" href="#ingest-of-r-rdata-files" title="Permalink to this headline">¶</a></h3> <div class="section" id="overview"> <h4>Overview.<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h4> <p>Support for ingesting R data files has been added in version 3.5. R has been increasingly popular in the research/academic community, owing to the fact that it is free and open-source (unlike SPSS and STATA). Consequently, more and more data is becoming available exclusively in RData format. This long-awaited feature makes it possible to ingest such data into DVN as “subsettable” files.</p> </div> <div class="section" id="requirements"> <h4>Requirements.<a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h4> <p>R ingest relies on R having been installed, configured and made available to the DVN application via RServe (see the Installers Guide). This is in contrast to the SPSS and Stata ingest - which can be performed without R present. (though R is still needed to perform most subsetting/analysis tasks on the resulting data files).</p> <p>The data must be formatted as an R dataframe (using data.frame() in R). If an .RData file contains multiple dataframes, only the 1st one will be ingested.</p> </div> <div class="section" id="data-types-compared-to-other-supported-formats-stat-spss"> <h4>Data Types, compared to other supported formats (Stat, SPSS)<a class="headerlink" href="#data-types-compared-to-other-supported-formats-stat-spss" title="Permalink to this headline">¶</a></h4> <div class="section" id="integers-doubles-character-strings"> <h5>Integers, Doubles, Character strings<a class="headerlink" href="#integers-doubles-character-strings" title="Permalink to this headline">¶</a></h5> <p>The handling of these types is intuitive and straightforward. The resulting tab file columns, summary statistics and UNF signatures should be identical to those produced by ingesting the same vectors from SPSS and Stata.</p> <p><strong>A couple of features that are unique to R/new in DVN:</strong></p> <p>R explicitly supports Missing Values for all of the types above; Missing Values encoded in R vectors will be recognized and preserved in TAB files (as ‘NA’), counted in the generated summary statistics and data analysis.</p> <p>In addition to Missing Values, R recognizes “Not a Number” (NaN) and positive and negative infinity for floating point values. These are now properly supported by the DVN.</p> <p>Also note that, unlike Stata, where “float” and “double” are supported as distinct data types, all floating point values in R are double precision.</p> </div> <div class="section" id="r-factors"> <h5>R Factors<a class="headerlink" href="#r-factors" title="Permalink to this headline">¶</a></h5> <p>These are ingested as “Categorical Values” in the DVN.</p> <p>One thing to keep in mind: in both Stata and SPSS, the actual value of a categorical variable can be both character and numeric. In R, all factor values are strings, even if they are string representations of numbers. So the values of the resulting categoricals in the DVN will always be of string type too.</p> <div class="line-block"> <div class="line"><strong>New:</strong> To properly handle <em>ordered factors</em> in R, the DVN now supports the concept of an “Ordered Categorical” - a categorical value where an explicit order is assigned to the list of value labels.</div> </div> </div> <div class="section" id="new-boolean-values"> <h5>(New!) Boolean values<a class="headerlink" href="#new-boolean-values" title="Permalink to this headline">¶</a></h5> <p>R Boolean (logical) values are supported.</p> </div> <div class="section" id="limitations-of-r-data-format-as-compared-to-spss-and-stata"> <h5>Limitations of R data format, as compared to SPSS and STATA.<a class="headerlink" href="#limitations-of-r-data-format-as-compared-to-spss-and-stata" title="Permalink to this headline">¶</a></h5> <p>Most noticeably, R lacks a standard mechanism for defining descriptive labels for the data frame variables. In the DVN, similarly to both Stata and SPSS, variables have distinct names and labels; with the latter reserved for longer, descriptive text. With variables ingested from R data frames the variable name will be used for both the “name” and the “label”.</p> <div class="line-block"> <div class="line"><em>Optional R packages exist for providing descriptive variable labels; in one of the future versions support may be added for such a mechanism. It would of course work only for R files that were created with such optional packages</em>.</div> </div> <p>Similarly, R categorical values (factors) lack descriptive labels too. <strong>Note:</strong> This is potentially confusing, since R factors do actually have “labels”. This is a matter of terminology - an R factor’s label is in fact the same thing as the “value” of a categorical variable in SPSS or Stata and DVN; it contains the actual meaningful data for the given observation. It is NOT a field reserved for explanatory, human-readable text, such as the case with the SPSS/Stata “label”.</p> <p>Ingesting an R factor with the level labels “MALE” and “FEMALE” will produce a categorical variable with “MALE” and “FEMALE” in the values and labels both.</p> </div> </div> <div class="section" id="time-values-in-r"> <h4>Time values in R<a class="headerlink" href="#time-values-in-r" title="Permalink to this headline">¶</a></h4> <p>This warrants a dedicated section of its own, because of some unique ways in which time values are handled in R.</p> <p>R makes an effort to treat a time value as a real time instance. This is in contrast with either SPSS or Stata, where time value representations such as “Sep-23-2013 14:57:21” are allowed; note that in the absence of an explicitly defined time zone, this value cannot be mapped to an exact point in real time. R handles times in the “Unix-style” way: the value is converted to the “seconds-since-the-Epoch” Greenwitch time (GMT or UTC) and the resulting numeric value is stored in the data file; time zone adjustments are made in real time as needed.</p> <p>Things get ambiguous and confusing when R <strong>displays</strong> this time value: unless the time zone was explicitly defined, R will adjust the value to the current time zone. The resulting behavior is often counter-intuitive: if you create a time value, for example:</p> <blockquote> <div>timevalue<-as.POSIXct(“03/19/2013 12:57:00”, format = “%m/%d/%Y %H:%M:%OS”);</div></blockquote> <p>on a computer configured for the San Francisco time zone, the value will be differently displayed on computers in different time zones; for example, as “12:57 PST” while still on the West Coast, but as “15:57 EST” in Boston.</p> <p>If it is important that the values are always displayed the same way, regardless of the current time zones, it is recommended that the time zone is explicitly defined. For example:</p> <blockquote> <div>attr(timevalue,”tzone”)<-“PST”</div></blockquote> <dl class="docutils"> <dt>or</dt> <dd>timevalue<-as.POSIXct(“03/19/2013 12:57:00”, format = “%m/%d/%Y %H:%M:%OS”, tz=”PST”);</dd> </dl> <p>Now the value will always be displayed as “12:57 PST”, regardless of the time zone that is current for the OS ... <strong>BUT ONLY</strong> if the OS where R is installed actually understands the time zone “PST”, which is not by any means guaranteed! Otherwise, it will <strong>quietly adjust</strong> the stored GMT value to <strong>the current time zone</strong>, yet still display it with the “PST” tag attached! One way to rephrase this is that R does a fairly decent job <strong>storing</strong> time values in a non-ambiguous, platform-independent manner - but gives no guarantee that the values will be displayed in any way that is predictable or intuitive.</p> <p>In practical terms, it is recommended to use the long/descriptive forms of time zones, as they are more likely to be properly recognized on most computers. For example, “Japan” instead of “JST”. Another possible solution is to explicitly use GMT or UTC (since it is very likely to be properly recognized on any system), or the “UTC+<OFFSET>” notation. Still, none of the above <strong>guarantees</strong> proper, non-ambiguous handling of time values in R data sets. The fact that R <strong>quietly</strong> modifies time values when it doesn’t recognize the supplied timezone attribute, yet still appends it to the <strong>changed</strong> time value does make it quite difficult. (These issues are discussed in depth on R-related forums, and no attempt is made to summarize it all in any depth here; this is just to made you aware of this being a potentially complex issue!)</p> <p>An important thing to keep in mind, in connection with the DVN ingest of R files, is that it will <strong>reject</strong> an R data file with any time values that have time zones that we can’t recognize. This is done in order to avoid (some) of the potential issues outlined above.</p> <p>It is also recommended that any vectors containing time values ingested into the DVN are reviewed, and the resulting entries in the TAB files are compared against the original values in the R data frame, to make sure they have been ingested as expected.</p> <p>Another <strong>potential issue</strong> here is the <strong>UNF</strong>. The way the UNF algorithm works, the same date/time values with and without the timezone (e.g. “12:45” vs. “12:45 EST”) <strong>produce different UNFs</strong>. Considering that time values in Stata/SPSS do not have time zones, but ALL time values in R do (yes, they all do - if the timezone wasn’t defined explicitely, it implicitly becomes a time value in the “UTC” zone!), this means that it is <strong>impossible</strong> to have 2 time value vectors, in Stata/SPSS and R, that produce the same UNF.</p> <p><strong>A pro tip:</strong> if it is important to produce SPSS/Stata and R versions of the same data set that result in the same UNF when ingested, you may define the time variables as <strong>strings</strong> in the R data frame, and use the “YYYY-MM-DD HH:mm:ss” formatting notation. This is the formatting used by the UNF algorithm to normalize time values, so doing the above will result in the same UNF as the vector of the same time values in Stata.</p> <p>Note: date values (dates only, without time) should be handled the exact same way as those in SPSS and Stata, and should produce the same UNFs.</p> </div> </div> <div class="section" id="fits-file-format-ingest"> <span id="fits-datafile-ingest"></span><h3>FITS File format Ingest<a class="headerlink" href="#fits-file-format-ingest" title="Permalink to this headline">¶</a></h3> <p>This custom ingest is an experiment in branching out into a discipline outside of the Social Sciences. It has been added in v.3.4 as part of the collaboration between the IQSS and the Harvard-Smithsonian Center for Astrophysics. FITS is a multi-part file format for storing Astronomical data (<a class="reference external" href="http://fits.gsfc.nasa.gov/fits_standard.html">http://fits.gsfc.nasa.gov/fits_standard.html</a>). DVN now offers an ingest plugin that parses FITS file headers for key-value metadata that are extracted and made searchable.</p> <p>FITS is now listed on the DVN AddFiles page as a recognized file format. The same asynchronous process is used as for “subsettable” files: the processing is done in the background, with an email notification sent once completed.</p> <p>Unlike with the “subsettable” file ingest, no format conversion takes place and the FITS file is ingested as is, similarly to “other materials” files. The process is limited to the extaction of the searchable metadata. Once the file is ingested and the study is re-indexed, these file-level FITS metadata fields can be searched on from the Advanced Search page, on either the Dataverse or Network level. Choose one of the FITS file Information listed in the drop down, and enter the relevant search term. Search results that match the query will show individual files as well as studies.</p> <p>The ingest also generates a short summary of the file contents (number and type of Header-Data Units) and adds it to the file description.</p> </div> <div class="section" id="metadata-references"> <span id="id27"></span><h3>Metadata References<a class="headerlink" href="#metadata-references" title="Permalink to this headline">¶</a></h3> <p>The Dataverse Network metadata is compliant with the <a class="reference external" href="http://www.icpsr.umich.edu/DDI/">DDI schema version 2</a>. The Cataloging Information fields associated with each study contain most of the fields in the study description section of the DDI. That way the Dataverse Network metadata can be mapped easily to a DDI, and be exported into XML format for preservation and interoperability.</p> <p>Dataverse Network data also is compliant with <a class="reference external" href="http://www.dublincore.org/">Simple Dublin Core</a> (DC) requirements. For imports only, Dataverse Network data is compliant with the <a class="reference external" href="http://www.fgdc.gov/metadata">Content Standard for Digital Geospatial Metadata (CSDGM), Vers. 2 (FGDC-STD-001-1998)</a> (FGDC).</p> <p>Attached is a PDF file that defines and maps all Dataverse Network Cataloging Information fields. Information provided in the file includes the following:</p> <ul class="simple"> <li>Field label - For each Cataloging Information field, the field label appears first in the mapping matrix.</li> <li>Description - A description of each field follows the field label.</li> <li>Query term - If a field is available for use in building a query, the term to use for that field is listed.</li> <li>Dataverse Network database element name - The Dataverse Network database element name for the field is provided.</li> <li>Advanced search - If a field is available for use in an advanced search, that is indicated.</li> <li>DDI element mapping for imports - For harvested or imported studies, the imported DDI elements are mapped to Dataverse Network fields.</li> <li>DDI element mapping for exports - When a study or dataverse is harvested or exported in DDI format, the Dataverse Network fields are mapped to DDI elements.</li> <li>DC element mapping for imports - For harvested or imported studies, the imported DC elements are mapped to specific Dataverse Network fields.</li> <li>DC element mapping for exports - When a study or dataverse is harvested or exported in DC format, specific Dataverse Network fields are mapped to the DC elements.</li> <li>FGDC element mapping for imports - For harvested or imported studies, the imported FGDC elements are mapped to specific Dataverse Network fields.</li> </ul> <p>Also attached is an example of a DDI for a simple study containing title, author, description, keyword, and topic classification cataloging information fields suitable for use with batch import.</p> <p><img alt="image9" src="_images/application-pdf.png" /> <a class="reference external" href="https://github.com/IQSS/dvn/blob/develop/doc/sphinx/source/datausers-guides_files/catalogingfields11apr08.pdf">catalogingfields11apr08.pdf</a></p> <p><img alt="image10" src="_images/application-octet-stream.png" /> <a class="reference external" href="https://github.com/IQSS/dvn/blob/develop/doc/sphinx/source/datausers-guides_files/simple_study_1.xml">simple_study.xml</a></p> </div> <div class="section" id="zelig-interface"> <h3>Zelig Interface<a class="headerlink" href="#zelig-interface" title="Permalink to this headline">¶</a></h3> <p>Zelig is statistical software for everyone: researchers, instructors, and students. It is a front-end and back-end for R (Zelig is written in R). The Zellig software:</p> <ul class="simple"> <li>Unifies diverse theories of inference</li> <li>Unifies different statistical models and notation</li> <li>Unifies R packages in a common syntax</li> </ul> <p>Zelig is distributed under the GNU General Public License, Version 2. After installation, the source code is located in your R library directory. You can download a tarball of the latest Zelig source code from <a class="reference external" href="http://projects.iq.harvard.edu/zelig">http://projects.iq.harvard.edu/zelig</a>.</p> <p>The Dataverse Network software uses Zelig to perform advanced statistical analysis functions. The current interface schema used by the Dataverse Network for Zelig processes is in the following location:</p> <p><strong>Criteria for Model Availability</strong></p> <p>Three factors determine which Zelig models are available for analysis in the Dataverse Network:</p> <ul class="simple"> <li>Some new models require data structures and modeling parameters that are not compatible with the current framework of the Dataverse Network and other web-driven applications. These types of models are not available in the Dataverse Network.</li> <li>Models must be explicitly listed in the Zelig packages to be used in the Dataverse Network, and all models must be disclosed fully, including runtime errors. Zelig models that do not meet these specifications are excluded from the Dataverse Network until they are disclosed with a complete set of information.</li> <li>An installation-based factor also can limit the Zelig models available in the Dataverse Network. A minimum version of the core software package GCC 4.0 must be installed on any Linux OS-based R machine used with the Dataverse Network, to install and run a key Zelig package, MCMCpack. If a Linux machine that is designated to R is used for DSB services and does not have the minimum version of the GCC package installed, the Dataverse Network looses at least eight models from the available advanced analysis models.</li> </ul> <p><img alt="image11" src="_images/application-octet-stream.png" /> <a class="reference external" href="https://github.com/IQSS/dvn/blob/develop/doc/sphinx/source/datausers-guides_files/configzeliggui_0.xml">configzeliggui.xml</a></p> </div> </div> </div> </div> </div> </div> </div> <div class="sidebar"> <h3>Table Of Contents</h3> <ul class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="">User Guide</a><ul> <li class="toctree-l2"><a class="reference internal" href="#common-tasks">Common Tasks</a><ul> <li class="toctree-l3"><a class="reference internal" href="#finding-data">Finding Data</a></li> <li class="toctree-l3"><a class="reference internal" href="#using-data">Using Data</a></li> <li class="toctree-l3"><a class="reference internal" href="#publishing-data">Publishing Data</a></li> <li class="toctree-l3"><a class="reference internal" href="#things-to-consider-next-steps">Things to Consider, Next Steps</a></li> <li class="toctree-l3"><a class="reference internal" href="#how-the-guides-are-organized">How the Guides Are Organized</a></li> <li class="toctree-l3"><a class="reference internal" href="#other-resources">Other Resources</a></li> <li class="toctree-l3"><a class="reference internal" href="#contact-us">Contact Us</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#finding-and-using-data">Finding and Using Data</a><ul> <li class="toctree-l3"><a class="reference internal" href="#search">Search</a></li> <li class="toctree-l3"><a class="reference internal" href="#view-studies-download-data">View Studies / Download Data</a></li> <li class="toctree-l3"><a class="reference internal" href="#subset-and-analysis">Subset and Analysis</a><ul> <li class="toctree-l4"><a class="reference internal" href="#tabular-data">Tabular Data</a></li> <li class="toctree-l4"><a class="reference internal" href="#network-data">Network Data</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#data-visualization">Data Visualization</a><ul> <li class="toctree-l4"><a class="reference internal" href="#explore-data">Explore Data</a></li> <li class="toctree-l4"><a class="reference internal" href="#set-up">Set Up</a></li> </ul> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#dataverse-administration">Dataverse Administration</a><ul> <li class="toctree-l3"><a class="reference internal" href="#create-a-dataverse">Create a Dataverse</a></li> <li class="toctree-l3"><a class="reference internal" href="#edit-general-settings">Edit General Settings</a></li> <li class="toctree-l3"><a class="reference internal" href="#edit-layout-branding">Edit Layout Branding</a></li> <li class="toctree-l3"><a class="reference internal" href="#edit-description">Edit Description</a></li> <li class="toctree-l3"><a class="reference internal" href="#edit-study-comments-settings">Edit Study Comments Settings</a></li> <li class="toctree-l3"><a class="reference internal" href="#manage-e-mail-notifications">Manage E-Mail Notifications</a></li> <li class="toctree-l3"><a class="reference internal" href="#add-fields-to-search-results">Add Fields to Search Results</a></li> <li class="toctree-l3"><a class="reference internal" href="#set-default-study-listing-sort-order">Set Default Study Listing Sort Order</a></li> <li class="toctree-l3"><a class="reference internal" href="#enable-twitter">Enable Twitter</a></li> <li class="toctree-l3"><a class="reference internal" href="#get-code-for-dataverse-link-or-search-box">Get Code for Dataverse Link or Search Box</a></li> <li class="toctree-l3"><a class="reference internal" href="#edit-terms-for-study-creation">Edit Terms for Study Creation</a></li> <li class="toctree-l3"><a class="reference internal" href="#edit-terms-for-file-download">Edit Terms for File Download</a></li> <li class="toctree-l3"><a class="reference internal" href="#manage-permissions">Manage Permissions</a></li> <li class="toctree-l3"><a class="reference internal" href="#create-user-account">Create User Account</a></li> <li class="toctree-l3"><a class="reference internal" href="#download-tracking-data">Download Tracking Data</a></li> <li class="toctree-l3"><a class="reference internal" href="#edit-file-download-guestbook">Edit File Download Guestbook</a></li> <li class="toctree-l3"><a class="reference internal" href="#openscholar">OpenScholar</a></li> <li class="toctree-l3"><a class="reference internal" href="#enabling-lockss-access-to-the-dataverse">Enabling LOCKSS access to the Dataverse</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#study-and-data-administration">Study and Data Administration</a><ul> <li class="toctree-l3"><a class="reference internal" href="#create-new-study">Create New Study</a></li> <li class="toctree-l3"><a class="reference internal" href="#manage-studies">Manage Studies</a></li> <li class="toctree-l3"><a class="reference internal" href="#manage-study-templates">Manage Study Templates</a></li> <li class="toctree-l3"><a class="reference internal" href="#data-uploads">Data Uploads</a></li> <li class="toctree-l3"><a class="reference internal" href="#manage-collections">Manage Collections</a></li> <li class="toctree-l3"><a class="reference internal" href="#managing-user-file-access">Managing User File Access</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#network-administration">Network Administration</a><ul> <li class="toctree-l3"><a class="reference internal" href="#dataverses-section">Dataverses Section</a><ul> <li class="toctree-l4"><a class="reference internal" href="#create-a-new-dataverse">Create a New Dataverse</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-dataverses">Manage Dataverses</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#subnetwork-section">Subnetwork Section</a><ul> <li class="toctree-l4"><a class="reference internal" href="#create-a-new-subnetwork">Create a New Subnetwork</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-subnetworks">Manage Subnetworks</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-classifications">Manage Classifications</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-study-comments-notifications">Manage Study Comments Notifications</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-controlled-vocabulary">Manage Controlled Vocabulary</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-network-study-templates">Manage Network Study Templates</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#harvesting-section">Harvesting Section</a><ul> <li class="toctree-l4"><a class="reference internal" href="#create-a-new-harvesting-dataverse">Create a New Harvesting Dataverse</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-harvesting">Manage Harvesting</a></li> <li class="toctree-l4"><a class="reference internal" href="#schedule-study-exports">Schedule Study Exports</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-oai-harvesting-sets">Manage OAI Harvesting Sets</a></li> <li class="toctree-l4"><a class="reference internal" href="#edit-lockss-harvest-settings">Edit LOCKSS Harvest Settings</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#settings-section">Settings Section</a><ul> <li class="toctree-l4"><a class="reference internal" href="#edit-name">Edit Name</a></li> <li class="toctree-l4"><a class="reference internal" href="#id10">Edit Layout Branding</a></li> <li class="toctree-l4"><a class="reference internal" href="#id11">Edit Description</a></li> <li class="toctree-l4"><a class="reference internal" href="#edit-dataverse-requirements">Edit Dataverse Requirements</a></li> <li class="toctree-l4"><a class="reference internal" href="#id12">Manage E-Mail Notifications</a></li> <li class="toctree-l4"><a class="reference internal" href="#id13">Enable Twitter</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#terms-section">Terms Section</a><ul> <li class="toctree-l4"><a class="reference internal" href="#edit-terms-for-account-creation">Edit Terms for Account Creation</a></li> <li class="toctree-l4"><a class="reference internal" href="#id14">Edit Terms for Study Creation</a></li> <li class="toctree-l4"><a class="reference internal" href="#id15">Edit Terms for File Download</a></li> <li class="toctree-l4"><a class="reference internal" href="#id16">Download Tracking Data</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#permissions-and-users-section">Permissions and Users Section</a><ul> <li class="toctree-l4"><a class="reference internal" href="#manage-network-permissions">Manage Network Permissions</a></li> <li class="toctree-l4"><a class="reference internal" href="#roles-by-version-state-table">Roles by Version State Table</a></li> <li class="toctree-l4"><a class="reference internal" href="#authorization-to-access-terms-protected-files-via-the-api">Authorization to access Terms-protected files via the API</a></li> <li class="toctree-l4"><a class="reference internal" href="#create-account">Create Account</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-users">Manage Users</a></li> <li class="toctree-l4"><a class="reference internal" href="#manage-groups">Manage Groups</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#utilities">Utilities</a></li> <li class="toctree-l3"><a class="reference internal" href="#web-statistics">Web Statistics</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#appendix">Appendix</a><ul> <li class="toctree-l3"><a class="reference internal" href="#control-card-based-data-ingest">Control Card-Based Data Ingest</a><ul> <li class="toctree-l4"><a class="reference internal" href="#csv-data-spss-style-control-card">CSV Data, SPSS-style Control Card</a></li> <li class="toctree-l4"><a class="reference internal" href="#tab-data-with-ddi-metadata">Tab Data, with DDI Metadata</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#spss-data-file-ingest">SPSS Data File Ingest</a><ul> <li class="toctree-l4"><a class="reference internal" href="#ingesting-spss-por-files-with-extended-labels">Ingesting SPSS (.por) files with extended labels</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#ingest-of-r-rdata-files">Ingest of R (.RData) files</a><ul> <li class="toctree-l4"><a class="reference internal" href="#overview">Overview.</a></li> <li class="toctree-l4"><a class="reference internal" href="#requirements">Requirements.</a></li> <li class="toctree-l4"><a class="reference internal" href="#data-types-compared-to-other-supported-formats-stat-spss">Data Types, compared to other supported formats (Stat, SPSS)</a><ul> <li class="toctree-l5"><a class="reference internal" href="#integers-doubles-character-strings">Integers, Doubles, Character strings</a></li> <li class="toctree-l5"><a class="reference internal" href="#r-factors">R Factors</a></li> <li class="toctree-l5"><a class="reference internal" href="#new-boolean-values">(New!) Boolean values</a></li> <li class="toctree-l5"><a class="reference internal" href="#limitations-of-r-data-format-as-compared-to-spss-and-stata">Limitations of R data format, as compared to SPSS and STATA.</a></li> </ul> </li> <li class="toctree-l4"><a class="reference internal" href="#time-values-in-r">Time values in R</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#fits-file-format-ingest">FITS File format Ingest</a></li> <li class="toctree-l3"><a class="reference internal" href="#metadata-references">Metadata References</a></li> <li class="toctree-l3"><a class="reference internal" href="#zelig-interface">Zelig Interface</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="dataverse-installer-main.html">Installers Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="dataverse-developer-main.html">DVN Developers Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="dataverse-api-main.html">APIs Guide</a></li> </ul> <h3 style="margin-top: 1.5em;">Search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms. </p> </div> <div class="clearer"></div> </div> </div> <div class="footer-wrapper"> <div class="footer"> <div class="left"> <a href="index.html" title="Dataverse Network Guides" >previous</a> | <a href="dataverse-installer-main.html" title="Installers Guide" >next</a> | <a href="genindex.html" title="General Index" >index</a> <br/> <a href="_sources/dataverse-user-main.txt" rel="nofollow">Show Source</a> </div> <div class="right"> <div class="footer"> © Copyright 1997-2013, President & Fellows Harvard University. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. </div> </div> <div class="clearer"></div> </div> </div> </body> </html>