Update readme + add example schema

Author: esoteric-ephemera

mpcontribs-lux/README.md

@@ -1,5 +1,29 @@
 ## MPContribs-LUX
 
-<span style="color:forestgreen"><i>Ego sum lux datorum</i></span>.
+<span style="color:goldenrod"><i><b>Ego sum lux datorum</b></i></span>.
 
-MPContribs-lux is a package which <it>sheds light</it> on data stored on the [Materials Project's AWS S3 OpenData bucket](https://materialsproject-contribs.s3.amazonaws.com/index.html#) by providing annotated schemas and optionally analysis tools to better explore user-submitted data.
+MPContribs-lux is a package which <it>sheds light</it> on data stored on the [Materials Project's AWS S3 OpenData bucket](https://materialsproject-contribs.s3.amazonaws.com/index.html#) by providing annotated schemas and optionally analysis tools to better explore user-submitted data.
+
+Adding a schema to this database is a <span style="color:red"><b>pre-requisite</b></span> for obtaining permission/IAM credentials for uploading data to MP's OpenData Bucket.
+Once a staff member from MP reviews and approves your data schema, your receive IAM role will be granted/updated (as appropriate).
+
+<span style="color:red"><b>What if I don't want my schemas / data made public yet?</b></span>
+
+To expedite the process of review, follow [these instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository) to make a private copy (not a fork, which cannot be private) of the `MPContribs` repo.
+Suppose you name your new repository `PrivateMPContribs` and your username is `<username>`, you would run these commands from a terminal:
+```console
+git clone --bare https://github.com/materialsproject/MPContribs.git
+cd MPContribs
+git push --mirror https://github.com/<username>/PrivateMPContribs.git
+cd ..
+rm -rf MPContribs
+```
+
+Then add your schemas to the private repo `PrivateMPContribs` and invite the maintainers of `MPContribs` to view it (you don't need to give us edit access).
+We will then review your schemas.
+When you're ready to make your data public, you will also have to make a public PR with your new schemas.
+
+<span style="color:red"><b>But my CSV/JSON/YAML/etc. file isn't complicated. Why do I need to upload a schema?</b></span>
+
+Schemas are important for ensuring accessibility, interoperability, and reproducibility, and for ensuring that you are fully aware of possible errors in your dataset.
+If you are not comfortable mimicking the example `pydantic` schemas in `mpcontribs.lux.projects.examples`

mpcontribs-lux/mpcontribs/lux/projects/examples.py

@@ -0,0 +1,59 @@
+"""Define example schemas for users.
+
+This schema is used for the public MPContribs project `test_solid_data`:
+    https://next-gen.materialsproject.org/contribs/projects/test_solid_data
+You can find its download on AWS S3:
+    https://materialsproject-contribs.s3.amazonaws.com/index.html#test_solid_data/solid_data.parquet
+"""
+
+from functools import cached_property
+
+from pydantic import BaseModel, Field
+
+from pymatgen.core import Structure
+
+class ExampleSchema(BaseModel):
+    """Define example schema with appropriate levels of annotated metadata."""
+
+    formula : str | None = Field(
+        None, description = "The chemical formula of the unit cell."
+    )
+
+    a0 : float | None = Field(
+        None, description = "The experimental equilibrium cubic "
+        "lattice constant a, in Å,  including zero-point corrections "
+        "for nuclear vibration."
+    )
+
+    b0 : float | None = Field(
+        None, description = "The experimental bulk modulus at "
+        "optimal lattice geometry, in GPa, including zero-point "
+        "corrections for nuclear vibration."
+    )
+
+    e0 : float | None = Field(
+        None, description = "The experimental cohesive energy, in eV/atom, "
+        "including zero-point corrections for nuclear vibration."
+    )
+
+    cif : str | None = Field(
+        None, description="The structure represented as a Crystallographic Information File."
+    )
+
+    material_id : str | None = Field(
+        None, description = "The Materials Project ID of the structure which "
+        "corresponds to this entry. The ID will start with `mp-`"
+    )
+
+    @cached_property
+    def get_pymatgen_structure(self) -> Structure | None:
+        """Get the pymatgen structure for this entry, if it exists.
+        
+        Example of adding functionality to downstream users to interact 
+        with your data.
+        
+        You can provide more advanced analysis tools, which we also show below.
+        """
+        if self.cif:
+            return Structure.from_str(self.cif,fmt="cif")
+        return None