Skip to content

Commit 7fb05a0

Browse files
Zachary-IpZach Ipsg-s
authored
Docs (#7)
* use setup.py * basic docs can be built * no pep517 * getting started * more updates * read cellsets * add logo * working autodoc * tests should pass now * removed self * more changes to docs * more docs * added more docs --------- Co-authored-by: Zach Ip <[email protected]> Co-authored-by: Srinivas Gorur-Shandilya <[email protected]> Co-authored-by: Srinivas Gorur-Shandilya <[email protected]>
1 parent 4e84bb1 commit 7fb05a0

16 files changed

+666
-134
lines changed

‎.github/workflows/main.yml

-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@ jobs:
4444
steps:
4545
- uses: actions/checkout@v3
4646

47-
4847
- uses: actions/setup-python@v4
4948
with:
5049
python-version: ${{ matrix.python-version }}

‎Makefile

+7
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ ifneq ($(shell test -f ${IDEAS_GITHUB_TOKEN_FILE} && echo yes),yes)
1717
$(error The GitHub token file ${IDEAS_GITHUB_TOKEN_FILE} does not exist)
1818
endif
1919

20+
install-poetry:
21+
@bash install-poetry.sh
22+
2023
test: verify-github-token
2124
poetry run coverage run -m pytest -sx --failed-first
2225

@@ -28,3 +31,7 @@ coverage-report: .coverage
2831
poetry run coverage html --omit="*/test*"
2932
open htmlcov/index.html
3033

34+
serve: install-poetry
35+
@echo "Serving docs locally..."
36+
poetry run mkdocs serve
37+

‎README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ Experimental pure-python API to read ISXD files
77
| File type | Support |
88
| --------- | ------- |
99
| CellSet | ✅ |
10-
| Movie | ✅ |
11-
| VesselSet | ✅ |
10+
| Movie | ❌ |
1211
| Events | ❌ |
12+
| VesselSet | ❌ |
1313

1414

1515
## Installation

‎docs/INDEX.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# isx: a pure-python API to read Inscopix data
2+
3+
`isx` is a lightweight pure-python API for reading
4+
Inscopix data files.
5+
6+
## Nomenclature and Description
7+
8+
This repository is distinct from the Python API for [IDPS](https://inscopix.com/software-analysis-miniscope-imaging/), which is also called `isx`.
9+
10+
| This repository | The IDPS API |
11+
| --------------- | ------------------- |
12+
| Freely available to the public (under a NC-BY license, see [License](LICENSE.md) for details) | Requires access to IDPS |
13+
| Only Python support | Python and MATLAB support |
14+
| Pure python implementation. Should work on any system that can run Python | Implemented in C++ with Python (or MATLAB) bindings |
15+
| No user support | Support via standard Inscopix channels for Inscopix customers |
16+
17+
18+
!!! info "Drop in replacement for the IDPS API"
19+
The goal of this repository is to act as a drop-in replacement for the IDPS Python API (for reading ISXD files). Therefore, code here is structured to mirror classes and functions in the IDPS Python API.
20+
21+
22+
!!! tip "`isx` or `py_isx`?"
23+
This repository is called `py_isx`, but defines a package called `isx`. Therefore, you would import this as follows:
24+
25+
```python
26+
import isx
27+
```
28+
29+
The reason for this is so that it can be used as a back-end for code that was written for the IDPS Python API, without requiring any change in user code.
30+
31+
## User Support
32+
33+
!!! Warning "No user support"
34+
This repository is provided as-is, with no ongoing support from Inscopix.
35+
36+
## Data Support
37+
38+
Currently, `isx` supports only a subset of Inscopix data types.
39+
40+
41+
| File type | Support |
42+
| --------- | ------- |
43+
| ISXD CellSet | ✅ |
44+
| ISXD Movie | ✅ |
45+
| GPIO data | ❌ |
46+
| ISXD Events | ❌ |
47+
| ISXD VesselSet | ❌ |
48+
49+
## License
50+
51+
`isx` has been released under a [CC BY-NC license](https://creativecommons.org/licenses/by-nc/4.0/).
52+
53+
This means that:
54+
55+
You are free to:
56+
57+
- Share — copy and redistribute the material in any medium or format
58+
- Adapt — remix, transform, and build upon the material
59+
The licensor cannot revoke these freedoms as long as you follow the license terms.
60+
61+
Under the following terms:
62+
63+
- Attribution — You must give appropriate credit , provide a link to the license, and indicate if changes were made . You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
64+
- NonCommercial — You may not use the material for commercial purposes .
65+
- No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

‎docs/LICENSE.md

+159
Large diffs are not rendered by default.

‎docs/contributing.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Contributing to `py_isx`
2+
3+
## General Information
4+
5+
Contributions to `py_isx` are welcome, but no guarantee is made
6+
that your contributions will be merged, or responded to.
7+
8+
## Reporting bugs
9+
10+
Please report bugs using our [issue tracker](https://github.com/inscopix/py_isx/issues) on GitHub. Unsolicited bug reports cannot be guaranteed a response.
11+
12+
## Contributing to documentation
13+
14+
## Contributing to code

‎docs/css/mkdocstrings.css

Whitespace-only changes.

‎docs/how-to/read-cellset.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# How to read ISXD Cellset files
2+
3+
4+
We first import `py_isx` using:
5+
6+
7+
```python
8+
import isx
9+
```
10+
11+
## Read a CellSet
12+
13+
CellSets can be easily opened in Python using the `isx.CellSet.read` method.
14+
```python
15+
cell_set = isx.CellSet.read('cellset.isxd')
16+
```
17+
Now that you have a `CellSet` object, you can use it to access the data in the file.
18+
19+
### Get the number of cells in the CellSet
20+
```python
21+
num_cells = cell_set.num_cells
22+
```
23+
With this information, you can pull the data from specific cells, or iterate over all of the cells in the file.
24+
25+
### Get the trace from a cell
26+
27+
```python
28+
# Pick a number less than `num_cells`
29+
cell_trace = cell_set.get_cell_trace(0)
30+
```
31+
32+
### Get the name of a cell
33+
```python
34+
cell_name = cell_set.get_cell_name(0)
35+
```
36+
37+
### Get the status of a cell
38+
```python
39+
cell_name = cell_set.get_cell_status(0)
40+
```
41+
42+
#### Alternatively, loop over all cells in the file
43+
```python
44+
for cell_idx in range(num_cells):
45+
cell_trace = cell_set.get_cell_trace(cell_idx)
46+
cell_name = cell_set.get_cell_name(cell_idx)
47+
cell_status = cell_set.get_cell_status(cell_idx)
48+
```

‎docs/images/logo.png

23.5 KB
Loading

‎docs/installing.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
2+
# Installation
3+
4+
## For Users
5+
6+
### Installing from source
7+
8+
If you plan to use this in your own project, use your
9+
favorite package manager to install this in your project.
10+
For example if you wanted to install using [poetry](https://python-poetry.org/):
11+
12+
```bash
13+
poetry add git+ssh://[email protected]/inscopix/py_isx.git
14+
```
15+
16+
Please refer to [Poetry's documentation](https://python-poetry.org/docs/cli/#add) for installing from
17+
git repositories for further details.
18+
19+
### Installing from a wheel
20+
21+
We also provide wheel files for installation locally.
22+
23+
## For Developers
24+
25+
### Get the code
26+
27+
```bash
28+
git clone [email protected]:inscopix/py_isx.git
29+
```
30+
31+
### Prerequisites
32+
33+
Make sure you have [poetry](https://python-poetry.org/) and
34+
[make](https://www.gnu.org/software/make//) installed.
35+
Verify that both are installed:
36+
37+
```bash
38+
make --version
39+
GNU Make 3.81
40+
Copyright (C) 2006 Free Software Foundation, Inc.
41+
This is free software; see the source for copying conditions.
42+
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
43+
PARTICULAR PURPOSE.
44+
45+
This program built for i386-apple-darwin11.3.0
46+
```
47+
48+
```bash
49+
poetry --version
50+
Poetry (version 1.7.1)
51+
```
52+
53+
### Install locally
54+
55+
You can then install the API locally by navigating to the directory you downloaded the code in, and running:
56+
57+
```bash
58+
poetry lock
59+
poetry install --all-extras
60+
```
61+
62+
Poetry installs using a "editable" install, so changes you make will be reflected in the code executed.
63+
64+
65+

‎docs/reference/classes.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# API Reference: Classes
2+
3+
!!! tip "How to use this reference"
4+
This page contains information about every Class and function in this package. This is meant as a detailed reference for this code. If you're looking to do something specific, the [How To](how-to.md) section may be more useful.
5+
6+
## `isx.Movie`
7+
8+
9+
::: isx.Movie
10+
options:
11+
show_root_heading: false
12+
show_source: false
13+
show_root_toc_entry: false
14+
members:
15+
- read
16+
- get_frame_data
17+
18+
19+
## `isx.CellSet`
20+
21+
::: isx.CellSet
22+
options:
23+
show_root_heading: false
24+
show_source: false
25+
show_root_toc_entry: false
26+
27+
28+
## `isx.Duration`
29+
30+
::: isx.Duration
31+
options:
32+
show_root_heading: false
33+
show_source: false
34+
show_root_toc_entry: false
35+
36+
37+
## `isx.Timing`
38+
39+
::: isx.Timing
40+
options:
41+
show_root_heading: false
42+
show_source: false
43+
show_root_toc_entry: false
44+
45+
## `isx.Spacing`
46+
47+
::: isx.Spacing
48+
options:
49+
show_root_heading: false
50+
show_source: false
51+
show_root_toc_entry: false

‎docs/reference/functions.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## Functions
2+
3+
::: isx.isxd_type
4+
5+
6+
7+
8+
::: isx._footer_length
9+
10+
11+
::: isx._extract_footer
12+
13+
14+
::: isx._get_isxd_times

‎install-poetry.sh

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
if ! command -v poetry &> /dev/null
2+
then
3+
echo "poetry could not be found, installing..."
4+
curl -sSL https://install.python-poetry.org | python3 -
5+
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bash_profile
6+
# tell git to use SSH to get code
7+
git config --global url.ssh://[email protected]/.insteadOf https://github.com/
8+
exit
9+
fi

0 commit comments

Comments
 (0)