Skip to content

Commit

Permalink
Merge branch 'master' into torch_interp
Browse files Browse the repository at this point in the history
  • Loading branch information
@carsen-stringer
carsen-stringer committed Dec 20, 2020
2 parents 272cd12 + 981effb commit 7a1baa7
Show file tree
Hide file tree
Showing 9 changed files with 126 additions and 128 deletions.
47 changes: 25 additions & 22 deletions README.md
View file
Expand Up @@ -15,7 +15,7 @@

A generalist algorithm for cell and nucleus segmentation.

This code was written by Carsen Stringer and Marius Pachitariu. To learn about Cellpose, read the [paper](https://t.co/4HFsxDezAP?amp=1) or watch the [talk](https://t.co/JChCsTD0SK?amp=1). For support, please open an [issue](https://github.com/MouseLand/cellpose/issues).
This code was written by Carsen Stringer and Marius Pachitariu. To learn about Cellpose, read the [paper](https://t.co/kBMXmPp3Yn?amp=1) or watch the [talk](https://t.co/JChCsTD0SK?amp=1). For support, please open an [issue](https://github.com/MouseLand/cellpose/issues).

If you want to improve Cellpose for yourself and for everyone else, please consider contributing manual segmentations for a few of your images via the built-in GUI interface (see instructions below).

Expand Down Expand Up @@ -45,25 +45,12 @@ Linux, Windows and Mac OS are supported for running the code. For running the gr

This process should take less than 5 minutes.

### (Option 1) Standard install in base environment

1. Install an [Anaconda](https://www.anaconda.com/download/) distribution of Python -- Choose **Python 3.7** and your operating system. Note you might need to use an anaconda prompt if you did not add anaconda to the path.
2. From your base environment in an anaconda prompt/command prompt, run
~~~~
pip install cellpose[gui]
~~~~

If you want to install without the GUI dependencies, run `pip install cellpose`.

### (Option 2) Install in a new environment

Alternatively you can use the included environment file (if you'd like a cellpose-specific environment). This environment file includes all the dependencies for using the GUI. Using the environment file is **recommended** if you have problems with *option 1*. Please follow these instructions:

1. Download the [`environment.yml`](https://github.com/MouseLand/cellpose/blob/master/environment.yml?raw=true) file from the repository. You can do this by cloning the repository, or copy-pasting the text from the file into a text document on your local computer.
2. Open an anaconda prompt / command prompt with `conda` for **python 3** in the path
3. Change directories to where the `environment.yml` is and run `conda env create -f environment.yml`
4. To activate this new environment, run `conda activate cellpose`
5. You should see `(cellpose)` on the left side of the terminal line. Now run `python -m cellpose` and you're all set.
2. Download the [`environment.yml`](https://github.com/MouseLand/cellpose/blob/master/environment.yml?raw=true) file from the repository. You can do this by cloning the repository, or copy-pasting the text from the file into a text document on your local computer.
3. Open an anaconda prompt / command prompt with `conda` for **python 3** in the path
4. Change directories to where the `environment.yml` is and run `conda env create -f environment.yml`
5. To activate this new environment, run `conda activate cellpose`
6. You should see `(cellpose)` on the left side of the terminal line. Now run `python -m cellpose` and you're all set.

To upgrade cellpose (package [here](https://pypi.org/project/cellpose/)), run the following in the environment:
~~~~
Expand All @@ -74,19 +61,35 @@ If you have an older `cellpose` environment you can remove it with `conda env re

Note you will always have to run **conda activate cellpose** before you run cellpose. If you want to run jupyter notebooks in this environment, then also `conda install jupyter` and `pip install matplotlib`.

If you're feeling adventurous you can also try to install cellpose from your base environment using the command
~~~~
pip install cellpose[gui]
~~~~

If you have **issues** with installation, see the [docs](https://cellpose.readthedocs.io/en/latest/installation.html) for more details, and then if the suggestions fail, open an issue.

### CUDA version
### GPU version (CUDA)

If you plan on running many images, you may want to install a GPU version of *mxnet*. We recommend using CUDA 10.0 or greater.

**ON WINDOWS**

Just install the GPU version of mxnet directly in the environment, i.e.:

~~~
pip install mxnet-cu101
~~~

If you plan on running many images, you may want to install a GPU version of *mxnet*. I recommend using CUDA 10.0 or greater. Follow the instructions [here](https://mxnet.apache.org/get_started?).
**ON LINUX**

Before installing the GPU version, remove the CPU version:
~~~
pip uninstall mxnet-mkl
pip uninstall mxnet
pip install mxnet-cu101
~~~

When upgrading cellpose, you will want to ignore dependencies (so that mxnet-mkl does not install):
Follow the instructions [here](https://mxnet.apache.org/get_started?) to determine what version to install to match your CUDA install. When upgrading GPU Cellpose in the future, you will want to ignore dependencies (so that mxnet-mkl does not install):
~~~
pip install --no-deps cellpose --upgrade
~~~
Expand Down
3 changes: 3 additions & 0 deletions cellpose/io.py
View file
Expand Up @@ -77,6 +77,9 @@ def get_image_files(folder, mask_filter, imf=None):
if igood:
imn.append(im)
image_names = imn

if len(image_names)==0:
raise ValueError('ERROR: no images in --dir folder')

return image_names

Expand Down
5 changes: 1 addition & 4 deletions cellpose/models.py
View file
Expand Up @@ -304,7 +304,6 @@ class CellposeModel(UnetModel):
net_avg: bool (optional, default True)
loads the 4 built-in networks and averages them if True, loads one network if False
diam_mean: float (optional, default 27.)
mean 'diameter', 27. is built in value for 'cyto' model
Expand Down Expand Up @@ -624,11 +623,8 @@ def train(self, train_data, train_labels, train_files=None,
if True it assumes you will fit a size model after training or resize your images accordingly,
if False it will try to train the model to be scale-invariant (works worse)
"""

nimg = len(train_data)

train_data, train_labels, test_data, test_labels, run_test = transforms.reshape_train_test(train_data, train_labels,
test_data, test_labels,
channels, normalize)
Expand All @@ -644,6 +640,7 @@ def train(self, train_data, train_labels, train_files=None,
test_data, test_flows,
pretrained_model, save_path, save_every,
learning_rate, n_epochs, momentum, weight_decay, batch_size, rescale)
self.pretrained_model = model_path
return model_path

class SizeModel():
Expand Down
4 changes: 4 additions & 0 deletions docs/command.rst
View file
Expand Up @@ -69,6 +69,10 @@ estimated:

python -m cellpose --dir ~/images_nuclei/test/ --pretrained_model nuclei --diameter 0. --save_png

.. warning::
The path given to ``--dir`` must be an absolute path.


Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
3 changes: 3 additions & 0 deletions docs/inputs.rst
View file
Expand Up @@ -34,3 +34,6 @@ You can give a list of 3D inputs, or a single 3D/4D stack.
When running on the command line, add the flag ``--do_3D`` (it will run all tiffs
in the folder as 3D tiffs).

If the 3D segmentation is not working well and there is inhomogeneity in Z, try stitching
masks in Z instead of running ``do_3D=True``. See details for this option here:
`stitch_threshold <settings.html#d-settings>`__.
82 changes: 2 additions & 80 deletions docs/installation.rst
View file
@@ -1,57 +1,7 @@
Installation
------------------------------

We recommend installing an `Anaconda`_ distribution of Python -- Choose
**Python 3.7** and your operating system. Note you might need to use an
anaconda prompt if you did not add anaconda to the path. From your base
environment (or you can make a new environment) in an anaconda
prompt/command prompt, run

::

pip install cellpose[gui]

If you want to install without the GUI dependencies, run ``pip install cellpose``.

.. note::
The first time you run cellpose it downloads the latest available trained
model weights from the cellpose website. These models are saved in your home
directory in a .cellpose folder, not in the code package.

With an environment file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Alternatively you can use the included environment file (if you'd like a
cellpose-specific environment). This environment file includes all the
dependencies for using the GUI. Using the environment file is
**recommended** if you have problems with the pip.
Please follow these instructions:

1. Download the `environment.yml`_ file from the repository. You can
do this by cloning the repository, or copy-pasting the text from the
file into a text document on your local computer.
2. Open an anaconda prompt / command prompt with ``conda`` for **python
3** in the path
3. Change directories to where the ``environment.yml`` is and run
``conda env create -f environment.yml``
4. To activate this new environment, run ``conda activate cellpose``
5. You should see ``(cellpose)`` on the left side of the terminal line.
Now run ``python -m cellpose`` and you're all set.

To upgrade cellpose (package `here`_), run the following in the
environment:

::

pip install cellpose --upgrade

If you have an older ``cellpose`` environment you can remove it with
``conda env remove -n cellpose`` before creating a new one.

.. note::
Now you will always have to run **conda activate cellpose** before you
run cellpose. If you want to run jupyter notebooks in this environment,
then also ``conda install jupyter``.
For basic install instructions, look up the main github readme.

Common issues
~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -100,34 +50,6 @@ OS are fine. The software has been heavily tested on Windows 10 and
Ubuntu 18.04, and less well tested on Mac OS. Please post an issue if
you have installation problems.

CUDA version
~~~~~~~~~~~~~~~~~~~~~~

If you plan on running many images, you may want to install a GPU
version of *mxnet*. I recommend using CUDA 10.0 or greater. Follow the
instructions `here <https://mxnet.apache.org/get_started?>`__.

Before installing the GPU version, remove the CPU version:

::

pip uninstall mxnet-mkl
pip uninstall mxnet

When upgrading cellpose, you will want to ignore dependencies (so that
mxnet-mkl does not install):

::

pip install --no-deps cellpose --upgrade

**Installation of github version**

Follow steps from above to install the dependencies. In the github
repository, run ``pip install -e .`` and the github version will be
installed. If you want to go back to the pip version of cellpose, then
say ``pip install cellpose``.


Dependencies
~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -157,4 +79,4 @@ automatically installed with conda/pip if missing):
.. _scipy: https://www.scipy.org/
.. _scikit-image: https://scikit-image.org/
.. _natsort: https://natsort.readthedocs.io/en/master/
.. _matplotlib: https://matplotlib.org/
.. _matplotlib: https://matplotlib.org/
77 changes: 59 additions & 18 deletions docs/settings.rst
View file
Expand Up @@ -21,6 +21,33 @@ running a list of images for reference:
You can make lists of channels/diameter for each image, or set the same channels/diameter for all images
as shown in the example above.

Channels
~~~~~~~~~~~~~~~~~~~~~~~~

Cytoplasm model (`'cyto'`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The cytoplasm model in cellpose is trained on two-channel images, where
the first channel is the channel to segment, and the second channel is
an optional nuclear channel. Here are the options for each:
1. 0=grayscale, 1=red, 2=green, 3=blue
2. 0=None (will set to zero), 1=red, 2=green, 3=blue

Set channels to a list with each of these elements, e.g.
``channels = [0,0]`` if you want to segment cells in grayscale or for single channel images, or
``channels = [2,3]`` if you green cells with blue nuclei.

Nucleus model (`'nuclei'`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The nuclear model in cellpose is trained on two-channel images, where
the first channel is the channel to segment, and the second channel is
always set to an array of zeros. Therefore set the first channel as
0=grayscale, 1=red, 2=green, 3=blue; and set the second channel to zero, e.g.
``channels = [0,0]`` if you want to segment nuclei in grayscale or for single channel images, or
``channels = [3,0]`` if you want to segment blue nuclei.


Diameter
~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -46,24 +73,18 @@ outputs. When the diameter is set smaller than the true size
then cellpose may over-split cells. Similarly, if the diameter
is set too big then cellpose may over-merge cells.

Channels
Resample
~~~~~~~~~~~~~~~~~~~~~~~~

Cytoplasm model (`'cyto'`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The cytoplasm model in cellpose is trained on two-channel images, where
the first channel is the channel to segment, and the second channel is
an optional nuclear channel. Here are the options for each:
1. 0=grayscale, 1=red, 2=green, 3=blue
2. 0=None (will set to zero), 1=red, 2=green, 3=blue

Set channels to a list with each of these elements, e.g.
``channels = [0,0]`` if you want to segment cells in grayscale or for single channel images, or
``channels = [2,3]`` if you green cells with blue nuclei.

Nucleus model (`'nuclei'`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The cellpose network is run on your rescaled image -- where the rescaling factor is determined
by the diameter you input (or determined automatically as above). For instance, if you have
an image with 60 pixel diameter cells, the rescaling factor is 30./60. = 0.5. After determining
the flows (dX, dY, cellprob), the model runs the dynamics. The dynamics can be run at the rescaled
size (``resample=False``), or the dynamics can be run on the resampled, interpolated flows
at the true image size (``resample=True``). ``resample=True`` will create smoother masks when the
cells are large but will be slower in case; ``resample=False`` will find more masks when the cells
are small but will be slower in this case. By default in v0.5 ``resample=False``, but in
previous releases the default was ``resample=True``.

The nuclear model in cellpose is trained on two-channel images, where
the first channel is the channel to segment, and the second channel is
Expand All @@ -74,8 +95,8 @@ always set to an array of zeros. Therefore set the first channel as

If the nuclear model isn't working well, try the cytoplasmic model.

Flow threshold
~~~~~~~~~~~~~~~~~~~~~~
Flow threshold (aka model fit threshold in GUI)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Note there is nothing keeping the neural network from predicting
horizontal and vertical flows that do not correspond to any real
Expand Down Expand Up @@ -106,3 +127,23 @@ is ``cellprob_threshold=0.0``. Decrease this threshold if cellpose is not return
as many masks as you'd expect. Similarly, increase this threshold if cellpose is
returning too masks particularly from dim areas.

3D settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Volumetric stacks do not always have the same sampling in XY as they do in Z.
Therefore you can set an ``anisotropy`` parameter to allow for differences in
sampling, e.g. set to 2.0 if Z is sampled half as dense as X or Y.

There may be additional differences in YZ and XZ slices
that make them unable to be used for 3D segmentation.
I'd recommend viewing the volume in those dimensions if
the segmentation is failing. In those instances, you may want to turn off
3D segmentation (``do_3D=False``) and run instead with ``stitch_threshold>0``.
Cellpose will create masks in 2D on each XY slice and then stitch them across
slices if the IoU between the mask on the current slice and the next slice is
greater than or equal to the ``stitch_threshold``.





22 changes: 18 additions & 4 deletions docs/train.rst
View file
Expand Up @@ -7,7 +7,13 @@ mask image (``dynamics.labels_to_flows``).
The cellpose pretrained models are trained using resized images so that the cells have the same median diameter across all images.
If you choose to use a pretrained model, then this fixed median diameter is used.

If you choose to train from scratch, you can set the median diameter you want to use for rescaling with the ``--diameter`` flag, or set it to 0 to disable rescaling.
If you choose to train from scratch, you can set the median diameter you want to use for rescaling with the ``--diameter`` flag, or set it to 0 to disable rescaling.
We trained the `cyto` model with a diameter of 30 pixels and the `nuclei` model with a diameter of 17 pixels.

When you rescale everything to 30. pixel diameter, if you have images with varying diameters
you may also want to learn a `SizeModel` that predicts the diameter from the styles that the
network outputs. Add the flag ``--train_size`` and this model will be trained and saved as an
``*.npy`` file.

The same channel settings apply for training models (see all Command line `options
<http://www.cellpose.org/static/docs/command.html>`_).
Expand All @@ -19,14 +25,15 @@ Note Cellpose expects the labelled masks (0=no mask, 1,2...=masks) in a separate
wells_000.tif
wells_000_masks.tif

If you use the --img_filter option (`--img_filter img` in this case):
If you use the --img_filter option (``--img_filter img`` in this case):

::

wells_000_img.tif
wells_000_masks.tif

/!\ The path given to `--dir` and `--test` must be absolute path.
.. warning::
The path given to ``--dir`` and ``--test_dir`` must be an absolute path.

Training-specific options

Expand All @@ -47,7 +54,14 @@ You can train from scratch as well:

python -m cellpose --train --dir ~/images_nuclei/train/ --pretrained_model None

You can specify the full path to a pretrained model to use:
To train the cyto model from scratch using the same parameters we did, download the dataset and run

::

python -m cellpose --train --train_size --use_gpu --dir ~/cellpose_dataset/train/ --test_dir ~/cellpose_dataset/test/ --img_filter _img --pretrained_model None --chan 2 --chan2 1


You can also specify the full path to a pretrained model to use:

::

Expand Down

0 comments on commit 7a1baa7

Please sign in to comment.