Skip to content

refactoring docs and README #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AtharvUmap merged 1 commit into from
Feb 13, 2026
Merged

refactoring docs and README #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 6 additions & 87 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,98 +25,17 @@ The modifications focus on the `classes.py` file, specifically enhancing the `Ex
2. **Varied Stimuli Durations:** Support for distribution-based durations rather than a single fixed duration.
3. **Conditional ITIs:** Implementation of Inter-trial Intervals that vary based on probability distributions or the relationship between specific stimuli.

---
## Neurodesign-plus Documentation

## Installation & Setup
The complete documentation for `neurodesign-plus` is hosted on [ReadTheDocs](https://neurodesign-plus.readthedocs.io/en/latest/). It serves as your primary resource for:

See [link](./manuals/SETUP.md) for environment setup and installation instructions.
1. **Getting Started:** Installation and setup.
2. **Core Concepts:** Understanding Neurodesign Efficiency Metrics.
3. **Advanced Usage:** Implementing fixed user inputs, variable durations, and conditional ITIs.
4. **Tutorials:** Jupyter notebook tutorials to fast-track your learning.

---

## Original Tool

The Neurodesign package is organized around three core classes: Experiment, Design, and Optimization.

1. Experiment defines the experiment specification (conditions/stimuli, durations, ITIs, constraints).

2. Design represents a concrete design instance generated from an experiment (event order + ITIs).

3. Optimization searches over candidate designs and selects designs based on efficiency metrics.

## Metrics

We are looking to optimize experimental design, but what defines good metrics?

The Neurodesign Python package optimizes these experiments based on four metrics:

1. **Fe : Estimation Efficiency**

Measures how well the design allows estimation of response shape and amplitude when events overlap in time.
High Fe means the model can separate the contributions of different events cleanly.

2. **Fd : Detection Efficiency**

Measures how well the design supports detecting differences between conditions assuming a fixed canonical HRF.
High Fd means convolved regressors for each condition are distinguishable.

3. **Fc: Confounding Efficiency**

Measures how closely the realized number of trials per condition matches the prescribed probabilities (e.g., 50/50).
High Fc means the realized proportions match what was specified.

4. **Ff : Frequency Accuracy**

Measures whether the condition sequence is balanced across time and transitions (immediate and longer-range).
High Ff means the design reduces serial dependencies and avoids systematic transition biases.

During optimization, you can assign weights to these metrics to reflect what matters most for your experiment.

**See [link](./manuals/METRICS.md) for guidelines on interpreting metrics when optimising designs.**

---

## Modifications Documentation

See [link](./manuals/TECHNICAL_CHANGES.md) for a detailed summary of changes relative to the upstream Neurodesign package.

With these new parameters and changes in the package, it is simply a matter of defining the parameters required for the specific use case and the tool will perform the optimization.

**Note** that precedence for order follows as (if all provided):

- Fixed ordering
- Controlled ordering
- Random ordering

The same holds for conditional_ITI and stimuli_durations.

---

## Tutorials

Tutorial notebooks / scripts are under `tutorials/`.

```
tutorials
├── base_functions Contains tutorials of the different base package functions.
├── new_functions Contains tutorials on using the modifications.
├── tutorial_1_neurodesign_base_overview Base tutorial of the neurodesign package.
└── tutorial_2_comparing_designs_across_experiments Tutorial on comparing designs across diverse experiment definitions.
```

For quick access, find the tutorials in the table below:
| # | Tutorial | Link |
| :---: | :--- | :---: |
| 1 | **tutorial_1_neurodesign_base_overview** | [View](./tutorials/tutorial_1_neurodesign_base_overview.ipynb) |
| 2 | **tutorial_2_comparing_designs_across_experiments** | [View](./tutorials/tutorial_2_comparing_designs_across_experiments.ipynb) |
| 3 | **tutorial_base_compare_and_simulate** | [View](./tutorials/base_functions/tutorial_base_compare_and_simulate.ipynb) |
| 4 | **tutorial_base_comparing_designs** | [View](./tutorials/base_functions/tutorial_base_comparing_designs.ipynb) |
| 5 | **tutorial_base_discovering_best_design** | [View](./tutorials/base_functions/tutorial_base_discovering_best_design.ipynb) |
| 6 | **tutorial_base_optimizating_and_report** | [View](./tutorials/base_functions/tutorial_base_optimizating_and_report.ipynb) |
| 7 | **tutorial_new_controlled_probabalistic_ordering** | [View](./tutorials/new_functions/tutorial_new_controlled_probabalistic_ordering.ipynb) |
| 8 | **tutorial_new_fixed_order** | [View](./tutorials/new_functions/tutorial_new_fixed_order.ipynb) |
| 9 | **tutorial_new_varied_ITI** | [View](./tutorials/new_functions/tutorial_new_varied_ITI.ipynb) |
| 10 | **tutorial_new_varied_stimuli_durations** | [View](./tutorials/new_functions/tutorial_new_varied_stimuli_durations.ipynb) |

## Credits

This is a fork of the original **Neurodesign** package.
Expand Down
Loading