pathology-image-features 0.2.0__tar.gz

pathology_image_features-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+dist/*
+tmp/*
+build/*
+.pytest_cache/*
+update_instructions.md
+.vscode/*
+*.sqlite3
+*.sqlite3-journal
+*.pyc
+*.ttl
+./examples/*.csv
+./examples/*.owl
+examples/snakemake-example/.snakemake/
+examples/snakemake-example/example_area_workflow/.snakemake/
+examples/snakemake-example/example_area_workflow/.pixi/
+examples/snakemake-example/example_vis_workflow/.snakemake/

pathology_image_features-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

pathology_image_features-0.2.0/.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py

pathology_image_features-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 spborder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pathology_image_features-0.2.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: pathology-image-features
+Version: 0.2.0
+Summary: Package implementation of terms from the Pathology Image Features Ontology (PIFO).
+Author-email: Sam Border <sam.border2256@gmail.com>
+License: LICENSE
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: girder-client>=5.0.10
+Requires-Dist: graphviz>=0.21
+Requires-Dist: large-image-converter>=1.34.2
+Requires-Dist: lxml>=6.1.1
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: ontology-package-boilerplate>=0.1.0
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: pytest>=9.1.1
+Requires-Dist: rasterio>=1.4.4
+Requires-Dist: rdflib>=7.6.0
+Requires-Dist: scikit-image>=0.26.0
+Requires-Dist: shapely>=2.1.2
+Requires-Dist: sphinx-rtd-theme>=3.1.0
+Requires-Dist: sphinx>=9.0.4
+Requires-Dist: typing-extensions>=4.15.0
+Description-Content-Type: text/markdown
+
+# pathology-image-features
+Repository dedicated to defining a functional feature ontology for pathology data.
+
+## Installation
+`pathology-image-features` is deployed through PyPI and can be installed using:
+
+```bash
+$ pip install pathology-image-features
+```
+
+## Usage
+
+Example script defining an image feature/calculating/visualizing/etc.
+
+## Contributing
+
+Find some example contribution guidelines and reference that in a separate file
+
+## License
+
+`pathology-image-features` is licensed under the terms of the MIT License.
+
+## Citation
+If you find this project to be useful in your own research, please consider citing:
+
+```
+@article{
+    title={},
+    author={},
+    journal={},
+    volume={},
+    number={},
+    pages={},
+    year={},
+    publisher={}
+}
+```
+
+
+

pathology_image_features-0.2.0/README.md

@@ -0,0 +1,40 @@
+# pathology-image-features
+Repository dedicated to defining a functional feature ontology for pathology data.
+
+## Installation
+`pathology-image-features` is deployed through PyPI and can be installed using:
+
+```bash
+$ pip install pathology-image-features
+```
+
+## Usage
+
+Example script defining an image feature/calculating/visualizing/etc.
+
+## Contributing
+
+Find some example contribution guidelines and reference that in a separate file
+
+## License
+
+`pathology-image-features` is licensed under the terms of the MIT License.
+
+## Citation
+If you find this project to be useful in your own research, please consider citing:
+
+```
+@article{
+    title={},
+    author={},
+    journal={},
+    volume={},
+    number={},
+    pages={},
+    year={},
+    publisher={}
+}
+```
+
+
+

pathology_image_features-0.2.0/boilerplate/class_template.txt

@@ -0,0 +1,20 @@
+"""
+
+Class template provided by pathology-image-features.
+Extracted from: $ontology_file_path at $current_datetime
+
+"""
+
+$parent_imports
+
+from rdflib import URIRef, Literal
+from rdflib.namespace import RDF, OWL, RDFS
+
+
+class $name($base_class):
+    """
+    $definition
+    """
+    iri = URIRef("$iri")
+
+    $annotation_properties

pathology_image_features-0.2.0/boilerplate/create_package.py

@@ -0,0 +1,64 @@
+"""
+
+Creating package using ontology-package-boilerplate
+
+"""
+
+import os
+import sys
+
+from rdflib import URIRef
+
+sys.path.append("./src/")
+
+from ontology_package_boilerplate import create
+
+from pathology_image_features.ontology.classes import Thing
+from pathology_image_features.ontology.classes.information_content_entity import (
+    information_content_entity,
+)
+
+
+def update():
+    data_annotation = URIRef("http://purl.obolibrary.org/obo/PIFO_0000135")
+    template_path = "./boilerplate/class_template.txt"
+    create(
+        ontology_filepath="./src/pathology_image_features/ontology/pifo.owl",
+        destination_path="./src/pathology_image_features/ontology/classes/process/planned_process/completely_executed_planned_process/",
+        base_class_obj=Thing,
+        scope=[data_annotation],
+        class_template=template_path,
+        clean=False,
+        verbose=True,
+        ignore_empty_annotations=True,
+    )
+
+
+def main():
+    template_path = "./boilerplate/class_template.txt"
+    create(
+        ontology_filepath="./src/pathology_image_features/ontology/pifo.owl",
+        destination_path="./src/pathology_image_features/ontology/classes/",
+        base_class_obj=Thing,
+        scope=[],
+        class_template=template_path,
+        clean=True,
+        verbose=True,
+    )
+
+    process_uri = URIRef("http://purl.obolibrary.org/obo/BFO_0000015")
+    process_template_path = "./boilerplate/process_template.txt"
+    create(
+        ontology_filepath="./src/pathology_image_features/ontology/pifo.owl",
+        destination_path="./src/pathology_image_features/ontology/classes/",
+        base_class_obj=Thing,
+        scope=[process_uri],
+        class_template=process_template_path,
+        clean=True,
+        verbose=True,
+    )
+
+
+if __name__ == "__main__":
+    # main()
+    update()

pathology_image_features-0.2.0/boilerplate/process_template.txt

@@ -0,0 +1,36 @@
+"""
+
+Class template provided by pathology-image-features.
+Extracted from: $ontology_file_path at $current_datetime
+
+"""
+
+$parent_imports
+$property_imports
+
+from rdflib import URIRef, Literal
+from rdflib.namespace import RDF, OWL, RDFS
+
+from ontology import PIFO
+
+class $class_name($base_class):
+    """
+    $definition
+    """
+    iri = URIRef("$iri")
+
+    $annotation_properties
+
+    @staticmethod
+    def _pull(input_data_item):
+        """
+        This method extracts the relevant data type from a given subject and returns it.
+        """
+        return input_data_item
+
+    def _run(self, input):
+        """
+        This method runs the process on the given input.
+        """
+        input = self._pull(input)
+        return input

pathology_image_features-0.2.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pathology_image_features-0.2.0/docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 73b0bdf381427242917661b7ca5fe495
+tags: 645f666f9bcd5a90fca523b33c5a78b7

pathology_image_features-0.2.0/docs/build/html/_sources/advanced_usage.rst.txt

@@ -0,0 +1,128 @@
+Advanced Usage
+===============
+
+Adding properties and restrictions to classes is a good way to preserve some desired functionality when classes are serialized so that all new instances of that class have the same property values.
+
+Properties
+----------
+
+Three different types of properties are implemented in *pathology-image-features*. These are:
+
+- **Annotation Properties** (strings which describe what a class or instance is)
+- **Object Properties** (links between classes/instances and other classes/instances)
+- **Datatype Properties** (assignments of data values to classes/instances)
+
+Properties can be accessed for new instances of a class through it's attributes. Properties are automatically given an "alias" which (in most cases) is resolvable to a valid Python attribute name.
+This alias is either the "rdfs:label" value for the property, the result of replacing the spaces in the "rdfs:label" value with underscores, or the final portion of the URI for the property after removing it's namespace.
+
+For example, the property "is about" (IAO:0000136) can be accessed from an instance in the following ways:
+
+.. code-block:: python
+
+    print(f'{instance.is_about=}')
+    print('------------------------')
+    print(f'{instance.get_property("is about")=}')
+    print('------------------------')
+    print(f'{instance.get_property("http://purl.obolibrary.org/obo/IAO_0000136")=}')
+    print('------------------------')
+
+
+Object and Datatype Properties have a "range" which defines the type of value that can be assigned to them. This is where you can specify both Python data types (for Datatype properties) and class/instance types for Object Properties.
+They also have a "domain" which defines which classes can use this property. Both domain and range can consist of either lists of classes or single classes.
+New properties can be defined using the following:
+
+.. code-block:: python
+
+    from pathology_image_features.ontology.properties import ObjectProperty, AnnotationProperty, DatatypeProperty
+
+    package_version = AnnotationProperty(iri = "http://example.org/package_version", definition = "The version of a package used.", name = "package version")
+    user_login_name = DatatypeProperty(iri = "http://example.org/user_login_name", definition = "The login name of the user.", name = "user login name", range = str)
+
+    # Where User and Group are defined classes elsewhere
+    user_group = ObjectProperty(iri = "http://example.org/user_group", definition = "The group the user belongs to.", name = "user group", domain = User, range = Group)
+
+
+After creating a new property, you can register it with the current graph using the 'register_property' method. This allows you to refer to it in class attributes and restrictions using it's alias.
+
+.. code-block:: python
+
+    from pathology_image_features.ontology import PIFO
+    from pathology_image_features.ontology.restrictions import Only
+    from somewhere import user_group, User, GroupA
+
+    PIFO.register_property(user_group)
+
+    class UserInGroupA(User):
+        """A class which is represented by any user belonging to Group A."""
+        equivalent_to = Only(on_property="user_group", on_class=GroupA)
+
+
+
+Restrictions
+------------
+
+Restrictions are used to describe classes based on some property requirements. In *pathology-image-features*, the class attribute 'equivalent_to' is where restrictions are accessed and applied on the creation of new instances.
+
+Builtin restriction types include:
+
+- Some: Specifying that at least instances of this class must have at least one value for a property that matches a given class.
+- Only: Specifying that only instances of this class may have a specified property/value combination.
+- Cardinality -> MinCardinality, MaxCardinality, ExactCardinality: Specifying that an instance must have a minimum, maximum, or exact number of values for a given property.
+
+Combinations of Restrictions can also be made using the "And", "Or", and "Not" classes.
+
+.. code-block:: python
+
+    from pathology_image_features.ontology.restrictions import And, Or, Not, Some, Only, MinCardinality, MaxCardinality, ExactCardinality
+
+    class UserInGroup(User):
+        """A class representing users which belong to at most one group."""
+        equivalent_to = And([
+            Some(on_property="user_group", on_class=Group), # Must have the user_group property (whose range is already Group so this is redundant)
+            MaxCardinality(on_property="user_group", value = 1) # Must have at most one value for the user_group property
+        ])
+
+    # Since the property "user_group" has a defined domain and range, the "Some" restriction can be omitted.
+    class UserInGroup(User):
+        equivalent_to = MaxCardinality(on_property="user_group", value = 1)
+
+    class UserInMultipleGroups(User):
+        """A class representing users which belong to more than one group."""
+        equivalent_to = MinCardinality(on_property="user_group", value = 2)
+
+
+Different behavior can be registered for instance creation when a "equivalent_to" attribute is present for a class. In some cases, it may be desirable to raise an error if a new instance does not have a value for a property which is defined in a Restriction.
+
+Restriction subclasses have a "on_missing" keyword argument on initialization which can be replaced with either "None" or a custom Callable to indicate what should be done if a property is not found for a given instance. By default, *pathology-image-features* will create a new instance of the "on_class" property and assign it to that instance if it is not present.
+
+.. code-block:: python
+
+    class UserInGroup(User):
+        equivalent_to = MaxCardinality(on_property="user_group", value = 1, on_missing=None)
+
+    # This will cause an error as no "user_group" value was provided to the instance
+    new_user = UserInGroup()
+
+    # This will not raise an error as the "user_group" value is specified for this instance
+    new_user = UserInGroup(user_group=GroupA())
+
+    def custom_on_missing(restriction, instance):
+        """If you want to set a default value as "GroupA" for non-grouped UserInGroup instances."""
+        default_val = GroupA()
+        user_group.__set__(instance, default_val)
+
+        setattr(
+            instance.__class__,
+            "user_group",
+            property(
+                lambda inst: user_group.__get__(inst),
+                lambda inst, val: user_group.__set__(inst,val),
+                lambda inst: user_group.__delete__(inst)
+            )
+        )
+
+    class UserInGroup(User):
+        equivalent_to = MaxCardinality(on_property="user_group", value = 1, on_missing=custom_on_missing)
+
+    new_user = UserInGroup()
+    print(f'{isinstance(new_user.user_group[0], GroupA)}') # Will print True

pathology_image_features-0.2.0/docs/build/html/_sources/ann_io.rst.txt

@@ -0,0 +1,20 @@
+Annotations I/O
+================
+
+Reading Annotations
+^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: pathology_image_features.ann_io.read
+    :members:
+
+Converting Annotations
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: pathology_image_features.ann_io.convert
+    :members:
+
+Writing Annotations
+^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: pathology_image_features.ann_io.write
+    :members:

pathology_image_features-0.2.0/docs/build/html/_sources/background.rst.txt

@@ -0,0 +1,105 @@
+Background
+=============
+
+*pathology-image-features* builds off of ontology principles to standardize common processes in an image analysis pipeline, specifically
+for the analysis of pathology data. This allows for better understanding how different types of quantitative metrics and processes
+are related to each other, as well as preparing data for input into an RDF/graph database.
+
+With this library, one can:
+
+- Read annotations for whole slide images (WSIs) from a variety of formats
+- Extract corresponding image regions for individual structures
+- String together complicated processes with minimal coding required
+- Define quantitative feature extraction pipelines with built-in documentation
+
+Why use ontology? What is ontology?
+------------------------------------
+
+In philosophy, ontology is the study of *being* (`Wikipedia <https://en.wikipedia.org/wiki/Ontology>`_). Ontologists collaborate (and sometimes argue)
+on the fundamental structure of reality and every entity within it. How different entities are defined, how they relate to one another, how
+individual "instances" of an entity are differentiated, and how sub-categories of entities are distinguished all fall under the umbrella of ontology.
+
+The highly specific nature of ontological concepts results in a highly formalized language for definitions which can be difficult for non-ontology
+experts to understand. One such example of an ontology is the `Basic Formal Ontology  <https://github.com/bfo-ontology/BFO-2020>`_. As an "upper-level"
+ontology, the BFO is meant to be as general as possible. This means that you won't find any specific terms relating to physical, chemical, or biological
+entities where a more specific "middle-" or "lower-" level ontology would be more appropriate. The `Gene Ontology <https://github.com/geneontology>`_
+is used for characterizing how individual genes are involved in specific biological processes and is useful for determining what is impacted under
+experimental conditions.
+
+Integrating ontology in Python
+-------------------------------
+
+In the context of programming, ontology principles are actually employed fairly often without people realizing it. Take a look at the following code
+adapted from `Owlready2 documentation <https://owlready2.readthedocs.io/en/v0.49/intro.html>`_.
+
+.. code-block:: python
+
+    from restaurant.menu import Pizza
+    from grocery_store.items import (
+        Cheese, PizzaSauce,
+        Pepperoni, Sausage,
+        Olives, Peppers
+    )
+
+    class VegetarianPizza(Pizza):
+        def add_topping(self, topping):
+            if type(topping) in [Pepperoni,Sausage]:
+                raise Exception('No meat allowed!')
+            self.toppings.append(topping)
+
+    class PepperoniAndCheesePizza(Pizza):
+        def add_topping(self, topping):
+            if type(topping) not in [Cheese,Pepperoni,PizzaSauce]:
+                raise Exception('What part of Pepperoni and Cheese do you not understand??')
+            self.toppings.append(topping)
+
+We can clearly see that `VegetarianPizza` and `PepperoniAndCheesePizza`, while both being types of `Pizza`, are constrained in the types of toppings
+that can be added to them. Using inheritance in Python, we can avoid restating a large amount of shared properties while assigning specific methods
+and properties to subclasses based on their desired function or characteristics. Extending on this example, we can define which types of customers
+can have which types of `Pizza` based on any dietary restrictions they might have (think `VegetarianCustomer` vs. `CarnivoreCustomer`). In OWL
+(Web Ontology Language), a `VegetarianPizza` can be defined like this (from `pizza.owl  <https://github.com/owlcs/pizza-ontology/blob/master/pizza.owl>`_):
+
+.. code-block:: xml
+
+    <owl:Class rdf:about="#VegetarianPizza">
+        <rdfs:label xml:lang="pt"
+            >PizzaVegetariana</rdfs:label>
+        <rdfs:comment xml:lang="en"
+            >Any pizza that does not have fish topping and does not have meat topping is a VegetarianPizza. Members of this class do not need to have any toppings at all.</rdfs:comment>
+        <owl:equivalentClass>
+            <owl:Class>
+                <owl:intersectionOf rdf:parseType="Collection">
+                    <owl:Class rdf:about="#Pizza"/>
+                    <owl:Class>
+                        <owl:complementOf>
+                            <owl:Restriction>
+                                <owl:onProperty rdf:resource="#hasTopping"/>
+                                <owl:someValuesFrom rdf:resource="#MeatTopping"/>
+                            </owl:Restriction>
+                        </owl:complementOf>
+                    </owl:Class>
+                    <owl:Class>
+                        <owl:complementOf>
+                            <owl:Restriction>
+                                <owl:onProperty rdf:resource="#hasTopping"/>
+                                <owl:someValuesFrom rdf:resource="#FishTopping"/>
+                            </owl:Restriction>
+                        </owl:complementOf>
+                    </owl:Class>
+                </owl:intersectionOf>
+            </owl:Class>
+        </owl:equivalentClass>
+    </owl:Class>
+
+
+Ontology in pathology image analysis
+--------------------------------------
+
+Pathology images are different from everyday, ordinary images for a variety of reasons. They are generally very high-resolution, they contain tissue
+which may have a specific type of stain applied, and they sometimes contain annotations of regions of interest (ROIs). In the process of analyzing
+these images, custom workflows are developed and subsequent datasets are constructed consisting of more images, annotations, or quantitative metrics.
+
+While writing up an ontology for these different components of an image analysis workflow, we realized that it would be also be beneficial to define the
+actual Python scripts which are used in the execution of these parts within the ontology. Not only would this prevent confusion in how a specific metric
+is calculated, it would also provide a means for serializing a pipeline into a graph database which can be reconstructed and run on subsequent datasets.
+And therefore, *pathology-image-features* was born!