Skip to main content

Galactic filaments

License GitHub Release

LIS² (Large Image Split Segmentation):

A toolbox for large-scale, single-image semantic segmentation.

GitHub Actions Docs Coverage

Pipeline Coverage

Installation

LIS² can be installed from PyPI using pip (once the package is published).

We recommend using a virtual environment to avoid conflicts with other Python packages.

  python -m venv .venv
  source .venv/bin/activate

  python -m pip install --upgrade pip
  pip install "lis2[cpu]"

The cpu extra installs the CPU version of PyTorch and torchvision. For GPU-enabled installations, see the :ref:installation options <installation-options>.

### Installation options

LIS² provides the following installation options:

   # CPU installation
   pip install "lis2[cpu]"

   # CUDA 13.2 installation
   pip install "lis2[cu132]"

The CUDA installation requires a compatible NVIDIA GPU and driver.

Development installation

To contribute to LIS² or run the test suite, clone the repository:

   git clone https://github.com/multi-learn/lis2.git
   cd lis2

We recommend using uv <https://docs.astral.sh/uv/>_ to manage the development environment:

   uv sync --extra cpu --group dev

This installs the project, its CPU dependencies and the development tools.

Test your installation

Run the test suite with:

   uv run --no-sync pytest

To generate a coverage report:

   uv run --no-sync pytest --cov=lis2 --cov-report=term-missing --cov-report=html

The HTML coverage report is generated in htmlcov/index.html.

Standard Usage

  1. Data preprocessing. An example of configuration is proposed in configs/config_preprocess.yaml. Make sure to adapt it to your folder organization. Then run the following command.
python scripts/main_preprocessing.py -c /path/to/your_config.yaml
  1. Training pipeline. Two possibilities : you can use scripts/main_train.py for a standard training, and scripts/main_training_k_fold.py for a k-fold training. Make sure to use the example configuration configs/training.yaml or config_kfolds.yaml according to your use case, with the right paths.
python scripts/main_train.py -c .path/to/your_config.yaml
  1. Run segmentation.

Advanced usage

For details about the different steps

1. Data preprocessing

In this phase, the data representing the galactic plan, contained in the .fits file is transformed into an h5 file of patches. Each patch is of a defined patch_size. If a patch is tempty, it is discarded.

2. Training pipeline

The training pipeline is divided into two different use cases : standard and k-folds. The standard use case is a specific case of k-fold with k=1, so we won't give much details about it as it can be deducted from the k-folds.

Now, we develop each of the steps of the training pipeline :

1- Initialization.

During the init phase, the fold_controller is initialized, according to its configuration given in the configuration file. This controller loads the patches.h5 file, created during the previous phase. Then it generates the k-folds splits according to the configuration, i.e. if k=4 and k_train=2:

splits = [[[1, 2], [3], [4]], [[3, 4], [1], [2]]]

with two folds into the train set, and the rest separated into valid and test.

Then, the controller assigns each patch to an area, and this area to a fold according to different strategies. We do this area trick to ensure the continuity of the data because of some normalization necessities. The default strategy is called random, which corresponds to a round robin strategy. A naïve strategy can also be used, where the image is divided into k equal parts, and then each part is considered as a fold. The indices of how the area are distributed into the folds are stored, so they don't have to be computed at each run.

2- Training

For each split, the train, valid and test sets are loaded according to the fold assigments. The model to train is loaded according to the configuration, and then k different versions of this model are trained. Some results are saved in log files.

3. Run segmentation

Dev guide

For details about how to use the library for your own use case

Modular Architecture with Configurable and TypedConfigurable

LIS2 is based on a modular architecture thanks to the Configurable and TypedConfigurable base classes. These classes allow for flexible, extensible, and standardized configuration of components (models, datasets, optimizers, metrics, etc.).

1. Configurable : Dynamic Creation of ComponentsCréation Dynamique de Composants

Configurable is a base class that uses schemas to dynamically validate configurations. It allows:

  • Validation: Each parameter is validated by type and constraint before instantiation using the Schema class.
  • Flexibility: Load configurations from Python dictionaries or YAML files. Configurations are dynamic because the parameters depend on the type of object/class requested.

Example :

from configurable import Configurable, Schema


class MyComponent(Configurable):
  config_schema = {
    'learning_rate': Schema(float, default=0.01),
    'batch_size': Schema(int, default=32),
  }

  def __init__(self):


config = {'learning_rate': 0.001, 'batch_size': 64}
component = MyComponent.from_config(config)
print(component.learning_rate)  # 0.001
print(component.batch_size)  # 64

2. TypedConfigurable : Gestion Dynamique de Sous-Classes

TypedConfigurable extends Configurable by adding the ability to dynamically choose a subclass to instantiate based on a type parameter.

Example with Models :

from configurable import TypedConfigurable, Schema


class BaseModel(TypedConfigurable):
  aliases = ['base_model']


class CNNModel(BaseModel):
  aliases = ['cnn']
  config_schema = {
    'filters': Schema(int, default=32),
    'kernel_size': Schema(int, default=3),
  }

  def __init__(self):


config = {'type': 'cnn', 'filters': 64, 'kernel_size': 5}
model = BaseModel.from_config(config)
print(model.filters)  # 64
print(model.kernel_size)  # 5

How Schemas Work

Concept of the Class Schema

Schema defines the expected structure for each configuration parameter. It plays a central role in validating and applying default values ​​when instantiating objects.

Main Schema Attributes:

  • type: Specifies the expected type (e.g., int, float, str).
  • default: Defines a default value if the parameter is not provided.
  • optional: Indicates whether the parameter is optional.
  • aliases: Allows you to use alternative names for the same parameter.

Schema defines the expected structure for each configuration parameter. It plays a central role in validating and applying default values when instantiating objects.

Adding a Component in Practice

Configurable

Define the class: Inherit from the appropriate base class (e.g., BaseModel, Metric, BaseDataset, etc.) or directly from Configurable and implement the necessary logic.

class NewComponent(Configurable):
  config_schema = {
    'param1': Schema(str),
    'param2': Schema(int, default=10),
  }

  def __init__(self):
    print(self.param1)
    print(self.param2)

Add in YAML configuration: Reference the new component with its parameters.

component:
  param1: "example"

Use in pipeline: Dynamically load and integrate the component via from_config.

import NewComponent

component = NewComponent.from_config(config['component'])

TypedConfigurable

Define subclasses: Create subclasses for each component type.

class NewComponent(Configurable):
  config_schema = {
    'param1': Schema(str, default="default"),
    'param2': Schema(int, default=10),
  }

  def __init__(self):
    print(self.param1)  # default
    print(self.param2)  # 10


class NewComponentNeg(Configurable):
  config_schema = {
    'param1': Schema(str, default="Neg"),
    'param2': Schema(int, default=-10),
  }

  def __init__(self):
    print(self.param1)  # Neg
    print(self.param2)  # -10
component:
  type: NewComponentNeg
  param1: "example"
import Configurable

component = Configurable.from_config(config['component'])

# Output
# example
# -10

Additional components can be added using the same process, as long as they inherit from Configurable. In addition, for some classes, such as models, base classes are already defined to facilitate the addition of new components:

  • BaseModel: Base class for models ( models/base_model.py).
  • BaseDataset: Base class for datasets ( datasets/dataset.py).
  • BaseOptimizer: Base class for optimizers ( core/optim.py).
  • BaseScheduler: Base class for schedulers ( core/scheduler.py).
  • Metric: Base class for metrics ( core/metrics.py).
  • Encoder: Base class for encoders ( models/encoders/encoder.py).
  • EarlyStopping: Base class for early stopping ( core/early_stopping.py).

Tests and Validation

Unit Tests

Unit tests are included in theClasse de base pour les modèles ( models/base_model.py).

  • BaseDataset: Base class for datasets ( datasets/dataset.py).
  • BaseOptimizer: Base class for optimizers ( core/optim.py).
  • BaseScheduler: Base class for schedulers ( core/scheduler.py).
  • Metric: Base class for metrics ( core/metrics.py).
  • Encoder: Base class for encoders ( models/encoders/encoder.py).
  • EarlyStopping: Base class for early stopping ( core/early_stopping.py).

Tests and Validation

Unit Tests

Unit tests are included in the PyTorch class ( datasets/dataset.py).

  • BaseOptimizer: Class for optimizers ( core/optim.py).
  • BaseScheduler: Class for schedulers ( core/scheduler.py).
  • Metric: Class for metrics ( core/metrics.py).
  • Encoder: Class for encoders ( models/encoders/encoder.py).
  • EarlyStopping: Class for early stopping ( core/early_stopping.py).

Tests and Validation

Units Tests

Unit tests are included in the package to ensure the components function properly. To run the tests, use the tests folder.

Trainer

The LIS² package provides a ready-to-use Trainer to orchestrate model training, validation, and testing. The Trainer dynamically integrates with all the components configured in a YAML file.

Example of Configuration YAML file

trainer:
  output_dir: ./results
  run_name: experiment_1
  model:
    type: unet
    in_channels: 1
    out_channels: 1
  optimizer:
    type: adam
    lr: 0.001
  epochs: 50
  batch_size: 16
  metrics:
    - type: dice

Outputs

  • Results: Metrics and losses are saved in the directory defined by output_dir.
  • Snapshots: Snapshot files contain:
  • The model state (MODEL_STATE).
  • The state of optimizers and schedulers.
  • The global configuration (GLOBAL_CONFIG).

Resuming from a Snapshot

Resuming from a Snapshot:

from core.trainer import Trainer

trainer = Trainer.from_snapshot("./results/experiment_1/best.pt")
trainer.train()

Metadata

Release files for lis2 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lis2 1.1.0
File Size Uploaded Provenance Actions
lis2-1.1.0.tar.gz 82.1 kB With provenance Details for lis2-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lis2 1.1.0
File Interpreter ABI Platform Actions
lis2-1.1.0-py3-none-any.whl Python 3 none any Details for lis2-1.1.0-py3-none-any.whl

Total release size: 189.3 kB

Release files / lis2-1.1.0.tar.gz

Download URL lis2-1.1.0.tar.gz
Size 82.1 kB
Tags Source
SHA-256 checksum
How to use checksums
72fedd8bfd2ff647afd6a9ee1cc48ae1e4187910d8e88cd66fe27fc095e8d276
BLAKE2b-256 checksum
How to use checksums
01cea83f20e9fc0fd8a2a87513f5c6be4869db520c64523a14437673619b615e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / lis2-1.1.0-py3-none-any.whl

Download URL lis2-1.1.0-py3-none-any.whl
Size 107.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9a6ccf28111e219b58d728a492f6a4f00b25724a631097ea40b22a98b52c3727
BLAKE2b-256 checksum
How to use checksums
4b5060e4a9b68a0433257a6e7b103280f59e6733fcaecb5950e6b2c0012fd692
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for lis2 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lis2-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page