Tools¶

Tools are a feature in IDEAS that allows you to process data into results for analysis. IDEAS offers many Inscopix tools for different analysis use cases such as calcium and behavior processing. Although these tools cover many analysis use cases, often times there are custom use cases for analysis, specific to a particular lab, experimental setup, data modality, etc. Enter custom tools analysis, a rich set of features in IDEAS that allow you to seamlessly take your custom analysis code and package it as a tool that can be used in projects on IDEAS.

Tools Library¶

The tools library is a place to explore and discover tools in IDEAS.

On this page you can see your custom tools and those created by others within your organization, as well as public, Inscopix tools. Tools can be filtered by keywords, tags, and author. There is also a filter to only show custom tools within your organization. Tools can also be sorted by criteria like date created, and can be pinned, similar to the project dashboard. Selecting one of the tools will navigate you to a project page for the tool.

From the tools library, the containers library is also accessible, where you can browse public and custom containers on IDEAS. Learn more about containers here.

Create Tool¶

New custom tools can be created by selecting the create tool button in the top-right corner of the tool library. This will open up a panel, prompting you to enter some preliminary information about the new tool, including a name, and short description. Both of these properties can be changed after the tool is created by editing the tool settings.

Tool Projects¶

Each tool in IDEAS has its own project page. This page is similar to regular project pages, but is specific to a tool. When you create a new custom tool, you’ll be navigated to the initial project page for the tool. This page will prompt you to publish the first version of your tool. Selecting the start draft button will navigate you to the tool publisher interface. Read more about the process of publishing tool versions here.

Version Table¶

Once the first tool version has been published, the tool project page will show information about the latest and previous published tool versions.

Each row in the version table can be expanded, showing the specification of the tool version, consisting of the tool parameters, outputs, and default resources.

Additionally, you can view a changelog of the version, describing what changed about the tool in the particular version.

Also, you can view information about the specific container image used for the tool version.

Tasks¶

Tasks executed in the tool publisher test step will appear in the tasks tab of the tool project. This tab will show statistics about tasks executed in this project for testing the tool, including the amount of compute credits consumed (learn more about quota usage here), the duration, the status, and any logs.

Files¶

Files can be uploaded to a tool project to be used in the tool publisher test table to test new versions before publishing to your organization. Files can be uploaded in the files tab of the tool project page, but files can also be uploaded directly to the tool publisher test table.

Settings¶

The settings tab is where you can edit tool project settings including:

Deletion¶

A tool can be deleted if it's no longer required by anyone in the tool orgainization. This action is available in the tool settings. When a tool is deleted, it cannot be used in any projects, by any users, across IDEAS in the future. Additionally, any storage for the tool code files is deleted.

Tool Publisher¶

The tool publisher is an interface that allows you to publish custom tools on IDEAS. It consists of four steps: upload, configure, test, and publish. The publisher allows you to publish new versions your custom tool.

Upload¶

The first step of the tool publisher is to create and upload your custom code. Custom code needs to be configured and tested locally, and then compressed into a bundle file that can be uploaded to IDEAS. Refer to this guide for more details on the local configuration process.

The publisher shows the CLI commands that you need to execute locally in order to configure, test, and bundle code locally. You can copy each command into a terminal on your computer to follow the local configuration process. After generating a bundle, select the file in the publisher and upload to IDEAS. If the bundle upload successfully, the publisher will automatically move to the next step if it's your first upload for this version.

If you've already uploaded a bundle, you will be asked to confirm the change. Any tasks created in the test table will also be reset whenever a new bundle is uploaded.

Configure¶

The second step of the tool publisher is to configure your tool parameters and outputs. Parameters are automatically identified from your tool function. No further configuration is necessary, but you can optionally customize details about the parameters.

Test¶

The third step of the publisher is to test your tool. Previously, you tested your tool locally with the CLI, but now you must test your tool as an analysis table. The parameter and output rows from the configure step will map to columns in the tool analysis table. You can upload data to this table and test different use cases to validate how your tool runs in the cloud, before publishing to IDEAS.

Publish¶

The final step is to publish the tool. Before publishing a tool version, you must describe the changes made in this version so that others in your organization can understand what's changed in this version of the tool. This description is apart of the changelog of the tool, visible in the tool project version table. The changelog also includes an auto-generated record of the changes made to the tool parameters, outputs, and default resources in this tool version.

In addition to a changelog, you must also specify a number for this tool version. Tool versions follow sematic versioning.

Finally, the publish step also has an option to copy a template for the tool documnetation. This template, in markdown format, is a standardized way for documenting tools. This template is used for Inscopix tools, and can be applied for your own custom tools.

Tool Function¶

A tool is essentially a wrapper around a function. In the context of IDEAS, functions accept input files and other parameters, process the input data and generate output files. Usually the processing that takes place is some kind of scientific analysis, but it could also be another type of operation, like data transformation, conversion, or export.

In order to create a custom tool in IDEAS, you must provide a python function, which is your tool function. A tool function defines the logic of your tool in Python. This function is meant to be an entrypoint to your analysis, which can call other functions, and third party libraries or programs. All IDEAS requires in order to create a custom tool is the entrypoint function which coordinates the tool logic in a reusable way. Functions need to also run in a configured execution environment, i.e., a container, which you can read more about here.

Tool Parameters¶

Most programming languages support functions as a way to reuse and package code. Within IDEAS, function parameters map to a tool parameter. When you configure your tool locally, IDEAS CLI introspects your tool function, automatically detecting the parameters, and mapping to compatible tool parameters in IDEAS.

When IDEAS CLI introspects your tool function and automatically identifies all of the parameters, it tries to infer as many details as possible about the function parameter, in order to initialize the corresponding tool parameter. All tool parameters have the following properties that can be customized in the configure step of the tool publisher.

Tool Parameter Types¶

There are several different types of tool parameters, which support different input value types. The following table summarizes the types of tool parameters supported in IDEAS.

IDEAS CLI tries to automatically identify the tool parameter types from your tool function, however the parameter type can be manually specified in the configure step of the publisher.

The following sections describe each tool parameter type in more detail.

File Parameter¶

The file parameter type is for any parameter representing an input file. Configuring a parameter as this type allows you to select files from your IDEAS project to use in a tool. IDEAS takes care of making the selected file from the user's project available in the cloud where the tool runs.

File parameters support the following customizations.

File Formats¶

A list of file formats to use for filtering compatible files for this parameter. A file format represents the standard for how data is stored in a file. File formats are often identified by the extension of the file, which is the convention used in IDEAS. This list will be used as a filter when selecting a data file from a project in the tool analysis table.

Tags¶

A list of tags to use for filtering compatible files to select from a project. Similar to file formatss, this list will be used as a filter when selecting a data file from a project in the tool analysis table. Tags are generated for files when generated from other custom tools. See adding tags to output data in custom tools.

Integer Parameter¶

The integer parameter type is for a function argument which represents a whole number, negative or positive.

Min, Max¶

An inclusive range can be defined for integer parameters, which restricts values between a min and/or max.

Float Parameter¶

The float parameter type is for a function argument which represents a decimal number, negative or positive.

Min, Max¶

An inclusive range can be defined for float parameters, which restricts values from a min and/or max.

String Parameter¶

A string parameter type is for a function argument which represents any string input. This parameter type does not have any additional configurations.

Boolean Parameter¶

A boolean parameter type is for a function argument which represents any boolean input (i.e., true or false, yes or no). This parameter type does not have any additional configurations.

Choice Parameter¶

A choice parameter type is for a function parameter which represents a string input selected from a defined list of choices. This parameter type is helpful for defining options that can be chosen from to run your custom tool.

Python Types to Tool Parameter Types¶

IDEAS currently supports the following python types for the tool function. When writing your tool function, ensure all parameters map to one of the following supported python types.

Tool Outputs¶

Aside from tool paramaters for inputs, a tool also has outputs.

Tool outputs can contain one or more results files. Each result file is available on the cloud and can be downloaded to your local computer. Each result file can also have additional output data, including previews, metadata, and tags.

!!! question "How do I get tool outputs to appear on IDEAS from my tool function?

When IDEAS runs your tool, it creates an empty, **output directory**, which is set to the [current working directory](https://en.wikipedia.org/wiki/Working_directory).
Any output files written to the current working directory will automatically be identified as result files, which will be made available in the [output column](#output-columns) of the tool.
So all you need to do in your tool function is ensure any result files are written to the current working directory.

Output Data¶

Output data is additional data associated with result files generated by a tool. This additionaly data is displayed in IDEAS, and helps to provide from contextual information about a result from a quick glance. You can understand what's in a result file, just by looking at it's previews, or metadata, or tags, without actually having to download the result file from the cloud.

Previews¶

Previews are figures that describe data stored in a result file. These can include figure plots, images, or movies. Previews are meant to be small files, which accompany a result file, and can be used to provide a quick summary or impression of the results in a file.

The following file formats (i.e., extensions) are supported for rendering previews:

Refer to the ideas Python API reference for more info on how to register previews to output files in a tool function.

Metadata¶

Metadata is any piece of key, value data which describes a result file in some way. Metadata can range from anything like the date the originating data was generated, or the subject id, experimental condition, behaviorial states, statistics etc.

Metadata consists of the following three properties:

The following json types are supported for metadata values:

• string
• boolean
• number
• array[string]

Tags¶

Tags are labels which describe a result file. Tags are helpful for assigning categorical labels for result files, which can be used to filter file inputs in downstream tools. For example, a tag can describe the type of data in a result file, like movie, traces, footprints, etc. Or tags can describe other attributes of a result file, like experimental conditions, behaviorial states, result classifition etc.

Output Columns¶

In addition to being able to assign output data to result files, you can group result files into different output columns.

By default, a single output column is created for a custom tool, which looks for any output files generated by the tool and places all detected files in a one column. You can customize the default setting by creating multiple output columns, representing different groups of result files.

Each output column identifies output files using a file pattern. The file pattern matches to files in the output directory. If a file matches a file pattern it's assigned to the corresponding output column.

!!! info "File patterns for output columns are relative to the output directory

The output directory is managed by IDEAS when your tool runs.
File patterns for output columns are defined relative to the output directory

**Absolute file patterns are not supported.**

The default file pattern is **/*, for a single output column. This file pattern means:

1. ** is used to match zero or more directories and subdirectories in the output directory
2. /* is used to match zero or more files in any of the matching directories

Combining these two pieces of the file pattern, this matches any file recursively in the output directory.

If for example, you want one output column with all files ending .csv in the output directory, the file pattern could be set to *.csv. However, this file pattern would not match csv files in subdirectories of the output directory. Instead, the file pattern could be set to **/*.csv, which will match any csv file in any subdirectory of the output directory.