<commit_before># Plugin examples

In this section, we give many examples of plugins.

## Getting started

### How to upgrade plugins from phy 1.0

Here are some things to know if you want to upgrade plugins to the latest v2.0 version of phy.

1. The event system has changed slightly. Replace:

```python
# DON'T USE. This was for phy 1.x, it does not work in phy 2.x
@myobject.connect
def on_event(arg):
    pass
```

by

```python
# USE THIS in phy 2.x.
from phy import connect

# 1. You can filter the events by sender. Here, this function is only called when the event
# is sent by `myobject`. If you don't add the `sender=` option, the function will be called
# for all events of that type sent by any object.
@connect(sender=myobject)
def on_eventname(sender, arg):
    # 2. The first positional parameter is always `sender` in event callbacks. It is mandatory.
    pass
```

2. Some controller methods have been renamed. See the [API documentation](api.md) for more details.

3. Make sure the deprecated package `phycontrib` is not loaded anywhere in your plugins, which could lead to conflicts. You should even make sure it is not installed in your phy2 environment.

4. Look at the plugin examples. They are good starting points to port your plugins. For example, there are example plugins for changing the number of spikes in the views, implementing custom recluster actions, adding custom matplotlib views, using custom cluster metrics and statistics, etc.


### How to use a plugin

1. Create a Python file in `~/.phy/plugins/` and copy-paste the code from [a plugin example on the GitHub repository](https://github.com/cortex-lab/phy/tree/master/plugins)
2. Edit `~/.phy/phy_config.py`, and specify the plugin names to load in the GUI:

```python
c.TemplateGUI.plugins = ['ExampleClusterStatsPlugin']  # list of plugin names to load in the TemplateGUI
```


## Hello world

Here is how to write a simple plugin that displays a message every time there's a new cluster assignment:

```python
# import from plugins/hello.py
"""Hello world plugin."""

from phy import IPlugin, connect


class ExampleHelloPlugin(IPlugin):<commit_msg>Update plugin documentation<commit_after># Plugin examples

In this section, we give many examples of plugins.

## Getting started

### How to use a plugin

1. Create a `myplugins.py` file in `~/.phy/plugins/` and copy-paste the code from [a plugin example on the GitHub repository](https://github.com/cortex-lab/phy/tree/master/plugins)
2. Edit `~/.phy/phy_config.py`, and specify the plugin names to load in the GUI:

```python
c.TemplateGUI.plugins = ['ExampleClusterStatsPlugin']  # list of plugin names to load in the TemplateGUI
```

The exact name of `myplugins.py` doesn't matter, since all Python scripts found in the plugin directories are automatically loaded by phy.

**Note**: there are three different concepts:

1. **Plugin directories**: the `~/.phy/phy_config.py` file contains a line like `c.Plugins.dirs = [r'~/.phy/plugins']` which is a list of directories that contain one or more **plugin files**.
2. **Plugin files**: a plugin file is any Python script that is found in the plugin directories. It contains one or more definitions of **plugin classes**.
3. **Plugin classes**: it is a Python class deriving from `IPlugin` which implements the logic of a plugin.

The `~/.phy/phy_config` file defines (1) the paths to the plugin directories (`c.Plugins.dirs`), and (2) the list of all plugin class names that needs to be loaded, and that are implemented in plugin files found in the plugin directories (`c.TemplateGUI.plugins`).

The idea is that one could *install* many plugins by putting the code in a plugin directory, but may not want to *activate* all of them every time.


### How to upgrade plugins from phy 1.0

Here are some things to know if you want to upgrade plugins to the latest v2.0 version of phy.

1. The event system has changed slightly. Replace:

```python
# DON'T USE. This was for phy 1.x, it does not work in phy 2.x
@myobject.connect
def on_event(arg):
    pass
```

by

```python
# USE THIS in phy 2.x.
from phy import connect

# 1. You can filter the events by sender. Here, this function is only called when the event
# is sent by `myobject`. If you don't add the `sender=` option, the function will be called
# for all events of that type sent by any object.
@connect(sender=myobject)
def on_eventname(sender, arg):
    # 2. The first positional parameter is always `sender` in event callbacks. It is mandatory.
    pass
```

2. Some controller methods have been renamed. See the [API documentation](api.md) for more details.

3. Make sure the deprecated package `phycontrib` is not loaded anywhere in your plugins, which could lead to conflicts. You should even make sure it is not installed in your phy2 environment.

4. Look at the plugin examples. They are good starting points to port your plugins. For example, there are example plugins for changing the number of spikes in the views, implementing custom recluster actions, adding custom matplotlib views, using custom cluster metrics and statistics, etc.


## Hello world

Here is how to write a simple plugin that displays a message every time there's a new cluster assignment:

```python
# import from plugins/hello.py
"""Hello world plugin."""

from phy import IPlugin, connect


class ExampleHelloPlugin(IPlugin):
{'fraction_non_alphanumeric': 0.0801043219076006, 'fraction_numerical': 0.006892697466467959, 'mean_word_length': 4.152591170825336, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4901532', 'n_tokens_mistral': 1494, 'n_tokens_neox': 1411, 'n_words': 794}