docs: New docs added (#76)

Co-authored-by: Tymoteusz Kwieciński <[email protected]>

.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

.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 ➡️

README.md

@@ -1,12 +1,72 @@
-# meteors <img src="assets/logo.png" align="right" width="150"/>
+# ☄️🛰️ Meteors <img src="assets/logo.png" align="right" width="150"/>
 
-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 <python version between '3.9' and '3.12'>
-rye sync
+curl -sSf https://rye.astral.sh/get | bash # Install Rye
+rye pin <python version >=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)

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

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 <python_version> && 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! 🎉🚀

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.