What tf.group does in tensorflow actually?

[Exe Paul]

Ok , so i am learning tensorflow and yes tensorflow documentation is really good but sometimes there are not even a single example to show the implementation of operation in real program. I tried to find these operations real life program and i couldn't even on stackoverflow and google group doesn't good collection of questions on these operations , i am asking this question so beginners in tensorflow will find this answer helpful :

So here are functions which i don't understand quite well , I request please provide 2 -2 example with each operation so i can understand easily.

    tf.assign_Add
    tf.cast
    tf.floor
    tf.random_iniform
    tf.shape() with argument
    tf.sigmoid
    tf.matmul vs tf.mul
    tf.stop_gradient
    tf.reduce_sum

[Sebastian Raschka]

Hi,

I am not sure if the tensorflow mailinglist is the best platform for that, but I am also not sure what other platform would be appropriate for learning-related questions. I think though that the API docs could benefit from "Examples" sections e.g., like in NumPy. Design-wise, however, it's a bit challenging to use docstrings for that I guess, since Tf is not as "dynamic" as NumPy. I can answer some quickly if that helps.

    tf.assign_Add

assign_add updates a variable by adding a value to it. E.g., if you variable is a scalar that is assigned to the variable name "my_scalar" with value 0. assign_adding a scalar with value 1 would increase it by one. I have a toy perceptron example here that uses it

https://github.com/rasbt/deep-learning-book/blob/master/code/ch02_perceptron/ch02_perceptron.ipynb

    tf.cast

this just changes the type of a tensor. E.g. if your tensor is [1, 2],  tf.cast(tensor, tf.float32) will change it to a float tensor.

tf.floor

this is equivalent in function to math.floor in Python, i.e., rounding values down.

 tf.random_iniform

equivalent to NumPy's numpy.random.uniform, drawing a random sample from a uniform distribution

   tf.sigmoid

tf.sigmoid computes the logistic sigmoid function. E.g., similar to "1 / (1 + math.exp(-z))" in python

    tf.reduce_sum

This is equivalent to numpy.add.reduce(ary) or np.sum(axis=0)

[Martin Wicke]

We have tried to make the docs comprehensive, but it's a lot of work. We would welcome any contribution that adds examples to existing docs in a PR. Our doc generator will render "Example:" sections in the docs so you can just add examples to the docstrings for each function.  

--
You received this message because you are subscribed to the Google Groups "Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to discuss+unsubscribe@tensorflow.org.
To post to this group, send email to dis...@tensorflow.org.
To view this discussion on the web visit https://groups.google.com/a/tensorflow.org/d/msgid/discuss/980a8dd8-09d6-40c0-ad66-90ee4e7fd975%40tensorflow.org.

[Sebastian Raschka]

Hi, Martin,

oh yeah, given how many functions there are, there's definitely a lot of work involved. But I am happy to help a bit with that and contribute examples over time to make the docs (even more) useful.

Btw. are those docstrings passed to testing utils like doctest that execute these examples? I think it would be generally useful, but I am not sure how feasible it is to set it up (if it isn't set up yet). Also, it would add additional syntactic overhead to the examples (maybe one could use interactive sessions to reduce that a bit though).

Best,

Sebastian

To unsubscribe from this group and stop receiving emails from it, send an email to discuss+u...@tensorflow.org.

[Martin Wicke]

We (sadly) do not have doctest or similar set up to test examples embedded in our documentation. As usual, any help with that would certainly be appreciated. 

Our docs go through a fair amount of processing in the publishing process, see this doc:

https://github.com/tensorflow/tensorflow/blob/master/tensorflow/docs_src/community/documentation.md

and any automated testing would be fairly straightforward to implement as part of this process. However, we do write straight markdown into our docstrings, and as you noted, not all our examples are immediately executable (they may contain ellipses etc. to make them more readable). That means that coverage would likely be partial. It may be possible to reduce this problem by preprocessing (for instance, translating 

```

some code

```

automatically into

>>>import tensorflow

>>>with tf.InteractiveSession():

>>>  some code

My knowledge of doctest is limited so I don't know what's feasible.

Martin

To unsubscribe from this group and stop receiving emails from it, send an email to discuss+unsubscribe@tensorflow.org.

To post to this group, send email to dis...@tensorflow.org.

To view this discussion on the web visit https://groups.google.com/a/tensorflow.org/d/msgid/discuss/789a040b-7d48-4fc8-948d-def995992f1a%40tensorflow.org.

[Sebastian Raschka]

Oh interesting, I use a similar approach for my own github projects (e.g., mlxtend and biopandas), that is having parsers for docstring -> markdown -> static-html

In my experience so far, this works very well for

(1) having the examples inside the docstrings (e.g. useful if someone wants to check the documentation in an IDE, via help(func) in an interactive env, or func? in ipython).

(2) testing the examples (and the function to some extend as well) as part of the unit tests and continuous integration

(3) generating the markdown and html docs

But like you said, the problem with doctests to execute correctly would be that there might be some annoying overhead that is bad for readability -- on the other hands, users would have a working example that they could paste into an active session to experiment with it, and we'd be sure that the written example is correct and up to date with the current function implementation. 

I am wondering though if it wouldn't be better to use the "doctest" syntax for the example section in the docstrings as it is commonly done. By that, I mean

>>> import tensorflow

>>> with tf.InteractiveSession():

>>> ... some code

This would make everything a bit easier and more natural to users of other packages like numpy, scipy, scikit-learn ... (plus it is easier to test it locally before committing without parsing the docstrings). On the other hand, the current docstring parser would need to be adjusted. But that should be pretty straight-forward, just putting an ``` in a line above the first `>>>` and adding a new line with ``` after the last `>>>`

What do you think?

Best,

Sebastian

To view this discussion on the web visit https://groups.google.com/a/tensorflow.org/d/msgid/discuss/789a040b-7d48-4fc8-948d-def995992f1a%40tensorflow.org.

[Sebastian Raschka]

PS: actually, we could have both, code "fences" and the ">>>" line starts so that the parser wouldn't need to be adjusted at all.

For example,

Examples

========

```

>>> import tensorflow

>>> with tf.InteractiveSession():

>>> ... some code

```

And for functions where it is really not feasible to have "working" doctests, one could just omit the ">>>" at line start to provide a minimal example for a user. Allowing both

1)

```

>>> import tensorflow

>>> with tf.InteractiveSession():

>>> ... some code

```

and 2)

```

some code

```

where doctests only run over lines that start with '>>>', which should be the default, would also make this transition to having executable code examples a smooth transition so that they can added one at a time by contributors

On Thursday, April 27, 2017 at 6:27:24 PM UTC-4, Exe Paul wrote:

[Martin Wicke]

+wolff@ FYI, from dis...@tensorflow.org

We appear to already have a way to include snippets from github in the docs directly, which points to another good possibility to test these snippets: we can take them out of test code. Wolff knows more about how that would work.

Martin

--
You received this message because you are subscribed to the Google Groups "Discuss" group.

To unsubscribe from this group and stop receiving emails from it, send an email to discuss+unsubscribe@tensorflow.org.

To post to this group, send email to dis...@tensorflow.org.

To view this discussion on the web visit https://groups.google.com/a/tensorflow.org/d/msgid/discuss/40b69602-27a1-4b0d-9ccc-373aacf05fdc%40tensorflow.org.

[Sebastian Raschka]

We appear to already have a way to include snippets from github in the docs directly,

In this case, adding the adding the examples as "fenced" code would also be an option to automatically test the examples in PRs? However, like you said ("we can take them out of test code") would probably be the "cleaner" way to do it in terms of code organization -- the workflow would be easier for external contributors I guess. Like mentioned in my previous mail, I think that supporting both, fenced code for examples that cannot be trivially executed and '>>>' lines for examples that should be included in doctests could be the most convenient way to go.

In any case, I am happy to contribute some doc examples, since I think that they are a very useful reference, especially for beginners.

Best,

Sebastian

To unsubscribe from this group and stop receiving emails from it, send an email to discuss+u...@tensorflow.org.

To post to this group, send email to dis...@tensorflow.org.