From e6e9094c7ec01d4974dcf69e712f58f160234f51 Mon Sep 17 00:00:00 2001 From: Vladimir Zaigrajew <41760848+WolodjaZ@users.noreply.github.com> Date: Wed, 18 Sep 2024 19:37:39 +0200 Subject: [PATCH] docs: New docs added (#76) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tymoteusz Kwieciล„ski <31191783+Fersoil@users.noreply.github.com> --- .github/CODE_OF_CONDUCT.md | 76 ++++++++++++++++++++++++++++++++++ .github/workflows/docs.yml | 22 ++++++---- README.md | 72 +++++++++++++++++++++++++++++--- changelog.md | 16 ++++--- docs/how-to-guides.md | 53 +++++++++++++++++++++++- docs/quickstart.md | 68 +++++++++++++++++++++++++++++- docs/reference.md | 71 +++++++++++++++++++++++-------- docs/tutorials/introduction.md | 30 ++++++++++++++ examples/{ => lime}/lime.ipynb | 0 mkdocs.yml | 14 ++++--- pyproject.toml | 3 +- src/meteors/hsi.py | 10 +++++ src/meteors/lime.py | 8 ++-- 13 files changed, 388 insertions(+), 55 deletions(-) create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 docs/tutorials/introduction.md rename examples/{ => lime}/lime.ipynb (100%) diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..4cdee72 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applies when +an individual is representing the project or its community in public spaces. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or acting +as an appointed representative at an online or offline event. Representation of +a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project lead contributors. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 88a4124..8acd1b1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -47,17 +47,23 @@ jobs: - name: Convert Jupyter examples to Markdown ๐Ÿ““โžก๏ธ๐Ÿ“„ run: | - mkdir -p docs/tutorials + output_dir="docs/tutorials/" if [ -d "examples" ]; then - if ls examples/*.ipynb 1> /dev/null 2>&1; then - for notebook in examples/*.ipynb; do - rye run jupyter nbconvert --to markdown "$notebook" --output-dir docs/tutorials - done - else - echo "No notebooks to convert." - fi + for dir in examples/*/; do + if [ -d "$dir" ]; then + dir_name=$(basename "$dir") + if ls "$dir"/*.ipynb 1> /dev/null 2>&1; then + for notebook in "$dir"/*.ipynb; do + rye run jupyter nbconvert --to markdown "$notebook" --output-dir "$output_dir" --output "$dir_name" + done + else + echo "No notebooks found in directory '$dir_name'." + fi + fi + done else echo "Directory 'examples' does not exist." + exit 1 fi - name: Move Assets to Docs โžก๏ธ diff --git a/README.md b/README.md index a06ebd4..04c0b05 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,72 @@ -# meteors +# โ˜„๏ธ๐Ÿ›ฐ๏ธ Meteors -draft of the package for creating explanations of hyperspectral and multispectral images +[![PyPI](https://img.shields.io/pypi/v/meteors.svg)](https://github.com/xai4space/meteors/blob/main/LICENSE) +[![PyPI - License](https://img.shields.io/pypi/l/meteors?style=flat-square)](https://opensource.org/licenses/MIT) +[![PyPI - Downloads](https://img.shields.io/pypi/dm/meteors?style=flat-square)](https://pypistats.org/packages/meteors) +[![GitHub star chart](https://img.shields.io/github/stars/xai4space/meteors?style=flat-square)](https://star-history.com/#xai4space/meteors) +[![Open Issues](https://img.shields.io/github/issues-raw/xai4space/meteors?style=flat-square)](https://github.com/xai4space/meteors/issues) +[![Docs - GitHub.io](https://img.shields.io/static/v1?logo=meteors&style=flat&color=pink&label=docs&message=meteors)](https://xai4space.github.io/meteors/latest) -Documentation: [https://xai4space.github.io/meteors/latest/](https://xai4space.github.io/meteors/latest/) +## ๐Ÿ›ฐ๏ธ Introduction -## How to Run +Meteors is an open-source package for creating explanations of hyperspectral and multispectral images. Developed primarily for [Pytorch](https://pytorch.org) models, Meteors was inspired by the [Captum](https://captum.ai/) library. Our goal is to provide not only the ability to create explanations for hyperspectral images but also to visualize them in a user-friendly way. + +_Please note that this package is still in the development phase, and we welcome any feedback and suggestions to help improve the library._ + +Meteors emerged from a research grant project between the Warsaw University of Technology research group [MI2.ai](https://www.mi2.ai/index.html) and [Kp Labs](https://kplabs.space), financially supported by the [European Space Agency (ESA)](https://www.esa.int). + +## ๐ŸŽฏ Target Audience + +Meteors is designed for: + +- Researchers, data scientists, and developers who work with hyperspectral and multispectral images and want to understand the decisions made by their models. +- Engineers who build models for production and want to troubleshoot through improved model interpretability. +- Developers seeking to deliver better explanations to end users on why they're seeing specific content. + +## ๐Ÿ“ฆ Installation + +**Requirements** + +- Python >= 3.9 +- PyTorch >= 1.10 +- Captum >= 0.7.0 + +Install with `pip`: + +```bash +pip install meteors +``` + +With conda: +_Coming soon_ + +## ๐Ÿ“š Documentation + +Please refer to the [documentation](https://xai4space.github.io/meteors/latest) for more information on how to use Meteors. + +## ๐Ÿค Contributing + +As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation. + +We use [rye](https://rye.astral.sh) as our project and package management tool. To start developing, follow these steps: ```bash -rye pin -rye sync +curl -sSf https://rye.astral.sh/get | bash # Install Rye +rye pin =3.9> # Pin the python version +rye sync # Sync the environment ``` + +Before pushing your changes, please run the tests and the linter: + +```bash +rye test +rye run pre-commit run --all-files +``` + +For more information on how to contribute, please refer to our [Contributing Guide](https://xai4space.github.io/meteors/latest/how-to-guides/). + +Thank you for considering contributing to Meteors! + +## ๐Ÿ’ซ Contributors + +[![Meteors contributors](https://contrib.rocks/image?repo=xai4space/meteors&max=100)](https://github.com/xai4space/meteors/graphs/contributors) diff --git a/changelog.md b/changelog.md index 0ebe30f..c9bfe64 100644 --- a/changelog.md +++ b/changelog.md @@ -1,17 +1,15 @@ # Changelog -## HyperXAI 0.0.1 - -- Prepared a simple draft of package along with some ideas and sample files for implementation of LIME for hyperspectral images. -- Segmentation mask for LIME using slic -- Spatial attributions using LIME - -## HyperXAI 0.0.2 +## meteors 0.0.2 (2024-08-11) +- No release - Refined package structure - simple modules for models and visualisation, installation using toml file - Spectral attributions using LIME - CUDA compatibility of LIME -## HyperXAI -> meteors 0.0.1 +## meteors 0.0.1 (2024-06-02) -- Renamed package to meteors +- No release +- Prepared a simple draft of package along with some ideas and sample files for implementation of LIME for hyperspectral images. +- Segmentation mask for LIME using slic +- Spatial attributions using LIME diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md index c004add..8439d00 100644 --- a/docs/how-to-guides.md +++ b/docs/how-to-guides.md @@ -1,3 +1,52 @@ -# How-to guide +# ๐Ÿค How to Contribute -TODO: Add a how-to guide here. +Thank you for your interest in contributing to Meteors! We welcome contributions from the community to help improve and expand the library. This guide will walk you through the process of contributing to the project. + +## ๐Ÿ“‹ Types of Contributions + +There are several ways you can contribute to Meteors: + +- ๐Ÿ› Reporting bugs +- ๐Ÿ’ก Suggesting new features or enhancements +- ๐Ÿ“– Improving documentation +- ๐Ÿ’ป Writing code (fixing bugs, implementing new features) +- ๐Ÿงช Adding or improving test cases +- ๐Ÿ“ฃ Spreading the word about Meteors + +## ๐ŸŒฟ Getting Started + +To start contributing to Meteors, follow these steps: + +1. ๐Ÿด Fork the Meteors repository on GitHub. +2. ๐Ÿ“ฅ Clone your forked repository to your local machine. +3. ๐Ÿ”€ Create a new branch for your contribution. +4. ๐Ÿ“ฆ Set rye `rye pin && rye sync`. +5. ๐Ÿ› ๏ธ Make your changes or additions. +6. โœ… Test your changes to ensure they work as expected `rye test`. +7. ๐Ÿงน Lint your code `rye run pre-commit run --all-files`. +8. ๐Ÿ“ Commit your changes with a clear and descriptive commit message. +9. ๐Ÿ“ค Push your changes to your forked repository. +10. ๐Ÿ”Œ Submit a pull request to the main Meteors repository. +11. ๐Ÿ“ Fill out the pull request template with the necessary information. + +## ๐Ÿ“ Code Guidelines + +When contributing code to Meteors, please follow these guidelines: + +- ๐Ÿ“š Document your code using docstrings and comments. +- โœ… Write unit tests for new features or bug fixes. +- ๐Ÿงน Ensure your code is clean, readable, and well-structured. +- ๐Ÿšจ Run the existing tests and make sure they pass before submitting a pull request. +- ๐Ÿ Run linter to clean the code. + +## ๐Ÿ“œ Code of Conduct + +Please note that by contributing to Meteors, you are expected to adhere to our [Code of Conduct](https://github.com/xai4space/meteors/blob/main/code_of_conduct.md). Be respectful, inclusive, and considerate in your interactions with others. + +## ๐Ÿ™Œ Recognition + +We appreciate all contributions to Meteors, and we make sure to recognize our contributors. Your name will be added to the list of contributors in the project's README file. + +If you have any questions or need further assistance, feel free to reach out to the maintainers or open an issue on the GitHub repository. + +Thank you for your contribution to Meteors! ๐ŸŽ‰๐Ÿš€ diff --git a/docs/quickstart.md b/docs/quickstart.md index b59fe15..904b353 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,3 +1,67 @@ -# Quickstart +# ๐Ÿš€ Quickstart -TODO: Add a quickstart guide here. +Welcome to the Quickstart Guide for Meteors! This guide will walk you through the basic steps to get started with using Meteors for explaining your hyperspectral and multispectral image models. + +## ๐Ÿ“‹ Prerequisites + +Before you begin, make sure you have the following installed: + +- Python >= 3.9 +- PyTorch >= 1.10 +- Captum >= 0.7.0 + +## ๐Ÿ“ฅ Installation + +To install Meteors, simply run the following command: + +```bash +pip install meteors +``` + +For conda users, we will provide a conda installation method in the near future. We promise!๐Ÿคž + +## ๐ŸŒŸ Basic Hyperspectral or Multispectral Data Object + +Meteors provide an easy-to-use object for handling hyperspectral and multispectral images. The `HSI` object is a simple way to process and manipulate your data. + +```python +from meteors import HSI +``` + +**Remember**, when providing data to the model, make sure it is in the final format that the model expects, without the batch dimension. The `HSI` object will handle the rest. +We also recommend providing the image data channel orientation, height, width, and the number of channels in the format `(CHW)`. For example: + +- Number of channels: C +- Height: H +- Width: W + +## ๐Ÿ” Explanation Methods + +Meteors provides several explanation methods for hyperspectral and multispectral images, including: + +- **LIME**: [Local Interpretable Model-agnostic Explanations](https://christophm.github.io/interpretable-ml-book/lime.html) +- More methods coming soon! + +To use a specific explanation method in [tutorials](tutorials/introduction.md) we provide for each method, example code. + +## ๐ŸŽจ Visualization Options + +Meteors offers various visualization options to help you understand and interpret the explanations in package `meteors.visualize`. + +```python +from meteors.visualize import visualize_spectral_attributes, visualize_spatial_attributes +``` + +## ๐Ÿ“š Tutorials + +We have several tutorials to help get you off the ground with Meteors. The tutorials are Jupyter notebooks and cover the basics along with demonstrating usage of Meteors . + +View the tutorials page [here](tutorials/introduction.md). + +## ๐Ÿ“– API Reference + +For an in-depth reference of the various Meteors internals, see our [API Reference](reference.md). + +## ๐Ÿ™Œ Contributing + +We welcome contributions to Meteors! Please refer to our [Contributing Guide](how-to-guides.md) for more information on how to get involved. diff --git a/docs/reference.md b/docs/reference.md index dd493b9..a5bde79 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,23 +1,60 @@ # API Reference -Structure: - -- [API Reference](#api-reference) - - [Meteors](#meteors) - - [Lime](#lime) - - [Lime Base](#lime-base) - - [HyperSpectral Image](#hsi) - -## Meteors - -### Lime - -::: src.meteors.lime +::: src.meteors.hsi.HSI +options: +show_bases: false +show_root_heading: true +show_root_full_path: false + +## Visualizations + +::: src.meteors.visualize.lime_visualize +options: +heading_level: 3 +show_bases: false +show_root_heading: true +show_root_full_path: false +members: - "visualize_spectral_attributes_by_waveband" - "visualize_spectral_attributes_by_magnitude" - "visualize_spectral_attributes" - "visualize_spatial_attributes" + +## Methods + +### LIME + +::: src.meteors.lime.HSIAttributes +options: +heading_level: 4 +show_bases: false +show_root_heading: true +show_root_full_path: false + +::: src.meteors.lime.HSISpatialAttributes +options: +heading_level: 4 +show_bases: true +show_root_heading: true +show_root_full_path: false + +::: src.meteors.lime.HSISpectralAttributes +options: +heading_level: 4 +show_bases: true +show_root_heading: true +show_root_full_path: false + +::: src.meteors.lime.Explainer +options: +heading_level: 4 +show_bases: false +show_root_heading: true +show_root_full_path: false + +::: src.meteors.lime.Lime +options: +heading_level: 4 +show_bases: true +show_root_heading: true +show_root_full_path: false ### Lime Base The Lime Base class was adapted from the Captum Lime implementation. This adaptation builds upon the original work, extending and customizing it for specific use cases within this project. To see the original implementation, please refer to the [Captum repository](https://captum.ai/api/_modules/captum/attr/_core/lime.html#LimeBase). - -### HyperSpectral Image - -::: src.meteors.hsi diff --git a/docs/tutorials/introduction.md b/docs/tutorials/introduction.md new file mode 100644 index 0000000..ece9e5e --- /dev/null +++ b/docs/tutorials/introduction.md @@ -0,0 +1,30 @@ +# ๐ŸŽ“ Introduction to Tutorials + +Welcome to the Meteors tutorials! These tutorials are designed to help you get started with using Meteors for explaining and visualizing hyperspectral and multispectral images. Whether you're new to Meteors or have some experience, these tutorials will guide you through various features and techniques step by step. + +## ๐Ÿ“š Tutorial List + +1. [LIME](lime.md) + +- HYPERVIEW Challenge +- Local Interpretable Model-agnostic Explanations (LIME) for hyperspectral images +- Vision Transformer (ViT) model for hyperspectral image regression + +## ๐Ÿš€ Getting Started + +To get started with the tutorials, make sure you have Meteors installed and set up on your machine. If you haven't done so already, follow the installation instructions in the [Quickstart](../quickstart.md) tutorial. + +Each tutorial is self-contained and focuses on a specific topic or technique. You can follow the tutorials in order or jump to the ones that interest you the most. The tutorials provide step-by-step instructions, code examples, and explanations to help you understand and apply the concepts effectively. + +## ๐Ÿ’ก Tips and Tricks + +- Take your time and experiment with the code examples provided in the tutorials. +- Don't hesitate to modify the code and try different parameters to see how they affect the results. +- Refer to the [API Reference](../reference.md) for detailed information on the Meteors functions and classes used in the tutorials. +- If you encounter any issues or have questions, feel free to reach out to the Meteors community or open an issue on the GitHub repository. + +## ๐ŸŽ‰ Let's Get Started! + +Ready to dive into the world of hyperspectral image explanation with Meteors? Choose a tutorial from the list above and start your journey! + +Happy learning and exploring with Meteors! โ˜„๏ธ๐Ÿ”โœจ diff --git a/examples/lime.ipynb b/examples/lime/lime.ipynb similarity index 100% rename from examples/lime.ipynb rename to examples/lime/lime.ipynb diff --git a/mkdocs.yml b/mkdocs.yml index 166f6ad..bd72137 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,14 @@ site_name: Meteors nav: - - Home ๐Ÿ : index.md - - Quickstart ๐Ÿš€: quickstart.md - # - Tutorials ๐Ÿ“š: - - API Reference ๐Ÿ“–: reference.md - - Changelog ๐Ÿ“: changelog.md - - How-To Guides ๐Ÿ“š: how-to-guides.md + - ๐Ÿ  Home: index.md + - ๐Ÿš€ Quickstart: quickstart.md + - ๐Ÿ“š Tutorials: + - ๐ŸŽ“ Introduction: tutorials/introduction.md + - LIME: tutorials/lime.md + - ๐Ÿ“– API Reference: reference.md + - ๐Ÿ“ Changelog: changelog.md + - ๐Ÿค How to Contribute: how-to-guides.md plugins: - search diff --git a/pyproject.toml b/pyproject.toml index 3c73cfe..9b0c472 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -63,7 +63,8 @@ plugins = [ [tool.codespell] skip = [ - "src/examples/*", + "examples/*", + ".github/CODE_OF_CONDUCT.md", ] ignore-words-list = "hsi,HSI" diff --git a/src/meteors/hsi.py b/src/meteors/hsi.py index 707ea6b..e6ed66c 100644 --- a/src/meteors/hsi.py +++ b/src/meteors/hsi.py @@ -228,6 +228,16 @@ def process_and_validate_binary_mask( class HSI(BaseModel): + """A dataclass for hyperspectral image data, including the image, wavelengths, and binary mask. + + Attributes: + image (torch.Tensor): The hyperspectral image data as a PyTorch tensor. + wavelengths (torch.Tensor): The wavelengths present in the image. + orientation (tuple[str, str, str]): The orientation of the image data. + device (torch.device): The device to be used for inference. + binary_mask (torch.Tensor): A binary mask used to cover unimportant parts of the image. + """ + image: Annotated[ # Should always be a first field torch.Tensor, PlainValidator(ensure_image_tensor), diff --git a/src/meteors/lime.py b/src/meteors/lime.py index 8d24b44..1f7d539 100644 --- a/src/meteors/lime.py +++ b/src/meteors/lime.py @@ -1464,10 +1464,10 @@ def get_spatial_attributes( perturbations_per_eval (int, optional): The number of perturbations to evaluate at once (Simply the inner batch size). Defaults to 4. verbose (bool, optional): Whether to show the progress bar. Defaults to False. - postprocessing_segmentation_output (Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None): - A segmentation postprocessing function for segmentation problem type. This is required for segmentation problem type as - lime surrogate model needs to be optimized on the 1d output, and the model should be able to modify the model output with - inner lime active region mask as input and return the 1d output (for example number of pixel for each class) and not class mask. + postprocessing_segmentation_output (Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None): A + segmentation postprocessing function for segmentation problem type. This is required for segmentation problem type as + lime surrogate model needs to be optimized on the 1d output, and the model should be able to modify the model output with + inner lime active region mask as input and return the 1d output (for example number of pixel for each class) and not class mask. Defaults to None. segmentation_method (Literal["slic", "patch"], optional): Segmentation method used only if `segmentation_mask` is None. Defaults to "slic".