`.) After this, I thought that maybe I should be using QIIME types as outputs, so (for testing purposes), I ditched the `dict` part of the output and just tried defining a return value for a list of strings as `qiime2.plugin.List[qiime2.plugin.Str]`, but that produced the same type(output\_view) != spec.view\_type error.
---
### Author:  [@gregcaporaso](https://forum.qiime2.org/u/gregcaporaso)
#### Post date: [February 27, 2024, 2:41pm UTC](https://forum.qiime2.org/t/guidance-on-typing-for-functions-underlying-plugin-actions/29368/2 "2024-02-27T14:41:44Z")
---
### Author:  [@gregcaporaso](https://forum.qiime2.org/u/gregcaporaso)
#### Post date: [February 27, 2024, 3:59pm UTC](https://forum.qiime2.org/t/guidance-on-typing-for-functions-underlying-plugin-actions/29368/3 "2024-02-27T15:59:23Z")
Hi @Amanda_Birmingham,
When defining functions that are registered to actions (`fit`, in your example), the types that you associate with the inputs and outputs are Python data types, and more specifically Python data types that are associated with the semantic type of that input or output by transformers.
Quick explanation of the motivation: This enables "viewing" artifacts as different data types internally - i.e., what the data represents (its semantic type) is decoupled from how we interact with it (its data type). For example, if you have a `FeatureTable[Frequency]` as input to an action ([eg](https://github.com/caporaso-lab/q2-dwq2/blob/e8fe1e5b32bfc2a331d48611b3a70b0fa5b19165/q2_dwq2/plugin_setup.py#L32)), that can be viewed as a `biom.Table` object or a `pandas.DataFrame` object, and the developer may choose between the two of those based on available functionality, efficiency for an operation they plan to carry out, their familiarity with the object, or whatever else. This also leaves the door open for semantic types to be viewed as new data types (e.g., by adding a transformer to a new, futuristic `superfast.Table` object), while not requiring all actions that take a `FeatureTable[Frequency]` as input to update their function to use the `superfast.Table` rather than the `pandas.DataFrame` or `biom.Table` API they were previously using.
I used your question as an opportunity to port some related content that I had written over to _Developing with QIIME 2_ (i.e., the new developer documentation), so you can now find a little more discussion about this [here](https://cap-lab.bio/developing-with-qiime2/plugins/explanations/types-of-types.html).
---
### Author:  [@Amanda\_Birmingham](https://forum.qiime2.org/u/Amanda_Birmingham)
#### Post date: [March 1, 2024, 10:26pm UTC](https://forum.qiime2.org/t/guidance-on-typing-for-functions-underlying-plugin-actions/29368/4 "2024-03-01T22:26:02Z")
Thank you, @gregcaporaso, the article is helpful--as you note, the word 'type' is quite overloaded! The word 'format' is also doing a lot of work, which I think adds to my confusion ๐
> When defining functions that are registered to actions ..., the types that you associate with the inputs and outputs are ... Python data types that are associated with the semantic type of that input or output by transformers.
This is very useful guidance. So, my current understanding is that when I am defining the inputs and outputs for a function that will be registered as an action:
- I can use data types (e.g., in-memory representations of data) like pandas.DataFrame or biom.Table (assuming the linked input in the action is of a SemanticType that can be transformed into those).
- I can also use _data types_ that are "Formats" in the QIIME sense (not in the file sense). For, example, I see the function underlying the `q2-demux.subsample_single` action takes in a [SingleLanePerSampleSingleEndFastqDirFmt](https://github.com/qiime2/q2-demux/blob/6e9a0cc8841a9cfbb5f517a256872700c7b75732/q2_demux/_subsample.py#L23C5-L23C21)
- I can also use QIIME "primitive types"? (e.g. I have seen examples of functions underlying actions where these functions take [inputs of the data type qiime2.Metadata](https://github.com/qiime2/q2-diversity/blob/99a0ccaaec14838b95845dbfe57f874d092b65c7/q2_diversity/_beta/_beta_rarefaction.py#L28-L29), although maybe this is relevant only to function inputs that come in via action 'parameters' and not those that come in via action 'inputs'?)
- I CANNOT use SemanticTypes. As I understand it, SemanticTypes **define** kinds of data, and are instantiated in memory (e.g., [`UchimeStats = SemanticType('UchimeStats')`](https://github.com/qiime2/q2-vsearch/blob/93dfc96d33e311c2a7deb53d0ba8237020a1d8e8/q2_vsearch/_type.py#L12) ), but don't actually _hold any data_ themselves ... which I guess would be a good reason I can't use them to pass data into a function ๐
- I CANNOT use (data?) types from the python `typing` library, such as `Union[Dict[str: float]`. Maybe this is because I cannot actually instantiate an object that is of the type `Dict[str: float]`? (Like, `my_dict = {"blue": 3.5}` qualifies as a `Dict[str: float]` but that is not its actual data type, which is `dict`.)
Any further corrections to my understanding would be very much welcome and appreciated. I am grateful to the QIIME team for all the support you folks provide!
---
### Author:  [@gregcaporaso](https://forum.qiime2.org/u/gregcaporaso)
#### Post date: [March 6, 2024, 4:25pm UTC](https://forum.qiime2.org/t/guidance-on-typing-for-functions-underlying-plugin-actions/29368/5 "2024-03-06T16:25:36Z")
> The word 'format' is also doing a lot of work
Good point - I'll keep that in mind as I'm writing _Developing with QIIME 2_.
All of the points you mention are correct. I'll provide a little bit of clarification on some (if I don't mention one it's b/c I have nothing to add to your description).
> I can also use _data types_ that are "Formats" in the QIIME sense
Yes, exactly - these are useful when you want to process a file within your action (e.g., iterate over the lines in a fastq file, as in your example).
> I can also use QIIME "primitive types"... maybe this is relevant only to function inputs that come in via action 'parameters' and not those that come in via action 'inputs'
Yes, exactly. That's a distinction between 'parameters' and 'inputs': parameters use primitive types while inputs are always artifacts and therefore have semantic types associated with them.
> I CANNOT use (data?) types from the python `typing` library
Correct. I chatted with @ebolyen about this and his perspective is that `typing` was changing a lot when we were working on this, so didn't prioritize it then, and it hasn't surfaced as a priority since it's stabilizing.
> I am grateful to the QIIME team for all the support you folks provide!
Thank you!
---
### Author:  [@gregcaporaso](https://forum.qiime2.org/u/gregcaporaso)
#### Post date: [March 6, 2024, 4:25pm UTC](https://forum.qiime2.org/t/guidance-on-typing-for-functions-underlying-plugin-actions/29368/6 "2024-03-06T16:25:56Z")