obj_tables/web/guide.html
<!doctype html>
<html class="no-js" lang="en" dir="ltr">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ObjTables: Tools for creating and reusing high-quality spreadsheets</title>
<meta name="description" content="ObjTables is a free, open-source toolkit for systematically building, annotating, validating, and parsing complex datasets with the ease of spreadsheets (e.g., XLSX), the rigor of schemas, and the power of object-oriented programming. ObjTables makes it easy to design schemas for datasets, generate template spreadsheets with inline help and validation for building datasets, capture metadata such as the author of a dataset, use schemas to validate the syntax and semantics of datasets, and use schemas to parse datasets into data structures for further analysis in languages such as Python. The ObjTables software is available through four interfaces: a web application, a web service, a command-line program, and a Python library. Together, ObjTables can help researchers define formats for domain-specific data, integrate diverse data, analyze complex datasets, and share data."/>
<meta name="keywords" content="data, table, schema, data model, meta model, data type, validate, Python"/>
<meta name="language" content="EN">
<meta name="copyright" content="ObjTables developers"/>
<meta name="author" content="ObjTables developers, info@objtables.org"/>
<meta name="reply-to" content="info@objtables.org"/>
<meta name="url" content="https://www.objtables.org">
<meta name="identifier-URL" content="https://www.objtables.org">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<link rel="mask-icon" href="/safari-pinned-tab.svg" color="#3bafda">
<meta name="msapplication-TileColor" content="#3bafda">
<meta name="theme-color" content="#ffffff">
<link rel="stylesheet" href="css/foundation-icons.css">
<link rel="stylesheet" href="css/foundation.min.css">
<link rel="stylesheet" href="css/raleway.css">
<link rel="stylesheet" href="css/app.css">
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-165117961-1"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-165117961-1');
</script>
</head>
<body>
<div class="off-canvas-wrapper">
<div class="off-canvas position-left" id="offCanvasLeft" data-off-canvas>
<!-- Close button -->
<button class="close-button" aria-label="Close menu" type="button" data-close>
<span aria-hidden="true">×</span>
</button>
<!-- Menu -->
<ul class="accordion" data-accordion data-allow-all-closed="true">
<li class="accordion-item is-active" data-accordion-item>
<a class="accordion-title">Guide</a>
<ul class="accordion-content" data-tab-content>
<li><a href="#authors">Authors</a></li>
<li><a href="#reviewers">Reviewers and editors</a></li>
<li><a href="#readers">Readers</a></li>
</ul>
</li>
<li class="accordion-item" data-accordion-item>
<a class="accordion-title">Software</a>
<ul class="accordion-content" data-tab-content>
<li><a href="app">Web application</a></li>
<li><a href="https://pypi.org/pypi/obj_tables/">Command-line program</a></li>
<li><a href="api">Web service</a></li>
<li><a href="https://pypi.org/pypi/obj_tables/">Python package</a></li>
<li class="separator"><a href="https://hub.docker.com/r/karrlab/obj_tables">Docker image</a></li>
<li><a href="https://github.com/KarrLab/obj_tables/">Source code</a></li>
</ul>
</li>
<li class="accordion-item" data-accordion-item>
<a class="accordion-title">Docs</a>
<ul class="accordion-content" data-tab-content>
<li><a href="docs#examples">Detailed example</a></li>
<li><a href="docs#more-examples">Additional examples</a></li>
<li class="separator"><a href="docs#schema-formats">Schema formats</a></li>
<li><a href="docs#data-types">Data types</a></li>
<li><a href="docs#dataset-formats">Dataset formats</a></li>
<li><a href="docs#validation">Data validation</a></li>
<li class="separator"><a href="app">Web application</a></li>
<li><a href="docs#cli">Command-line program</a></li>
<li><a href="api">Web service</a></li>
<li><a href="docs#python">Python package: introduction</a></li>
<li><a href="https://sandbox.karrlab.org/tree/obj_tables">Python package: tutorials</a></li>
<li><a href="https://docs.karrlab.org/obj_tables">Python package: docs</a></li>
<li class="separator"><a href="docs#other-languages">Working with <i>ObjTables</i> in other languages</a></li>
<li><a href="docs#other-resources">Resources for working with <i>ObjTables</i></a></li>
<li><a href="docs#comparison">Comparison with other tools</a></li>
<li><a href="docs#design-choices">Design choices</a></li>
<li><a href="docs#limitations">Known limitations</a></li>
<li><a href="docs#roadmap">Future directions</a></li>
<li><a href="docs#faq">FAQ</a></li>
<li class="separator"><a href="docs#help">More help</a></li>
</ul>
</li>
<li class="accordion-item" data-accordion-item>
<a class="accordion-title">About</a>
<ul class="accordion-content" data-tab-content>
<li><a href="about#license">License</a></li>
<li><a href="about#citation">Citation</a></li>
<li class="separator"><a href="about#contribute">Contributing</a></li>
<li class="separator"><a href="about#team">Team</a></li>
<li><a href="about#funding">Funding</a></li>
<li class="separator"><a href="about#contact">Contact info</a></li>
</ul>
</li>
</ul>
</div>
<div class="off-canvas-content" data-off-canvas-content>
<div class="page-title">
<div class="grid-container">
<div class="grid-x grid-padding-x">
<div class="large-8 medium-6 small-12 cell title">
<button class="menu-icon hide-for-medium" type="button" data-open="offCanvasLeft"></button>
<a href="/">
<span class="title"><i>ObjTables</i><span class="show-for-large">:</span></span>
<span class="subtitle show-for-large">
Tools for creating and reusing high-quality spreadsheets
</span>
</a>
</div>
<div class="large-4 medium-6 hide-for-small-only cell links">
<ul class="dropdown menu" data-dropdown-menu>
<li class="active-page">
<a>Guide</a>
<ul class="menu">
<li><a href="#authors">Authors</a></li>
<li><a href="#reviewers">Reviewers and editors</a></li>
<li><a href="#readers">Readers</a></li>
</ul>
</li>
<li>
<a>Software</a>
<ul class="menu">
<li><a href="app">Web application</a></li>
<li><a href="https://pypi.org/pypi/obj_tables/">Command-line program</a></li>
<li><a href="api">Web service</a></li>
<li><a href="https://pypi.org/pypi/obj_tables/">Python package</a></li>
<li class="separator"><a href="https://hub.docker.com/r/karrlab/obj_tables">Docker image</a></li>
<li><a href="https://github.com/KarrLab/obj_tables/">Source code</a></li>
</ul>
</li>
<li>
<a>Docs</a>
<ul class="menu">
<li><a href="docs#examples">Detailed example</a></li>
<li><a href="docs#more-examples">Additional examples</a></li>
<li class="separator"><a href="docs#schema-formats">Schema formats</a></li>
<li><a href="docs#data-types">Data types</a></li>
<li><a href="docs#dataset-formats">Dataset formats</a></li>
<li><a href="docs#validation">Data validation</a></li>
<li class="separator"><a href="app">Web application</a></li>
<li><a href="docs#cli">Command-line program</a></li>
<li><a href="api">Web service</a></li>
<li><a href="docs#python">Python package: introduction</a></li>
<li><a href="https://sandbox.karrlab.org/tree/obj_tables">Python package: tutorials</a></li>
<li><a href="https://docs.karrlab.org/obj_tables">Python package: docs</a></li>
<li class="separator"><a href="docs#other-languages">Working with <i>ObjTables</i> in other languages</a></li>
<li><a href="docs#other-resources">Resources for working with <i>ObjTables</i></a></li>
<li><a href="docs#comparison">Comparison with other tools</a></li>
<li><a href="docs#design-choices">Design choices</a></li>
<li><a href="docs#limitations">Known limitations</a></li>
<li><a href="docs#roadmap">Future directions</a></li>
<li><a href="docs#faq">FAQ</a></li>
<li class="separator"><a href="docs#help">More help</a></li>
</ul>
</li>
<li>
<a>About</a>
<ul class="menu">
<li><a href="about#license">License</a></li>
<li><a href="about#citation">Citation</a></li>
<li class="separator"><a href="about#contribute">Contributing</a></li>
<li class="separator"><a href="about#team">Team</a></li>
<li><a href="about#funding">Funding</a></li>
<li class="separator"><a href="about#contact">Contact info</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="grid-container content">
<div class="grid-x grid-padding-x">
<div class="large-2 cell">
<div class="toc-container">
<div class="toc">
<h2>Contents</h2>
<div class="section-content">
<ul>
<li><a href="#authors">Guide for authors</a></li>
<li><a href="#reviewers">Guide for reviewers and editors</a></li>
<li><a href="#readers">Guide for readers</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="large-10 cell content-container">
<div id="authors">
<h2>Quick start guide for authors</h2>
<div class="section-content">
<p>We recommend that authors follow these steps to create reusable spreadsheets:</p>
<ol class="vertically-spaced-list">
<li><b>Encode your data into a spreadsheet:</b> Use LibreOffice Calc, Microsoft Excel, OpenOffice Calc, WPS Spreadsheets, or a similar program to encode your data into a spreadsheet:
<ol style="list-style-type: lower-roman;">
<li>Encode each distinct type of object into a separate worksheet.</li>
<li>Encode each distinct object into a separate row of a worksheet.</li>
<li>Encode an identifier for each object into the first column of each worksheet.</li>
<li>Encode each additional attribute of each object into additional columns.</li>
<li>Use the identifiers of each object to encode relationships between objects into cells.</li>
<li>Encode each Boolean-valued attribute into <span class="monospace">TRUE</span> or <span class="monospace">FALSE</span>. Encode each numeric-valued attribute into a number. Encode all other attributes into strings.</li>
<li>Prepend <span class="monospace">!!</span> to the title of each worksheet.</li>
<li>Add a row that begins with <span class="monospace">!!ObjTables type='Data' class='<class-name>' description='<brief description of the data represented by the table>' tableFormat='row' date='<YYYY-MM-DD>'</span> to the top of each worksheet.</li>
<li>Add a row of column headings to each worksheet. Optionally, add headings for groups of columns to an additional row.</li>
<li>Prepend <span class="monospace">!</span> to each column heading.</li>
</ol>
<p>See the documentation <a href="docs"><i class="fi-link"></i></a> for examples of spreadsheets, additional options for encoding data into spreadsheets, and more information about the markup syntax for indicating the class and attribute represented by each worksheet and column.</p>
</li>
<li><b>Design a schema for your spreadsheet:</b> Use LibreOffice Calc, Microsoft Excel, OpenOffice Calc, WPS Spreadsheets, or a similar program to describe the schema for your spreadsheet in an additional worksheet:
<ol style="list-style-type: lower-roman;">
<li>Add an additional worksheet with the title <span class="monospace">!!_Schema</span>.</li>
<li>Set the first cell of the first row equal to <span class="monospace">!!!ObjTables description='<brief description of the dataset>' date='<YYYY-MM-DD>'</span>.</li>
<li>Set the first cell of the second row equal to <span class="monospace">!!ObjTables type='Schema' tableFormat='row' date='<YYYY-MM-DD>'</span>.</li>
<li>Set the first six columns of the third row equal to <span class="monospace">!Name</span>, <span class="monospace">!Type</span>, <span class="monospace">!Parent</span>, <span class="monospace">!Format</span>, <span class="monospace">!Verbose name</span>, and <span class="monospace">!Verbose name plural</span>.</li>
<li>Add a row for each distinct type of object:
<ul>
<li>The first cell should declare the name of the type. This should be equal to the value of the <span class="monospace">class</span> attribute of the corresponding worksheet.</li>
<li>The second cell should be equal to <span class="monospace">Class</span>.</li>
<li>The third cell should be empty.</li>
<li>The fourth cell should be equal to <span class="monospace">row</span>.</li>
<li>The fifth cell should be the singular form of the title.</li>
<li>The sixth cell should be the name of title of the corresponding worksheet, which should be plural.</li>
</ul>
</li>
<li>Add a row for each attribute of each object:
<ul>
<li>The first cell should declare the name of the attribute.</li>
<li>The second cell should be equal to <span class="monospace">Attribute</span>.</li>
<li>The third cell should be the name of the parent class of the attribute.</li>
<li>The fourth cell should indicate the data type of the attribute. For example, Boolean-valued attributes should have the value <span class="monospace">Boolean</span>, float-valued attributes should have the value <span class="monospace">Float</span>, string-valued attributes should have the value <span class="monospace">String</span>, and attributes that represent relationships should have one of the values <span class="monospace">OneToOne</span>, <span class="monospace">OneToMany</span>, <span class="monospace">ManyToOne</span>, or <span class="monospace">ManyToMany</span>.</li>
<li>The fifth cell should contain the heading of the column that corresponds to the attribute.</li>
</ul>
<li>Set the first arguments of each related attribute to the name of the related class and the name of the reverse attribute in the related class (e.g., <span class="monospace">ManyToMany('Parent', related_name='children')</span>).</li>
<li>Optionally, use arguments to define constraints on the values of the attributes. For example, use the <span class="monospace">min</span> argument to define the minimum allowed value of a float-valued attribute.</li>
</ol>
<p>See the documentation <a href="docs#examples"><i class="fi-link"></i></a> for examples of schemas, additional options for encoding data into spreadsheets, information about the available types of attributes, and information about the available constraints on the value of each attribute.</p>
</li>
<li><b>Validate your spreadsheet:</b> Use the <i>ObjTables</i> web application <a href="app"><i class="fi-link"></i></a> to validate that your spreadsheet is consistent with your schema. The <i>ObjTables</i> software will report any errors. If necessary, iteratively correct these errors and re-validate your spreadsheet. Once your spreadsheet is valid, other researchers will be able to use <i>ObjTables</i> to re-use and compose your data.</li>
<li><b>Pretty-print your spreadsheet:</b> Prior to publication, we recommend using the <i>ObjTables</i> web application <a href="app"><i class="fi-link"></i></a> to pretty-print your spreadsheet. This will add a table of contents, highlight and freeze the column headings, and add inline help information about each column.</li>
<li><b>Publish your spreadsheet and its schema:</b> When you publish your spreadsheet, make sure to also include its schema as an additional worksheet so that other researchers can reuse your data.</li>
</ol>
</div>
</div>
<div id="reviewers">
<h2>Quick start guide for reviewers and editors</h2>
<div class="section-content">
<p>We recommend that reviewers and editors follow these steps to ensure that authors publish reusable spreadsheets:</p>
<ol class="vertically-spaced-list">
<li><b>Validate each spreadsheet:</b> Use the <i>ObjTables</i> web application <a href="app"><i class="fi-link"></i></a> to validate that each spreadsheet is consistent with its schema.</li>
<li><b>Report any errors to the authors:</b> Copy any errors identified by the web application to your critique.</li>
<li><b>Request that the authors provide reusable spreadsheets:</b> If the submitted spreadsheets are not reusable, ask the authors to revise their spreadsheets so that they can be reused by other investigators.</li>
</ol>
</div>
</div>
<div id="readers">
<h2>Quick start guide for readers</h2>
<div class="section-content">
<p>We recommend that readers follow these steps to reuse published spreadsheets:</p>
<ul class="vertically-spaced-list">
<li><b>Visualizing schemas:</b> Use the <i>ObjTables</i> web application <a href="app"><i class="fi-link"></i></a> to generate UML diagrams for schemas. A UML diagram can be a useful tool for understanding the structure of a spreadsheet.</li>
<li><b>Comparing spreadsheets:</b> Use the <i>ObjTables</i> web application to compare spreadsheets that are encoded into the same schema. The web application will determine if the spreadsheets are equivalent. If the spreadsheets are different, the web application will describe the differences between the spreadsheets.</li>
<li><b>Merging spreadsheets:</b> Use the <i>ObjTables</i> web application to merge spreadsheets that are encoded with the same or overlapping schemas. The web application will return a single spreadsheet that contains the combined content of the individual spreadsheets.</li>
<li><b>Analyzing the content of a spreadsheet:</b> Use the <i>ObjTables</i> Python package to parse a spreadsheet into a high-level data structure, and use packages such as Pandas, scikit-learn, and SciPy or custom code to analyze this data structure.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="privacy-notice">
<p>By using this site you agree to use cookies to collect limited personal information to help us improve <i>ObjTables</i> as outlined in our <a href="privacy-policy">Privacy Policy</a>.</p>
</div>
</div>
</div>
<script src="js/jquery-3.4.1.min.js"></script>
<script src="js/foundation.min.js"></script>
<script src="js/app.js"></script>
</body>
</html>