Quick start guide for authors

We recommend that authors follow these steps to create reusable spreadsheets:

  1. Encode your data into a spreadsheet: Use LibreOffice Calc, Microsoft Excel, OpenOffice Calc, WPS Spreadsheets, or a similar program to encode your data into a spreadsheet:
    1. Encode each distinct type of object into a separate worksheet.
    2. Encode each distinct object into a separate row of a worksheet.
    3. Encode an identifier for each object into the first column of each worksheet.
    4. Encode each additional attribute of each object into additional columns.
    5. Use the identifiers of each object to encode relationships between objects into cells.
    6. Encode each Boolean-valued attribute into TRUE or FALSE. Encode each numeric-valued attribute into a number. Encode all other attributes into strings.
    7. Prepend !! to the title of each worksheet.
    8. Add a row that begins with !!ObjTables type='Data' class='<class-name>' description='<brief description of the data represented by the table>' tableFormat='row' date='<YYYY-MM-DD>' to the top of each worksheet.
    9. Add a row of column headings to each worksheet. Optionally, add headings for groups of columns to an additional row.
    10. Prepend ! to each column heading.

    See the documentation 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.

  2. Design a schema for your spreadsheet: Use LibreOffice Calc, Microsoft Excel, OpenOffice Calc, WPS Spreadsheets, or a similar program to describe the schema for your spreadsheet in an additional worksheet:
    1. Add an additional worksheet with the title !!_Schema.
    2. Set the first cell of the first row equal to !!!ObjTables description='<brief description of the dataset>' date='<YYYY-MM-DD>'.
    3. Set the first cell of the second row equal to !!ObjTables type='Schema' tableFormat='row' date='<YYYY-MM-DD>'.
    4. Set the first six columns of the third row equal to !Name, !Type, !Parent, !Format, !Verbose name, and !Verbose name plural.
    5. Add a row for each distinct type of object:
      • The first cell should declare the name of the type. This should be equal to the value of the class attribute of the corresponding worksheet.
      • The second cell should be equal to Class.
      • The third cell should be empty.
      • The fourth cell should be equal to row.
      • The fifth cell should be the singular form of the title.
      • The sixth cell should be the name of title of the corresponding worksheet, which should be plural.
    6. Add a row for each attribute of each object:
      • The first cell should declare the name of the attribute.
      • The second cell should be equal to Attribute.
      • The third cell should be the name of the parent class of the attribute.
      • The fourth cell should indicate the data type of the attribute. For example, Boolean-valued attributes should have the value Boolean, float-valued attributes should have the value Float, string-valued attributes should have the value String, and attributes that represent relationships should have one of the values OneToOne, OneToMany, ManyToOne, or ManyToMany.
      • The fifth cell should contain the heading of the column that corresponds to the attribute.
    7. 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., ManyToMany('Parent', related_name='children')).
    8. Optionally, use arguments to define constraints on the values of the attributes. For example, use the min argument to define the minimum allowed value of a float-valued attribute.

    See the documentation 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.

  3. Validate your spreadsheet: Use the ObjTables web application to validate that your spreadsheet is consistent with your schema. The ObjTables 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 ObjTables to re-use and compose your data.
  4. Pretty-print your spreadsheet: Prior to publication, we recommend using the ObjTables web application 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.
  5. Publish your spreadsheet and its schema: When you publish your spreadsheet, make sure to also include its schema as an additional worksheet so that other researchers can reuse your data.

Quick start guide for reviewers and editors

We recommend that reviewers and editors follow these steps to ensure that authors publish reusable spreadsheets:

  1. Validate each spreadsheet: Use the ObjTables web application to validate that each spreadsheet is consistent with its schema.
  2. Report any errors to the authors: Copy any errors identified by the web application to your critique.
  3. Request that the authors provide reusable spreadsheets: If the submitted spreadsheets are not reusable, ask the authors to revise their spreadsheets so that they can be reused by other investigators.

Quick start guide for readers

We recommend that readers follow these steps to reuse published spreadsheets:

  • Visualizing schemas: Use the ObjTables web application to generate UML diagrams for schemas. A UML diagram can be a useful tool for understanding the structure of a spreadsheet.
  • Comparing spreadsheets: Use the ObjTables 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.
  • Merging spreadsheets: Use the ObjTables 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.
  • Analyzing the content of a spreadsheet: Use the ObjTables 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.

By using this site you agree to use cookies to collect limited personal information to help us improve ObjTables as outlined in our Privacy Policy.